零侵入实现分布式追踪：Requests + OpenTelemetry实战指南
项目地址: https://gitcode.com/GitHub_Trending/re/requests 你是否在排查分布式系统问题时，面对无数微服务调用日志无从下手？是否想追踪一个API请求从发出到响应的完整链路？本文将带你使用Requests的钩子（Hook）机制结合OpenTelemetry，零侵入实现HTTP请求的全链路追踪，让每个请求都可追踪、可分析。读完本文你将掌握：
- Requests钩子机制的实战应用
- OpenTelemetry追踪上下文的注入与提取
- 零代码侵入实现分布式追踪的完整方案
- 生产环境中的最佳实践与性能优化
为什么需要分布式追踪
在微服务架构中，一个用户请求往往需要经过多个服务协同处理。传统的日志系统难以将这些跨服务的请求关联起来，当出现问题时，定位根源如同大海捞针。分布式追踪（Distributed Tracing）通过在请求间传递唯一标识符（Trace ID），将分散的日志串联成完整链路，帮助开发者快速定位问题。
OpenTelemetry是CNCF托管的开源项目，提供了一套统一的可观测性解决方案，包括分布式追踪、指标和日志。它通过上下文传播（Context Propagation）在服务间传递追踪信息，而Requests作为Python最流行的HTTP库，其灵活的钩子机制为实现零侵入追踪提供了可能。
Requests钩子机制解析
Requests库的钩子机制允许我们在请求生命周期的特定阶段插入自定义逻辑。通过分析src/requests/hooks.py源码，我们发现目前支持的钩子类型主要是response，即在获取响应后触发。
# src/requests/hooks.py 核心代码
HOOKS = ["response"]
def default_hooks():
return {event: [] for event in HOOKS}
def dispatch_hook(key, hooks, hook_data, **kwargs):
"""Dispatches a hook dictionary on a given piece of data."""
hooks = hooks or {}
hooks = hooks.get(key)
if hooks:
if hasattr(hooks, "__call__"):
hooks = [hooks]
for hook in hooks:
_hook_data = hook(hook_data, **kwargs)
if _hook_data is not None:
hook_data = _hook_data
return hook_data
钩子函数接收响应对象作为参数，并可以对其进行修改后返回。这一特性使得我们可以在不修改Requests源码的情况下，为所有HTTP请求添加追踪逻辑。
OpenTelemetry快速上手
OpenTelemetry由API、SDK和收集器（Collector）三部分组成。API定义了一套标准接口，SDK提供了具体实现，收集器负责接收、处理和导出追踪数据。要实现Requests的分布式追踪，我们需要使用OpenTelemetry的trace模块和propagate模块。
首先安装必要的依赖：
pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-b3
基本的追踪流程如下：
- 创建TracerProvider并配置导出器
- 获取Tracer对象
- 创建Span并设置为当前上下文
- 使用Propagator将上下文注入HTTP请求头
- 在响应返回后结束Span
零侵入实现方案
1. 编写追踪钩子函数
我们通过response钩子在请求完成后添加追踪信息。钩子函数需要完成以下工作：
- 从响应对象中提取请求上下文
- 创建或恢复Span
- 记录请求/响应信息
- 设置Span状态和属性
from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode
from opentelemetry.propagate import inject, extract
from opentelemetry.context import attach, detach
def trace_hook(response, **kwargs):
# 从响应中获取请求对象
request = response.request
# 提取上下文（如果有）
context = extract(request.headers)
token = attach(context)
try:
# 创建或获取Span
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span(
f"{request.method} {request.url}",
context=context,
kind=trace.SpanKind.CLIENT,
) as span:
# 设置Span属性
span.set_attribute("http.method", request.method)
span.set_attribute("http.url", request.url)
span.set_attribute("http.status_code", response.status_code)
# 设置Span状态
if response.status_code >= 400:
span.set_status(Status(StatusCode.ERROR))
span.set_attribute("error", True)
span.set_attribute("error.message", response.reason)
# 记录响应时间
duration = (response.elapsed.total_seconds() * 1000) # 转换为毫秒
span.set_attribute("http.duration_ms", duration)
finally:
detach(token)
return response
2. 全局注册钩子
通过分析src/requests/sessions.py，我们发现Session对象的hooks属性可以全局注册钩子。因此，我们可以创建一个带有追踪钩子的Session基类：
import requests
from requests.sessions import Session
class TracedSession(Session):
def __init__(self):
super().__init__()
# 注册追踪钩子
self.hooks["response"].append(trace_hook)
# 使用示例
session = TracedSession()
response = session.get("https://httpbin.org/get")
对于不使用Session的场景，我们可以通过猴子补丁（Monkey Patch）的方式全局注册钩子，但这种方式可能会影响所有Requests调用，建议谨慎使用：
import requests
from requests.api import request
def traced_request(method, url, **kwargs):
# 添加钩子参数
kwargs.setdefault("hooks", {}).setdefault("response", []).append(trace_hook)
return request(method, url, **kwargs)
# 替换requests.request
requests.request = traced_request
3. 上下文传播实现
为了实现跨服务追踪，我们需要在请求头中注入追踪上下文。OpenTelemetry提供了多种传播器（Propagator），这里我们使用B3传播器，它是Zipkin推荐的格式。
from opentelemetry.propagate import inject
from opentelemetry.propagators.b3 import B3MultiFormat
def inject_trace_context(request, **kwargs):
# 设置B3传播器
propagator = B3MultiFormat()
# 创建当前上下文
context = trace.get_current_span().get_span_context()
# 注入请求头
inject(request.headers, propagator=propagator, context=context)
return request
# 将上下文注入钩子添加到请求前
# 注意：Requests没有request钩子，需要通过PreparedRequest实现
由于Requests没有提供request阶段的钩子，我们需要通过PreparedRequest来实现请求前的上下文注入：
from requests import Request, Session
def traced_prepare_request(req, session):
# 注入追踪上下文
inject_trace_context(req)
return session.prepare_request(req)
# 使用示例
s = Session()
req = Request('GET', 'https://httpbin.org/get')
prepped = traced_prepare_request(req, s)
resp = s.send(prepped)
完整代码实现
结合以上分析，我们可以构建一个完整的Requests追踪工具：
# requests_tracing.py
import time
from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode
from opentelemetry.propagate import inject
from opentelemetry.propagators.b3 import B3MultiFormat
from opentelemetry.context import attach, detach
from requests.sessions import Session
# 初始化OpenTelemetry
def init_telemetry(service_name="requests-tracing"):
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-collector:4317"))
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# 设置B3传播器
from opentelemetry.propagate import set_global_textmap
set_global_textmap(B3MultiFormat())
class TracedSession(Session):
def __init__(self):
super().__init__()
self.hooks["response"].append(self._trace_hook)
def prepare_request(self, request):
# 注入追踪上下文
inject(request.headers)
return super().prepare_request(request)
def _trace_hook(self, response, **kwargs):
# 提取上下文
context = trace.get_current_span().get_span_context()
token = attach(context)
try:
tracer = trace.get_tracer(__name__)
span_name = f"{response.request.method} {response.url.split('?')[0]}"
# 从请求头提取上下文
carrier = response.request.headers
ctx = trace.get_current_span().get_span_context()
with tracer.start_as_current_span(
span_name,
context=ctx,
kind=trace.SpanKind.CLIENT,
) as span:
# 设置HTTP属性
span.set_attribute("http.method", response.request.method)
span.set_attribute("http.url", response.url)
span.set_attribute("http.status_code", response.status_code)
span.set_attribute("http.user_agent", response.request.headers.get("User-Agent", ""))
# 设置状态
if response.status_code >= 400:
span.set_status(Status(StatusCode.ERROR))
span.set_attribute("error", True)
span.set_attribute("error.message", response.reason)
# 记录响应时间
duration = response.elapsed.total_seconds() * 1000 # 毫秒
span.set_attribute("http.duration_ms", duration)
finally:
detach(token)
return response
使用方法：
# 初始化追踪
init_telemetry("my-service")
# 创建追踪会话
s = TracedSession()
# 发送请求
response = s.get("https://httpbin.org/get")
print(f"Response: {response.status_code}")
测试与验证
为了验证追踪效果，我们可以使用OpenTelemetry提供的控制台导出器：
from opentelemetry.sdk.trace.export import ConsoleSpanExporter
def init_telemetry(service_name="requests-tracing"):
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
provider = TracerProvider()
# 添加控制台导出器
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
发送请求后，我们可以在控制台看到类似以下的追踪输出：
{
"name": "GET https://httpbin.org/get",
"context": {
"trace_id": "0x5f8d7a3e9b5c8d1a",
"span_id": "0x7b3f9d2c4e6a8b0d",
"trace_state": "{}"
},
"kind": "SPAN_KIND_CLIENT",
"parent_id": null,
"start_time": "2023-11-15T08:30:45.123456Z",
"end_time": "2023-11-15T08:30:45.654321Z",
"status": {
"status_code": "STATUS_CODE_OK"
},
"attributes": {
"http.method": "GET",
"http.url": "https://httpbin.org/get",
"http.status_code": 200,
"http.duration_ms": 530.865
},
"events": [],
"links": []
}
生产环境最佳实践
1. 性能优化
- 采样策略：在高流量场景下，全量采样会产生大量数据，建议使用概率采样：
from opentelemetry.sdk.trace import Sampler, TracerProvider
from opentelemetry.sdk.trace.sampling import ProbabilitySampler
provider = TracerProvider(sampler=ProbabilitySampler(0.1)) # 10%采样率
- 异步导出：使用BatchSpanProcessor代替SimpleSpanProcessor，减少IO阻塞
2. 错误处理
在钩子函数中添加异常处理，避免追踪逻辑影响主流程：
def _trace_hook(self, response, **kwargs):
try:
# 追踪逻辑
...
except Exception as e:
# 记录错误但不中断请求
print(f"Tracing error: {e}")
return response
3. 敏感信息过滤
避免在追踪数据中记录敏感信息：
# 过滤请求头
def sanitize_headers(headers):
sensitive_headers = ["Authorization", "Cookie", "Set-Cookie"]
return {k: v if k not in sensitive_headers else "***" for k, v in headers.items()}
总结与展望
本文详细介绍了如何利用Requests的钩子机制和OpenTelemetry实现零侵入的分布式追踪方案。通过这种方式，我们可以在不修改业务代码的情况下，为所有HTTP请求添加追踪能力，极大提升了微服务架构的可观测性。
未来，我们可以进一步扩展这一方案：
- 支持更多的钩子事件（如异常处理）
- 集成指标收集，监控请求成功率和响应时间
- 实现分布式日志关联，将追踪ID注入日志系统
通过OpenTelemetry的标准化接口，我们可以轻松切换不同的后端存储和分析工具，如Jaeger、Zipkin、Prometheus等，为分布式系统的可观测性提供统一解决方案。
希望本文能帮助你更好地理解Requests的钩子机制和OpenTelemetry的追踪原理，在实际项目中落地分布式追踪，让你的微服务架构更加透明和可靠。如果你想深入了解Requests的高级用法，可以参考官方文档docs/user/advanced.rst。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
