Viser – 类型安全的度量客户端

文档：

此库为在 Rust 库和应用程序中定义和报告度量提供了包装。它基于 prometheus-client 库，并增加了更高层次的/更优雅的功能。

功能

• 允许以惯用和类型安全的方式注册和报告度量。
• 允许通过访问其当前值来测试度量。(注意：尚未实现访问直方图度量数据的操作。)

度量是什么

度量是在一段时间内进行的数值测量。度量在应用程序中定义和收集，并报告给外部系统，例如 Prometheus，然后可以使用例如 Grafana 仪表板来访问它们。

Prometheus 和兼容系统支持 3 种主要 度量类型

• 计数器 是单调递增的整数值
• 仪表 是可以增加或减少的整数或浮点值。从逻辑上讲，报告的仪表值可以被视为有效，直到下一个值被报告。
• 直方图 是按可配置的桶计数的浮点值。从逻辑上讲，直方图观察某种概率分布，观察是瞬时的（与仪表值不同）。

所有类型的度量都可以提供 标签。每个标签集定义一个独立的度量。因此，标签空间应该相对较小。

除了这些主要类型之外，Prometheus 和此库还支持一个额外的 info 度量类型。它应该用于观察在程序生命周期内不更改的值（组件配置、应用程序版本/ git 提交等元数据等）。此度量类型的值编码为标签。从概念上讲，info 度量类似于具有恒定值 1 的仪表。

用法

将此添加到您的 Crate.toml 中

[dependencies]
vise = "0.2.0"

定义和报告度量

度量定义为结构体，每个字段对应一个度量或一组度量

use vise::*;
use std::{fmt, time::Duration};

/// Metrics defined by the library or application. A single app / lib can define
/// multiple metric structs.
#[derive(Debug, Metrics)]
#[metrics(prefix = "my_app")]
// ^ Prefix added to all field names to get the final metric name (e.g., `my_app_latencies`).
pub(crate) struct MyMetrics {
    /// Simple counter. Doc comments for the fields will be reported
    /// as Prometheus metric descriptions.
    pub counter: Counter,
    /// Integer-valued gauge. Unit will be reported to Prometheus and will influence metric name
    /// by adding the corresponding suffix to it (in this case, `_bytes`).
    #[metrics(unit = Unit::Bytes)]
    pub gauge: Gauge<u64>,
    /// Group of histograms with the "method" label.
    /// Each `Histogram` or `Family` of `Histogram`s must define buckets; in this case,
    /// we use default buckets for latencies.
    #[metrics(buckets = Buckets::LATENCIES, labels = ["method"])]
    pub latencies: LabeledFamily<&'static str, Histogram<Duration>>,
}

// Commonly, it makes sense to make metrics available using a static:
#[vise::register]
static MY_METRICS: Global<MyMetrics> = Global::new();

// Metrics are singletons globally available using the `instance()` method.
MY_METRICS.counter.inc();
assert_eq!(MY_METRICS.counter.get(), 1); // Useful for testing

let latency = MY_METRICS.latencies[&"test"].start();
// Do some work...
let latency: Duration = latency.observe();
// `latency` can be used in logging etc.

有关更多示例，请参阅 crate 文档。

测试度量

根据您如何报告指标（例如，是否使用全局状态），测试指标可能需要重构。

• 您可以在测试的逻辑中传递指标类型（的）引用，以便这些类型可以被注入并随后由测试进行检查。
• 或者，您的逻辑可能产生随后作为指标报告的统计数据（这可能对性能也有益）。在这种情况下，生成的统计数据可以通过测试进行检查。

最佳实践

另请参阅： Prometheus 指南

• 指标和指标标签应使用 snake_case 命名。（这应由 Clippy 执行并检查在 Metrics derive 宏中执行的检查。）
• 指标应以前缀或一系列前缀开头，描述拥有该指标的域/子域。前缀应由单个 _ 字符分隔。
• 带有单位的指标应具有相应的后缀（例如，_seconds）。如果您指定了其单位，则自动将该后缀添加到指标名称中；您必须不要手动指定它。
• 标签名称不应重复指标名称。
• 每个标签的标签值应具有合理的低基数。
• 如果标签值编码为字符串（而不是整数、整数范围等），则应使用 snake_case。
• Family 中的指标应具有统一的意义。如果可以在不涉及标签具体细节的情况下记录 Family，则通常您已经走上了正确的道路。

示例：RocksDB 大小指标

假设我们想报告我们应用程序中 RocksDB 实例的实时和总数据大小。我们可能想定义

• 仪表系列（因为数据大小在报告下一次大小之前逻辑上保持不变）
• ...使用 rocksdb_ 前缀
• ...为实时和总数据大小分别定义单独的系列（因为它们测量两个不同的事物）
• ...使用 db 和 cf 标签指定数据库 ID 和列族名称（数据库 ID 应全局唯一；列族可能在不同 db 值之间有所不同）
• ...使用 Unit::Bytes（因为数据大小以字节为单位）

因此，我们可能有以下指标

rocksdb_live_data_size_bytes{db="merkle_tree",cf="default"} 123456789
rocksdb_live_data_size_bytes{db="merkle_tree",cf="stale_keys"} 123456
rocksdb_total_data_size_bytes{db="merkle_tree",cf="default"} 130000000
rocksdb_total_data_size_bytes{db="merkle_tree",cf="stale_keys"} 130000

许可

根据您选择的以下条款进行分发

• Apache License，版本 2.0，（LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT 许可证（LICENSE-MIT 或 https://open-source.org.cn/licenses/MIT）

任选其一。