Iceberg REST Metrics API

A 2026 formalization of the Iceberg REST Catalog (IRC) specification that adds a dedicated telemetry-reporting endpoint — `POST /v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics` — through which compute engines (Spark, Trino, Flink, and other IRC-compliant clients) push query-level execution telemetry back to the catalog after a scan or commit completes. Reports are typed **ScanReport** (rows read, bytes processed, filter/query duration, snapshot read) and **CommitReport** (commit duration, added/removed files, operation type) payloads, each carrying a shared `trace-id` field so a single logical query's scan and any resulting commit can be correlated at the catalog layer, even across engine boundaries.

Before this endpoint, query-level cost, performance, and access telemetry lived wherever the compute engine chose to emit it — Spark UI, Trino's event-listener framework, Flink metrics — none of which the catalog could see or tie back to the RBAC/credential-vending decision it had already made to grant that engine table access. The catalog knew *who was authorized*; it had no record of *what they actually did*. The /metrics endpoint closes that loop: because every table load and credential vend already flows through the catalog, having engines report execution telemetry back through the same channel turns the catalog into the single place where access grants and actual usage can be joined — without instrumenting the compute layer at all.

Cost allocation per table/namespace/principal (bytes-processed billing without engine-side cost-tracking plugins); catalog-layer audit trails that tie a credential grant to the query that used it; security forensics (reconstructing what a compromised identity actually scanned, not just what it was authorized to scan); cross-engine query observability (one telemetry stream regardless of whether Spark, Trino, or Flink executed the query); SLA/performance monitoring without deploying per-engine listeners.