Add metadata to metrics

[hlbarber]

Motivation

Closes #370

Changes

• Add &Metadata argument to the Recorder::register_* methods
• Add target: * and Level::* arguments to macros.
  • target defaults to module_path!()
  • Level defaults to Level::INFO.

TODO

• Add documentation
• Add info_counter!, warn_counter!, etc
• Improve test coverage

[hlbarber]

Posted this in a draft state to garner comments before polishing it up.

[tobz]

@hlbarber High-level thoughts: this is pretty straightforward, but the macros should probably look more like the tracing macros.

In and of itself, Metadata feels as straightforward as I imagined it to be, but the lack of macro examples and the copied approach of how the describe_* macros handle detecting the unit parameter have solidified my thoughts around the macros needing to handle this better and in a way that's entirely compatible with the current macros. This is separate from actually providing level-prefixed variants of the macros, which I'm still a little hesitant about.

Essentially, what I'd want to see is:

• target and level require a struct field notation in the macro arguments (like tracing)
• metric name is always the first argument
• parse the remaining arguments as either the "fixed function" target or level fields, or as labels (label parsing logic stays as-is)
• cannot specify target or level after we've parsed something label-like (set a flag once we see the first non-target/level arg, basically)

Or with examples:

register_counter!("metric_name");
register_counter!("metric_name", "label_a" => "...");
register_counter!("metric_name", target: "overridden");
register_counter!("metric_name", level: Level::TRACE, &some_vec_of_labels);
register_counter!("metric_name", target: "overridden", level: Level::Info, "service" => "foo");

Ultimately, seeing this PR, I'd say that you could keep going with everything else on your list but hold off on the info_counter! stuff. If you're willing to take a crack at the procedural macro changes I've proposed above, that'd be good to. Otherwise, I would likely submit those as changes directly to your PR in the next week or two.

[hlbarber]

tracing::span and tracing::event, in order, accepts:

• Optional target: target: {target}
• Required level: Level::{LEVEL}
• Required name: "{name}" (for span!)

This implementation, in order, accepts:

• Optional target: target: {target}
• Optional level: Level::{LEVEL} (for backwards compatibility)
• Required metrics name: "{name}"
• ...

register_counter!("metric_name");
register_counter!("metric_name", "label_a" => "...");
register_counter!(target: "overridden", "metric_name");
register_counter!(Level::TRACE, "metric_name", &some_vec_of_labels);
register_counter!(target: "overridden", Level::Info, "metric_name", "service" => "foo");

target and level require a struct field notation in the macro arguments

I can change level: Level::{LEVEL} or make Level::{LEVEL} required (like tracing) - either of these will avoid the "unit parameter approach" (which I agree should perhaps be avoided). I think the struct field notation helps for optional fields.

Side note: Perhaps the unit parameter should be struct field notation too? Maybe this allows these macros to be done declaratively rather than procedurally.

metric name is always the first argument

Can do, but this seems like a departure tracing where

macro_rules! span {
    (target: $target:expr, parent: $parent:expr, $lvl:expr, $name:expr) => { ... };
    (target: $target:expr, parent: $parent:expr, $lvl:expr, $name:expr, $($fields:tt)*) => { ... };

[tobz]

I can change level: Level::{LEVEL} or make Level::{LEVEL} required (like tracing) - either of these will avoid the "unit parameter approach" (which I agree should perhaps be avoided). I think the struct field notation helps for optional fields.

Right, I want level to use the struct field notation because it it's optional.

Side note: Perhaps the unit parameter should be struct field notation too? Maybe this allows these macros to be done declaratively rather than procedurally.

The hard-coded bits of the describe_*! macros are going away with the rework to metric "attributes" -- #337 (comment) -- so I would just ignore that for the moment.

Can do, but this seems like a departure tracing where

Fair point. I wasn't thinking we'd necessarily mirror everything about how the tracing macros do it, but I suppose all named optionals having to come first would make parsing easier, especially if we attempted to rewrite the macros to be declarative.

I'm also not against doing that either -- proc macros are heavy -- but it might need to be staged as an improvement that comes after this and metrics attributes, because those two items get rid of the grossest parts of the procedural macros, which is the wishy-washy handling of specific positional arguments (i.e. is this arg a Unit? let's check some hardcoded paths).

Let's stick with the current tracing-inspired approach for now.

[tobz]

After sitting down and going over this, I feel a lot better about the nature of the change and what we're adding.

Left two small comments.

[tobz]

Left one little doc comment thing, and it looks like this needs to have cargo fmt run on it, but overall very close. 👍🏻

[tobz]

Looks like this needs to be changed to something like [metrics macros][metrics_macros] and then add [metrics_macros]: https://docs.rs/metrics/latest/metrics/#macros at the bottom of the overall doc comment.

I don't think there's a way to do intradoc links with just a crate name, but it's also cleaner/more intuitive, I think, to link the macros section of the metrics crate since that's where people will be consuming them from.

[tobz]

I'm going to try and take a look, in a few days, at just finalizing the remaining requested changes myself since it's so close.

[hlbarber]

"Rust / feature-check" is throwing a note: /usr/bin/ld: final link failed: No space left on device, any suggestions?

[tobz]

LGTM.

The feature check CI step has been finicky lately with "out of disk space" errors cropping up a lot. I just check this stuff manually before cutting releases and it's usually fine, so just gonna ignore it for now.