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
Getting started
Install ClickStack OpenTelemetry instrumentation package
Use the following command to install the ClickStack OpenTelemetry package.
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.
Configure environment variables
Afterwards you'll need to configure the following environment variables in your shell to ship telemetry to ClickStack:
The OTEL_SERVICE_NAME
environment variable is used to identify your service in the HyperDX app, it can be any name you want.
Run the application with OpenTelemetry Python agent
Now you can run the application with the OpenTelemetry Python agent (opentelemetry-instrument
).
If you are using Gunicorn
, uWSGI
or uvicorn
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.
- Gunicorn
- uWSGI
- uvicorn
OpenTelemetry currently does not work with uvicorn
run using the --reload
flag or with multi-workers (--workers
). We recommend disabling those flags while testing, or using Gunicorn.
Advanced configuration
Network capture
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.
Troubleshooting
Logs not appearing due to log level
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:
Exporting to the console
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.
Read more about Python OpenTelemetry instrumentation here: https://opentelemetry.io/docs/instrumentation/python/manual/