feat(observability): 抓取去掉首页预热，交易补齐链路埋点

两个问题一起处理，都与「出站请求与可观测性」有关。 ## 抓取：正常路径不再多打一次首页 site_session 原先每条通道每 30 分钟打一次 www.rakuten.co.jp/ 做预热，而且预热返回非 2xx 时 warmed_at 不置位——那种情况下每个请求前都会再打一次首页。 Akamai 的 cookie 随任意页面响应下发，目标页自己就会带回来，专门先打一次首页除了多一个出站请求（以及多一次被风控计数的机会）之外没有额外收益：首个请求无论打哪个 URL 都是冷的 ~11s，之后都复用 cookie。改为 cookie 由目标页响应建立（_note_cookies）、超 TTL 主动清空（_drop_expired_cookies）。首页只保留在失败修复路径上（_rewarm_on_home）：目标页已经吃了挑战页时，拿首页换一套干净 cookie 比继续撞同一个 URL 更安全。happy path 的出站请求数 2 → 1。 _note_cookies 刻意不在每次响应时刷新时刻：TTL 要从「这套 cookie 第一次出现」算起，每次都刷新会让一套 cookie 被无限续命，反而绕过了 session_ttl_seconds 的本意。 profile_status() 的 warmed 字段名保留（上游健康检查看板在用），语义改为「当前有可复用的 Akamai cookie」，不再代表「已专门预热过首页」。 ## 交易：此前没有任何有意义的链路数据根因是 trading 的实际工作两类自动埋点都覆盖不到：站点交互走 Playwright（不经 httpx），worker 主循环是后台 asyncio 任务（没有 HTTP 入口，因此没有根 span）。于是发给网关的每次 httpx 调用各自成为孤立 trace——观测后台上只剩一堆请求记录。新增手工埋点： - order.task：一笔下单的根 span，一个 task_id 一条 trace，带 order.route （execute / recovery / already_finished）与终态 order.terminal_status - order.step.*：清车 → 加购 → 校验 → 确认 → 提交 → 付款，每步一个子 span，带 order.evidence_ref，可从 span 直接定位落盘证据 - site.*：12 个 Playwright 交互方法（用 traced 装饰器而非 with 块——这些方法的函数体本就很长，再加一层缩进不利于阅读） - account_query：只读查询单的根 span，带 query.outcome 空转的长轮询（30 秒一次、绝大多数返回空）用 suppressed() 屏蔽：量大且没有信息量，把观测后台刷满的正是它们。领到任务后的网关调用都在任务根 span 底下，不受影响。闸门 / 风控拦截会被 _execute_with_renewal 吞掉转 needs_human，异常冒不到根 span，被拦下的单在 trace 里跟成功下单一模一样。加 _execute_recording_errors 一层统一记录，比每个 except 分支各写一遍省事，也不会漏掉后续新增的分支。 _report_safe 写 span 属性前判断 is_recording()：付款后监控是 create_task 起的， asyncio 在创建时就把 context 复制了进去，等它真正跑起来根 span 早已结束—— get_current_span() 拿到的仍是那个已结束的 span（不是 INVALID_SPAN），写属性会打 "Setting attribute on ended span"。当前监控路径不传 terminal_status 走不到那里，这道判断是防以后。 ## 顺带修掉：instrument_app 从未生效 instrument_app 用 _provider is None 做前置判断，但三个服务都在模块导入时执行 app = create_app()，而 setup_telemetry 要等 lifespan 才跑——那时 _provider 还是 None，照着判断直接 return。**FastAPI 从来没被打桩过，三个服务一条 server span 都没有。** 实测确认两件事：导入期打桩能出 span，lifespan 内打桩出不来（instrument_app 是加中间件，应用开始服务后加进去不生效）；provider 后设也不影响 ProxyTracer 委托到真实 provider。所以只能在导入期装，判断条件改为 otel_enabled。 app/gateway/main.py 此前完全没接 telemetry，worker 出站请求带过来的 traceparent 没人接上，一条下单链路在网关这里断掉，只看得到 worker 侧那半截。补上 setup_telemetry(service_name="rakuten-gateway") 与 instrument_app / shutdown。 ## 验证新增 8 个用例：首页零请求、cookie 复用与过期清空、失败后用首页换 cookie、一任务一 trace 的父子结构、闸门失败标 ERROR、空转不埋点，以及 instrument_app 调用顺序的回归测试。全量 526 passed。 Playwright 那些 site.* 埋点只做了静态验证（测试用桩替换站点方法），没有跑真实浏览器下单确认 span 真的落地。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-28 14:56:49 +08:00
parent bba45d7f7c
commit 3c7618a1d6
12 changed files with 727 additions and 113 deletions
@@ -20,8 +20,14 @@ from typing import Any

 import pytest

+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.trace import StatusCode
+
 from app.shared.errors import BrowserDeadError, CheckoutBlockedError, OrderGuardError
 from app.shared.task_state import OrderState, TaskStatus
+from app.trading.worker import runner as runner_module
 from app.trading.worker import verify
 from app.trading.worker.evidence import EvidenceStore
 from app.trading.worker.local_db import LocalDB
