使用 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 消耗,针对延迟和错误率设置告警,持续提升抓取管道的可靠性。
前置条件
- 拥有有效 ingestion key 的 SigNoz Cloud 账户,或 自托管 SigNoz 实例
- Python 3.9 或更高版本
- Firecrawl API key。如果没有,请在 firecrawl.dev 注册获取
- 一个调用 Firecrawl Python SDK 的应用(
firecrawl-py2.0.0 或更高版本)
使用 OpenTelemetry 监控 Firecrawl
firecrawl-otel 包注册了一个 OpenTelemetry instrumentor 入口点,因此 OpenTelemetry CLI 无需任何代码改动即可启用它。关于该包的详细信息,请参阅 firecrawl-otel PyPI 页面。
第 1 步:安装依赖包
Copypip 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 环境变量:
Copyexport 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:
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:

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

这些 Firecrawl span 不包含 GenAI 属性,因此不会出现在 AI Observability 中。要查看调用量、延迟、credits 和结果,请使用 Firecrawl dashboard。
在 SigNoz 中查看 Firecrawl 指标
除了 trace 之外,埋点还会记录调用量、延迟、credits 消耗和返回结果等指标,并按操作类型打标签。这些指标可以在 Metrics 标签页中查看:

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

Firecrawl 可观测性 Dashboard
你還可以查看我們自定義的 Firecrawl 儀表盤,它提供專門用於監控 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 和应用:
- Temporal observability with OpenTelemetry——追踪 workflow、activity 和长时间运行的 agent 执行
- OpenClaw observability with OpenTelemetry——追踪各消息渠道中的网关会话、工具调用和模型用量
- LangChain and LangGraph observability with OpenTelemetry——追踪 chain、agent、图节点和工具调用
- Monitor Agno agents with OpenTelemetry——追踪 Agno teams 和 workflow 中的 agent 运行、工具调用和模型请求
- Monitor Claude Code with OpenTelemetry——追踪会话 token 用量、每任务成本和 API 性能
浏览 all LLM observability integrations,为你的其他技术栈添加可观测性埋点。