指标收集 API

OnePath 的指标（metrics）API 参考。提供原子计数器（counter）、瞬时值（gauge）、对数分桶直方图（histogram）三类指标的注册与更新，以及统一的快照拉取接口。本页仅覆盖 metrics 部分，分布式链路追踪 Span API 见 Span/Trace API。

两个变体均支持

metrics 子系统在 full 与 tiny 两个变体下行为一致，无需额外配置。

指南视角（内置指标清单、自动埋点、限制与注意事项）见 分布式追踪与指标。

数据类型

onepath_counter_t / onepath_gauge_t / onepath_histogram_t

typedef struct onepath_counter   *onepath_counter_t;
typedef struct onepath_gauge     *onepath_gauge_t;
typedef struct onepath_histogram *onepath_histogram_t;

三类指标的不透明句柄，分别由 onepath_counter_register() / onepath_gauge_register() / onepath_histogram_register() 返回。用户不可解引用，句柄生命周期由库管理。

onepath_metric_sample_t

typedef struct {
    const char     *name;            /* 指标名 */
    const char     *description;     /* 描述 */
    int             type;            /* ONEPATH_METRIC_* */

    /* Counter / Gauge */
    int64_t         value;           /* counter 累计值; gauge 当前值 */

    /* Histogram */
    uint64_t        hist_count;      /* 观测次数 */
    uint64_t        hist_sum;        /* 观测值累加 */
    uint64_t        hist_min;        /* 最小值 */
    uint64_t        hist_max;        /* 最大值 */
    const uint64_t *hist_buckets;    /* 32 个桶计数数组 (仅 type=HISTOGRAM 有效) */
    size_t          hist_bucket_count;
} onepath_metric_sample_t;

快照项，由 onepath_metrics_snapshot() 在遍历时通过回调传给用户。hist_buckets 指向库内部数组，仅在回调期间有效，回调返回后不可继续使用。

选项与初始化

onepath_metrics_opts_t

typedef struct {
    const char *ndjson_path;    /* 定期输出 snapshot 到 NDJSON, NULL 禁用 */
    uint32_t    flush_ms;       /* NDJSON flush 间隔, 默认 5000 */
} onepath_metrics_opts_t;

ONEPATH_METRICS_OPTS_DEFAULT

#define ONEPATH_METRICS_OPTS_DEFAULT { NULL, 0 }

onepath_metrics_opts_t 的默认初始化宏。

onepath_metrics_init

int onepath_metrics_init(const onepath_metrics_opts_t *opts);

初始化 metrics 子系统。

• 参数：opts — 选项指针，传 NULL 表示默认（注册表可用，不自动导出）
• 返回值：ONEPATH_OK 成功
• 注意：首次 onepath_*_register() 时若 ONEPATH_METRICS_ENABLE=1 会自动 lazy init

onepath_metrics_shutdown

void onepath_metrics_shutdown(void);

关闭 metrics 子系统，释放资源。

函数

Counter

onepath_counter_register

onepath_counter_t onepath_counter_register(const char *name, const char *description);

注册或获取一个计数器。

• 参数：name — 指标名（稳定键）；description — 描述文本，可为 NULL
• 返回值：句柄；若 metrics 未初始化返回 NULL（后续 API 均 no-op）
• 注意：按 name 幂等，第二次注册同名返回同一句柄

onepath_counter_add

void onepath_counter_add(onepath_counter_t c, int64_t delta);

累加计数器（原子）。

• 参数：c — 计数器句柄，NULL 被忽略；delta — 增量（可为负，实现为有符号原子加）

onepath_counter_inc

void onepath_counter_inc(onepath_counter_t c);

等价于 onepath_counter_add(c, 1)。

• 参数：c — 计数器句柄，NULL 被忽略

Gauge

onepath_gauge_register

onepath_gauge_t onepath_gauge_register(const char *name, const char *description);

注册或获取一个 gauge。语义同 onepath_counter_register()。

• 参数：name — 指标名；description — 描述，可为 NULL
• 返回值：句柄；若 metrics 未初始化返回 NULL（后续 API 均 no-op）

onepath_gauge_set

void onepath_gauge_set(onepath_gauge_t g, int64_t value);

设置 gauge 的当前值。

• 参数：g — gauge 句柄，NULL 被忽略；value — 当前值

onepath_gauge_add

void onepath_gauge_add(onepath_gauge_t g, int64_t delta);

对 gauge 当前值做增量调整。

• 参数：g — gauge 句柄，NULL 被忽略；delta — 增量

Histogram

onepath_histogram_register

onepath_histogram_t onepath_histogram_register(const char *name, const char *description);

注册直方图（32 个对数桶）。

• 参数：name — 指标名；description — 描述，可为 NULL
• 返回值：句柄；若 metrics 未初始化返回 NULL（后续 API 均 no-op）

onepath_histogram_observe

void onepath_histogram_observe(onepath_histogram_t h, uint64_t value);

观测一个值。

• 参数：h — 直方图句柄，NULL 被忽略；value — 观测值（通常是 μs 级延迟，但单位由用户决定）

快照导出

onepath_metric_cb

typedef void (*onepath_metric_cb)(const onepath_metric_sample_t *sample, void *userdata);

快照遍历回调函数原型。

onepath_metrics_snapshot

void onepath_metrics_snapshot(onepath_metric_cb cb, void *userdata);

遍历所有已注册指标的当前值，对每个同步调用 cb。

• 参数：cb — 回调函数；userdata — 透传给回调的用户数据指针
• 注意：遍历期间持注册表读锁，允许并发 observe。库不内置 HTTP 服务器，应用通过此函数拉取快照后按需对接 Prometheus / 日志 / 共享内存 / OTLP 等

常量与枚举

指标类型（ONEPATH_METRIC_*）

常量	值	含义
ONEPATH_METRIC_COUNTER	1	计数器（单调累计）
ONEPATH_METRIC_GAUGE	2	瞬时值（可增可减）
ONEPATH_METRIC_HISTOGRAM	3	对数分桶直方图

直方图分桶

直方图固定为 32 个对数桶，按 2 的幂次划分（单位由用户决定，通常 μs）：

bucket[0]  = [1,    2)        us
bucket[1]  = [2,    4)        us
bucket[2]  = [4,    8)        us
...
bucket[i]  = [2^i,  2^(i+1))  us
...
bucket[31] = [2^31, 2^32)     us

即 bucket[i] = [2^i, 2^(i+1)) us。小于 1 的值归入 bucket[0]，达到或超过 2^32 的值归入 bucket[31]。快照中 hist_buckets 数组长度恒为 32（hist_bucket_count == 32）。

内存与所有权

• onepath_counter_t / onepath_gauge_t / onepath_histogram_t 句柄由库内部管理，按 name 幂等去重；句柄一旦注册即长期有效，直至 onepath_metrics_shutdown()，用户无需也无需接口手动销毁单个句柄。
• 传入 NULL 的句柄给任意写入 API 均为 no-op，安全。
• metrics 未初始化时，三个 _register 返回 NULL，整套 API 退化为零开销 no-op，无需在调用点做条件判断。
• onepath_metrics_init() 的 opts 仅在调用期间被读取，调用返回后即可释放或复用，库不持有其指针。
• onepath_metric_sample_t 及其 hist_buckets 数组仅在 onepath_metric_cb 回调执行期间有效；如需在回调外保留，请自行拷贝所需字段，回调返回后原指针失效。

相关指南

• 分布式追踪与指标 — 内置指标清单、自动埋点、限制与注意事项