references/python.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Python Logs installation
Canonical URL: https://posthog.com/docs/logs/installation/python
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install OpenTelemetry packages
- Get your project token
- Configure the SDK
- Use OpenTelemetry logging
- Test your setup
- Next steps
-
1
Install OpenTelemetry packages
Required
pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp -
2
Get your project token
Required
You'll need your PostHog project token to authenticate log requests. This is the same key you use for capturing events and exceptions with the PostHog SDK.
Important: Use your project token which starts with
phc_. Do not use a personal API key (which starts withphx_).You can find your project token in Project Settings.
-
3
Configure the SDK
Required
Set up the OpenTelemetry SDK to send logs to PostHog.
Note: The logs API is still experimental in
opentelemetry-python, so it's only exposed under the private_logsimport path (e.g.opentelemetry._logs). Use these imports rather thanopentelemetry.logs, which doesn't exist yet.import logging from opentelemetry._logs import set_logger_provider from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler from opentelemetry.sdk._logs.export import BatchLogRecordProcessor from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter # Configure the logger provider logger_provider = LoggerProvider() set_logger_provider(logger_provider) # Create OTLP exporter with API key in header otlp_exporter = OTLPLogExporter( endpoint="https://us.i.posthog.com/i/v1/logs", headers={"Authorization": "Bearer <ph_project_token>"} ) # Add processor logger_provider.add_log_record_processor( BatchLogRecordProcessor(otlp_exporter) ) # Attach the OpenTelemetry handler to the root logger logging.getLogger().addHandler(LoggingHandler(logger_provider=logger_provider))Alternatively, you can pass the API key as a query parameter:
otlp_exporter = OTLPLogExporter( endpoint="https://us.i.posthog.com/i/v1/logs?token=<ph_project_token>" ) -
4
Use OpenTelemetry logging
Required
With the handler attached in the previous step, you can start logging with standard Python logging and the records flow to PostHog:
import logging logging.basicConfig(level=logging.INFO) # Use standard Python logging logger = logging.getLogger("my-app") logger.info("User action", extra={"userId": "123", "action": "login"}) logger.warning("Deprecated API used", extra={"endpoint": "/old-api"}) logger.error("Database connection failed", extra={"error": "Connection timeout"}) -
5
Test your setup
Recommended
Once everything is configured, test that logs are flowing into PostHog:
- Send a test log from your application
- Check the PostHog Logs interface for your log entries
- Verify the logs appear in your project
-
Next steps
Checkpoint
What you can do with your logs
| Action | Description | | --- | --- | | Why you need logs | What logs show you that nothing else does | | Search logs | Use the search interface to find specific log entries | | Filter by level | Filter by
INFO,WARN,ERROR, etc. | | Link session replay | Connect logs to users and session replays by passingposthogDistinctIdandsessionId| | Link logs to a person | Surface every log emitted on behalf of a user on their PostHog person profile | | Logging best practices | Learn what to log, how to structure logs, and patterns that make logs useful in production |