import logging, json

# 配一个最简单的日志器：带时间、级别
logging.basicConfig(level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s")
log = logging.getLogger("agent")

# ❌ 新手写法：一句大白话，事后没法按字段搜
# print("用户问了问题，模型答完了")

# ✅ 结构化写法：把关键信息拼成 JSON，一条日志一个「事件」
log.info(json.dumps({
    "event": "llm_call",          # 事件类型：这次是「调用大模型」
    "user_id": "u_123",           # 谁触发的
    "model": "claude-3.5",        # 用了哪个模型
    "input_tokens": 820,          # 输入花了多少 token
    "output_tokens": 156,         # 输出多少 token
    "latency_ms": 1340,           # 耗时（毫秒）
    "ok": True                    # 成功还是失败
}, ensure_ascii=False))
# 输出：2026-07-12 10:20:01 [INFO] {"event":"llm_call","user_id":"u_123",...}

import uuid, time, logging, json
log = logging.getLogger("agent")

# 一次请求进来，先发一个「身份证号」
trace_id = str(uuid.uuid4())[:8]   # 例如 "a1b2c3d4"

def span(name):                     # 一个小工具：给某一步计时并打日志
    t0 = time.time()
    return t0, name

def end_span(t0, name):
    ms = int((time.time() - t0) * 1000)
    # 每一步都带上同一个 trace_id → 事后能串成一条线
    log.info(json.dumps({"trace_id": trace_id, "span": name, "ms": ms}))

t0, n = span("检索知识库")
# ... 这里执行真正的检索 ...
end_span(t0, n)          # 输出 {"trace_id":"a1b2c3d4","span":"检索知识库","ms":300}

# 以 Langfuse 为例，接入常常只要一个「装饰器」——套在函数上就自动记 trace
from langfuse.decorators import observe   # 概念示意，实际以官方文档为准

@observe()                    # 加这一行，这次调用的耗时/输入/输出就被自动记录
def answer(question: str) -> str:
    # ... 你原本的 Agent 逻辑，一行不用改 ...
    return "生成的回答"

answer("退货政策是什么？")     # 跑完，Langfuse 面板里就能看到这条 trace

✋ 动手 10 分钟：给一次调用打一条完整的结构化日志

新建 day55.py,把「trace_id + span 计时 + token/延迟 + 成败」串成一条像样的日志(不接任何平台,先手搓一遍找感觉):

import uuid, time, json, logging, random
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s")
log = logging.getLogger("agent")

def call_agent(question):
    trace_id = str(uuid.uuid4())[:8]     # 本次请求身份证
    t0 = time.time()
    ok = random.random() > 0.1           # 假装 10% 概率失败
    time.sleep(random.uniform(0.2, 1.5)) # 假装在干活，随机耗时
    latency_ms = int((time.time() - t0) * 1000)
    log.info(json.dumps({                # 一条结构化日志：谁、干了啥、花多少、成不成
        "trace_id": trace_id,
        "event": "answer",
        "question": question,
        "input_tokens": random.randint(200, 900),
        "output_tokens": random.randint(50, 300),
        "latency_ms": latency_ms,
        "ok": ok
    }, ensure_ascii=False))
    return ok, latency_ms

# 跑 20 次，再自己算错误率和 P95，体会「指标」是怎么从日志聚合出来的
results = [call_agent(f"问题{i}") for i in range(20)]
err_rate = sum(1 for ok, _ in results if not ok) / len(results)
lat_sorted = sorted(ms for _, ms in results)
p95 = lat_sorted[int(len(lat_sorted) * 0.95) - 1]
print(f"错误率 = {err_rate:.0%}   P95 延迟 = {p95}ms")

加分题:把这 20 条日志重定向到文件 python day55.py > app.log,再用 grep '"ok": false' app.log 把失败的挑出来——体会结构化日志「可检索」的好处。