AI 内容创作 / 系统课时

日志、指标与链路追踪

日志、指标与链路追踪

本课建立实时数字人的可观测性最小闭环:用结构化日志记录一次请求发生了什么,用指标观察阶段耗时与 GPU 资源趋势,再用统一 trace_id 串联 ASR、对话、TTS 和渲染阶段。完成后,故障定位将从猜测转为按证据还原调用链。

学习目标

  • 设计日志、指标与追踪共享的标识和字段。
  • 采集阶段耗时、请求结果与 NVIDIA GPU 快照。
  • 识别链路断裂、指标高基数和计时方式错误等问题。

可观测性数据模型

结构化日志记录事件,链路追踪还原阶段和父子关系,指标衡量总体分布。请求相关的日志可携带 trace_id 与 span_id。聚合指标的维度只选数量可控的服务、阶段、状态和发布版本。有 exemplar 支持时,可把少量观测值链接到对应 trace;无需为每个 trace 创建独立时间序列。OpenTelemetry 日志字段 · OpenTelemetry exemplar

同一进程内测量阶段和请求耗时使用单调时钟;UTC 墙上时间用于检索日志。跨进程传递追踪上下文,分段测量本地耗时。并行阶段的耗时可能重叠,分析总耗时应看关键路径和等待区间。日志使用受控的错误码,避免打印可能包含输入或凭据的异常文本。

数字人日志指标与链路追踪闭环

最小可运行采集器

把以下程序保存为 observability_demo.py。默认运行合成请求,结构化输出的每个父子阶段和根请求都由上下文管理器记录结束。单独用 --gpu 运行一次设备采样,部署时由独立采集器周期调用,使用设备 UUID 区分显卡。显存单位为 MiB。设备报告 N/A 时保留其他字段,缺失与 0 分开。NVIDIA nvidia-smi

python
import argparse
import csv
import json
import secrets
import subprocess
import time
from contextlib import contextmanager
from datetime import datetime, timezone


def emit(event, **fields):
    ts = datetime.now(timezone.utc).isoformat(timespec="milliseconds")
    print(json.dumps({"ts": ts, "event": event, **fields}, ensure_ascii=False))


@contextmanager
def span(trace_id, stage, parent=None):
    span_id = secrets.token_hex(8)
    fields = {"trace_id": trace_id, "span_id": span_id, "parent_span_id": parent, "stage": stage}
    started = time.perf_counter_ns()
    status = "ok"
    emit("span.start", **fields)
    try:
        yield span_id
    except BaseException:
        status = "error"
        raise
    finally:
        duration = (time.perf_counter_ns() - started) / 1_000_000
        emit("span.end", **fields, status=status, duration_ms=round(duration, 3))


def request(fail_stage=None):
    trace_id = secrets.token_hex(16)
    with span(trace_id, "request") as root:
        for stage in ("asr", "dialogue", "tts", "render"):
            with span(trace_id, stage, root):
                time.sleep(0.005)
                if stage == fail_stage:
                    raise RuntimeError("synthetic stage failure")


def read_gpu_snapshot():
    command = [
        "nvidia-smi", "--query-gpu=uuid,utilization.gpu,memory.used,memory.total",
        "--format=csv,noheader,nounits",
    ]
    try:
        result = subprocess.run(command, capture_output=True, text=True, check=True, timeout=2)
    except (OSError, subprocess.SubprocessError):
        return {"status": "unavailable", "devices": []}

    devices = []
    for row in csv.reader(result.stdout.splitlines(), skipinitialspace=True):
        if len(row) != 4:
            continue
        gpu, *raw = (cell.strip() for cell in row)
        if not gpu.startswith("GPU-"):
            continue
        values = [int(cell) if cell.isascii() and cell.isdecimal() else None for cell in raw]
        devices.append(dict(zip(("gpu", "utilization_pct", "used_mib", "total_mib"), [gpu, *values])))
    return {"status": "ok" if devices else "no_data", "devices": devices}


if __name__ == "__main__":
    cli = argparse.ArgumentParser()
    mode = cli.add_mutually_exclusive_group()
    mode.add_argument("--gpu", action="store_true")
    mode.add_argument("--fail-stage", choices=("asr", "dialogue", "tts", "render"))
    args = cli.parse_args()
    if args.gpu:
        emit("gpu.snapshot", **read_gpu_snapshot())
    else:
        try:
            request(args.fail_stage)
        except RuntimeError:
            raise SystemExit(1)
bash
python observability_demo.py
python observability_demo.py --fail-stage tts
python observability_demo.py --gpu

默认命令输出 10 行 JSON,根 span 包含 ASR、对话、TTS、渲染四个子 span,所有结束状态均为 ok。注入 TTS 故障时程序退出码为 1,TTS 和根 span 均以 error 结束,未进入渲染。独立 GPU 采样仅输出一行;驱动或命令不可用时状态为 unavailable。示例只输出日志,直方图与计数器需接入指标系统。

验证与告警边界

先用同一个 trace_id 检查已执行阶段是否完整,并按 span_id 配对开始和结束。跨 HTTP 服务使用 W3C traceparent:收到有效上下文后保留 trace ID,在本地创建 span,向下游传播时用当前调用的 span ID 作为父 ID。跨队列由发布者注入、消费者提取上下文;多个消息汇合时可用 span links 保留关联。示例没有实现 HTTP/队列传播,真实服务可用追踪 SDK 注入和提取。W3C Trace Context

指标验证应关注分布而不是单次值。阶段延迟通常用直方图计算 p50、p95 和 p99,请求结果用计数器统计成功、超时与取消,GPU 显存和利用率使用仪表值。告警需要同时设置持续窗口和最小请求量,避免一次冷启动触发误报。若时序库中出现大量只包含一个样本的序列,应立即检查是否把 trace_id、session_id 或原始错误文本误设为标签。

排障顺序应保持固定:先看失败率或 p95 告警,再打开对应 trace,随后查看最慢 span 的结构化日志,最后对照同一时间窗口的 GPU 与队列指标。这样可以区分模型推理变慢、显存不足、排队拥塞和下游超时,避免只凭某一条错误日志下结论。

本课总结

  • 日志和追踪用 trace/span 标识关联,聚合指标可通过 exemplar 连接个别观测。
  • 用单调时钟测量本地阶段,独立采集 GPU 指标并区分缺失值。
  • 按告警窗口选择 trace,将关键路径与同窗资源数据对照。

下一课预告

下一课将用结构化证据区分排队、媒体时间基准、显存峰值与模型制品故障。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

日志、指标与链路追踪

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通