Category: Architecture

Track user outcomes, worker health, and delivery cost with a small metric set.

Follow one asset through the system

Give an upload and every downstream job a shared asset ID in logs and traces. Measure time from upload completion to ready state, failure rate by stage, retry count, and queue age. Separate user-caused validation failures from service failures so an increase in rejected files does not look like a broken worker pool.

Watch delivery, not just processing

Track derivative generation requests, cache hit ratio, bytes delivered, and playback or image errors from the client. A queue can be healthy while users still see broken URLs. Sample client telemetry with privacy and cost limits rather than collecting every raw URL.

Put thresholds on decisions

An alert should indicate a response: growing oldest-job age may call for worker capacity; rising corrupt-output failures may require a recipe rollback. Review the cost per processed asset and per delivered gigabyte alongside reliability, then retire metrics that no one uses.

A concrete acceptance test

Trace one upload through processing and delivery, then simulate a corrupt source and a stalled queue. Confirm that dashboards separate user rejection, worker failure, and age of the oldest job. Run this test with a realistic asset and record the observed state, output URL, and failure reason.

Implementation check

• Trace one asset across each processing stage.
• Separate validation rejection from service failure.
• Alert on queue age and delivery errors with clear owners.

Related guides

• A developer’s guide to media pipelines
• CDN cache keys for transformed media

Primary reference: Official documentation.

Notify applications when assets become ready without duplicate side effects.

Publish state changes as events

A processing system can emit uploaded, ready, failed, or deleted events after committing the corresponding state. Give each event a unique ID, asset ID, event type, timestamp, and schema version. The receiver should be able to fetch the current asset state rather than treating an event payload as the only truth.

Verify and deduplicate

Sign webhook requests and verify the signature over the raw request body. The consumer records event IDs and handles repeat deliveries idempotently. A fast acknowledgment followed by queued work keeps transient downstream slowness from causing unnecessary retries.

Expect disorder

Events can arrive late or out of order. Make handlers compare versions or retrieve current state before moving a record backward. Provide a replay or reconciliation path so a temporary endpoint outage does not leave an asset permanently stuck in processing.

A concrete acceptance test

Deliver ready twice, then deliver an older processing event. The consumer should acknowledge all three requests while the application keeps one ready asset state. Run this test with a realistic asset and record the observed state, output URL, and failure reason.

Implementation check

• Verify signatures against the raw body.
• Deduplicate by event ID before side effects.
• Reconcile state when events arrive out of order.

Related guides

• A developer’s guide to media pipelines
• CDN cache keys for transformed media

Primary reference: Official documentation.

A practical map from browser upload to reliable image and video delivery.

Map the lifecycle

A media pipeline starts before the file reaches storage. The client needs a safe way to send bytes, the server needs an identity for the asset, workers need repeatable jobs, and delivery needs URLs with predictable behavior. Treat the original as an immutable input. Derivatives are outputs that can be recreated when requirements change.

Choose boundaries that survive change

Separate upload authorization, object storage, processing, metadata, and delivery. A product that only accepts small profile photos may process synchronously. Large video uploads, multiple renditions, or moderation usually justify a queue and an explicit processing state. Store the asset ID, owner, source key, checksum, status, dimensions, and derivative references in a database; keep binary bytes in object storage.

Design for retries

Give every processing job an idempotency key tied to the asset and recipe version. A retry should find the existing output or safely replace it. Publish an asset only after required derivatives exist, then make the delivery URL visible to the application. Keep failure states observable so a missing thumbnail does not silently become a broken page.

A concrete acceptance test

Upload a source image, force one worker failure, and confirm that a retry produces one ready asset with no duplicate derivative. Then change the recipe version and verify that the original remains unchanged. Run this test with a realistic asset and record the observed state, output URL, and failure reason.

Implementation check

• Keep the source immutable and give each derivative a recipe version.
• Move the asset to ready only after required outputs pass validation.
• Correlate upload, processing, and delivery logs with one asset ID.

Related guides

• What to measure in a media pipeline
• Direct browser uploads without exposing storage credentials

Primary reference: Official documentation.

Related field note

Continue with Designing queue backpressure for human and agent operators.