metrics.rs

Overview

This file defines the RoutingMetrics struct, which encapsulates telemetry metrics related to routing operations in the system. It provides a structured way to record and report different types of metrics, including histograms for measuring durations and counters for event counts. The metrics are designed to be used with an OpenTelemetry meter, enabling detailed monitoring of routing performance and request handling.

RoutingMetrics Struct

Description

RoutingMetrics holds several OpenTelemetry metric instruments used to track routing-related metrics:

• ext_msg_delivery_duration: A histogram measuring the duration of external message delivery in microseconds.

• ext_msg_processing_duration: A histogram measuring the duration of external message processing, bucketed by configured boundaries, tagged with HTTP status codes.

• boc_by_address_response: A histogram measuring response durations for "BOC by address" requests, similarly bucketed and tagged.

• state_request: A counter tracking the number of state requests received.

The struct is marked Clone to allow duplication of metric handles.

Fields

Methods

new(meter: &Meter) -> RoutingMetrics

Creates and initializes a new RoutingMetrics instance using the provided OpenTelemetry Meter.

• Parameters:

  • meter: Reference to an OpenTelemetry Meter used to create metric instruments.

• Returns: A fully initialized RoutingMetrics struct with histograms and counter instruments.

• Implementation Details:

  • Defines fixed histogram boundaries [50.0, 100.0, ..., 15000.0] for bucketing durations.

  • Uses the meter to build histograms and counters with meaningful metric names.

  • Histograms for processing duration and BOC responses are configured with these boundaries for precise latency tracking.

• Example Usage:

  let meter = /* get meter from OpenTelemetry provider */;
  let metrics = RoutingMetrics::new(&meter);
  

report_ext_msg_delivery_duration(&self, value: u64)

Records a single measurement of external message delivery duration.

• Parameters:

  • value: Duration value in microseconds to record.

• Returns: ()

• Behavior:

  • Uses the out_of_bounds_guard! macro to validate that the value is within acceptable bounds before recording.

  • Records the value in ext_msg_delivery_duration histogram without any additional labels.

• Example Usage:

  metrics.report_ext_msg_delivery_duration(120);
  

report_ext_msg_processing_duration(&self, value: u64, http_code: u16)

Records the duration of processing an external message, with an associated HTTP response code label.

• Parameters:

  • value: Duration value in microseconds.

  • http_code: HTTP status code to tag the measurement.

• Returns: ()

• Behavior:

  • Applies bounds check on the duration.

  • Records the value in the ext_msg_processing_duration histogram, tagging the metric with a key-value pair "code" set to the string representation of the HTTP code.

• Example Usage:

  metrics.report_ext_msg_processing_duration(300, 200);
  

report_boc_by_address_response(&self, value: u64, http_code: u16)

Records the duration of "BOC by address" response times, tagged with HTTP status code.

• Parameters:

  • value: Duration in microseconds.

  • http_code: HTTP status code label.

• Returns: ()

• Behavior:

  • Checks bounds on the value.

  • Records in the boc_by_address_response histogram with "code" label.

• Example Usage:

  metrics.report_boc_by_address_response(450, 404);
  

report_state_request(&self)

Increments the counter for received state requests by one.

• Parameters: None

• Returns: ()

• Behavior:

  • Simply increments the state_request counter by 1 without any labels.

• Example Usage:

  metrics.report_state_request();
  

Implementation Details

• The file uses the opentelemetry crate's metrics API for instrument creation and recording.

• The macro out_of_bounds_guard! from telemetry_utils is used to ensure recorded metric values are within valid ranges to prevent invalid telemetry data.

• Histograms use predefined bucket boundaries to categorize latency/duration metrics, aiding in latency distribution analysis.

• HTTP codes are attached as labels to histograms to enable filtering and aggregation by response status.

• The Clone trait on RoutingMetrics allows safe duplication of the metrics handle for use across threads or components.

Interaction With Other Components

• This metrics module interacts primarily with the telemetry subsystem, relying on an OpenTelemetry Meter instance provided externally.

• It is expected to be used by routing or networking components that handle external messages, state requests, and BOC queries, enabling them to report performance and usage metrics.

• The out_of_bounds_guard! macro is defined in telemetry_utils, which is a utility module ensuring metric values are validated before recording.

• Metrics collected here can be exported to monitoring backends for visualization and alerting as part of the system's observability framework.

Visual Diagram

classDiagram
class RoutingMetrics {
+ext_msg_delivery_duration: Histogram<u64>
+ext_msg_processing_duration: Histogram<u64>
+boc_by_address_response: Histogram<u64>
+state_request: Counter<u64>
+new(meter: &Meter) RoutingMetrics
+report_ext_msg_delivery_duration(value: u64)
+report_ext_msg_processing_duration(value: u64, http_code: u16)
+report_boc_by_address_response(value: u64, http_code: u16)
+report_state_request()
}
RoutingMetrics ..> Meter : uses to create metrics
RoutingMetrics ..> Histogram : contains
RoutingMetrics ..> Counter : contains
RoutingMetrics ..> "telemetry_utils::out_of_bounds_guard!" : uses