奇链 奇链
← 文章 / 编程开发
signoz 5小时前 · 2026-09-23 10:34:47 · 0 阅读

Python OpenTelemetry 自动插桩指南

本指南介绍如何用 OpenTelemetry 对你的 Python 应用进行埋点，并把链路数据发送到 SigNoz。自动埋点方式开箱即用，支持 Django、Flask、FastAPI、Falcon、Celery 以及大多数 Python 库。

使用自托管版 SigNoz？

大部分步骤相同。只需按 Cloud → Self-Hosted 的说明修改 endpoint 地址，并去掉 ingestion key 请求头。

前置条件

本文已在 Python 3.11 和 OpenTelemetry Python SDK v1.27.0 上测试通过。

发送链路数据到 SigNoz

VMKubernetesWindowsDocker什么算 VM？

VM 是运行在物理硬件上的虚拟计算机，包括：

  • 云 VM：AWS EC2、Google Compute Engine、Azure VMs、DigitalOcean Droplets
  • 本地 VM：VMware、VirtualBox、Hyper-V、KVM
  • 裸金属服务器：直接运行 Linux/Unix 的物理服务器

如果你是把 Python 应用直接部署在服务器或 VM 上、不使用容器，请按本节操作。

第 1 步：设置环境变量

复制
export OTEL_RESOURCE_ATTRIBUTES="service.name=<service-name>,service.version=<service-version>"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_METRICS_EXPORTER="none"
为什么要显式禁用 metrics？

bootstrap 命令（第 3 步）会为所有检测到的库安装 instrumentation，包括 requests、urllib3、httpx 等 HTTP 客户端。这些库会为每次发出的 HTTP 调用生成请求耗时直方图等指标，还可以选择性地记录请求/响应体大小。

由于 opentelemetry-distro 默认启用指标采集，即使本指南仅涵盖 trace 配置，这些 HTTP 指标仍会被发送到 SigNoz。对于频繁发起 HTTP 请求的应用，数据量可能会迅速增长。

将其设置为 none 可以关闭指标采集，同时保持 trace 功能正常运行。如果稍后需要指标功能，可以将其改为 otlp 或直接移除该变量。

请确认以下参数：

  • <region>：你的 SigNoz Cloud 区域
  • <your-ingestion-key>：你的 SigNoz 摄入密钥
  • <service-name>：服务的描述性名称（例如 payment-service）
  • <service-version>（可选）：发布版本号、镜像 tag 或 git SHA（例如 1.4.2、a01dbef8）
推荐做法：为部署标记设置 service.version

将 service.version 设为每次构建动态生成的值，而非固定字符串。SigNoz 会在该值发生变化时自动检测新的部署事件。常见的取值来源：

  • Bash / shell：service.version=$(git rev-parse --short HEAD)
  • GitHub Actions：service.version=${{ github.sha }}
  • GitLab CI：service.version=$CI_COMMIT_SHORT_SHA
  • Kubernetes：从 Helm chart 镜像 tag 或 CI 变量中注入

步骤 2. 安装 OpenTelemetry 包

复制
pip install opentelemetry-distro opentelemetry-exporter-otlp

步骤 3. 安装依赖项的 instrumentation

该命令会自动检测已安装的依赖包，并添加对应的 instrumentation 库：

复制
opentelemetry-bootstrap --action=install
提示

请在安装完所有应用依赖项后运行此命令，它只会为已安装的包添加 instrumentation。

步骤 4. 运行应用程序

复制
opentelemetry-instrument <your_run_command>

如需特定框架的指令，请参阅下方框架 instrumentation部分。

DirectOTel Operator管理多个服务？

如需集中管理 instrumentation 或无代码变更的自动注入，请参阅 OTel Operator 选项卡。

第 1 步：设置环境变量

在部署清单中添加以下环境变量：

Copy 
env:
- name: OTEL_RESOURCE_ATTRIBUTES
  value: 'service.name=<service-name>,service.version=<service-version>'
- name: OTEL_EXPORTER_OTLP_ENDPOINT
  value: 'https://ingest.<region>.signoz.cloud:443'
- name: OTEL_EXPORTER_OTLP_HEADERS
  value: 'signoz-ingestion-key=<your-ingestion-key>'
- name: OTEL_EXPORTER_OTLP_PROTOCOL
  value: 'http/protobuf'
- name: OTEL_METRICS_EXPORTER
  value: 'none'
为什么要显式禁用 metrics？

bootstrap 命令（第 3 步）会为所有检测到的库安装 instrumentation，包括 requests、urllib3 和 httpx 等 HTTP 客户端。这些库会为每次外发的 HTTP 调用生成诸如请求时长直方图，以及可选的请求/响应体大小等 metrics。

由于 opentelemetry-distro 默认启用 metrics，即使本指南仅涵盖 traces，这些 HTTP metrics 仍会被发送到 SigNoz。对于高频发起 HTTP 调用的应用而言，数据量会迅速增长。

