firecrawl-otel 0.1.1

OpenTelemetry instrumentation for the Firecrawl SDK — ship scrape/crawl/search traces and metrics to SigNoz or any OTLP backend.

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:

Span attribute	Example
firecrawl.operation	scrape, crawl, search, map
url.full	https://example.com
firecrawl.query	what is opentelemetry (search)
firecrawl.formats	markdown,html
firecrawl.results	5
firecrawl.credits_used	12
firecrawl.status	completed

Metrics:

Metric	Type	Description
firecrawl.requests	counter	Calls, tagged by firecrawl.operation + outcome (ok/error)
firecrawl.request.duration	histogram (ms)	Latency per call
firecrawl.credits.used	counter	Firecrawl credits consumed
firecrawl.results.returned	histogram	Documents/pages/results returned

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