Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions scripts/firecrawl-page.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { integrations } from '../src/lib/integrations.mjs';

const page = readFileSync(
new URL('../src/pages/docs/integrations/traceai/firecrawl.mdx', import.meta.url),
'utf8',
);

// Page contracts, not a claim of live API execution. Version and lifecycle
// assertions follow the released traceAI-firecrawl 0.1.1 wheel.
test('Firecrawl setup uses released packages and instruments before client construction', () => {
assert.match(page, /traceAI-firecrawl==0\.1\.1/);
assert.match(page, /firecrawl-py==4\.50\.0/);
assert.match(page, /fi-instrumentation-otel==1\.2\.3/);
assert.match(page, /Python 3\.10–3\.13/);
assert.match(page, /firecrawl-py >=4\.46\.2,<5/);
const example = page.match(/```python\n([\s\S]*?)```/)?.[1];
assert.ok(example);
assert.match(example, /from traceai_firecrawl import FirecrawlInstrumentor/);
assert.match(example, /project_type=ProjectType\.OBSERVE/);
assert.match(example, /os\.environ\["FIRECRAWL_API_KEY"\]/);
assert.match(example, /client\.scrape\("https:\/\/example\.com", formats=\["markdown"\]\)/);
assert.match(example, /client\.search\("OpenTelemetry Python documentation", limit=2\)/);
assert.ok(example.indexOf('.instrument(') < example.indexOf('client = Firecrawl('));
assert.match(example, /finally:\n tracer_provider\.force_flush\(\)\n tracer_provider\.shutdown\(\)/);
assert.match(page, /python firecrawl_example\.py/);
assert.match(page, /Open \*\*Observe\*\*/);
assert.match(page, /separate root traces/);
});

test('Firecrawl uninstrument disables wrappers held by existing clients', () => {
assert.match(page, /`FirecrawlInstrumentor\(\)\.uninstrument\(\)` stops tracing subsequent calls, including calls through clients already constructed/);
assert.match(page, /re-enable instrumentation, construct new clients/);
assert.doesNotMatch(page, /keep tracing until|remain traced after.*uninstrument/i);
});

test('Firecrawl documents current operation coverage and job error semantics', () => {
for (const operation of ['extract', 'batch_scrape', 'wait_batch_scrape', 'agent', 'browser_execute']) {
assert.ok(page.includes('`' + operation + '`'));
}
assert.match(page, /`wait_batch_scrape` is async-only/);
assert.match(page, /one span, not one per page or internal poll/);
assert.match(page, /successful status poll records the job state without becoming an error itself/);
assert.match(page, /including `interact` and `parse`, are not instrumented/);
assert.doesNotMatch(page, /No `agent`/);
});

