Module metrics 

APIs for integrating with the router’s metrics.

The macros contained here are a replacement for the telemetry crate’s MetricsLayer. We will eventually convert all metrics to use these macros and deprecate the MetricsLayer. The reason for this is that the MetricsLayer has:

• No support for dynamic attributes
• No support dynamic metrics.
• Imperfect mapping to metrics API that can only be checked at runtime.

New metrics should be added using these macros.

Prefer using _with_unit types for all new macros. Units should conform to the OpenTelemetry semantic conventions, some of which has been copied here for reference:

• Instruments that measure a count of something should only use annotations with curly braces to give additional meaning. For example, use {packet}, {error}, {fault}, etc., not packet, error, fault, etc.
• Other instrument units should be specified using the UCUM case sensitive (c/s) variant. For example, Cel for the unit with full name degree Celsius.
• When instruments are measuring durations, seconds (i.e. s) should be used.
• Instruments should use non-prefixed units (i.e. By instead of MiBy) unless there is good technical reason to not do so.

NB: we have not yet modified the existing metrics because some metric exporters (notably Prometheus) include the unit in the metric name, and changing the metric name will be a breaking change for customers.

Compatibility

This module uses types from the opentelemetry crates. Since OpenTelemetry for Rust is not yet API-stable, we may update it in a minor version, which may require code changes to plugins.

Examples

// Count a thing:
u64_counter!(
    "apollo.router.operations.frobbles",
    "The amount of frobbles we've operated on",
    1
);
// Count a thing with attributes:
u64_counter!(
    "apollo.router.operations.frobbles",
    "The amount of frobbles we've operated on",
    1,
    frobbles.color = "blue"
);
// Count a thing with dynamic attributes:
let attributes = vec![];
if (frobbled) {
    attributes.push(opentelemetry::KeyValue::new("frobbles.color".to_string(), "blue".into()));
}
u64_counter!(
    "apollo.router.operations.frobbles",
    "The amount of frobbles we've operated on",
    1,
    attributes
);
// Measure a thing with units:
f64_histogram_with_unit!(
    "apollo.router.operation.frobbles.time",
    "Duration to operate on frobbles",
    "s",
    1.0,
    frobbles.color = "red"
);

Functions

meter_provider

Returns the currently configured global MeterProvider.