@@ -900,6 +906,130 @@ async def test_monitor_order_stops_after_max_checks_without_finding_order(
    assert gateway.reports == []


+# ---- 链路追踪：一个任务一条 trace ----
+
+
+@pytest.fixture
+def spans(monkeypatch) -> InMemorySpanExporter:
+    """把 runner 模块级 tracer 换成写内存的
+
+    不动全局 provider：OTel 的全局 provider 只允许设置一次，测试间共享会互相污染。
+    """
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    monkeypatch.setattr(runner_module, "tracer", provider.get_tracer("test"))
+    return exporter
+
+
+def _stub_happy_path(runner: WorkerRunner) -> None:
+    """把整条下单流程替换成桩，让 execute() 一路走到付款完成"""
+
+    async def _clear():
+        return {"removed_count": 0, "cart_count": 0, "html": "<html/>", "screenshot": b"p"}
+
+    async def _snapshot(*args, **kwargs):
+        return PageSnapshot(html="<html/>", screenshot=b"p")
+
+    async def _parse(html: str):
+        return CheckoutSummary(payable_yen=297)
+
+    async def _submit(task):
+        return SubmitOutcome(
+            site_order_id="ord-1", evidence=PageSnapshot(html="<html/>", screenshot=b"p")
+        )
+
+    async def _unchanged(order_id: str):
+        return OrderStatusSnapshot(found=True, order_state=None)
+
+    runner._site.clear_cart = _clear  # type: ignore[assignment]
+    runner._site.add_to_cart = _snapshot  # type: ignore[assignment]
+    runner._site.verify_cart = _snapshot  # type: ignore[assignment]
+    runner._site.enter_checkout = _snapshot  # type: ignore[assignment]
+    runner._site.parse_checkout = _parse  # type: ignore[assignment]
+    runner._site.submit_order = _submit  # type: ignore[assignment]
+    runner._site.pay = _snapshot  # type: ignore[assignment]
+    runner._site.check_order_status = _unchanged  # type: ignore[assignment]
+
+
+async def test_order_task_emits_one_trace_with_a_span_per_step(
+    runner: WorkerRunner, spans: InMemorySpanExporter
+):
+    """一笔下单 = 一条 trace，每个步骤一个子 span，全部挂在任务根 span 底下
+
+    worker 是后台 asyncio 任务，没有 HTTP 入口。不开这个根 span 的话，下游每次
+    出站调用都各自成为孤立 trace——观测后台上就只剩「一堆请求记录」，看不出
+    这是同一笔单、也看不出卡在哪一步。这条用例把链路结构钉住。
+    """
+    _stub_happy_path(runner)
+
+    await runner.handle(_make_task(task_id="t1", intent={"item_url": "https://x/y/", "quantity": 2}))
+
+    finished = spans.get_finished_spans()
+    root = next(s for s in finished if s.name == "order.task")
+    steps = [s for s in finished if s.name.startswith("order.step.")]
+
+    # 步骤 span 覆盖整条流水，且顺序与执行顺序一致
+    assert [s.name for s in steps] == [
+        "order.step.cart-add",
+        "order.step.cart-check",
+        "order.step.order-confirm",
+        "order.step.order-submit",
+        "order.step.payment",
+    ]
+    # 每个步骤都挂在任务根底下，同一条 trace
+    for step in steps:
+        assert step.parent.span_id == root.context.span_id
+        assert step.context.trace_id == root.context.trace_id
+
+    assert root.attributes["order.task_id"] == "t1"
+    assert root.attributes["order.route"] == "execute"
+    assert root.attributes["order.item_url"] == "https://x/y/"
+    # 证据路径落在 span 上：看到失败步骤能直接找到现场
+    assert steps[0].attributes["order.evidence_ref"]
+    assert steps[3].attributes["order.site_order_id"] == "ord-1"
+
+
+async def test_guard_failure_marks_task_span_as_error(
+    runner: WorkerRunner, spans: InMemorySpanExporter
+):
+    """金额守卫拦下时任务根 span 要是 ERROR，并带上对外错误码
+
+    闸门拦截会被 _execute_with_renewal 吞掉转 needs_human（不抛出 handle），
+    所以根 span 很容易显示成功——这里确认它没有。
+    """
+    _stub_happy_path(runner)
+
+    async def _pricey(html: str):
+        return CheckoutSummary(payable_yen=999_999)
+
+    runner._site.parse_checkout = _pricey  # type: ignore[assignment]
+
+    await runner.handle(_make_task(task_id="t1"))
+
+    root = next(s for s in spans.get_finished_spans() if s.name == "order.task")
+    assert root.status.status_code is StatusCode.ERROR
+    assert root.attributes["error.type"] == "OrderGuardError"
+    # 提交步骤没有发生：拦在确认页之后、提交之前
+    names = [s.name for s in spans.get_finished_spans()]
+    assert "order.step.order-submit" not in names
+
+
+async def test_idle_lease_does_not_emit_spans(runner: WorkerRunner, spans: InMemorySpanExporter):
+    """空转的长轮询不产生 span——否则每 30 秒一条孤立 trace 会把观测后台刷满"""
+    runner._running = True
+
+    async def _lease_then_stop(worker_id: str, *, wait: int = 30, site: str | None = None):
+        runner.stop()  # 领到空就停，避免死循环
+        return None
+
+    runner._gateway.lease = _lease_then_stop  # type: ignore[assignment]
+
+    await runner.run()
+
+    assert spans.get_finished_spans() == ()
+
+
 async def test_monitor_order_swallows_check_errors_and_keeps_polling(
    runner: WorkerRunner,
 ):