docs(observability): store every OTLP metric in one table and query it with time-series functions

[spiceemma]

spiceai/spiceai#15066 added a metrics store: a sink: dataset with params.otlp_metrics: all receives every OTLP metric in one table with a fixed schema, including exponential histograms and summaries. The PR also added an OTLP/HTTP receiver at POST /v1/metrics and three SQL aggregates for metrics: histogram_quantile, increase, and rate. Before this change, the Data Ingestion page described only per-metric datasets (one dataset per metric name, with a column per attribute) received over gRPC.

The new sections sit beside the OTLP logs docs in #2378 without touching the same lines. git apply --check of the #2378 diff on top of this branch applies cleanly.

Pages changed

• website/docs/features/data-ingestion/index.md: the OpenTelemetry section now introduces both kinds of dataset and adds "Sending metrics" (gRPC and POST /v1/metrics, with a Collector otlphttp example), "Metrics store" (configuration, export outcomes, schema, and querying with histogram_quantile, increase, and rate), and a "Per-metric datasets" heading. The existing per-metric subsections move under that heading one level down. Their heading text, and so their anchors, are unchanged.

Versioned docs

vNext only. The merge commit d836f804 is in no release tag (git tag --contains returns nothing), not in v2.4.0-rc.1 or v2.4.0-rc.2, and opentelemetry_store.rs is not on release/2.4. Versioned docs are unchanged.

Verification

Trunk SHA 9a25991b0384c7fc6b25fc838d6d71ce6f65ea57.

• Reproduced: the param name is otlp_metrics with value all: pub const OTLP_METRICS_PARAM: &str = "otlp_metrics"; (crates/runtime/src/opentelemetry_store.rs:49)
• Reproduced: the schema columns and types match METRICS_STORE_SCHEMA, for example Field::new("series_hash", DataType::UInt64, false), (crates/runtime/src/opentelemetry_store.rs:75)
• Reproduced: the metric_type values include "exponential_histogram", (crates/runtime/src/opentelemetry_store.rs:596). Sums, histograms, and exponential histograms carry temporality, and only sums carry is_monotonic (crates/runtime/src/opentelemetry_store.rs:583-601).
• Reproduced: the function names are pub const HISTOGRAM_QUANTILE_UDAF_NAME: &str = "histogram_quantile"; (crates/runtime-datafusion-udfs/src/timeseries.rs:40), with "increase" and "rate" defined at lines 41 and 42.
• Reproduced: the HTTP route is pub(crate) const METRICS_PATH: &str = "/v1/metrics"; (crates/runtime/src/http/v1/otlp.rs:49), and the limit is pub(crate) const MAX_DECOMPRESSED_BODY_BYTES: u64 = 128 * 1024 * 1024; (crates/runtime/src/http/v1/otlp.rs:137)
• Reproduced: the store-failure message is "Failed to write to the OpenTelemetry metrics store; retry the export", (crates/runtime/src/opentelemetry.rs:256)
• Reproduced: the warning for a store dataset that is not writable is "OpenTelemetry metrics store dataset {} is not writable. Set \access: read_write` on it to store metrics.",` (crates/runtime/src/opentelemetry.rs:341)
• Observed, not isolated: the store accepts every metric type without per-metric datasets, per-metric datasets still receive their metric, and a failed store write falls back to per-metric routing. This comes from the opentelemetry::tests in the source PR's CI: feat: store and query OTLP metrics as time series spiceai#15066
• Observed, not isolated: histogram_quantile matches hand-computed Prometheus values and rejects mixed bucket layouts, and increase/rate handle counter resets and integer counters. This comes from the timeseries::tests in the source PR: feat: store and query OTLP metrics as time series spiceai#15066
• Unverified, code inspection only: a store write failure returns gRPC UNAVAILABLE / HTTP 503 after the per-metric fallback, read-only keys get 403 on POST /v1/metrics, and a (time_unix_nano, series_hash) primary key on Cayenne stores a retried export once. No spiced build containing this change was run, and the installed release binary predates it.
• Unverified, code inspection only: both SQL examples (date_bin with histogram_quantile, and rate grouped by series_hash) and the Collector otlphttp example were not executed. The Collector example defines its otlp receiver (added in review); it was checked against the Collector configuration reference, not validated with a Collector binary.
• build: npm run build in website/ passed locally ([SUCCESS] Generated static files in "build"., exit 0; no broken links or anchors reported)

[github-actions]

✅ Pull with Spice Passed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected
• ✅ Has at least one assignee: spiceemma

[github-actions]

🔍 Pull with Spice Failed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected

Failed checks:

• ❌ At least one assignee is required for this pull request.

Please address these issues and update your pull request.

[github-actions]

🔍 Pull with Spice Failed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected

Failed checks:

• ❌ At least one assignee is required for this pull request.

Please address these issues and update your pull request.

[github-actions]

🔍 Pull with Spice Failed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected

Failed checks:

• ❌ At least one assignee is required for this pull request.

Please address these issues and update your pull request.

[github-actions]

🔍 Pull with Spice Failed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected

Failed checks:

• ❌ At least one assignee is required for this pull request.

Please address these issues and update your pull request.

[Copilot]

🟡 Changes recommended

The Collector example references an undefined receiver and fails configuration validation as written.

1 open finding

• Define the missing OTLP receiver referenced by the metrics pipeline · New

What changed in this PR

Documents the new OTLP metrics store alongside existing per-metric ingestion in the unversioned documentation.

Changes:

• Describes gRPC and HTTP ingestion with a Collector example.
• Adds metrics store configuration, schema, export behavior, and SQL examples.
• Groups existing documentation under “Per-metric datasets” while preserving anchors.

File	Description
website/​docs/​features/​data-ingestion/​index.md	Documents metrics storage, ingestion, and time-series queries.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

🚀 deployed to https://bdc181d4.spiceai-org-website.pages.dev

[Copilot]

🟢 Approved

The documentation matches the referenced implementation, and no unresolved blocking issues remain.

0 open findings

1 resolved since last review

• Define the missing OTLP receiver referenced by the metrics pipeline

🧠 Review effort: Balanced

[github-actions]

🚀 deployed to https://514cd835.spiceai-org-website.pages.dev