Video generation API observability: trace submission, collection, and delivery

Video generation API observability starts with a durable correlation chain: user action, submission attempt, remote job, and stored artifact. Without that chain, a dashboard can report HTTP success while customers receive no usable video, or report socket timeouts while the renders eventually succeed.

Instrument the stages separately. Submission measures acceptance. Collection measures when your application observes the remote outcome. Delivery measures when a validated file becomes available from your own storage. These timestamps answer different operational questions and should not be collapsed into one latency histogram.

Record a sanitized event shape

The following JavaScript function prepares a log record from an existing job snapshot. It omits API keys, prompts, and output URLs because those fields can contain credentials, private content, or signed query parameters.

function jobObservation(localRequestId, job, elapsedMs) {
  return {
    event: 'video_job_observed',
    local_request_id: localRequestId,
    job_id: job.id,
    model: job.model,
    state: job.state,
    error_code: job.error?.code ?? null,
    output_count: job.outputs?.length ?? 0,
    credits_held: job.credits_held,
    credits_actual: job.credits_actual,
    created_at: job.created_at,
    finished_at: job.finished_at,
    observed_elapsed_ms: elapsedMs,
  };
}

Log state transitions or meaningful changes instead of every identical polling snapshot. Keep the latest complete snapshot in your application database if support needs detailed diagnosis. A log stream should not become a second uncontrolled repository of customer media links.

Choose metrics by decision

Metric	Decision it supports
Submission rejection count by error code	Fix auth, parameters, quota, or balance
Ambiguous submission count	Investigate duplicate-spend risk
Age of oldest active job	Detect work needing reconciliation
Collection lag after finished_at	Improve polling or worker scheduling
Artifact-copy failure rate	Repair delivery without regenerating
Actual credits per delivered video	Understand operational cost

Avoid using job IDs as metric labels because every render creates another value. Keep identifiers in searchable logs or traces, and use bounded labels such as model, stage, and error class for aggregate metrics.

Distinguish observer failure from render failure

The repository’s worker statistics include a failed count for exceptions while advancing jobs. That number does not mean the same thing as jobs whose remote state is failed. If you operate the gateway, name these metrics distinctly. If you are an API consumer, keep your failed status reads separate from terminal render failures for the same reason.

The internal backoff module defines a thirty-minute stuck threshold. This is an alerting threshold in the implementation, not an automatic promise that the job fails or refunds at thirty minutes. Your own product deadline may be shorter, but label it as an application deadline.

Verification checklist

Trace one recorded success from local action to stored artifact, then repeat with a failed render and a failed download. Confirm that every event can be correlated, secrets are absent, and metric labels remain bounded. Ensure an old active job raises an investigation signal without silently submitting replacement work.

See production checks, cost budgeting, and download validation.

Continue with production operations

• AI video API webhook vs polling: which one to use and when
• How to call a video generation API without blocking your agent
• generation operation unique key: deduplicate local intent without inventing API idempotency
• Browse all production operations guides