Python 零代码接入¶

Beacon Python 的零代码流程支持 Python 3.10 至 3.14。请将它安装在应用使用的同一个虚拟环境中。

接入前，请先完成公共配置，开启 DataKit OpenTelemetry 采集器。以下命令以 Linux/macOS Shell 为例，假设应用与 DataKit 部署在同一主机；跨主机或容器部署时，请替换 127.0.0.1 并调整监听地址。

安装¶

选择与应用框架匹配的 extra：

# FastAPI；使用 Flask 或 requests 时替换对应 extra
pip install 'beacon-otel[fastapi]'

启动¶

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

将 uvicorn myapp:app 替换为应用原有启动命令。可用 beacon --version 检查当前生效的版本。

调试与诊断¶

Beacon Python 的零代码入口没有统一的 SDK 调试日志开关，OTEL_LOG_LEVEL=debug 不会自动配置 Python 的 logging 级别。需要详细日志时，通过应用已有的日志配置将 opentelemetry Logger 设为 DEBUG 并配置输出 Handler。

无需修改应用源码的初步诊断，可以在保留 OTLP 导出的同时增加控制台 Span 输出：

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

沿用上文的服务名、OTLP 地址和协议，访问一个受支持框架的接口，再检查文件中的 Span。控制台副本可帮助区分“未生成 Span”和“向接收端导出失败”，不代表 OTLP 投递成功，也不是 SDK 调试日志。

排障后恢复原启动命令，移除额外的 console 导出器，并恢复应用日志级别。

Profile¶

先开启 DataKit Profile 采集器，再设置以下变量并沿用上文的启动方式。Profile 使用独立的 HTTP 上传地址，不复用 OTLP Trace 地址。

在应用使用的虚拟环境中安装 profiling extra：

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

请将 fastapi 替换为应用实际使用的组件。

通过 HTTP 上传 pprof¶

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

如需认证，可使用 OTEL_PROFILING_PPROF_HEADERS 设置以逗号分隔的 名称:值 HTTP Header。

写入本地 pprof 文件¶

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

请先创建目标目录，并将其纳入部署环境的文件保留策略。

额外采集器¶

开启 Profile 后默认采集调用栈。请按需增加其他采集器：

export OTEL_PROFILING_MEMORY_ENABLED=true
export OTEL_PROFILING_LOCK_ENABLED=true
# 仅限 Python 3.12 及以上
export OTEL_PROFILING_EXCEPTION_ENABLED=true

默认导出周期为 60 秒，进程必须存活超过该周期才能进行周期性上传。

参数参考¶

环境变量名称区分大小写。运行时参数表中的间隔均以秒为单位。

运行时与采集器¶

环境变量	类型 / 可选值	默认值	说明
`OTEL_PROFILING_ENABLED`	布尔值	`false`	在自动插桩启动阶段启动 Profiler。
`OTEL_PROFILING_EXPORTER`	`none`、`pprof`、`pprof_http`、`otlp`	自动选择	选择导出器。未设置时，如配置了 pprof 上传 URL，则选择 `pprof_http`，否则选择 `otlp`。
`OTEL_PROFILING_SAMPLE_INTERVAL`	正数	`0.01`	调用栈采样间隔。
`OTEL_PROFILING_EXPORT_INTERVAL`	正数	`60`	Profile 刷新和导出间隔。
`OTEL_PROFILING_MAX_FRAMES`	正整数	`64`	单次采样捕获的最大栈帧数。
`OTEL_PROFILING_INCLUDE_TRACE_CONTEXT`	布尔值	`true`	在可用时加入当前 Trace 和 Span 上下文。
`OTEL_PROFILING_EXCEPTION_ENABLED`	布尔值	`false`	启用异常 Profile。
`OTEL_PROFILING_EXCEPTION_SAMPLING_INTERVAL`	正整数	`100`	异常采样步长。
`OTEL_PROFILING_EXCEPTION_COLLECT_MESSAGE`	布尔值	`false`	采集异常消息；启用前需评估敏感数据风险。
`OTEL_PROFILING_LOCK_ENABLED`	布尔值	`false`	启用 threading 和 asyncio 锁采集器。
`OTEL_PROFILING_MEMORY_ENABLED`	布尔值	`false`	启用内存 Profile。
`OTEL_PROFILING_MEMORY_INTERVAL`	正数	导出间隔	内存采集间隔。
`OTEL_PROFILING_MEMORY_TOP_STATS`	正整数	`200`	每次内存采集保留的最大统计项数量。
`OTEL_PROFILING_MEMORY_IGNORE_PROFILER`	布尔值	`true`	排除 Profiler 自身产生的内存分配。

pprof 导出¶

环境变量	类型 / 可选值	默认值	说明
`OTEL_PROFILING_PPROF_PATH`	文件路径前缀	`otel-profiles`	生成 `.pprof` 文件的路径前缀；两种 pprof 导出器都会保留本地副本。
`OTEL_PROFILING_PPROF_UPLOAD_URL`	HTTP(S) URL	`http://localhost:8126/profiling/v1/input`	`pprof_http` 使用的上传地址。导出器未设置时，配置此变量也会选择 `pprof_http`。
`OTEL_PROFILING_PPROF_HEADERS`	逗号分隔的 `名称:值`	空	附加 HTTP 请求头。

Security¶

同一个 beacon-otel wheel 已包含需主动启用的 Security，支持标准 GIL 的 CPython 3.11 至 3.14。参阅 Python Security 指南。

验证接入¶

访问应用接口，产生经过受支持框架或依赖库的请求，再进入观测云「应用性能监测 > 链路」，按上文服务名筛选。完整检查步骤参见公共配置，无数据时参见故障排查。