charlesdong1991 commented on code in PR #617: URL: https://github.com/apache/fluss-rust/pull/617#discussion_r3430698347
########## website/docs/user-guide/rust/metrics.md: ########## @@ -0,0 +1,179 @@ +--- +sidebar_position: 5 +--- +# Metrics + +The Fluss Rust client is instrumented with client-side metrics for the connection +layer, the write pipeline, and the read (scanner) pipeline. Metrics are emitted +through the [`metrics`](https://docs.rs/metrics) crate facade, so collecting them is +opt-in and costs nothing until you install a recorder. + +## How it works + +The client never decides *where* metrics go. It only emits them via the `metrics` +facade. Your application installs a global **recorder** (for example a Prometheus +exporter), and that recorder decides how to store and expose the values. + +- **No recorder installed** — every metric call is a zero-cost no-op. This is the + default, so the client adds no overhead unless you opt in. +- **Recorder installed** — values flow to whatever backend the recorder represents + (Prometheus, StatsD, OpenTelemetry, a test recorder, etc.). + +This differs from the Fluss Java client, where metric reporters are configured +server-side in `conf/server.yaml` (`metrics.reporters: jmx,prometheus`) and +discovered through plugins. The Rust client instead follows the idiomatic Rust +`metrics` ecosystem: the application owns recorder installation, and rate +computation is left to the backend (e.g. PromQL `rate()`) instead of a built-in +background rate thread. + +## Installing a recorder + +Use any [`metrics`-compatible exporter](https://docs.rs/metrics/latest/metrics/#related-crates). +The example below uses `metrics-exporter-prometheus` to expose a scrape endpoint: + +```rust +use metrics_exporter_prometheus::PrometheusBuilder; + +PrometheusBuilder::new() + .with_http_listener(([0, 0, 0, 0], 9000)) + .install() + .expect("failed to install Prometheus recorder"); +``` + +A full, runnable program is available as the `example-prometheus-metrics` example +in the `fluss-examples` crate. + +:::warning Install the recorder before writing or scanning +The client caches metric handles the first time a writer or scanner is created, +binding them to whichever recorder is installed at that moment. Install your global +recorder **before** calling `FlussConnection::new` (ideally as the very first thing +in `main`). If you install it after creating a writer or scanner, those metrics will Review Comment: i think returning an error isn't workable because "no recorder installed" is a supported mode most users run in, so writer/scanner creation can't fail just because no recorder is present Also metrics facade has no hook to detect "installed too late". The only alternative is to stop caching handles and re-resolve per record, and that will have hot-path cost so we should try to avoid. wdyt? i can also some more explanation on that in this doc 🙏 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
