This reference is an architectural example, not a live CDNLog.com API endpoint. It shows how a platform team can represent CDN request records consistently across providers while retaining the source detail needed for replay and debugging.
Schema principles
- Stable core, flexible extensions: normalize common concepts and namespace provider-specific fields.
- Explicit semantics: document timestamp boundaries, timing units, null behavior, and enum meanings.
- Deterministic identity: use a stable event key for idempotent retries and replay.
- Privacy by design: allowlist fields and remove secrets before shared analytics.
- Observable quality: include source, schema, observed time, and processing status.
Reference JSON event
cdnlog.event.v1
{
"schema_version": "1.0",
"event_id": "example-cdn:dist-42:01JAX...",
"event_time": "2026-10-23T18:42:11.423Z",
"observed_time": "2026-10-23T18:42:19.807Z",
"source": {
"provider": "example-cdn",
"account_id": "acct-main",
"distribution_id": "dist-42",
"source_ref": "stream:7:184401"
},
"service": {
"name": "catalog-api",
"environment": "production",
"route_group": "GET /v1/items/:id"
},
"request": {
"id": "req-9d2f...",
"method": "GET",
"host": "api.example.test",
"path_class": "/v1/items/:id",
"protocol": "h2"
},
"response": {
"status_code": 200,
"result_source": "origin",
"bytes": 18462
},
"cdn": {
"edge_region": "us-west",
"cache_outcome": "miss",
"origin_pool": "catalog-primary-west"
},
"timing_ms": {
"origin_connect": 12.9,
"origin_first_byte": 142.7,
"edge_total": 166.4
},
"sampling": { "rate": 1.0, "method": "none" },
"extensions": { "example_cdn": { "raw_cache_code": "MISS" } }
}Core field dictionary
| Field | Type | Requirement | Meaning |
|---|---|---|---|
schema_version | string | required | Version of the canonical event contract. |
event_id | string | required | Deterministic or stable unique key used for idempotency. |
event_time | RFC 3339 timestamp | required | Provider-defined request event time, documented as start or completion. |
observed_time | RFC 3339 timestamp | required | Time the normalization pipeline received or observed the event. |
source.provider | string enum | required | Normalized provider identifier. |
source.source_ref | string | recommended | Stream offset, object key, or source position for provenance and replay. |
service.route_group | string | recommended | Bounded, versioned route pattern for metrics and ownership. |
response.result_source | enum | recommended | Edge, edge function, origin, policy, or unknown source of the response. |
cdn.cache_outcome | enum | recommended | Hit, miss, bypass, revalidated, stale, error fallback, or unknown. |
timing_ms.* | number | optional | Durations normalized to milliseconds with documented boundaries. |
sampling.rate | number | recommended | Fraction of eligible source events represented by the record. |
extensions | object | optional | Namespaced provider values preserved without forcing false normalization. |
Recommended normalized enums
Cache outcome
hit, miss, bypass, revalidated, stale, error_fallback, unknown.
Result source
edge, edge_function, origin, policy, client_abort, unknown.
Policy action
allow, block, challenge, rate_limit, redirect, log, unknown.
Null reason
not_supported, not_enabled, not_applicable, redacted, parse_error.
Validation and quality checks
- Reject records above an approved maximum size before expensive parsing.
- Validate timestamps, numeric units, required identifiers, and known enum values.
- Track unknown fields and enums rather than silently dropping them.
- Distinguish zero, null, and missing values.
- Verify that redaction ran successfully before shared storage or fan-out.
- Measure event-to-observed lag, duplicates, parser failures, and source coverage.
- Use fixtures for cache states, retries, subrequests, malformed URLs, large headers, and absent timing fields.
Implementation path
- Create the schema and field dictionary in a version-controlled repository.
- Build one provider adapter and preserve the raw source record for a bounded replay window.
- Write contract tests for semantics, privacy, and data quality.
- Publish a compact operational topic and a complete archival dataset.
- Derive one dashboard using bounded dimensions and validate it against sampled events.
- Add a second provider only after capability and null handling are explicit.
Use the essential field guide to select fields, the pipeline guide for transport, and the multi-CDN guide for cross-provider comparison.
Use the schema as a contract, not a suggestion.
Version every meaning, preserve provenance, validate privacy, and measure the quality of the log pipeline itself.