python代码探针方案OpenTelemetry

简单介绍在 OpenTelemetry 中Metrics指标是用于量化系统行为和监控应用程序性能如 HTTP 响应时间、错误率、吞吐量等的重要信号。以下是关于如何使用 OpenTelemetry Metrics、核心包以及如何自定义采集并上传指标的完整指南opentelemetry也可以做链路采集一、 核心包与组件要在 Python 环境中使用 OpenTelemetry Metrics你需要依赖以下核心组件OpenTelemetry API (opentelemetry-api)提供定义和记录指标的接口如 Meter、Instruments。OpenTelemetry SDK (opentelemetry-sdk)负责在内存中聚合原始测量数据并按照固定间隔如每 60 秒触发导出。导出器Exporters负责将聚合后的指标数据发送到目标后端。例如opentelemetry-exporter-otlp通过 OTLP 协议发送或opentelemetry-exporter-prometheus。二、 定义与采集指标的 3 个核心步骤在代码中手动采集指标通常遵循以下标准流程1. 获取 Meter仪表从MeterProvider中获取一个Meter它是创建和管理指标的主要入口。pythonfrom opentelemetry import metrics # 获取一个 Meter通常传入服务名称作为标识 meter metrics.get_meter(my_service_meter)2. 创建 Instruments度量仪器根据业务需求选择合适的仪器类型。OpenTelemetry 支持多种类型Counter计数器用于只增不减的值如请求总数、错误数。Gauge仪表盘用于可增可减的当前状态值如当前活跃连接数、CPU 使用率。Histogram直方图用于记录值的分布情况如请求耗时、响应体大小。python# 创建一个计数器 request_counter meter.create_counter( namehttp_requests_total, descriptionTotal number of HTTP requests, unit1 ) # 创建一个直方图 response_time_histogram meter.create_histogram( namehttp_response_duration, descriptionHTTP response duration, unitms )3. 记录测量值Record Measurements在业务逻辑中调用仪器记录数据并附带相关的属性Attributes/Labels以便后续进行多维度过滤和聚合。python# 记录一次请求 request_counter.add(1, {http.method: GET, http.status_code: 200}) # 记录响应耗时 response_time_histogram.record(150, {http.method: GET})三、 将指标上传到远端配置 Exporter在 SDK 初始化时你需要配置 Exporter 将数据推送到远端存储系统如 Prometheus、Jaeger 或商业监控平台。示例使用 OTLP 协议导出到远端 Collectorpythonfrom opentelemetry.sdk.metrics import MeterProvider from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter # 1. 配置导出器指定远端地址 exporter OTLPMetricExporter(endpointgrpc://your-collector-endpoint:4317, insecureTrue) # 2. 配置读取器设置导出间隔例如每 60 秒导出一次 reader PeriodicExportingMetricReader(exporter, export_interval_millis60000) # 3. 将 Reader 注入到 MeterProvider 中并设为全局默认 provider MeterProvider(metric_readers[reader]) metrics.set_meter_provider(provider)三种方案方式一命令行参数模式适合本地临时调试这种方式将配置直接写在启动命令中适合快速验证连通性。基础pip install opentelemetry-distro \ opentelemetry-exporter-otlp opentelemetry-bootstrap -a install pip install opentelemetry-propagator-b3 pip install opentelemetry-processor-baggage上报依赖包有多种比如redis-----opentelemetry-instrumentation-redisfastapi----opentelemetry-instrumentation-fastapi等1. 使用 gRPC 协议启动bashopentelemetry-instrument \ --traces_exporter otlp \ --metrics_exporter otlp \ --logs_exporter none \ --exporter_otlp_protocol grpc \ --exporter_otlp_endpoint http://localhost:4317 \ --exporter_otlp_insecure true \ --resource_attributes service.namemy-python-app \ python manage.py2. 使用 HTTP 协议启动bashopentelemetry-instrument \ --traces_exporter otlp \ --metrics_exporter otlp \ --logs_exporter none \ --exporter_otlp_protocol http/protobuf \ --exporter_otlp_endpoint http://localhost:4318 \ --resource_attributes service.namemy-python-app \ python manage.py方式二环境变量模式生产环境推荐将参数转换为环境变量启动命令保持极简。1. 使用 gRPC 协议的环境变量配置bashexport OTEL_SERVICE_NAMEmy-python-app export OTEL_TRACES_EXPORTERotlp export OTEL_METRICS_EXPORTERotlp export OTEL_LOGS_EXPORTERnone export OTEL_EXPORTER_OTLP_PROTOCOLgrpc export OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317 export OTEL_EXPORTER_OTLP_INSECUREtrue2. 使用 HTTP 协议的环境变量配置bashexport OTEL_SERVICE_NAMEmy-python-app export OTEL_TRACES_EXPORTERotlp export OTEL_METRICS_EXPORTERotlp export OTEL_LOGS_EXPORTERnone export OTEL_EXPORTER_OTLP_PROTOCOLhttp/protobuf export OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4318启动命令两者通用bashopentelemetry-instrument python manage.py方式三自定义业务指标监控代码级实战如果您需要监控核心业务如订单量、处理耗时需要在代码中手动埋点。1. 确保安装核心依赖bashpip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp2. 完整可执行的业务监控代码将以下代码放入您的业务模块如metrics.py或直接在manage.py中pythonimport time from opentelemetry import metrics # 1. 获取 Meter全局唯一应用启动时初始化一次即可 meter metrics.get_meter(order-service-meter) # 2. 定义业务指标⚠️ 必须在模块级别定义严禁在循环/请求中重复创建 # 订单创建总数Counter只增不减 order_counter meter.create_counter( nameorders.created.total, descriptionTotal number of created orders, unit1 ) # 订单处理耗时Histogram用于统计 P90/P95 延迟 order_duration meter.create_histogram( nameorders.processing.duration, descriptionTime taken to process an order, unitms ) # 当前正在处理的订单数UpDownCounter可增可减 active_orders meter.create_up_down_counter( nameorders.active.current, descriptionCurrent number of active orders ) # 3. 业务逻辑埋点示例 def create_order(order_type: str, user_id: str): 模拟一个真实的订单创建业务函数 # 活跃订单数 1 active_orders.add(1, {order_type: order_type}) try: start_time time.time() # 您的真实业务逻辑 print(fProcessing order for user: {user_id}) time.sleep(0.05) # 模拟 50ms 的业务耗时 # duration (time.time() - start_time) * 1000 # 记录成功订单 order_counter.add(1, { order_type: order_type, status: success }) # 记录耗时 order_duration.record(duration, {order_type: order_type}) except Exception as e: # 记录失败订单 order_counter.add(1, { order_type: order_type, status: failed, error_type: type(e).__name__ }) finally: # 无论成功失败活跃订单数 -1 active_orders.add(-1, {order_type: order_type}) 核心避坑指南必读HTTP 协议的 Endpoint 格式使用 HTTP 协议时OTEL_EXPORTER_OTLP_ENDPOINT只需写到主机和端口如http://localhost:4318SDK 会自动拼接/v1/traces或/v1/metrics路径。千万不要在环境变量里手动加上/v1/traces否则会导致 404 错误。指标复用原则create_counter等创建方法非常轻量但绝对不能在每次请求时调用。必须在代码外层定义一次然后在业务方法中只调用.add()或.record()。自动与手动结合生产环境的最佳实践是方式二环境变量零代码启动 方式三核心业务手动插桩。框架层的 HTTP 耗时交给自动插桩核心业务转化率交给手动插桩。您可以直接复制上述代码和命令进行本地测试。如果在执行过程中遇到 Collector 连不上的问题可以先检查 4317/4318 端口是否开放