← 文章 / 云原生与基础设施
signoz 11天前 · 2026-11-11 04:42:18 · 16 阅读

使用 OpenTelemetry 和 SigNoz 进行 Firecrawl 监控

通过 OpenTelemetry 采集 traces 和 metrics,Firecrawl 监控让你实时掌握网页抓取和爬取工作负载的运行状况。Firecrawl 本身不会输出 OpenTelemetry 数据,因此本指南使用 firecrawl-otel——一个封装了 Firecrawl Python SDK 的客户端埋点包。它无需修改任何调用代码,就能追踪所有 scrape、crawl、search、map、extract 和 batch_scrape 调用,并记录调用次数、延迟、消耗的 credits 以及返回结果数等指标。

在 SigNoz 中获得完整的 Firecrawl 可观测性后,你可以对每次抓取调用进行端到端追踪,定位缓慢或失败的操作,跟踪 Firecrawl 套餐的 credit 消耗,针对延迟和错误率设置告警,持续提升抓取管道的可靠性。

前置条件

使用 OpenTelemetry 监控 Firecrawl

firecrawl-otel 包注册了一个 OpenTelemetry instrumentor 入口点,因此 OpenTelemetry CLI 无需任何代码改动即可启用它。关于该包的详细信息,请参阅 firecrawl-otel PyPI 页面。

第 1 步:安装依赖包

Copy
pip install "firecrawl-otel[instruments]" opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap --action=install

[instruments] extra 会一并安装 Firecrawl SDK(firecrawl-py)。如果你自行管理 firecrawl-py,可以去掉它,直接安装 firecrawl-otel。

第 2 步:配置导出到 SigNoz

使用自托管 SigNoz?

大部分步骤相同。只需按照 Cloud → Self-Hosted 中的说明修改 endpoint 并移除 ingestion key header 即可。

设置标准的 OpenTelemetry 环境变量:

Copy
export OTEL_SERVICE_NAME=<your-service-name>
export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.signoz.cloud:443
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

请核实以下配置值:

  • <your-service-name>:应用名称,例如 firecrawl-prod。SigNoz 中服务将以此名称显示。
  • <region>:您的 SigNoz Cloud 区域。
  • <your-ingestion-key>:您的 SigNoz ingestion key。

第三步:运行应用

使用 opentelemetry-instrument 启动应用,该命令会自动启用 Firecrawl instrumentor:

Copy
opentelemetry-instrument python your_app.py

此时,Firecrawl 的调用将生成 trace。每次调用会产生一个 span,包含操作类型、目标 URL、消耗积分及返回结果,同时记录调用量、延迟、积分消耗和结果等 metrics。

Prefer to instrument in code?

在启动时、创建 Firecrawl 客户端之前,调用一次 FirecrawlInstrumentor().instrument() 即可。由于客户端在构造时绑定方法,因此 instrumentation 之前创建的客户端不会被追踪。注意,代码内配置不会自动设置 exporter,需在应用中自行配置。参见 package documentation 了解代码内配置方法及如何显式传入 tracer 和 meter provider。

在 SigNoz 中查看 Firecrawl Trace

配置完成后,应用会自动为每次 Firecrawl 调用生成 trace。

在 SigNoz 的 Traces 选项卡中可查看这些 trace:

Firecrawl Trace View
Firecrawl Trace View

在 SigNoz 中点击某个 trace,就能看到它的详细信息,包括所有关联的 span 及其事件和属性。每个 Firecrawl span 都带有 firecrawl.* 属性,描述操作类型、目标 URL、消耗的 credits 以及返回的结果数量。

Firecrawl Detailed Trace View
Firecrawl Detailed Trace View
AI Observability

这些 Firecrawl span 不包含 GenAI 属性,因此不会出现在 AI Observability 中。要查看调用量、延迟、credits 和结果,请使用 Firecrawl dashboard。

在 SigNoz 中查看 Firecrawl 指标

除了 trace 之外,埋点还会记录调用量、延迟、credits 消耗和返回结果等指标,并按操作类型打标签。这些指标可以在 Metrics 标签页中查看:

Firecrawl Metrics View
Firecrawl Metrics View

点击任意指标可以查看其类型、单位和属性,也可以在 Explorer 中打开并绘制图表:

Firecrawl Metric Details
Firecrawl Metric Details

Firecrawl 可观测性 Dashboard

你還可以查看我們自定義的 Firecrawl 儀表盤,它提供專門用於監控 Firecrawl 使用情況的視覺化圖表。儀表盤包含針對爬取操作優化的預建圖表,並附帶快速上手的導入指南。

Firecrawl Dashboard
Firecrawl 儀表盤模板

Firecrawl 可觀測性故障排除

SigNoz 中無 Trace 數據

  • 確認應用程序是否實際觸發了 Firecrawl 調用。閒置的應用程序不會產生任何數據。
  • 核對 OTEL_EXPORTER_OTLP_ENDPOINT 中的地區設置與你的 SigNoz 賬戶是否一致。
  • OpenTelemetry 會在發送前對數據進行批處理,因此在調用後請等待 10-30 秒。

驗證 Instrumentor 是否激活

如果通過代碼而非 opentelemetry-instrument 進行埋點,請確保 FirecrawlInstrumentor().instrument() 在構建 Firecrawl 客戶端之前執行。在此之後創建的客戶端將保留原始未儀表化的方法。

該儀表化針對 Firecrawl Python SDK 2.0.0 及以上版本。在舊版 SDK 結構中,它不會採取行動而只是不報錯,因此如果 Traces 選項卡意外為空,可能是已安裝的 firecrawl-py 版本過低。

認證錯誤 (401 / 403)

重新檢查 OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" 中的 Ingestion Key。它必須與 SigNoz Ingestion 設置中的精確密鑰一致,不能有多餘的空格或引號。

端點問題

請保留 OTEL_EXPORTER_OTLP_ENDPOINT 中的 https:// 協議方案和 :443 端口。導出器會自動附加信號路徑,因此無需手動添加。

配置 OpenTelemetry Collector(可選)

什麼是 OpenTelemetry Collector?

可以把 OTel Collector 理解為應用程序和 SigNoz 之間的中間層。應用程序不直接向 SigNoz 發送數據,而是先發送到 Collector,再由其進行轉發。

為什麼要使用它?

  • 数据清洗——过滤掉不需要的噪音 trace,或在数据离开服务器前移除敏感信息。
  • 保持应用轻量——让 Collector 负责批量处理、重试和压缩,而不占用应用代码。
  • 自动附加上下文——Collector 可以给数据打上有用信息,比如来自哪个 Kubernetes pod 或云区域。
  • 面向未来的灵活性——以后想往多个后端发数据?Collector 让这变得很简单,无需改动应用。

参考 Switch from direct export to Collector 中的分步指引来迁移你的配置。

更多细节请查看 Why use the OpenTelemetry Collector? 和 Collector configuration guide。

相关集成

追踪运行在这套基础设施之上的 agent 和应用:

浏览 all LLM observability integrations,为你的其他技术栈添加可观测性埋点。

原始来源: signoz

评论 (0)