指标与 Metrics

OpenViking 提供 /metrics 端点，用于向 Prometheus、Grafana Agent 等监控系统导出运行时指标。

与 /api/v1/observer/* 和 /api/v1/stats/* 不同，/metrics 的定位是：

面向机器抓取，而不是面向人工阅读
返回 Prometheus exposition 文本，而不是统一 JSON 包装
偏系统运行态与服务运行质量，不承担业务分析接口职责

API 参考

metrics()

导出当前进程内的 Prometheus 指标文本。

该端点通常被 Prometheus 定时抓取，也可以用于本地调试或手工排查。

认证

当前实现中，/metrics 未接入 get_request_context 等鉴权依赖，因此可直接访问。
也就是说，从代码实现角度看，/metrics 当前等价于公开抓取端点。
如果后续通过网关、反向代理或服务端策略收紧访问控制，应以实际部署配置为准。

HTTP API

GET /metrics

bash

curl -X GET http://localhost:1933/metrics

如果你的部署环境在网关或代理层要求鉴权，可以按网关要求附加请求头，例如：

bash

curl -X GET http://localhost:1933/metrics \
  -H "Authorization: Bearer your-key"

响应格式

成功时返回 text/plain; version=0.0.4; charset=utf-8，内容为 Prometheus exposition 格式文本，例如：

text

# HELP openviking_http_requests_total Total number of HTTP requests
# TYPE openviking_http_requests_total counter
openviking_http_requests_total{method="GET",route="/api/v1/system/status",status="200"} 12

# HELP openviking_http_inflight_requests Number of inflight HTTP requests
# TYPE openviking_http_inflight_requests gauge
openviking_http_inflight_requests{route="/api/v1/system/status"} 0

当指标系统未启用时，返回：

HTTP 状态码：404
响应体：

text

Prometheus metrics are disabled.

示例：Prometheus 抓取配置

yaml

scrape_configs:
  - job_name: openviking
    metrics_path: /metrics
    static_configs:
      - targets: ["localhost:1933"]

如果你的部署环境对 /metrics 做了网关鉴权，可以通过反向代理、service discovery，或 Prometheus 支持的鉴权方式为该抓取任务配置请求头。

注意事项

/metrics 适合高频抓取，因此其中的指标应保持低基数、低成本。
/metrics 返回的是 Prometheus 文本，不是标准 OpenViking API 的 {status, result, time} JSON 结构。
业务分析类统计（如 memory health、staleness、session extraction）应继续使用 /api/v1/stats/*，而不是迁移到 /metrics。
人工查看组件瞬时状态更适合使用 /api/v1/observer/*。

指标与 Metrics ​

API 参考 ​

metrics() ​

相关文档 ​

指标与 Metrics

API 参考

metrics()

相关文档