将其设置为 none 可在保持 traces 正常工作的同时禁用 metrics。若后续需要 metrics，可将其改为 otlp，或直接移除该变量。

请核对以下变量值：

  • <region>：你的 SigNoz Cloud 区域（SigNoz Cloud region）。
  • <your-ingestion-key>：你的 SigNoz 摄入密钥（ingestion key）。
  • <service-name>：服务描述性名称（例如 payment-service）。
  • <service-version>（可选）：发行版本、镜像标签或 Git SHA（例如 1.4.2、a01dbef8）。
建议：为部署标记设置 service.version

将 service.version 设为每次构建独有的值，而非静态字符串。SigNoz 会在该值每次变更时检测一次部署。常用取值来源：

  • Bash / shell：service.version=$(git rev-parse --short HEAD)
  • GitHub Actions：service.version=${{ github.sha }}
  • GitLab CI：service.version=$CI_COMMIT_SHORT_SHA
  • Kubernetes：从 Helm chart 的镜像标签或 CI 变量中注入

    • 第 2 步：安装 OpenTelemetry 包

    Copy
    pip install opentelemetry-distro opentelemetry-exporter-otlp

    第 3 步：为你的依赖安装插桩

    这条命令会检测已安装的包，并自动添加对应的插桩库：

    Copy
    opentelemetry-bootstrap --action=install
    Info

    请在安装完应用的所有依赖之后运行这条命令，它只会为已经安装的包添加插桩。

    第 4 步：运行你的应用

    Copy
    opentelemetry-instrument <your_run_command>

    各框架的具体启动命令参见下文框架插桩部分。

    OpenTelemetry Operator 可以自动向 Python Pod 注入插桩，无需修改应用镜像。

    第 1 步：部署 OpenTelemetry Operator

    按照 K8s OTel Operator 安装指南安装 Operator 和 Collector。

    第 2 步：创建 Instrumentation 资源

    创建 instrumentation.yaml 来配置 Python 自动插桩：

    instrumentation.yaml
    apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: python-instrumentation
spec:
  exporter:
    endpoint: http://otel-collector-collector:4318
  propagators:
    - tracecontext
    - baggage
  env:
    - name: OTEL_METRICS_EXPORTER
      value: "none"
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: "service.version=<service-version>"
  python:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-python:latest
    为什么要显式禁用 metrics？

    OTel Operator 的 Python 自动插桩镜像包含对 requests、urllib3、httpx 等 HTTP 客户端的插桩。这些库会为每次发出的 HTTP 调用生成指标，比如请求耗时直方图。

    由于 metrics 默认开启，即使本指南只涉及 traces，这些 HTTP 指标也会被发送到你的 Collector。对于频繁发起 HTTP 调用的应用来说，这部分开销会迅速累积。

    将 OTEL_METRICS_EXPORTER 设为 none 即可禁用指标上报，同时保持链路追踪正常运行。若后续需要启用指标，可将其更改为 otlp，或直接移除该环境变量。

    将此资源部署到你的集群中。

    步骤 3：为 Deployment 添加注解

    在 Pod 模板的 metadata.annotations 中添加以下注解：

    Copy
    instrumentation.opentelemetry.io/inject-python: "true"
instrumentation.opentelemetry.io/otel-python-platform: "glibc"  # 或使用 "musl"（Alpine）

    请将 instrumentation.yaml 中的 <service-version> 替换为实际的服务版本标识，如发布版本号、镜像 tag 或 Git SHA（例如 1.4.2、a01dbef8）。

    建议：为 Deployment 标记设置 service.version

    将 service.version 设置为每次构建产生的动态值，而非固定字符串。每当该值发生变化，SigNoz 都会检测并标记一次新的部署。常见取值来源：

    • Bash / Shell：service.version=$(git rev-parse --short HEAD)
    • GitHub Actions：service.version=${{ github.sha }}
    • GitLab CI：service.version=$CI_COMMIT_SHORT_SHA
    • Kubernetes：从 Helm Chart 的镜像 tag 或 CI 变量中注入

    步骤 1：设置环境变量

    Copy
    $env:OTEL_RESOURCE_ATTRIBUTES = "service.name=<service-name>,service.version=<service-version>"
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://ingest.<region>.signoz.cloud:443"
$env:OTEL_EXPORTER_OTLP_HEADERS = "signoz-ingestion-key=<your-ingestion-key>"
$env:OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf"
$env:OTEL_METRICS_EXPORTER = "none"
    为什么要显式禁用指标？

    引导命令（步骤 3）会为所有检测到的库安装探针，包括 requests、urllib3 和 httpx 等 HTTP 客户端。这些库会为每次外发 HTTP 请求生成指标，例如请求时长直方图，并可选择记录请求/响应体大小。

    由于 opentelemetry-distro 默认开启指标功能，这些 HTTP 指标将被 s

    原始来源： signoz

    评论 (0)