Skip to main content
Use the ClickStack Python SDK to send logs and traces to ClickHouse Observability. The SDK is an OpenTelemetry distribution published as hyperdx-opentelemetry and automatically instruments supported Python libraries and frameworks.

​
Install the SDK

Install the ClickStack Python SDK in your application’s Python environment:
The bootstrap command installs instrumentation for your application’s installed dependencies. Run it after installing those dependencies.

​
Configure your destination

Open Team Settings → Data → Managed Telemetry in your service and copy the OTLP HTTP endpoint and API key. Use the complete HTTPS endpoint, including its port:

​
Start your application

Run your application with automatic instrumentation:
Replace app.py with your application’s entry file. OTEL_LOG_LEVEL sets the SDK’s logging level. Set it to warning to capture the test message below, or info for lower-severity application logs. The SDK defaults to ERROR when no level is configured. The ClickStack SDK already installs a log exporter. Setting OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=false prevents OpenTelemetry’s logging instrumentation from adding another exporter and duplicating log records; the SDK still exports logs.

​
Verify ingestion

Make requests to your application and emit a Python log message at WARNING level or above. In ClickHouse Observability, select a recent time range and search Logs or Traces for my-python-app (or the service name you configured).

​
Optional configuration

To capture HTTP request headers and bodies, enable advanced network capture before starting your application:
Request headers and bodies can contain sensitive data. Enable capture only for data you intend to collect.

​
Troubleshooting

If logs are missing, check OTEL_LOG_LEVEL and your application’s logger and handler levels. Set them to capture the severity of the messages you expect. For instrumentation and exporter troubleshooting, see the OpenTelemetry Python troubleshooting guide.