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

> Python for ClickStack - The ClickHouse Observability Stack

# Python

ClickStack uses the OpenTelemetry standard for collecting telemetry data (logs and
traces). Traces are auto-generated with automatic instrumentation, so manual
instrumentation isn't required to get value out of tracing.

This guide integrates:

* **Logs**
* **Metrics**
* **Traces**

<h2 id="getting-started">
  Getting started
</h2>

<h3 id="install-clickstack-otel-instrumentation-package">
  Install ClickStack OpenTelemetry instrumentation package
</h3>

Use the following command to install the [ClickStack OpenTelemetry package](https://pypi.org/project/hyperdx-opentelemetry/).

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

Install the OpenTelemetry automatic instrumentation libraries for the packages used by your Python application. We recommend that you use the
`opentelemetry-bootstrap` tool that comes with the OpenTelemetry Python SDK to scan your application packages and generate the list of available libraries.

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

<h3 id="configure-environment-variables">
  Configure environment variables
</h3>

Afterwards you'll need to configure the following environment variables in your shell to ship telemetry to ClickStack via the OpenTelemetry collector:

<Tabs>
  <Tab title="Managed ClickStack">
    ```shell theme={null}
    OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
    OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 
    ```
  </Tab>

  <Tab title="ClickStack Open Source">
    ```shell theme={null}
    export HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' \
    OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
    OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 
    ```
  </Tab>
</Tabs>

*The `OTEL_SERVICE_NAME` environment variable is used to identify your service in the HyperDX app, it can be any name you want.*

<h3 id="run-the-application-with-otel-python-agent">
  Run the application with OpenTelemetry Python agent
</h3>

Now you can run the application with the OpenTelemetry Python agent (`opentelemetry-instrument`).

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

<h4 id="using-uvicorn-gunicorn-uwsgi">
  If you're using `Gunicorn`, `uWSGI` or `uvicorn`
</h4>

In this case, the OpenTelemetry Python agent will require additional changes to work.

To configure OpenTelemetry for application servers using the pre-fork web server mode, make sure to call the `configure_opentelemetry` method within the post-fork hook.

<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 [currently doesn't work](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/385) with `uvicorn` run using the `--reload`
    flag or with multi-workers (`--workers`). We recommend disabling those flags while testing, or using Gunicorn.
  </Tab>
</Tabs>

<h2 id="advanced-configuration">
  Advanced configuration
</h2>

<h4 id="network-capture">
  Network capture
</h4>

By enabling network capture features, developers gain the capability to debug
HTTP request headers and body payloads effectively. This can be accomplished
simply by setting `HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE` flag to 1.

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

<h2 id="troubleshooting">
  Troubleshooting
</h2>

<h3 id="logs-not-appearing-due-to-log-level">
  Logs not appearing due to log level
</h3>

By default, OpenTelemetry logging handler uses `logging.NOTSET` level which
defaults to WARNING level. You can specify the logging level when you create a
logger:

```python theme={null}
import logging

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

<h3 id="exporting-to-the-console">
  Exporting to the console
</h3>

The OpenTelemetry Python SDK usually displays errors in the console when they
occur. However, if you don't encounter any errors but notice that your data is
not appearing in HyperDX as expected, you have the option to enable debug mode.
When debug mode is activated, all telemetries will be printed to the console,
allowing you to verify if your application is properly instrumented with the
expected data.

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

Read more about Python OpenTelemetry instrumentation here:
[https://opentelemetry.io/docs/instrumentation/python/manual/](https://opentelemetry.io/docs/instrumentation/python/manual/)