Crate serde_prometheus

A serde implementation for Prometheus' text-based exposition format.

Currently this library only supports serialisation to Prometheus' format for exporting metrics but this might be extended to deserialisation later on down the line.

serde_prometheus will work with most metric libraries' structs out of the box, however some work may be required to get them into a format expected by Prometheus.

Metric names exposed in the format are derived from the value's name in the struct or map that contains it.

Basic Usage

#[derive(Serialize)]
struct HitCount(u64);

#[derive(Serialize)]
struct MetricRegistry {
    my_struct: MyStructMetrics
}

#[derive(Serialize)]
struct MyStructMetrics {
    hit_count: HitCount
}

let metrics = MetricRegistry {
    my_struct: MyStructMetrics {
        hit_count: HitCount(30)
    }
};

assert_eq!(
   serde_prometheus::to_string(&metrics, None, HashMap::new())?,
   "hit_count{path = \"my_struct\"} 30\n"
);

Global Labels

Global labels can be added to all metrics exported by serde_prometheus using the HashMap passed into serde_prometheus::to_string for example:

let mut labels = HashMap::new();
labels.insert("my_key", "my_value");

let serialised = serde_prometheus::to_string(&metrics, None, labels)?;
assert_eq!(serialised, "hit_count{my_key = \"my_value\", path = \"my_struct\"} 30\n");

Global Prefix

And a global prefix can be added to all metrics:

assert_eq!(
   serde_prometheus::to_string(&metrics, Some("my_prefix"), HashMap::new())?,
   "my_prefix_hit_count{path = \"my_struct\"} 30\n"
);

Metadata/key manipulation

Serde's newtype implementation is (ab)used by serde_prometheus to add metadata to serialised fields without breaking backwards compatibility with serde_json and such.

For example, serde_prometheus support has been added to metered-rs's histograms whilst still keeping the same JSON schema, it does this by using a call to serialize_newtype_struct in a struct's Serialize trait impl, the format for the type names is as follows:

keymodifiers|key=value,key2=value2

Modifiers can also be used in labels using a == like so:

|key3==modifiers

The path stack is reset for each label value, however after applying the key modifiers, it is retained when writing the path label itself.

The modifiers that can be used are:

Modifier	Description
<	Pops a value off of the path stack and prepends it to the name
!	Pops the last value off of the path stack and drops it

These can be combined and are read from left to right, for example:

struct HitCount(u64);
impl Serialize for HitCount {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        // metric name: include our key (hit_count), ignore the second (my_method), and include the third (my_struct)
        // metric meta: for the method_name, ignore our key (hit_count), include the second (my_method)
        serializer.serialize_newtype_struct("<!<|my_key=my_value,method_name==!<", &self.0)
    }
}

let metrics = MetricRegistry {
    my_struct: MyStructMetrics {
        my_method: MyMethodMetrics {
            hit_count: HitCount(30)
        }
    }
};

let serialised = serde_prometheus::to_string(&metrics, None, HashMap::new())?;
assert_eq!(
   serialised,
   // would be `hit_count{path = "my_struct/my_method"}` without the Serialize impl
   "my_struct_hit_count{my_key = \"my_value\", method_name = \"my_method\"} 30\n"
);

Enums

Error
TypeHint

Functions

to_string

Outputs a metered::MetricRegistry in Prometheus' simple text-based exposition format.