test('Firecrawl preserves privacy actions and avoids public verification diaries', () => {
assert.match(page, /Search query text is captured by default/);
assert.match(page, /FI_HIDE_INPUTS=true/);
assert.match(page, /does not hide host, format, job or session metadata/);
assert.match(page, /FI_PII_REDACTION=true/);
assert.match(page, /browser code or output/);
assert.match(page, /raw exception text or tracebacks/);
assert.match(page, /not to separate HTTP instrumentation or your application's logs/);
assert.doesNotMatch(page, /live vendor verification|fi_verify|168-test|privacy scan|not proven live|Status: beta|fc0dbe7b/i);
});

test('Firecrawl is discoverable through the shared integration catalog', () => {
const entry = integrations.find(integration => integration.id === 'firecrawl');
assert.equal(entry?.href, '/docs/integrations/traceai/firecrawl');
assert.equal(entry?.category, 'frameworks');
assert.equal(entry?.method, 'traceAI SDK');
});
1 change: 1 addition & 0 deletions scripts/integrations.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import './azure-openai-java.test.mjs';
import './langsmith-page.test.mjs';
import './vercel-platform-page.test.mjs';
import './scalekit-page.test.mjs';
import './firecrawl-page.test.mjs';
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
Expand Down
1 change: 1 addition & 0 deletions src/lib/integrations.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ export const integrations = [
{ id: 'fastmcp-python', name: 'FastMCP Python', href: '/docs/integrations/frameworks/fastmcp', category: 'frameworks', summary: 'Export native Python MCP client and server spans.', method: 'Native OTLP', logo: 'mcp' },
{ id: 'mcp-python', name: 'MCP for Python', href: '/docs/integrations/traceai/mcp-python', category: 'frameworks', summary: 'Export native MCP 2.x client requests and server tool spans.', method: 'Native OTLP', logo: 'mcp', aliases: ['Model Context Protocol Python'] },
{ id: 'mcp', name: 'Model Context Protocol', href: '/docs/integrations/traceai/mcp', category: 'frameworks', summary: 'Propagate context with TypeScript and existing Python MCP integrations.', method: 'traceAI SDK', logo: 'mcp', aliases: ['MCP'] },
{ id: 'firecrawl', name: 'Firecrawl', href: '/docs/integrations/traceai/firecrawl', category: 'frameworks', summary: 'Trace Python web scraping, search, crawl and browser operations.', method: 'traceAI SDK', logo: 'generic-framework' },
{ id: 'mastra', name: 'Mastra', href: '/docs/integrations/traceai/mastra', category: 'frameworks', summary: 'Trace TypeScript agents and workflows in Mastra.', method: 'traceAI SDK', logo: 'mastra' },
{ id: 'vercel-ai-sdk', name: 'Vercel AI SDK', href: '/docs/integrations/traceai/vercel', category: 'frameworks', summary: 'Capture model and tool calls from the Vercel AI SDK.', method: 'traceAI SDK', logo: 'vercel' },
{ id: 'vercel-ai-sdk-python', name: 'AI SDK for Python', href: '/docs/integrations/frameworks/vercel-ai-sdk-python', category: 'frameworks', summary: 'Export native Python AI SDK generation, agent and tool spans.', method: 'OpenTelemetry', logo: 'vercel', aliases: ['Vercel Python', 'Vercel AI SDK Python'] },
Expand Down
107 changes: 107 additions & 0 deletions src/pages/docs/integrations/traceai/firecrawl.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
---
title: "Firecrawl Integration with Future AGI Tracing"
description: "Trace Firecrawl v2 Python scraping, search, crawl, extraction, agent and browser operations in Future AGI with traceAI-firecrawl."
---

Use the maintained `traceAI-firecrawl` package to see Firecrawl v2 Python calls, latency and errors in Future AGI. It instruments both `Firecrawl` and `AsyncFirecrawl`, with one span per supported call rather than one per page or internal poll.

## Prerequisites

- Python 3.10–3.13 and `firecrawl-py >=4.46.2,<5`.
- A Firecrawl API key with credits for the operations you run.
- [Future AGI API and secret keys](/docs/admin-settings/api-keys).

This guide uses the v2 client (`from firecrawl import Firecrawl`). The legacy v1 `FirecrawlApp` is not instrumented. Do not enable another Firecrawl instrumentor for the same calls.

## 1. Install

```bash
pip install "traceAI-firecrawl==0.1.1" "firecrawl-py==4.50.0" "fi-instrumentation-otel==1.2.3"
```

## 2. Configure credentials

```bash
export FI_API_KEY="your-futureagi-api-key"
export FI_SECRET_KEY="your-futureagi-secret-key"
export FIRECRAWL_API_KEY="your-firecrawl-api-key"
```

The tracing SDK sends spans to Future AGI Cloud by default. For a self-hosted deployment, set `FI_BASE_URL` to your Future AGI API base URL before starting the application.

Search query text is captured by default. To omit it, set `FI_HIDE_INPUTS=true` before calling `instrument()`. See [Privacy](#privacy) for the other captured fields.

## 3. Trace a scrape and search

Save this as `firecrawl_example.py`. Call `instrument()` **before** constructing the client.

```python
import os

from firecrawl import Firecrawl
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from traceai_firecrawl import FirecrawlInstrumentor

tracer_provider = register(
project_name="firecrawl",
project_type=ProjectType.OBSERVE,
)
FirecrawlInstrumentor().instrument(tracer_provider=tracer_provider)

client = Firecrawl(api_key=os.environ["FIRECRAWL_API_KEY"])
try:
client.scrape("https://example.com", formats=["markdown"])
client.search("OpenTelemetry Python documentation", limit=2)
finally:
tracer_provider.force_flush()
tracer_provider.shutdown()
```

Run the example in the shell where you set the credentials:

```bash
python firecrawl_example.py
```

Open **Observe** in Future AGI and select the `firecrawl` project. Look for `firecrawl.scrape` (TOOL) and `firecrawl.search` (RETRIEVER), with duration and status. The scrape records `server.address=example.com`, not the returned page body. The search records a result count and, unless hidden, the query in its input.

Calls made inside an existing OpenTelemetry parent span appear as its children. Without a parent, the two example calls create separate root traces. In a long-running application, keep the provider alive and shut it down only when the application exits.

## What is captured

| Operations | Span kind | Metadata |
|---|---|---|
| `scrape`, `map` | TOOL | Target host (`server.address`); requested format names on scrape |
| `search` | RETRIEVER | `gen_ai.retrieval.query`, `input.value`, `firecrawl.result_count` |
| `crawl`, `start_crawl`, `get_crawl_status`, `cancel_crawl` | TOOL | Job ID, requested limit, job status; page count on blocking crawl |
| `extract`, `start_extract`, `get_extract_status` | TOOL | Job ID and status |
| `batch_scrape`, `start_batch_scrape`, `wait_batch_scrape`, `get_batch_scrape_status`, `get_batch_scrape_status_page`, `get_batch_scrape_errors`, `cancel_batch_scrape` | TOOL | Job ID and status; page count on blocking batch calls |
| `agent`, `start_agent`, `get_agent_status`, `cancel_agent` | TOOL | Job ID and status |
| `browser`, `browser_execute`, `delete_browser`, `list_browsers` | TOOL | Session ID when available |

Span names use `firecrawl.<method>`. Only methods exposed by the installed client are wrapped; `wait_batch_scrape` is async-only. Credit usage is recorded as `firecrawl.credits_used` when returned by the SDK. Requested format names, job IDs and session IDs use the `firecrawl.formats`, `firecrawl.job_id` and `firecrawl.session_id` attributes.

A blocking crawl or batch operation produces one span, not one per page or internal poll. A blocking operation that returns a `failed` or `cancelled` job ends with ERROR; a successful status poll records the job state without becoming an error itself. SDK exceptions mark the span ERROR and are re-raised unchanged. Error metadata includes a safe exception type and HTTP status when available, not the vendor's exception message.

## Privacy

- Search query text is captured by default, capped at 1024 characters after redacting the client's API key. The target host and operation metadata are also captured.
- This instrumentor does not capture page content, screenshots, URL paths or query strings, extraction or agent prompts and schemas, browser code or output, the Firecrawl API key, raw exception text or tracebacks.
- Set `FI_HIDE_INPUTS=true` before instrumentation to omit search query text. This does not hide host, format, job or session metadata. Set `FI_PII_REDACTION=true` to apply shared PII redaction to query text instead.
- These limits apply to the Firecrawl instrumentor's spans, not to separate HTTP instrumentation or your application's logs.

## Client lifecycle and limits

- Top-level clients constructed before `instrument()` are not traced. Construct them afterwards.
- Calling `FirecrawlInstrumentor().uninstrument()` stops tracing subsequent calls, including calls through clients already constructed while instrumentation was enabled. If you later re-enable instrumentation, construct new clients to use the new wrappers.
- `Firecrawl.watcher()` polling runs in its own thread, so its instrumented status polls do not inherit the calling thread's parent span.
- Use typed `ScrapeOptions` / `ScrapeFormats` when supplying nested format options. A raw nested dict in `scrape_options["formats"]` is not recorded as format metadata.
- Methods outside the table, including `interact` and `parse`, are not instrumented.

## Troubleshooting

- **No spans:** construct the client after instrumentation, check both Future AGI keys, and let the provider flush before the process exits. Outside the supported `firecrawl-py` range, `instrument()` logs an error and wraps nothing.
- **Duplicate spans:** enable only one Firecrawl instrumentor for the same calls.
- **Unauthorized or rate-limited calls:** check the Firecrawl key for HTTP 401, and your plan's rate limits for HTTP 429. The span records `firecrawl.error.status_code` when available.
- **`firecrawl.credits_used` is `0`:** the SDK can fill in `0` when the API omits it; do not treat it as proof that the call was free.
Loading