fal.ai tracing
Wrap the fal client with Frametail to capture spans around generative calls.
Why integrate
The @fal-ai/client wrapper records latency, inputs, outputs, and errors for each fal call, sending spans to Frametail automatically when tracing is enabled.
Basic setup
import { FrametailClient } from 'frametail'
import * as fal from '@fal-ai/client'
const frametail = new FrametailClient({
apiKey: process.env.FRAMETAIL_API_KEY!,
projectKey: process.env.FRAMETAIL_PROJECT_KEY!,
enableTracing: true,
})
const tracedFal = frametail.wrapFalClient(fal)
await tracedFal.subscribe('fal-ai/flux/schnell', { input: { prompt: '...' } })OpenTelemetry-aligned spans
Fal instrumentation follows OpenTelemetry conventions so traces work with standard tooling and Frametail dashboards:
| Area | Convention |
|---|---|
| Trace context | W3C trace IDs (32 hex chars) and span IDs (16 hex chars); traceparent header on HTTP export when a span is active |
| Span status | UNSET, OK, or ERROR (OpenTelemetry SpanStatusCode) |
| Gen AI | gen_ai.request.model, gen_ai.provider.name (fal) |
| Input | gen_ai.input.messages (user text prompt) |
| Output | gen_ai.output.messages (assistant URI parts with modality: video or image) |
| Job id | gen_ai.response.id |
| Provider | frametail.provider: fal |
Each span also includes a falSpanData object with endpoint id, timing, queue metadata, and sanitized payloads.
Span names and types
| Operation | Span name | Span type (typical) |
|---|---|---|
run, subscribe (video endpoints) | fal.run, fal.subscribe | video.generate |
run, subscribe (image / flux / sdxl, etc.) | fal.run, fal.subscribe | compose |
stream | fal.stream | task |
| Queue APIs | fal.queue.submit, fal.queue.status, … | tool |
subscribe is the recommended blocking API for text-to-image: it uses the queue with client-side polling and produces the same traced spans as run.
Traces dashboard
After a generation completes, open Traces in the dashboard and filter by provider fal. Projected columns include prompt, model, job id, and either video URL or image URL depending on output kind, so you can inspect production generations without parsing raw attributes.
Configuration
Set enableTracing: false only when you intentionally disable export (for example, in local-only tests). See the SDK reference for defaults and custom exporters.