Python zero-code instrumentation¶

Beacon Python supports the documented zero-code workflow on Python 3.10 through 3.14. Install it in the same virtual environment as the application.

Before starting, enable the DataKit OpenTelemetry input as described in Common configuration. The commands use a Linux/macOS shell and assume that the application and DataKit run on the same host. Replace 127.0.0.1 and adjust the listening address for remote or container deployments.

Install¶

Choose the extra that matches the application:

# FastAPI; use flask or requests for those integrations
pip install 'beacon-otel[fastapi]'

Run¶

export OTEL_SERVICE_NAME=my-python-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
beacon uvicorn myapp:app

Replace uvicorn myapp:app with the application's existing command. beacon --version verifies which distribution is active.

Debugging and diagnostics¶

The Beacon Python zero-code entry point does not provide a unified SDK debug-log switch. OTEL_LOG_LEVEL=debug does not automatically configure Python logging levels. For detailed logs, use the application's existing logging configuration to set the opentelemetry logger to DEBUG and attach an output handler.

For an initial check without application source changes, add console Span output while retaining OTLP export:

beacon --version
OTEL_TRACES_EXPORTER=otlp,console \
  beacon uvicorn myapp:app > beacon-python-diagnostic.log 2>&1

Keep the service name, OTLP endpoint, and protocol above. Send a request through a supported framework and inspect Spans in the file. Console output helps distinguish missing Spans from receiver export failures; it neither confirms OTLP delivery nor enables SDK debug logs.

Return to the normal launch command, remove the additional console exporter, and restore application logging levels after troubleshooting.

Profile¶

Enable the DataKit Profile input, then set the variables below and retain the launch configuration above. Profiles use a separate HTTP upload endpoint, independent of the OTLP traces endpoint.

Install the profiling extra in the application's virtual environment:

pip install 'beacon-otel[fastapi,profiling]'

Replace fastapi with the integration used by the application.

Upload pprof over HTTP¶

export OTEL_SERVICE_NAME=my-python-service
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=pprof_http
export OTEL_PROFILING_PPROF_UPLOAD_URL=http://127.0.0.1:9529/profiling/v1/input
beacon uvicorn myapp:app

When authentication is required, set OTEL_PROFILING_PPROF_HEADERS to a comma-separated list of name:value headers.

Write pprof files locally¶

export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=pprof
export OTEL_PROFILING_PPROF_PATH="$PWD/profiles"
beacon uvicorn myapp:app

Create the target directory first and include it in the deployment's retention policy.

Additional collectors¶

Stack sampling is enabled with profiling. Add collectors only as needed:

export OTEL_PROFILING_MEMORY_ENABLED=true
export OTEL_PROFILING_LOCK_ENABLED=true
# Python 3.12 or later
export OTEL_PROFILING_EXCEPTION_ENABLED=true

The default export interval is 60 seconds. The process must remain alive beyond that interval to produce periodic uploads.

Configuration reference¶

Environment-variable names are case-sensitive. Interval values in the runtime table are seconds.

Runtime and collectors¶

Environment variable	Type / accepted values	Default	Description
`OTEL_PROFILING_ENABLED`	Boolean	`false`	Starts the profiler during auto-instrumentation bootstrap.
`OTEL_PROFILING_EXPORTER`	`none`, `pprof`, `pprof_http`, `otlp`	Automatic	Selects the exporter. If unset, a configured pprof upload URL selects `pprof_http`; otherwise Beacon selects `otlp`.
`OTEL_PROFILING_SAMPLE_INTERVAL`	Positive number	`0.01`	Stack sampling interval.
`OTEL_PROFILING_EXPORT_INTERVAL`	Positive number	`60`	Profile flush and export interval.
`OTEL_PROFILING_MAX_FRAMES`	Positive integer	`64`	Maximum stack frames captured per sample.
`OTEL_PROFILING_INCLUDE_TRACE_CONTEXT`	Boolean	`true`	Adds active trace and span context when available.
`OTEL_PROFILING_EXCEPTION_ENABLED`	Boolean	`false`	Enables exception profiling.
`OTEL_PROFILING_EXCEPTION_SAMPLING_INTERVAL`	Positive integer	`100`	Exception sampling stride.
`OTEL_PROFILING_EXCEPTION_COLLECT_MESSAGE`	Boolean	`false`	Includes exception messages. Review sensitive-data implications before enabling.
`OTEL_PROFILING_LOCK_ENABLED`	Boolean	`false`	Enables threading and asyncio lock collectors.
`OTEL_PROFILING_MEMORY_ENABLED`	Boolean	`false`	Enables memory profiling.
`OTEL_PROFILING_MEMORY_INTERVAL`	Positive number	Export interval	Memory capture interval.
`OTEL_PROFILING_MEMORY_TOP_STATS`	Positive integer	`200`	Maximum memory statistics retained per capture.
`OTEL_PROFILING_MEMORY_IGNORE_PROFILER`	Boolean	`true`	Excludes allocations attributed to the profiler itself.

pprof export¶

Environment variable	Type / accepted values	Default	Description
`OTEL_PROFILING_PPROF_PATH`	File-path prefix	`otel-profiles`	Prefix for generated `.pprof` files. Both pprof exporters write a local copy.
`OTEL_PROFILING_PPROF_UPLOAD_URL`	HTTP(S) URL	`http://localhost:8126/profiling/v1/input`	Upload URL used by `pprof_http`. Setting it while the exporter is unset also selects `pprof_http`.
`OTEL_PROFILING_PPROF_HEADERS`	Comma-separated `name:value` pairs	Empty	Extra HTTP request headers.

Security¶

The same beacon-otel wheel contains opt-in Security for standard-GIL CPython 3.11 through 3.14. See the Python Security guide.

Verify¶

Send a request through a supported framework or library, then open APM > Traces in Guance and filter by the configured service name. See Common configuration for verification steps and Troubleshooting if no data appears.