Signals¶

All signals carry service.name=cf2otel. Cloudflare-specific names begin cloudflare.*; GenAI names follow gen_ai.*; the poller's own measurements begin cf2otel.*. Names are declared in internal/semconv and this page is the public inventory.

Cloudflare physical-request self-metrics¶

cf2otel.api.requests is a monotonic Counter with unit {request}; cf2otel.api.duration and cf2otel.api.limiter_wait are Histograms with unit s. Each physical HTTP exchange records exactly one count and one sample in both histograms, including REST pagination, GraphQL settings and query calls, retry attempts and followed redirect hops. A cache hit makes no HTTP request and records nothing. Cancellation while acquiring quota also records nothing. The existing read-only guard, limiter rate, retries and collector cadence are unchanged.

These three metrics carry only cf2otel.collector (the scheduler's registered collector name, or unattributed outside scheduled/one-shot/range collection), cf2otel.api.method (rest or graphql) and, only on a failed HTTP exchange, cf2otel.error.class. HTTP 429 is rate_limited, HTTP 401/403 is auth, context deadlines and network timeouts are timeout, and other transport errors or HTTP 4xx/5xx responses are other. Followed HTTP redirects and HTTP 2xx responses carry no error class. Logical errors in HTTP 2xx envelopes, body reads and schema decoding are not transport-header outcomes; collector scrape errors and the separate envelope-error metric retain their existing semantics. No HTTP verb, route, URL, scope ID, query, status code or response/error text is an attribute on these three metrics. Registered collector names are trusted application identifiers, never populated from upstream responses.

Duration runs from the start of the HTTP call through response headers or a transport error. Limiter wait measures that hop's process-budget acquisition before the HTTP call (including the negligible immediate-acquisition time), excluding retry backoff and response-body processing. Both use the explicit second boundaries: 0.25, 0.5, 1, 1.5, 2, 3, 4, 5, 7.5, 10, 15, 20, 30, 45, 60, 90, 120. Metrics emit directly, even when the collector later fails or retains its checkpoint; they do not measure successful logical polls or rows. Existing cf2otel.api.request spans and cf2otel.api.retries retain their status-class attributes; spans retain the HTTP verb on cf2otel.api.method. Aggregate request queries remain valid, but the old request/duration cf2otel.status_class dimension is replaced by the bounded dimensions above.

Source deny-lists¶

The source deny-list settings use exact semantic names from this inventory before Prometheus translation. otlp.metric_denylist suppresses SDK registration/observation; otlp.attribute_denylist removes keys from every signal attribute bag, including generated event_name and nested span bags, but not resources or bodies. Both default to empty. Denying event_name removes the usual event-name log query selector, not the log signal. Dropping dimensions merges counter/histogram series and loses their distinction; gauge and retained-snapshot collisions use the last input point. Denying metrics does not disable their collectors or upstream reads.

Public vendor status¶

Both public status collectors are opt-in and off by default. They use an isolated unauthenticated HTTP client, not the tenant Cloudflare API client.

The gauge carries only string cloudflare.status.component.name (public vendor name) and cloudflare.status.component.type (group, component, or reserved remainder). Distinct (name,type) labels are sorted lexically; duplicates take the worst numeric status. Up to statuspage.component_cap ordinary series (default 500) are retained, plus one name=other,type=remainder series with the worst status of all overflow rows. The reserved type cannot collide with real components named other. No component IDs or guessed region labels are emitted; status codes are not averaged. A successful full snapshot replaces all points, including clearing retired components or a valid empty array. TTL is three configured polling intervals; failed reads do not refresh it. Absence or expiry is unavailable state, not proof of health.

Incident logs carry string attributes cloudflare.status.incident.id, .name, .status, .impact, and cloudflare.status.update.id, .status. These identifiers never become metric labels. Body text is capped at 8192 UTF-8 bytes without splitting a rune. cloudflare.status.update.truncated is the string enum "true" when clipped; an unclipped body leaves it absent (consumers may also accept "false"). It is not a boolean attribute. Duplicate update IDs at the same source timestamp emit once per response, while edited revisions with a new timestamp emit separately. There is no publication-latency holdback or persistent seen-ID ledger. Successful commits advance the durable checkpoint to the source bound (UTC seconds), including empty polls; restarting with FileStore does not reemit committed updates. Newly visible updates whose updated_at is at or older than that checkpoint are intentionally not emitted. Late older updates may therefore be missed even while still on the latest page. A newer revision after restart is emitted. Selected updates retain the scheduler's at-least-once commit semantics; partial export/checkpoint failures can replay them.

Components and incident windows are independent: a valid component snapshot can publish while incident delivery is unavailable. Neither channel establishes the other's freshness. The vendor's latest-50 limit can permanently omit off-page updates after an outage or a busy period. No complete backfill or arbitrary-latency once-only guarantee is claimed. The Workers and platform dashboard tab includes a component status table and an incident-update log panel with all status attributes. Prometheus translates the unit-1 gauge to cloudflare_status_component_status_ratio; the suffix does not mean an availability ratio. Its instant query may retain a last sample during Prometheus lookback after SDK snapshot expiry. No live runtime enablement or dashboard provisioning is implied.

Zone selection and poll gauges¶

zones.exclude (or comma-separated CF2OTEL_ZONES__EXCLUDE) defaults to empty. Selectors match exact zone IDs or case-insensitive zone names, with no regex or wildcard expansion. Each zone consumer first applies its existing include and account-ownership rules and validates them, then removes excluded zones. An unmatched exclusion is ignored; an unmatched include still has its existing behavior. A valid selection entirely removed by exclusions is a successful empty zone poll. Account-level queries, including Logpush's account scope, are unchanged.

The four cf2otel.zones.* gauges use only cf2otel.collector; filtered and skipped also use cf2otel.zone.reason. Reasons are bounded to include, exclude, unentitled, no_account, and other. Discovered counts the API discovery result; filtered counts zones removed by selection; processed counts distinct zones actually queried, not settings reads, query subdivisions, or datasets; skipped counts remaining eligible zones not queried. No zone name or ID is a gauge label. Every successful complete poll emits zero for absent reason series. Failed polls retain the existing no-partial-output behavior and do not refresh these gauges.

WARP recently seen fleet¶

cloudflare.warp.devices is a Gauge with unit 1, from account-scoped GET /accounts/{account}/dex/fleet-status/devices, source last_seen. It counts unique devices within warp.last_seen_window (default 15 minutes, maximum 60), not the total physical or licensed fleet. Network status strings are preserved as observed; there is no documented connected/active Boolean classification.

Its five string dimensions are cloudflare.warp.status, cloudflare.warp.platform, cloudflare.warp.client_version, cloudflare.warp.mode, and cloudflare.warp.colo. A sixth string attribute, cloudflare.warp.remainder, is false on normal tuples and true on overflow. Normal tuples are sorted lexically, retaining the first warp.max_metric_series (default 500); excess tuples and tuples containing a dimension longer than 256 bytes are summed into one all-other remainder. This preserves the device total and distinguishes a real all-other tuple from overflow. Empty dimension strings remain observed empty strings. No device ID, user identity, timestamp, raw body, log, trace or additional metric is emitted. IDs exist only during a poll for identical-tuple deduplication; conflicting duplicate IDs fail the whole snapshot.

Pages are fetched in ascending order, respecting a server page size at most 50, until a short/empty page (including an empty read after a full final page). Reported totals are not completion proof. Invalid/missing/null required strings, malformed arrays, HTTP failures, mismatched paging, stalled full pages or the 10,000-page/100,000-unique-device safety bounds fail without partial publication or expiry refresh. Successful empty arrays clear previous points; successful snapshots expire after three actual configured collector intervals.

This opt-in collector uses the existing expiring SDK snapshot batch emitter, never ordinary cumulative Gauge fallback. The row shape is doc-derived from the official device method and pinned by local fixtures. The root's current canary observed only successful empty rows (doc-0003, section 16); populated rows and real fleet pagination are not live-verified. Dashboard delivery is a separate pending work item.

DEX test results¶

The opt-in dex.tests snapshot collector emits the following Gauges from provider .avg values. It does not recompute slot statistics or query individual hops.

All points have only string attributes cloudflare.dex.test.name and cloudflare.dex.test.kind (http or traceroute). No account, device or test ID, URL, address, raw body, log or trace is exported. A named test must start with an ASCII letter and contain only ASCII letters, digits, spaces, underscores and hyphens, at most 128 characters; reserved other and other names go to the remainder. Operators must still avoid sensitive names. Duplicate name/kind pairs with distinct IDs fail catalog enumeration instead of merging or labeling by ID.

dex.max_metric_series bounds sticky named identities plus six reserved signal/kind remainders across polls until restart. Overflow points have test name other and preserve test kind. Their value is the arithmetic mean of the available per-test provider averages for that signal/kind, not a weighted fleet statistic. Missing/null optional averages are omitted, not fabricated as zero; finite nonnegative values are required, with percentages at most 100. Invalid results fail only that test. See configuration for cap allocation, failure isolation and expiry semantics.

The catalog is GET /accounts/{account}/dex/tests/overview, with tests[] containing id, name and kind, fully enumerated at 50 rows per page. Detail reads use GET /accounts/{account}/dex/http-tests/{test} or GET /accounts/{account}/dex/traceroute-tests/{test}, with UTC millisecond ISO from/to and interval=minute. The default result window is one hour, bounded to seven days, with no detail pagination. Provider averages keep their documented units exactly. Shapes come from the official HTTP test result method and traceroute result method, and are proved locally with fixtures, a real shared HTTP client and the SDK. The drift contract registers all three paths but reports both detail templates as documented_only, unprobed; no live tests exist. Only the list endpoint canary is live-probed. Populated/live-runtime proof and dashboard panels remain separate root-owned work; this source does not claim full task acceptance.

Workers AI aggregate metrics¶

The opt-in workersai.metrics collector reads account-scoped aiInferenceAdaptiveGroups, not raw inference rows. It emits additive Counters from complete UTC five-minute half-open buckets, with no metric attributes:

Count and bucket time are required; optional sums are selected only when advertised and within the field limit. Missing/null optional values are omitted, not zero-filled. Empty windows emit no fabricated metrics. Counts and sums add across successful windows; a malformed value or saturated single bucket fails the whole window without checkpoint advancement or partial publication. Query limits and dataset duration/retention are respected, with saturated windows bisected at five-minute boundaries. The existing platform series cap applies. No model/resource ID, tag, cost, byte metric, log or trace is selected or emitted.

The scheduler holds back ten minutes and aligns its upper bound to a complete five-minute bucket. This is operational policy, not a guarantee of ingestion latency or recovery of late arrivals after a checkpoint has advanced. Dashboard panels and live canary/proof delivery are separate root-owned work.

Logs and traces¶

Loki stores the OTLP log attributes as structured metadata. Filter from {service_name="cf2otel"}, then use | event_name="cloudflare.http.request" or another event value. Paths, IPs, emails, user agents and ray IDs stay on logs or spans, never on metric series.

Extension declarations (collector implementations pending)¶

These declarations reserve the following signals; this seam-only change does not emit them. Existing outputs remain unchanged. Every selection uses advertised settings.availableFields names in part_field form and respects field budgets, maxDuration and notOlderThan. Health checks are disabled on Free and enabled on the verified Pro plan; disabled scopes are skipped, not queried. HTTP visits are available on Free/Pro adaptive Groups. Threat rollups have observed retention of about three days on Free and seven days on Pro, with a three-day maximum query duration on both. Account adaptive HTTP settings permit 32 days, sufficient for a 31-day UTC month. Zone Logpush settings permit one day on Free and seven on Pro (retention includes about one extra hour); account Logpush permits about 30 days. Account DO/D1/Queue settings permit 32-day windows and 90-day retention. These are observed plan settings, not universal guarantees; runtime settings remain authoritative. No new permission or resource is provisioned.

Metrics¶

The seat source is GET /accounts/{account}/access/users. Cloudflare's official Go SDK AccessUserListResponse defines access_seat and gateway_seat as boolean flags, separately from active device count. cf2otel preserves field presence: false is valid, but missing, null and nonboolean flags fail the scrape. Each successful full-list scrape emits exactly two gauge points, including two zeros for a genuinely empty list. A user with both flags contributes one to each type. Existing cloudflare.access.users inventory is unchanged.

Platform gauges select the latest complete five-minute source bucket and emit at export time. D1, KV, Durable Objects and Queue base gauges use the globally latest bucket across resources, then MAX within each resolved name or remainder; older resource buckets are not carried forward. R2 keeps its per-resource latest-bucket behavior. Base counters SUM within each resolved name or remainder. Queue averages still require the advertised queue ID for correct per-queue statistics; missing required fields fail before query, emission or checkpoint advancement. The emitter attaches the listed UCUM units to OTLP instruments. RUM timing values are converted from source microseconds to seconds before recording. The GenAI operation histogram and poller API/scrape histograms use explicit second-based buckets, including sub-second boundaries. Scrape duration includes 300-second and longer boundaries through 7200 seconds, so polls exceeding the five-minute cadence remain measurable; API request and limiter-wait boundaries are unchanged. Queue IDs are used only inside source aggregation and are never metric attributes.

Prometheus compatibility naming adds _seconds for s when the base name lacks it and _ratio for dimensionless gauges. Names already ending in _bytes retain that suffix, and annotated {token} and {request} units add no suffix. The generated Grafana dashboard (dashboards/cf2otel.json, built by grafana/build_dashboard.py) queries only the suffixed names.

AI Gateway metrics combine Cloudflare request outcome measurements with GenAI duration and usage conventions.

AI Gateway token usage falls back to a complete, untruncated captured JSON response when the gateway input or output count is zero or missing. Supported shapes are Workers AI result.usage.input_tokens/output_tokens, top-level usage.input_tokens/output_tokens, and Chat Completions usage.prompt_tokens/completion_tokens. Each positive gateway count stays authoritative; request logs, GenAI spans and token counters/histograms share the resolved values. A missing or zero total is recomputed only when both counts are known and their sum fits in a signed 64-bit integer. Negative, fractional, non-numeric and overflowing body counts are rejected. Non-JSON, unavailable and truncated bodies supply no fallback. This requires ai_gateway.capture_bodies; no extra API reads are made and capture limits stay in force. Usage source is absent when no body count is used. Costs are not inferred from token counts. Previously committed rows are not reprocessed; compare post-deployment source windows after checkpoint lag has recovered.

cloudflare.ai_gateway.log_coverage.gap comes from the separate aigateway.coverage collector, which is off by default. REST gateway logs stay the primary AI Gateway source; requests sent with log collection off, or dropped by gateway log limits or retention, never appear there, while aiGatewayRequestsAdaptiveGroups still counts them. Each commit compares one closed, aligned five-minute window ending at least 10 minutes before now, held back past the measured 139-365 s Groups ingestion lag, and reports one value per configured gateway: positive means Groups counted requests the REST log lacks, zero means the sources agree, and negative means Groups is behind REST. The Groups selection is count and dimensions.gateway, checked against the dataset's availableFields; a window older than the dataset's notOlderThan is skipped as a retention gap. The REST count pages the gateway log list and counts distinct log IDs. A failed commit retries the same window, and the gauge value for a window never accumulates. The collector polls every five minutes and commits five-minute windows whatever interval and max_window say, so each steady-state poll commits and exports one window; a poll that lands before the next window closes does nothing. During catch-up after an outage or at first start, several windows can commit before one metric export, so the exported gauge carries the newest committed window. An explicit collection range refuses any window that ends inside the 10-minute holdback. It also refuses a range spanning more than one closed five-minute window: the collector always registers with a five-minute max_window, so only an explicit -since/-before range (not the steady-state poll) can ask for more, and exporting just the first window while reporting success would silently hide the rest of the requested range. Request one five-minute window per call instead. Enable it in YAML with enabled, interval, initial_lookback and max_window under collectors.aigateway.coverage, or use environment overrides such as CF2OTEL_COLLECTORS__AIGATEWAY_COVERAGE__ENABLED=true; configuration validation still requires a positive interval and max_window.

The retired AI Gateway dashboard's Data boundaries panel was static provenance guidance; Gateway metadata exceptions was a row grouping failed-request and DLP tables, not a separate API field. The AI Gateway Logs API inventory sampled on 2026-09-26 found no data-boundary or exception fields in 50 log-detail rows. Of that sample, 24 rows had a non-null dlp_action (FLAG), each with one dlp_profiles finding checking either the request (23) or the response (1); dlp_action maps to flagged (FLAG), blocked (BLOCK) or other (any other non-empty value), and a request with an action but no findings still counts once on cloudflare.ai_gateway.dlp.requests with direction other.

Attributes¶

D1/KV/Queue/Durable Objects base metrics resolve IDs through read-only account list endpoints. Successful and failed name lookups are cached for one hour, shared within each domain. Requests start at 50 rows per page and follow server-capped page sizes, up to 100 pages and 5000 rows. Only a complete, consistent list is published; a later-page or refresh failure replaces any expired mapping with a failed state, yielding other for one hour rather than retaining stale names indefinitely. Blank, invalid UTF-8, over-128-character, reserved other, unknown and ambiguous names yield other; IDs never become a fallback label. Optional unavailable grouping fields yield a safe remainder; required Queue statistics fields remain mandatory.

Each affected base metric admits 49 normal complete attribute sets for the collector lifetime plus one reserved other set (50 total). Admission stays sticky across windows, bounding cumulative SDK series growth until restart. R2 operations count the bucket/action pair, so different actions on one bucket remain distinct until capped; the canonical remainder sets every present resource/action dimension to other and conserves counter sums (gauge remainder is MAX). The existing total platform per-window cap defaults to 500 and applies deterministic full-attribute ordering when truncation is necessary. Existing metric names, units and depth quantile selections are unchanged; percentiles are never averaged. Operator-defined resource names may be sensitive: review them before export. Dashboard panels and live/canary entitlement proof are separate root-owned work.

Only bounded attributes should be used to group metrics. cloudflare.access.identity.inferred=true means a time, host and IP correlation, not a Cloudflare-provided identity on the HTTP event.

Declared name inventory¶

This exhaustive inventory is keyed to the internal/semconv declarations. It includes attributes that may appear only when the source API returns their fields or body capture is enabled.

Loop 14 attribute seams¶

Collector scrape error classes¶

Registration seeds cf2otel.scrape.errors with one zero-valued point per registered, enabled collector, using cf2otel.error.class="other". This makes never-failing collectors visible without recording a failure. Window collectors also receive a zero-valued cf2otel.window.commit_failures point with only cf2otel.collector; actual commit failures continue to carry their existing signal and retry/dropped outcome dimensions. Disabled collectors get no seed, and disabling periodic self-observability snapshots does not disable these registration points. Dry-run does not export or persist them.

cf2otel.scrape.errors remains a monotonic counter with unit 1: each failed collector attempt adds one, grouped by cf2otel.collector and the bounded cf2otel.error.class attribute. Successful attempts do not add an error. No raw error message, upstream field name, response body or HTTP code becomes an attribute.

Classification follows typed errors through wrappers. Explicit typed entitlement errors take precedence over HTTP status: unavailable GraphQL fields or disabled datasets are unentitled. HTTP 429 is rate_limited; HTTP 401/403 is auth unless a typed entitlement error is present. Context deadline exhaustion and network timeout errors are timeout. GraphQL field-limit errors and JSON syntax or type errors are schema. Retention gaps, saturated windows, cancellation, other HTTP failures and unknown errors are other; message text is never used to infer a class. Classification observes failures without changing retries, permission handling, checkpoint decisions or collector scheduling.

The full classification above applies to collector scrape errors, not export errors or scrape duration/success metrics. Physical-request metrics use the transport-only subset documented above. Existing aggregate queries can continue to sum scrape errors across classes. This is the code/documentation portion of CFO-0051.03 (classify collector errors); the dashboard panel is delivered separately.

Opt-in HTTP colo, ASN and safe error routes¶

All three toggles are absent by default. Per-feature/zone lexical caps conserve counts in one remainder, and every point counts against the existing complete-window HTTP cap. An optional exact host allowlist filters only these features and adds no host label. See configuration for limits, normalizer behavior and failure semantics. Dashboard delivery is a separate signal batch.

Load balancer provider health flag¶

The opt-in loadbalancers.health snapshot reads only the documented direct optional result.pop_health.healthy property of the pool health method. This is an unattributed provider-reported health flag, not regional aggregate pool availability: true maps to 1, false to 0, absent/null is unknown and omitted. No region, origin health, origin RTT, weights or rule totals are inferred. The current documented RTT example has an explicit ms suffix, but stable regional and origin attribution is still undocumented and remains unimplemented.

Configured pool names are the only labels, bounded to 128 UTF-8 bytes with no controls. Internal pool IDs are request-only; no identifier/address fallback. The existing platform series cap reserves one other slot and sticky named admission until restart. other is the minimum of known flags among excluded pools (any observed unhealthy flag yields 0), excluding unknowns; it is not a complete fleet health guarantee. Failures and unknown flags can leave coverage incomplete. Snapshots expire after three poll intervals. A valid empty catalog clears them; a valid subset atomically replaces them, omitting unknown and failed pools. All failed reads retain original expiry. An all-unknown valid response clears prior known values and returns an unknown-coverage error, never a healthy classification.

The pool catalog is live-probed by the drift canary and allows empty accounts. Health detail is explicitly documented_only, fixture-only and unprobed because root preparation observed no live pools. Populated runtime health and regional/origin joins remain unverified. The original regional/origin health and RTT acceptance criterion remains incomplete; the request-count addition below does not waive it.

Load balancer pool request counts¶

The existing disabled-by-default loadbalancers.health toggle also collects documented count grouped by dimensions.selectedPoolName from zone-scoped loadBalancingRequestsAdaptiveGroups. Requests mean uncached load-balancer resolutions, not all HTTP requests. No raw Adaptive row counting or sample-interval multiplication is used. The gauge represents the trailing configured polling interval, with half-open [from,to) bounds rounded out to whole source seconds. It replaces, rather than accumulates, overlapping polls; use the value directly, never rate, increase, or a sum over successive snapshots. This is a polling snapshot, not a checkpointed backfill counter. Late-arriving data and polling outages may leave traffic unobserved.

The collector lists pools first. An empty account makes only the pool-list request, clears prior snapshots and makes no zone, health-detail or GraphQL requests. With pools, only zones belonging to the configured account (and existing cloudflare.zones allowlist, if set) are queried. Selections use settings.availableFields; an absent, disabled or explicitly unentitled dataset, or either missing required field, is a traffic no-op with no fabricated zero. Auth, transport, malformed settings/rows, saturation and unusable duration/retention/field/page limits remain errors, with no partial traffic publication or refresh of prior snapshot expiry. One strict singleton batch per eligible zone prevents silent field renegotiation from losing the pool grouping. The canary contract checks these two advertised fields, permits absent/disabled plans, and is proved only by local fake-upstream fixtures; no live dataset proof is claimed.

Public configured pool names are the only labels: no zone/account/pool ID, host, origin address or region is emitted. Names use the same 128-byte UTF-8/no-controls validation. Health takes priority within the existing combined platform series cap; remaining traffic slots admit pool names lexically, reserving one other slot. Traffic other is the sum of overflow counts, a literal pool named other, and historical names unresolved in the current catalog, never the health flag's minimum. If health exhausts the cap, traffic points are omitted. Counts from eligible zones are summed by pool; unentitled zones provide no contribution, so these are not necessarily complete account totals. Empty/denied valid traffic clears prior request counts. Both snapshots expire after three configured polling intervals. Regional/origin health and origin RTT remain explicitly unimplemented.

Completed poll diagnostics¶

cf2otel.poll.completed is one structured process-pipeline log per scheduler run, including successful, failed and shutdown-canceled runs. cf2otel.poll.outcome is success, error or canceled; cf2otel.collector is a registered collector name. Its JSON body includes wall durations (duration_seconds, collect_seconds, commit_lock_seconds, commit_seconds), committed_windows, committed_logs, committed_spans, and api request totals split into list_requests, detail_requests, body_requests and other_requests. HTTP failures are physical header/transport failures, including handled 404s. http_header_seconds_sum and limiter_wait_seconds_sum sum overlapping requests and must not be added to wall phases. Collection wall time includes body reading and decoding. Committed items are counted only after delivery, metric replay and checkpoint persistence succeed; partial exports, dropped windows and snapshots are not checkpointed item counts. A log count includes span-attached log records. These are telemetry records, not necessarily source rows.

The internal cf2otel.poll span parents operational API spans and correlates the completion log. Imported source spans keep their existing parentage. Operational traces use an independent exporter/processor with the same configured endpoint and resource under the existing provider lifecycle. Their export outcome uses cf2otel.export.signal=operational_traces, outside source-commit failure tracking. No SDK global provider, sampling or destination changes are introduced.