外观
32 - P99升高该先看哪里:用日志、指标与OpenTelemetry追踪定位慢请求
摘要
请求变慢,CPU与数据库平均耗时却正常。本文用真实OpenTelemetry SDK关联日志、指标与父子span,帮助后端开发者定位耗时阶段、验证候选原因,并避开高基数指标的坑。
已实测:CPython 3.13.7、OpenTelemetry API/SDK 1.45.1、SQLite 3.50.4。本实验是本进程请求处理函数、真实SQLite查询与SDK内存导出器,不是完整HTTP服务或OTLP后端。更多结果见工程实践与验收手册。跨进程传播、生产采样、Collector和监控后端待验证。
1. 场景:平均值正常,慢请求仍然存在
教学服务处理三次查询:一次正常、一次在SQLite用户函数中引入明确的短延迟、一次查询不存在的表。只打印“请求完成”看不到慢在哪里;只统计成功数看不到数据库错误;只记录SQL平均时长又不能定位单次请求。我们需要三个观测视角各自回答不同问题,再用稳定关联字段把它们接起来。
log(日志)保存具体事件及上下文,适合还原某次失败;metric(指标)按稳定维度聚合数量或分布,适合发现趋势;trace(追踪)连接同一操作里的阶段,适合查看一次请求的调用关系。它们有交集,但并非随便选择一种就覆盖所有证据。 可进一步阅读OpenTelemetry与链路追踪:分布式追踪解释跨进程上下文传播。
P99表示统计分布中约99%的观测不超过该值,不是最慢一次,也不是每个窗口一定有足够样本支撑稳定估计。三个请求只能做关联功能演示,不能据此计算具有生产解释力的P99。本篇标题里的慢请求问题需要在真实流量和明确窗口下评估,示例先证明数据能正确关联。
把诊断顺序固定为“聚合发现、关系缩小、事件核对、进一步反证”。指标先给出哪类请求受影响,trace沿同一操作的父子关系缩小阶段,日志解释该阶段发生了什么,最后仍要用资源与执行证据区分根因。第23篇线上分诊的候选判断在这里得到可关联的数据,不能让任何一种观测直接跳到根因。
先预测三个请求会留下什么:正常与延迟请求都是200,不存在表请求是500;每个请求各有root与database子span,而不是六次独立请求。随机ID不必提前知道,关系与数量必须能预测。下面就用这些结构断言,避免把打印很多字段当成可观测性已经成立。
2. span与trace:关系比随机字符串重要
span(追踪片段)描述有开始、结束和属性的一段操作;trace是一组相关span组成的操作链。trace ID标识链,span ID标识具体片段,父span ID建立调用关系。示例每个 GET /counts 处理片段内部创建 database.query 子片段,二者共享trace ID,子片段的parent指向对应根片段。
SDK(Software Development Kit,开发工具包)实际记录span生命周期并交给processor(处理器)导出。示例采用 SimpleSpanProcessor 与 InMemorySpanExporter,立即将完成的片段保存内存,方便验收。它们是真实OpenTelemetry实现,但不证明OTLP(OpenTelemetry传输协议)后端、采样和网络重试已经配置正确。
业务代码拿 trace.get_current_span() 读取当前上下文,不手工拼一个随机字符串冒充追踪。若当前没有有效span,ID可能为零;因此日志应该在有效请求span内部产生。示例断言三个请求有三个不同trace ID,每个root恰好对应一个database子span。
request ID与trace ID仍是不同概念。前者可以由应用入口维护并用于用户支持;后者由追踪协议关联调用链。重试同一业务操作可能产生不同trace,却共享operation ID。把它们分开保存,才能回答“这次尝试在哪里慢”和“同一业务到底执行几次”。
跨服务传播通常采用如W3C Trace Context的协议,不能把HTTP入站trace ID当成可信业务身份。客户端可以提供上下文,服务端仍要做鉴权、长度验证和边界处理。当前脚本没有HTTP传播实验,这部分应标待验证,而不是将本进程父子关系扩展成跨机器端到端证明。
图表将在阅读到此处时加载…
图里的最后一步不可省略。追踪定位阶段,并不自动确定该阶段内部的物理原因。
3. ContextVar:异步上下文不是全局变量
ContextVar(上下文变量)让相关执行上下文保存自己的值,适合请求级关联字段。简单全局 request_id 在并发请求里会相互覆盖;线程局部变量也未必匹配同线程多个异步任务的隔离需求。示例每次请求set得到token,finally用reset恢复,避免下一个操作继承前一个请求ID。
这不表示ContextVar会自动传到任意进程、消息系统或所有第三方线程。asyncio.to_thread有其文档约定,其他执行器和库需要验证实际传播行为。跨进程任务应明确序列化必要关联字段,不能让“上下文”成为隐式依赖。
结构化日志以JSON字段输出request_id、trace_id、event和level,查询时不必从自由文本里猜标识位置。事件名保持稳定,例如 request.start、request.success 和 request.database_failed,参数和异常细节按敏感性控制。日志级别不是业务状态,错误事件应同时有可理解的阶段与错误分类。
禁止把令牌、密码、原始个人数据或完整SQL参数直接写入。脱敏也不应破坏关键关联:保留稳定非敏感操作标识,记录错误类别和阶段,必要时把详细敏感信息留在受控系统。示例不输出数据库原始异常内容,也不声称覆盖了所有脱敏需求。
日志handler本身可能失败或阻塞,生产环境应验证输出策略与缓冲行为。演示同步打印简单可读,不代表高吞吐服务应该在每个热路径同步导出大量记录。观测系统不应成为新的数据库连接持有原因。
4. 指标标签为什么不能放request_id
示例Counter(计数器)记录请求数,Histogram(直方图)记录持续时间,标签仅有固定路由 /counts 与状态 200/500。Counter总数为三,按状态分出成功与失败;Histogram保存对应时长分布信息。没有用每个请求ID建立独立标签组合。
cardinality(基数)指标签组合的数量。request ID、operation ID、用户ID和完整URL通常取值很多,每个值可能产生新时序,导致存储、索引和聚合开销增长。把“所有维度都能查”搬进指标标签,会让监控自身失去可用性。个体关联交给日志和trace,指标保存稳定聚合维度。
路由模板 /orders/{id} 通常比实际URL /orders/123 更适合作指标标签;错误码应分成有限分类,不能直接用任意异常字符串。tenant维度是否允许取决于数量与监控预算,不能一概宣称所有业务标签都禁止,只需明确数量增长和查询价值。
延迟单位显式为秒,span内部的时间戳和时长打印为纳秒,避免把0.02秒与20000000纳秒误当不同量级事实。SDK属性不是你的仪表盘配置,后端如何聚合、直方图边界如何配置、不同实例数据如何合并,都要按后端验证。
指标按窗口聚合时,要区分吞吐下降和延迟下降。过载系统可能拒绝大部分请求,仅剩少量快速成功,平均耗时变好却体验更差。应该同时观察进入数、拒绝数、完成数和成功率,相关准入行为参见后台队列。
5. 慢span说明了什么,没说明什么
第二次请求实际执行SQLite用户函数 training_delay(),函数主动短暂休眠。database子span包含这段同步SQL调用,因而成为受控慢候选。我们没有制造锁等待,没有服务器网络,也没有并发连接池;不能把它命名成“证实数据库锁等待”。
父span时长包括子span与其他代码;若多个子span并发,子时长之和可能超过父时长,不能简单相加归因。一个span覆盖很宽也会失去定位能力:数据库阶段若包括连接获取、SQL和结果消费,要拆分或记录更具体的事件,结合连接池篇查借出和持有。
最慢span只是该批样本的候选。支持数据库阶段慢的证据是时长集中在那里;反证可能是SQL本身快、主要耗时在获取连接,或者追踪中排队段更长。进一步查查询次数、计划、锁状态和资源持有后,才能缩小原因。不要从“名字叫database”直接推出加索引。
对同一个database.query阶段,比较延迟与失败两个变化。第二次调用training_delay,SQL内部主动等待,阶段变慢但业务仍成功;第三次查询不存在表,真实OperationalError进入子span,root标Error与500,日志记录request.database_failed。名称相同,状态关系却不同:慢不等于失败,失败也不要求最慢。
指标按200/500汇总,trace保留各自父子关系,日志以同trace ID补充成功或失败事件。这样才能同时看见慢成功和可能快速失败。示例的延迟是已知注入,支持关联功能与阶段测量;它没有锁图,不能借database名字证明锁等待或索引问题。
状态码、span status和日志level最好能形成一致解释,但并非所有4xx都意味着服务端内部错误,业务取消也需要分类。设计属性时先明确判断标准,再统一库和中间件行为,避免一个组件把用户输入错误标成系统故障,另一个组件只显示200。
6. 采样与缺失数据:没有trace不是没有请求
sampling(采样)决定哪些追踪被记录或导出,能控制观测开销,也会导致某些请求没有完整trace。head sampling(开始时采样)在看到结果前作决定;tail sampling(结束后采样)可以依据结果选择,但需要额外缓冲与系统能力。当前内存示例不是生产采样方案。
如果根据异常或慢请求后采样,查询到的trace不代表整体请求分布,不能直接计算整体错误率。指标是完整聚合还是也受限,日志是否丢失、导出队列是否满、SDK关闭是否flush,都会影响证据。对缺失记录的合理表述是“当前观测未找到”,不是“事件没有发生”。
示例finally关闭SQLite、移除自定义handler并shutdown两个provider,避免重复运行时handler累积或资源残留。批量处理器生产配置还需验证有界缓冲、导出超时、关闭预算和丢弃计数。观测关闭不能无限阻塞业务进程,业务任务也不能因为日志发送失败全部停止。
追踪数据保存时间与访问权限应结合隐私和排障窗口设计。高价值详细样本可以受控保留,低价值重复事件可以聚合,不能以“可观测性需要”为由永久保存全部业务内容。本篇只验证技术关联,不冒充完整安全审计。
7. 实战:验证关联,而不是看打印好不好看
完整独立文件32_observability.py使用OpenTelemetry SDK,安装版本按工程环境锁文件;运行前记录实际API/SDK版本,二者兼容性需要保证。
powershell
python -m pip install opentelemetry-api==1.45.1 opentelemetry-sdk==1.45.1
python docs/python/examples/32_observability.py预期有六个完成span,三个请求root、三个database子span;六条JSON日志,同一请求两条共享request_id与trace_id;Counter点值总计三,标签不含request_id。trace IDs由SDK生成,每次不同,不把随机值写成固定预期。
示例打印最慢database候选及纳秒时长。时长受调度影响,不比较固定倍数,也不声称这三次运行代表生产P99。结构断言检查父子关系、关联数量和指标总数,是比肉眼看字符串更稳定的验收。
独立任务一:加入 queue.wait 与 work.execute 两个阶段,通过真实有界Queue让排队等待发生,检查父子关系而不是凭名字推测。任务二:给失败请求额外结构化字段,证明没有使用异常自由文本作为指标标签。任务三:在日志产生前后检查ContextVar重置,保证后续无请求操作不会继承上一次标识。
任务四:为慢请求列一项支持证据和一项尚未排除的原因,补充相应测量。验收允许结论为“只能定位到数据库阶段,不能区分内部锁/执行/消费”,诚实的范围比没有依据的确定归因更有工程价值。
8. 排障推演与容易踩的坑
面对P99上升,先确认路由、状态、时间窗口、样本量和部署变化,再筛对应trace。若入口到工作开始变长,查队列和线程池;若连接获取变长,查池借出与持有;若查询次数随结果规模增长,查N+1;若单次SQL阶段变长,再查目标库计划、锁与数据分布。
修复后使用同范围比较延迟、错误和资源占用,不能只找到一条变快trace就宣布恢复。采样策略或流量结构变化也能让观察“变好”,必须记录这些条件。回到性能测量的同输入与同边界原则,才能评估改动是否解决实际瓶颈。
容易踩的坑是request_id写成全局变量导致串请求、指标使用高基数字段、span只包住异步任务创建而没有包住实际执行、把客户端取消标成事务回滚、把内存导出成功写成OTLP上线成功。每个坑都有具体边界,修复后必须用状态断言或目标环境实验确认。
面试问三种观测为何都需要,回答聚合发现、阶段定位和事件还原。问trace能否证明根因,回答它缩小候选,还需反证与更细测量。问如何控制开销,讨论稳定标签、采样、批量导出、容量和关闭期限,并说明丢弃数据的可见性。
从一次慢请求走到可重复的验证
从database慢迁移到queue慢,先保持请求、结果与关联规则不变,只把额外等待放在有界队列领取之前。预测长时间应落入queue.wait,而不是work.execute;只有把span围绕真实等待与执行建立,追踪才能检验这个预测。若只是给原span换名,状态边界没有变化,仍无法区分候选。
继续检验数据库内部候选时复用同一原则:保持SQL与输入,只改连接持有时间看checkout等待;保持数据与结果,只改加载策略看SELECT次数。指标用于确认影响范围,trace用于找阶段,池与查询事件用于反证。三层变化一起改后看到一条快trace,不能知道哪个原因成立。
时间窗口必须对齐。应用指标是某一分钟,数据库慢日志却来自上一小时,二者即便都出现异常也不能直接归因。先对齐请求时间、部署版本、实例与业务范围,再按trace标识关联事件。分布式时钟差异还会影响跨机器事件顺序,使用父子关系与本机持续时间解释时序,比只按墙钟排序可靠。
指标总数与日志条数也未必天然相等。一个请求可能多条日志,采样或过滤可能删除记录,重试可能建立多次HTTP尝试;只有先明确计数对象,差异才可解释。示例断言每个请求两条日志属于受控功能验收,不把这条比例推广到真实服务。
上线验证应包括观测系统故障:导出端不可用、缓冲满、关闭超时,业务是否仍按预算运行,丢弃量是否可见。当前内存导出器不会测试网络不可用,因此相关检查必须进入目标环境验收清单,不能由六个span成功导出代替。
9. 结尾
可观测性把请求、阶段和结果关联起来,而根因结论仍需支持证据与反证共同约束。
- 指标发现聚合变化,trace定位阶段,日志补充具体事件。
- request_id与trace_id做关联,低基数字段做指标标签。
- 明确采样、导出和实验边界,慢span是候选证据而非自动根因。
参考与完整代码
- OpenTelemetry Python instrumentation
- OpenTelemetry Python SDK Trace
- OpenTelemetry Python SDK Metrics
- Python ContextVar
python
"""真实 OpenTelemetry SDK,内存导出器;未验证 OTLP 后端。"""
from contextvars import ContextVar
import json
import logging
import sqlite3
import time
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import InMemoryMetricReader
from opentelemetry.trace import Status, StatusCode
request_id = ContextVar("request_id", default="-")
class JsonHandler(logging.Handler):
def __init__(self):
super().__init__()
self.records = []
def emit(self, record):
context = trace.get_current_span().get_span_context()
entry = {"request_id": request_id.get(), "trace_id": format(context.trace_id, "032x"),
"event": record.getMessage(), "level": record.levelname}
self.records.append(entry)
print(json.dumps(entry, sort_keys=True))
def main():
exporter = InMemorySpanExporter()
traces = TracerProvider()
traces.add_span_processor(SimpleSpanProcessor(exporter))
tracer = traces.get_tracer("series.observability")
reader = InMemoryMetricReader()
meters = MeterProvider(metric_readers=[reader])
meter = meters.get_meter("series.observability")
requests = meter.create_counter("requests", unit="1")
latency = meter.create_histogram("request.duration", unit="s")
handler = JsonHandler()
logger = logging.getLogger("series.observability")
logger.setLevel(logging.INFO)
logger.propagate = False
logger.addHandler(handler)
connection = sqlite3.connect(":memory:", autocommit=True)
connection.execute("CREATE TABLE events(id INTEGER PRIMARY KEY)")
connection.execute("INSERT INTO events VALUES(1)")
# 教学注入:SQLite 用户函数休眠,不把它称为真实锁等待。
connection.create_function("training_delay", 0, lambda: time.sleep(0.02) or 1)
try:
for number in range(3):
token = request_id.set(f"request-{number}")
start = time.monotonic()
status = "200"
try:
with tracer.start_as_current_span("GET /counts") as root:
root.set_attribute("http.route", "/counts")
logger.info("request.start")
try:
with tracer.start_as_current_span("database.query") as database:
database.set_attribute("db.system.name", "sqlite")
if number == 1:
connection.execute("SELECT training_delay() FROM events").fetchall()
elif number == 2:
connection.execute("SELECT * FROM missing_table").fetchall()
else:
connection.execute("SELECT * FROM events").fetchall()
logger.info("request.success")
except sqlite3.OperationalError:
status = "500"
root.set_status(Status(StatusCode.ERROR, "database operation failed"))
logger.error("request.database_failed")
root.set_attribute("http.response.status_code", int(status))
finally:
attributes = {"http.route": "/counts", "status": status}
requests.add(1, attributes)
latency.record(time.monotonic() - start, attributes)
request_id.reset(token)
spans = exporter.get_finished_spans()
roots = [span for span in spans if span.name == "GET /counts"]
children = [span for span in spans if span.name == "database.query"]
assert len(roots) == len(children) == 3
for root in roots:
child = next(span for span in children if span.context.trace_id == root.context.trace_id)
assert child.parent.span_id == root.context.span_id
related = [entry for entry in handler.records if entry["trace_id"] == format(root.context.trace_id, "032x")]
assert len(related) == 2
assert related[0]["request_id"] == related[1]["request_id"]
assert len({entry["trace_id"] for entry in handler.records}) == 3
data = reader.get_metrics_data()
points = [point for resource in data.resource_metrics for scope in resource.scope_metrics
for metric in scope.metrics if metric.name == "requests" for point in metric.data.data_points]
assert sum(point.value for point in points) == 3
assert all("request_id" not in point.attributes for point in points)
slow = max(children, key=lambda span: span.end_time - span.start_time)
assert slow.status.status_code != StatusCode.ERROR
print("spans:", len(spans), "requests:", sum(point.value for point in points))
print("slow candidate:", slow.name, "duration ns:", slow.end_time - slow.start_time)
finally:
connection.close()
logger.removeHandler(handler)
traces.shutdown()
meters.shutdown()
if __name__ == "__main__":
main()