firecrawl-otel

OpenTelemetry instrumentation for the Firecrawl Python SDK. Trace every scrape / crawl / search / map / extract call and ship the traces and metrics to SigNoz, or any OTLP backend, without changing your Firecrawl call sites.

Firecrawl does not emit OpenTelemetry itself, so this package instruments it on the client side using the standard OpenTelemetry BaseInstrumentor pattern.

Install

pip install "firecrawl-otel[instruments]"

The [instruments] extra pulls in the Firecrawl SDK (firecrawl-py); drop it and install plain firecrawl-otel if you manage firecrawl-py yourself.

Quickstart

from firecrawl import Firecrawl
from firecrawl_otel import FirecrawlInstrumentor

FirecrawlInstrumentor().instrument()      # once, at startup

app = Firecrawl(api_key="fc-...")         # your normal client, unchanged
doc = app.scrape("https://example.com")   # automatically traced

Point the telemetry at SigNoz with standard OpenTelemetry environment variables:

# SigNoz Cloud (region = us | us2 | eu | eu2 | in | in2)
export OTEL_SERVICE_NAME=my-app
export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.us.signoz.cloud:443
export OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=<your-key>

For self-hosted SigNoz use http://localhost:4317 and no headers.

Zero-code option

Because the package registers an opentelemetry_instrumentor entry point, the OpenTelemetry CLI can enable it with no code change at all:

pip install "firecrawl-otel[instruments]" opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
opentelemetry-instrument python your_app.py

What you get in SigNoz

Traces: one span per Firecrawl call:

Metrics:

Notes

• Call instrument() before creating the Firecrawl client. The unified client binds its methods at construction time, so instrument at startup (as in the quickstart); clients created afterwards are traced.
• This library configures no exporters. Exporter setup stays with your app (the OTEL_* env vars above, or opentelemetry-instrument). That keeps it composable with the rest of your OpenTelemetry setup.
• Pass explicit providers if you don't use the globals: FirecrawlInstrumentor().instrument(tracer_provider=tp, meter_provider=mp).
• Disable again with FirecrawlInstrumentor().uninstrument().
• A runnable end-to-end demo (scrape → search → crawl) lives in examples/.

Development

pip install -e ".[dev]"
pytest
python -m build && twine check dist/*

License

Apache-2.0