Hey Anand, The metrics endpoint and metrics reporting is intended to be best-effort and the RESTMetricsReporter implementation also ensures it does not bubble up any errors. I don't think we want reads/writes to fail just because the server couldn't store information about the scan/commit.
We document 204, 400, 401, 403, 404, 419, 503 and 5XX on the /metrics endpoint because those are all potential errors. It is up to the catalog implementation to decide whether to throw a 500 or just log an error. The catalog can also decide to discard metrics reports and return 204. Clients are not expected to retry, simply because it would increase the overall duration of a scan/commit and we don't want to negatively affect the read/write path. I'm not sure we need to update the wording in the spec. As I mentioned, it is up to catalog implementations to decide what to do and we don't want to be prescriptive. I hope that helps and answers your questions. Eduard On Tue, Nov 3, 2026 at 1:42 AM Anand Kumar Sankaran via dev < [email protected]> wrote: > Hi all, > > I'm a contributor to Apache Polaris. We have a question about the REST > catalog's metrics endpoint (POST > /v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics, > reportMetrics) that we'd like to settle with the Iceberg community before > changing server behavior. > > *Background* > > Polaris can persist metrics reports sent to this endpoint. Today, if the > database write fails, the endpoint returns a 500. A pending Polaris PR [1] > would log the failure, increment a drop counter, and return 204 instead. > The motivation is that a degraded metrics store shouldn't show up as a > catalog failure. The discussion on the Polaris dev list [2] has split on > this. > > > *What the spec says* > The spec defines the operation as "Send a metrics report to this endpoint > to be processed by the backend". It documents 204, 400, 401, 403, 404, 419, > 503 and 5XX. It doesn't say whether reporting is best-effort or whether a > catalog must signal a failure to process a report. It also doesn't say what > a client should do on a 5xx. > > *What clients do* > > As far as I know, the Java client's REST metrics reporter catches and logs > errors from this endpoint and does not retry. I haven't checked the other > implementations (PyIceberg, iceberg-rust, iceberg-go), so please correct me. > > *The two readings* > > *1. Best-effort telemetry.* The client sends the report and moves on. A > catalog may drop a report it can't persist, as long as it surfaces that to > operators. A 5xx tells the client nothing it can act on. > > *2. A normal REST write.* If the catalog can't process the report, it > says so with a 5xx, and clients may retry. This matters for anyone using > the reports for auditing or billing, though it only helps if clients > actually retry. > > *Questions* > > 1. Is reportMetrics intended to be best-effort? Is a catalog allowed to > accept a report and discard it, or fail to process it, without signaling > failure? > 2. If a catalog can't process a report, what should it return? Is 5xx the > expected answer, or is 204 acceptable? > 3. Should clients be expected to retry a failed report? If so, the spec > should say that. If not, it should say reporting is not guaranteed delivery. > 4. Should the spec state any of this in the endpoint description, so > implementations behave consistently? > > We'd like to follow whatever the community decides rather than invent > Polaris-specific behavior. I'm happy to send a spec PR with clarifying > wording once there's a direction. > > Thanks, > Anand > > [1] https://github.com/apache/polaris/pull/5395 > [2] https://lists.apache.org/thread/0r7fpq153d2ny0tbt162051dh0jv3wjb > > -- > [image: Workday Logo] <https://www.workday.com/> > Anand Kumar Sankaran > Sr Principal, Software Engineer (Distributed Systems) > Office of the CTO > [email protected] >
