> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Python для ClickStack — стек обсервабилити ClickHouse

# Python

export const ClickStackIntegrates = ({signals = []}) => {
  const list = Array.isArray(signals) ? signals : String(signals).split(",");
  const supported = list.map(s => String(s).trim().toLowerCase());
  const pillStyle = {
    display: "inline-flex",
    alignItems: "center",
    padding: "0.125rem 0.625rem",
    borderRadius: "9999px",
    fontSize: "0.8125rem",
    fontWeight: 500,
    lineHeight: 1.6,
    color: "#161517",
    backgroundColor: "#faff69",
    border: "1px solid rgba(0, 0, 0, .1)",
    marginRight: "0.5rem"
  };
  return <div style={{
    margin: "0 0 1.25rem"
  }}>
      <span style={{
    marginRight: "0.5rem"
  }}>Это руководство поддерживает:</span>
      {supported.includes("logs") && <span style={pillStyle}>Журналы</span>}
      {supported.includes("metrics") && <span style={pillStyle}>Метрики</span>}
      {supported.includes("traces") && <span style={pillStyle}>Трассировки</span>}
    </div>;
};

ClickStack использует стандарт OpenTelemetry для сбора телеметрических данных (журналов и
трассировок). Трассировки автоматически создаются с помощью автоматического инструментирования, поэтому ручное
инструментирование не требуется, чтобы начать получать пользу от трассировки.

<ClickStackIntegrates signals={['logs', 'metrics', 'traces']} />

<h2 id="getting-started">
  Начало работы
</h2>

<h3 id="install-clickstack-otel-instrumentation-package">
  Установите пакет ClickStack OpenTelemetry для инструментирования
</h3>

Используйте следующую команду, чтобы установить [пакет ClickStack OpenTelemetry для инструментирования](https://pypi.org/project/hyperdx-opentelemetry/).

```shell theme={null}
pip install hyperdx-opentelemetry
```

Установите библиотеки автоматического инструментирования OpenTelemetry для пакетов, используемых вашим Python-приложением. Мы рекомендуем использовать
инструмент `opentelemetry-bootstrap`, входящий в состав OpenTelemetry Python SDK, чтобы просканировать пакеты вашего приложения и сгенерировать список доступных библиотек.

```shell theme={null}
opentelemetry-bootstrap -a install
```

<h3 id="configure-environment-variables">
  Настройте переменные окружения
</h3>

После этого настройте в вашей оболочке следующие переменные окружения, чтобы отправлять телеметрию в ClickStack через OpenTelemetry Collector:

<Tabs>
  <Tab title="Управляемый ClickStack">
    ```shell theme={null}
    OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' \
    OTEL_EXPORTER_OTLP_ENDPOINT=<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT> 
    ```
  </Tab>

  <Tab title="ClickStack с открытым исходным кодом">
    ```shell theme={null}
    export HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' \
    OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' \
    OTEL_EXPORTER_OTLP_ENDPOINT=<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT> 
    ```
  </Tab>
</Tabs>

*Переменная окружения `OTEL_SERVICE_NAME` используется для идентификации вашего сервиса в приложении HyperDX; ей можно присвоить любое имя.*

<h3 id="run-the-application-with-otel-python-agent">
  Запустите приложение с агентом OpenTelemetry Python
</h3>

Теперь вы можете запустить приложение с помощью агента OpenTelemetry Python (`opentelemetry-instrument`).

```shell theme={null}
opentelemetry-instrument python app.py
```

<h4 id="using-uvicorn-gunicorn-uwsgi">
  Если вы используете `Gunicorn`, `uWSGI` или `uvicorn`
</h4>

В этом случае для работы агента OpenTelemetry для Python потребуются дополнительные изменения.

Чтобы настроить OpenTelemetry для серверов приложений, использующих режим pre-fork, обязательно вызовите метод `configure_opentelemetry` в хуке post-fork.

<Tabs>
  <Tab title="Gunicorn">
    ```python theme={null}
    from hyperdx.opentelemetry import configure_opentelemetry

    def post_fork(server, worker):
        configure_opentelemetry()
    ```
  </Tab>

  <Tab title="uWSGI">
    ```python theme={null}
    from hyperdx.opentelemetry import configure_opentelemetry
    from uwsgidecorators import postfork

    @postfork
    def init_tracing():
        configure_opentelemetry()
    ```
  </Tab>

  <Tab title="uvicorn">
    OpenTelemetry [в настоящее время не работает](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/385) с `uvicorn`, запущенным с флагом `--reload`
    или с несколькими воркерами (`--workers`). Во время тестирования рекомендуем отключить эти флаги или использовать Gunicorn.
  </Tab>
</Tabs>

<h2 id="advanced-configuration">
  Расширенная конфигурация
</h2>

<h4 id="network-capture">
  Захват сетевого трафика
</h4>

Включив возможности захвата сетевого трафика, разработчики могут эффективно
отлаживать заголовки HTTP-запросов и полезные нагрузки в их теле.
Это можно сделать,
просто установив флаг `HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE` в 1.

```shell theme={null}
export HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE=1
```

<h2 id="troubleshooting">
  Устранение неполадок
</h2>

<h3 id="logs-not-appearing-due-to-log-level">
  Журналы не отображаются из-за уровня логирования
</h3>

По умолчанию обработчик логирования OpenTelemetry использует уровень `logging.NOTSET`,
что фактически означает уровень WARNING. Уровень логирования можно указать при создании
логгера:

```python theme={null}
import logging

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)
```

<h3 id="exporting-to-the-console">
  Вывод в консоль
</h3>

Python SDK OpenTelemetry обычно выводит ошибки в консоль при их
возникновении. Однако если ошибок нет, но вы замечаете, что данные
не появляются в HyperDX, как ожидается, можно включить режим отладки.
Когда режим отладки включён, все телеметрические данные будут выводиться в консоль,
что позволит проверить, правильно ли инструментировано ваше приложение и передаёт ли оно
ожидаемые данные.

```shell theme={null}
export DEBUG=true
```

Подробнее об инструментировании Python с помощью OpenTelemetry читайте здесь:
[https://opentelemetry.io/docs/instrumentation/python/manual/](https://opentelemetry.io/docs/instrumentation/python/manual/)