接入 OTel 链路追踪 + 镜像默认启用

抓取-解析链路原本只有日志，出现"抓回内容但解析不出预期字段"时定位慢。
接入 OpenTelemetry traces（FastAPI/httpx 自动 + 手写 fetch/parse span），
解析失败时把页面 HTML 作为 span event 上报，便于事后复现。
Dockerfile 默认开启，镜像一启动即导出到自建 OTLP endpoint。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

app/scraping/services/rakuten_client.py

@@ -8,6 +8,8 @@ from __future__ import annotations
 
 import logging
 
+from opentelemetry import trace
+
 from app.scraping.core import site
 from app.shared.config import Settings
 from app.shared.errors import ScrapeParseError
@@ -43,8 +45,10 @@ from app.scraping.utils.urls import (
     split_item_url,
     split_shop_url,
 )
+from app.shared.telemetry import snapshot
 
 logger = logging.getLogger(__name__)
+tracer = trace.get_tracer(__name__)
 
 
 class RakutenClient:
@@ -62,19 +66,32 @@ class RakutenClient:
             url = build_search_url(payload)
 
         logger.info("抓取搜索页：url=%s", url)
-        html = await self._session.fetch_html(url, mobile=False)
-        state = extract_initial_state(html)
-        result = parse_search(
-            state,
-            request_url=url,
-            page=payload.page,
-            exclude_ads=payload.exclude_ads,
-        )
-        logger.info(
-            "搜索完成：url=%s items=%s ads=%s total=%s",
-            url, len(result.items), result.ad_count, result.total_count,
-        )
-        return result
+        html: str | None = None
+        with tracer.start_as_current_span("parse.rakuten.search") as span:
+            span.set_attribute("parse.site", "rakuten")
+            span.set_attribute("parse.op", "search")
+            try:
+                html = await self._session.fetch_html(url, mobile=False)
+                state = extract_initial_state(html)
+                result = parse_search(
+                    state,
+                    request_url=url,
+                    page=payload.page,
+                    exclude_ads=payload.exclude_ads,
+                )
+                span.set_attribute("parse.items", len(result.items))
+                span.set_attribute("parse.ads", result.ad_count)
+                span.set_attribute("parse.total", result.total_count)
+                logger.info(
+                    "搜索完成：url=%s items=%s ads=%s total=%s",
+                    url, len(result.items), result.ad_count, result.total_count,
+                )
+                return result
+            except Exception:
+                span.record_exception()
+                span.set_attribute("parse.fail_reason", "parse_error")
+                snapshot(span, "parse.failed_html", html, self._settings.otel_snapshot_max_bytes)
+                raise
 
     async def genres(self, payload: GenreRequest) -> GenreData:
         """抓取分类树：顶层分类列表，或指定分类的信息与直接子分类"""
@@ -82,14 +99,25 @@ class RakutenClient:
         url = build_genre_url(genre_id)
 
         logger.info("抓取分类树：url=%s genre_id=%s", url, genre_id)
-        html = await self._session.fetch_html(url, mobile=False)
-        state = extract_initial_state(html)
-        result = parse_genres(state, genre_id=genre_id)
-        logger.info(
-            "分类树完成：genre_id=%s name=%s children=%s",
-            result.genre_id or "root", result.name, len(result.children),
-        )
-        return result
+        html: str | None = None
+        with tracer.start_as_current_span("parse.rakuten.genres") as span:
+            span.set_attribute("parse.site", "rakuten")
+            span.set_attribute("parse.op", "genres")
+            try:
+                html = await self._session.fetch_html(url, mobile=False)
+                state = extract_initial_state(html)
+                result = parse_genres(state, genre_id=genre_id)
+                span.set_attribute("parse.children", len(result.children))
+                logger.info(
+                    "分类树完成：genre_id=%s name=%s children=%s",
+                    result.genre_id or "root", result.name, len(result.children),
+                )
+                return result
+            except Exception:
+                span.record_exception()
+                span.set_attribute("parse.fail_reason", "parse_error")
+                snapshot(span, "parse.failed_html", html, self._settings.otel_snapshot_max_bytes)
+                raise
 
     async def shop_detail(self, payload: ShopDetailRequest) -> ShopDetailData:
         """抓取商家详情"""
@@ -100,14 +128,25 @@ class RakutenClient:
         url = build_shop_url(shop_code)
 
         logger.info("抓取店铺页：url=%s", url)
