refactor!: make global core optional, add derive macro, add MetricsGroup and MetricsGroupSet traits, reoganize modules

[Frando]

Description

• Makes the static superglobal Core optional behind the new static_core feature. The macros to modify metrics tracked in the static core, inc, inc_by, etc are also behind this feature flag now.
• Makes the Metric trait dyn-compatible, and renames it to MetricsGroup. The name method now takes &self. Adds a register(&self, registry: &mut Registry) method to the Metric trait to register already-constructed metrics to a prometheus-client registry. The new method is moved to a new trait MetricsGroupExt which is auto-impl'd for all types that impl MetricsGroup.
• Adds a new Metric trait that is implemented on Gauge and Counter to provide a common interface.
• Adds a custom trait and derive macro Iterable that works similar to struct_iterable, but returns an iterator over &dyn Metric and does not allocate for iteration. Removes the struct_iterable dependency.
• Adds a derive macro MetricsGroup that expands to the Iterable impl and also implements Default by calling FieldType::new(description) for each field, where description is the first line of the field's doc comment, or a custom string set via #[metrics(description = "my description")]. Also implements MetricsGroup, with a name of either the struct name converted to camel_case, or a custom name set via #[metrics_group(name = "my_name")]
• Adds a trait MetricsGroupSet that can be implemented on structs that contain multiple structs which each implement Metric. Requires a method groups(&self) -> impl Iterator<Item = &dyn MetricsGroup> to iterate over all contained metric structs. Provides a method register(&self, registry: &mut Registry) which uses iter to register all contained metrics onto a prometheus-client registry. Provides a method iter(&self) -> impl Iterator<Item = (&'static str, &dyn MetricItem> to iterate over all metric items from all contained groups.
• Modifies the functions to start services (start_metrics_service, start_metrics_dumper, start_metrics_exporter) to take a impl MetricsSource as additional required argument. When the static_core feature is enabled, you can pass the zerosized GlobalRegistry struct, which impls MetricsSource and exposes all metrics contained in the static Core. When not using the static core, you can either pass a Registry or an Arc<RwLock<Registry>> to run the services for a regular registry created in application code.

Breaking Changes

Most import paths changed, but apart from that it is mostly API additions. Migration should be straightforward.

• iroh_metrics::core::{Counter, Gauge} are now iroh_metrics::{Counter, Gauge}
• iroh_metrics::core::Metric is now iroh_metrics::MetricsGroup.
  • MetricsGroup::name now takes &self as argument
  • MetricsGroup::new is removed.
• metrics::{start_metrics_server, start_metrics_exporter, start_metrics_dumper} is now service::{start_metrics_server, start_metrics_exporter, start_metrics_dumper}. They all take a registry argument, which takes any T: impl MetricSource. For the old behavior of using the static Core, pass the zero-sized struct static_core::GlobalRegistry.
• iroh_metrics::core::Core is now at iroh_metrics::static_core::Core and behind the static_core feature flag (not enabled by default)
• The macros inc, inc_by, set, dec, dec_by are now behind the static_core feature flag (not enabled by default)
• iroh_metrics::core module is removed
• struct_iterable::Iterable is no longer exported from iroh-metrics, and is no longer a supertrait of MetricsGroup
  • instead, MetricsGroup now has iroh_metrics::Iterable and iroh_metrics::IntoIterable supertraits. They can be implemented manually, but it is recommended to use the new MetricsGroup or Iterable derive macros exported from iroh_metrics. See their docs for details.
  • There is now a iroh_metrics::MetricsGroup derive macro that includes the functionality previously provided by struct_iterable.

Notes & open questions

Change checklist

• Self-review.
• Documentation updates following the style guide, if relevant.
• Tests if relevant.
• All breaking changes documented.

[github-actions]

Documentation for this PR has been generated and is available at: https://n0-computer.github.io/iroh-metrics/pr/15/docs/iroh_metrics/

Last updated: 2025-04-14T10:49:00Z

[Arqu]

Just a small typo comment, this is great stuff!

[Arqu]

👍

[Frando]

Thanks for the review!

One thing I'm wondering, while we're already doing breaking API changes: To me the trait Metric is a bit confusing, because it sounds like it defines a single metric, whereas it does define a group of metrics. So I'm wondering if we should rename it: Metric would become MetricsGroup, and the new MetricSet would become MetricsGroupSet. To me this is more fitting - wdyt @Arqu?

[Arqu]

Yeah, that makes sense, at least it should have been a plural like Metrics.
I'd say go for it, given we don't change this code all that often.

[Frando]

I went ahead with the rename: Metric-> MetricsGroup, MetricSet -> MetricsGroupSet

[Frando]

@Arqu @dignifiedquire
Should we go forward with this?
Once merged, I think we'd need a release as well, so that we can update downstream crates (net-tools, iroh, iroh-*) to use the new release, merge their PRs (I'll add the remaining) and then be coherent again on the next iroh release. Or wdyt?

[Arqu]

I don't see a reason not to, we already decided we want to move forward with it.

[dignifiedquire]

LFG