Tracing

What to trace

Instrument user-visible workflows first: end-to-end generation, edits, and exports. Add finer spans only where they explain latency or failure (for example, upload, preprocess, diffusion, postprocess).

Span inputs and outputs

Capture structured metadata rather than full binary payloads when possible — URIs, dimensions, codec, token counts, and model IDs. Redact secrets and personally identifiable information before attaching fields.

Errors

Mark spans with error status when a stage fails, and include a concise machine-readable code plus a short human message. This makes trace lists and alerts actionable.

OpenTelemetry alignment

Frametail traces are designed to align with OpenTelemetry standards so you can reason about production data with familiar semantics:

• Trace context (W3C) — Trace and span ids are lowercase hex (32 and 16 characters). The TypeScript SDK can attach a traceparent header when exporting spans to the HTTP API, linking downstream scoring or custom pipelines to the same trace.
• Span status — Spans use UNSET, OK, and ERROR, matching OpenTelemetry SpanStatusCode.
• Semantic attributes — Provider wrappers (fal, AI SDK, OpenRouter) set gen_ai.request.model, gen_ai.provider.name, multimodal gen_ai.input.messages / gen_ai.output.messages, and frametail.provider. The backend projects these into dashboard columns (prompt, video URL, model, job id) for filtering and live scoring.

Provider-specific detail remains in structured blobs (for example falSpanData) when you need timing, queue position, or sanitized raw payloads.

Correlating releases

Add release or commit tags on traces so dashboards can compare builds. Pair traces with benchmarks for quality regressions the dashboard alone might miss.

SDK paths

• TypeScript SDK tracing helpers
• fal client wrapper