-        html = await self._session.fetch_html(url, mobile=False)
-        state = extract_initial_state(html)
-        result = parse_shop_detail(state, shop_code=shop_code, html=html)
-        logger.info(
-            "店铺详情完成：shop_code=%s shop_id=%s name=%s reviews=%s",
-            result.shop_code, result.shop_id, result.shop_name, result.review_count,
-        )
-        return result
+        html: str | None = None
+        with tracer.start_as_current_span("parse.rakuten.shop_detail") as span:
+            span.set_attribute("parse.site", "rakuten")
+            span.set_attribute("parse.op", "shop_detail")
+            try:
+                html = await self._session.fetch_html(url, mobile=False)
+                state = extract_initial_state(html)
+                result = parse_shop_detail(state, shop_code=shop_code, html=html)
+                span.set_attribute("parse.reviews", result.review_count)
+                logger.info(
+                    "店铺详情完成：shop_code=%s shop_id=%s name=%s reviews=%s",
+                    result.shop_code, result.shop_id, result.shop_name, result.review_count,
+                )
+                return result
+            except Exception:
+                span.record_exception()
+                span.set_attribute("parse.fail_reason", "parse_error")
+                snapshot(span, "parse.failed_html", html, self._settings.otel_snapshot_max_bytes)
+                raise
 
     async def shop_items(self, payload: ShopItemsRequest) -> SearchResultData:
         """抓取商家名下的商品列表
@@ -116,14 +155,25 @@ class RakutenClient:
         `sid=` 限定店铺后的产物，因此这里转成一次搜索。只给 shop_code 时
         需要先取一次店铺详情换出 shop_id。
         """
-        shop_id = payload.shop_id
-        if shop_id is None:
-            detail = await self.shop_detail(ShopDetailRequest(shop_code=payload.shop_code))
-            if detail.shop_id is None:
-                raise ScrapeParseError(f"未能取得店铺 {payload.shop_code} 的 shop_id")
-            shop_id = detail.shop_id
+        with tracer.start_as_current_span("parse.rakuten.shop_items") as span:
+            span.set_attribute("parse.site", "rakuten")
+            span.set_attribute("parse.op", "shop_items")
+            try:
+                shop_id = payload.shop_id
+                if shop_id is None:
+                    detail = await self.shop_detail(ShopDetailRequest(shop_code=payload.shop_code))
+                    if detail.shop_id is None:
+                        raise ScrapeParseError(f"未能取得店铺 {payload.shop_code} 的 shop_id")
+                    shop_id = detail.shop_id
 
-        return await self.search(payload.to_search_request(shop_id))
+                result = await self.search(payload.to_search_request(shop_id))
+                span.set_attribute("parse.items", len(result.items))
+                span.set_attribute("parse.total", result.total_count)
+                return result
+            except Exception:
+                span.record_exception()
+                span.set_attribute("parse.fail_reason", "parse_error")
+                raise
 
     async def item_detail(self, payload: ItemDetailRequest) -> ItemDetailData:
         """抓取商品详情"""
@@ -137,33 +187,47 @@ class RakutenClient:
         url = build_item_url(shop_code, item_code)
 
         logger.info("抓取商品详情：url=%s", url)
-        # 部分官方旗舰店的商品页会跳出市场域名，落到各自的独立站点；
-        # 校验与解析都按最终落地域名分派，落到未登记站点时由校验器抛错。
-        page = await self._session.fetch(
-            url, mobile=True, validator=build_item_page_validator(url)
-        )
-
-        if host_of(page.url) == site.ITEM_HOST:
-            detail = parse_item_detail(
-                extract_initial_state(page.html),
-                item_url=url,
-                shop_code=shop_code,
-                include_sku_variants=payload.include_sku_variants,
-            )
-        else:
-            detail = parse_subsite_item(
-                SubsitePage(
-                    html=page.html,
-                    requested_url=url,
-                    final_url=page.url,
-                    shop_code=shop_code,
-                    item_code=item_code,
-                    include_sku_variants=payload.include_sku_variants,
+        html: str | None = None
+        with tracer.start_as_current_span("parse.rakuten.item_detail") as span:
+            span.set_attribute("parse.site", "rakuten")
+            span.set_attribute("parse.op", "item_detail")
+            try:
+                # 部分官方旗舰店的商品页会跳出市场域名，落到各自的独立站点；
+                # 校验与解析都按最终落地域名分派，落到未登记站点时由校验器抛错。
+                page = await self._session.fetch(
+                    url, mobile=True, validator=build_item_page_validator(url)
                 )
-            )
+                html = page.html
 
-        logger.info(
-            "详情完成：url=%s source=%s name=%s price=%s skus=%s",
-            url, detail.source, detail.item_name[:40], detail.price, detail.sku.variant_count,
-        )
-        return detail
+                if host_of(page.url) == site.ITEM_HOST:
+                    detail = parse_item_detail(
+                        extract_initial_state(page.html),
+                        item_url=url,
+                        shop_code=shop_code,
+                        include_sku_variants=payload.include_sku_variants,
+                    )
+                else:
+                    detail = parse_subsite_item(
+                        SubsitePage(
+                            html=page.html,
+                            requested_url=url,
+                            final_url=page.url,
+                            shop_code=shop_code,
+                            item_code=item_code,
+                            include_sku_variants=payload.include_sku_variants,
+                        )
+                    )
+
+                span.set_attribute("parse.source", detail.source)
+                span.set_attribute("parse.price", detail.price)
+                span.set_attribute("parse.variant_count", detail.sku.variant_count)
+                logger.info(
+                    "详情完成：url=%s source=%s name=%s price=%s skus=%s",
+                    url, detail.source, detail.item_name[:40], detail.price, detail.sku.variant_count,
+                )
+                return detail
+            except Exception:
+                span.record_exception()
+                span.set_attribute("parse.fail_reason", "parse_error")
+                snapshot(span, "parse.failed_html", html, self._settings.otel_snapshot_max_bytes)
+                raise