OpenViking /metrics 端点实战：接入 Prometheus、Grafana 的机器化监控体系

OpenViking /metrics 端点实战接入 Prometheus、Grafana 的机器化监控体系【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 通过一个面向机器抓取的/metrics端点把运行健康、请求质量、模型用量与探针状态暴露为 Prometheus exposition 文本供 Prometheus、Grafana Agent 等系统周期性拉取。本篇以该端点的 API 行为为主线串联其底层四层架构DataSource → Collector → MetricRegistry → Exporter、server.observability.metrics配置项与account_id租户维度策略帮助你在生产环境中把 OpenViking 接入完整的监控告警链路。一、端点定位为什么用/metrics而不是 Observer/StatsOpenViking 同时提供三类可观测出口它们的输出格式与目标人群不同出口目标输出格式典型用途/metrics机器抓取、高频Prometheus exposition 文本Grafana 面板、告警规则、趋势聚合/api/v1/observer/*人类查看组件快照JSON / 状态表调试、健康检查/api/v1/stats/*分析型统计JSON记忆健康度、陈旧度、会话抽取从 API 参考 与 Metrics 概念文档 的口径一致可以看出/metrics只承载低基数、低成本指标专门服务于监控、告警、容量观察与回归诊断而分析型统计仍留在/api/v1/stats/*不受 Prometheus 抓取模型约束。这套边界在源码里有明确落地。/metrics路由定义在 metrics.py其职责非常纯粹# openviking/server/routers/metrics.py router.get(/metrics) async def metrics(request: Request): Return Prometheus metrics in text exposition format. exporters getattr(request.app.state, metrics_exporters, []) prometheus_exporter next( (e for e in exporters if isinstance(e, PrometheusExporter)), None, ) if prometheus_exporter is None: return PlainTextResponse(status_code404, contentPrometheus metrics are disabled.\n) return PlainTextResponse( contentawait prometheus_exporter.export(), media_typetext/plain; version0.0.4; charsetutf-8, )这段代码印证了文档中的两个关键事实成功时返回text/plain; version0.0.4; charsetutf-8的 Prometheus 文本当 Prometheus exporter 未启用时返回 HTTP404与Prometheus metrics are disabled.文案。二、认证与调用方式认证现状在当前实现中/metrics没有挂载get_request_context或任何鉴权依赖因此从代码路径看它是一个公开的抓取端点。这一点在路由源码里可以确认——它只依赖Request对象未注入任何 auth 依赖。若你后续通过网关、反向代理或部署策略收紧访问控制请以实际部署配置为准。基本调用GET /metricscurl -X GET http://localhost:1933/metrics带网关/代理层鉴权的调用如果你的部署在网关层保护了/metricscurl -X GET http://localhost:1933/metrics \ -H Authorization: Bearer your-key响应示例成功时返回 Prometheus exposition 文本# HELP openviking_http_requests_total Total number of HTTP requests # TYPE openviking_http_requests_total counter openviking_http_requests_total{methodGET,route/api/v1/system/status,status200} 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注意/metrics返回的是 Prometheus 文本而不是 OpenViking 标准{status, result, time}JSON 响应封装。人类可读的组件快照请优先使用/api/v1/observer/*。Prometheus 抓取配置scrape_configs: - job_name: openviking metrics_path: /metrics static_configs: - targets: [localhost:1933]如果你的部署在网关层保护了/metrics请通过代理、服务发现或 Prometheus 的鉴权选项为该抓取任务配置所需的鉴权。三、四层架构从业务事件到 exposition 文本理解/metrics为什么“既便宜又稳定”关键在于它的四层管线。这一管线在 Metrics 概念文档 中有完整示意也与源码结构一一对应业务逻辑 / HTTP 请求 / 后台任务 │ ▼ DataSource 事件发射 / 状态读取 │ ▼ Collector 语义路由 标签 │ ▼ MetricRegistry 进程内指标存储 │ ▼ Exporter Prometheus 文本渲染 │ ▼ /metrics对应源码目录为 openviking/metrics其中datasources/、collectors/、core/、exporters/四个子目录分别承载上述四层。DataSource两种输入形态DataSource 以两种方式向指标系统提供输入事件型Event-based业务代码在关键节点发射事件如检索完成、模型调用成功、资源摄取阶段完成。读型Read-based在/metrics导出前读取当前状态如队列状态、锁状态、探针状态。源码印证global_api.py 的_build_event_router把每个事件名绑定到一个 Collector例如http.request→HTTPCollector、embedding.call→EmbeddingCollector、retrieval.completed→RetrievalCollector、resource.stage→ResourceIngestionCollector。模块 docstring 明确说明业务代码调用 DataSource API 发射观测事件Collector 订阅这些事件并是唯一允许写入MetricRegistry的层——这保证了架构一致性。Collector语义路由与标签Collector 把输入转换为指标语义选择写入哪个指标、附加哪些标签、以及失败如何暴露例如valid1/0。MetricRegistry进程内存储进程内指标存储保存当前指标值并供给 exporter。ExporterPrometheus 文本渲染首个 exporter 实现即 Prometheus exporter。其源码 prometheus.py 揭示了两个对运维很重要的稳定性设计# openviking/metrics/exporters/prometheus.pyexport 方法核心 async def export(self) - str: if self._collector_manager is not None: try: await self._collector_manager.refresh_all( self._registry, deadline_secondsself._refresh_deadline_seconds, # 默认 1.0s ) except Exception: pass # 刷新失败被吞掉指标必须不破坏 /metrics 本身 return self.render()刷新是 best-effort 的每次导出前尝试刷新所有注册 Collector但任何刷新异常都会被吞掉确保某个子系统宕机也不会让/metrics不可用。空族渲染为单个零样本_process_counter_series/_process_gauge_series会在无样本且无标签时输出一个0样本_render_empty_histogram会输出全零 bucket从而让 Grafana 面板与告警查询在首个真实增量发生前保持稳定。Histogram 采用累计桶_render_histogram_series按 Prometheus 规范以累计方式导出桶计数并统一_count/_sum的标签排序以保证输出确定。此外render()还会导出openviking_metrics_dropped_series_total{metric...}诊断指标用于观测被丢弃的序列。四、核心指标族与常用标签以下是当前 openviking/metrics/collectors 中 Collector 暴露的代表性指标族源自 Metrics 概念文档按主题分组。请求与操作指标族类型常用标签含义openviking_http_requests_totalCounteraccount_id, method, route, statusHTTP 请求总数openviking_http_request_duration_secondsHistogramaccount_id, method, route, statusHTTP 延迟分布openviking_http_inflight_requestsGaugeaccount_id, route当前在途请求进程内近似openviking_operation_requests_totalCounteraccount_id, operation, status结构化操作总数openviking_operation_duration_secondsHistogramaccount_id, operation, status结构化操作耗时分布检索与资源处理指标族类型常用标签含义openviking_retrieval_requests_totalCounteraccount_id, context_type检索请求数openviking_retrieval_results_totalCounteraccount_id, context_type检索命中总数openviking_retrieval_latency_secondsHistogramaccount_id, context_type检索延迟分布openviking_retrieval_zero_result_totalCounteraccount_id, context_type检索零结果数openviking_retrieval_rerank_used_totalCounteraccount_id使用 rerank 的检索数openviking_retrieval_rerank_fallback_totalCounteraccount_idrerank 降级次数openviking_resource_stage_totalCounteraccount_id, stage, status资源摄取阶段计数openviking_resource_stage_duration_secondsHistogramaccount_id, stage, status摄取阶段耗时分布openviking_resource_wait_duration_secondsHistogramaccount_id, operation摄取等待时长分布如排队典型stage取值request、parse、summarize、persist、finalize、process。模型调用与 Token指标族类型常用标签含义openviking_model_calls_totalCountermodel_type, provider, model_name统一模型调用数openviking_model_tokens_totalCountermodel_type, provider, model_name, token_type统一模型 token 数openviking_vlm_calls_totalCounteraccount_id, provider, model_nameVLM 调用数openviking_vlm_tokens_input_total/_output_total/_totalCounteraccount_id, provider, model_nameVLM 输入/输出/总 tokenopenviking_vlm_call_duration_secondsHistogramaccount_id, provider, model_nameVLM 调用耗时分布openviking_embedding_requests_total/_errors_totalCounteraccount_id, status/account_id, error_codeembedding 请求/错误数openviking_embedding_latency_seconds/_call_duration_secondsHistogramaccount_id, status/account_id, provider, model_nameembedding 延迟openviking_rerank_calls_total/_call_duration_secondsCounter / Histogramaccount_id, provider, model_namererank 调用与耗时openviking_operation_tokens_totalCounteraccount_id, operation, stage, token_type操作级 token 归因openviking_model_*提供跨 embedding/VLM 的统一视图适合做全局用量openviking_vlm_*与openviking_embedding_*更适合按工作负载细分的面板。队列、锁、任务、会话指标族类型常用标签含义openviking_queue_processed_total/_errors_totalCounterqueue各队列处理/错误数openviking_queue_pending/_in_progressGaugequeue各队列待处理/进行中项openviking_lock_active/_waiting/_staleGauge无活跃/等待/可能陈旧的锁openviking_task_pending/_running/_completed/_failedGaugetask_type任务跟踪器各状态数openviking_cache_hits_total/_misses_totalCounterlevel缓存命中/未命中openviking_session_lifecycle_totalCounteraccount_id, action, status会话生命周期事件数openviking_session_contexts_used_total/_archive_totalCounteraccount_id, action/account_id, status会话上下文使用/归档探针与健康态指标族类型常用标签含义openviking_service_readinessGauge可能含valid主服务就绪度openviking_api_key_manager_readinessGauge可能含validAPI key 管理器就绪度openviking_storage_readinessGaugeprobe, valid存储探针如agfsopenviking_model_provider_readinessGaugeprovider, valid模型提供方就绪度openviking_async_system_readinessGaugeprobe, valid异步系统就绪度openviking_retrieval_backend_readinessGaugeprobe, valid检索后端就绪度openviking_encryption_component_healthGaugevalid加密组件整体健康openviking_encryption_root_key_ready/_kms_provider_readyGaugevalid/provider, valid根密钥/KMS 提供方就绪其中valid的含义贯穿各探针族valid1表示该样本由一次成功刷新产生valid0表示是降级或陈旧值应谨慎使用。常用标签语义标签含义示例account_id租户维度标签test-account、__unknown__、__overflow__routeHTTP 路由模板/api/v1/search/findmethodHTTP 方法GET、POSTstatus请求或阶段状态200、ok、erroroperation结构化操作名search.find、resources.add_resourcecontext_type检索上下文类型resourceprovider模型/外部服务提供方volcenginemodel_name模型名doubao-seed-1-8-251228stage阶段标签随指标族而异资源阶段parsetoken 归因阶段embed_queryvalid当前样本是否新鲜有效1/0补充要点account_id仅在受控的白名单指标族上启用以防止高基数增长valid0表示当前状态/探针样本是降级或陈旧值而非标签本身格式错误stage的语义依赖指标族openviking_resource_stage_*是资源摄取阶段openviking_operation_tokens_total是 token 归因阶段。五、配置详解开关、Exporter 与租户维度5.1 主开关与配置结构指标子系统通过server.observability.metrics显式启用。配置模型定义在 config.py 的MetricsConfig默认enabled: bool False即默认关闭必须显式打开{ server: { observability: { metrics: { enabled: true, account_dimension: { enabled: true, max_active_accounts: 100, metric_allowlist: [ openviking_http_requests_total, openviking_http_request_duration_seconds, openviking_http_inflight_requests, openviking_operation_requests_total, openviking_operation_duration_seconds, openviking_vlm_calls_total, openviking_vlm_call_duration_seconds, openviking_rerank_* ] } } } } }推荐的配置心智模型server.observability.metrics.enabled指标子系统总开关。server.observability.metrics.account_dimension控制是否启用account_id标签、以及允许在哪些指标族上启用。5.2 ExporterPrometheus 与 OTLP默认通过 Prometheus exposition 格式在/metrics导出指标也可在server.observability.metrics.exporters下启用其他 exporter。关键配置字段对应MetricsExportersConfig/OTelExporterConfigexporters.prometheus.enabled启用 Prometheus exporter提供/metrics默认true。exporters.otel.enabled启用从同一进程内 registry 的 OTLP 导出默认false。exporters.otel.protocolgrpc或http。exporters.otel.tls.insecure仅对 OTLP/gRPC 有效true表示明文无 TLS默认false。exporters.otel.endpointOTLP 端点gRPC 用host:4317HTTP 用完整 URL默认localhost:4317。exporters.otel.service_nameOTLPservice.name资源属性默认openviking-server。exporters.otel.export_interval_msOTLP 推送间隔毫秒默认10000。exporters.otel.headers可选自定义 OTLP 头gRPC 下作为 metadata、HTTP 下作为请求头发送。使用 gRPC 时headers中的键应为小写如x-byteapm-appkeyHTTP 无此限制。OTLP exporter 的实现见 otel.py它把同一个MetricRegistry序列化为 OTLP protobuf通过 HTTP 或 gRPC 推送且保留 histogram 的 bucket/count/sum 语义、不重新聚合。示例同时启用 Prometheus 与 OTLP/gRPC{ server: { observability: { metrics: { enabled: true, exporters: { prometheus: { enabled: true }, otel: { enabled: true, protocol: grpc, tls: { insecure: true }, endpoint: otel-collector:4317, service_name: openviking-server, export_interval_ms: 10000, headers: {} } } } } } }启动链路应用生命周期在 app.py 中调用init_metrics_from_server_config(config, appapp, serviceservice)当config.observability.metrics.enabled为真时日志打印Prometheus metrics enabled at /metrics。初始化过程见 global_api.py创建 registry、注册默认 Collector、构建事件路由、创建 exporter 并写入app.state.metrics_exporters关闭时则清空全局状态并重置租户维度运行时。5.3account_id租户维度策略这是防止 Prometheus 基数爆炸的核心机制实现于 account_dimension.py默认启用但仅白名单指标族会获得真实租户 id空 allowlist 时仍会得到__unknown__。解析优先级显式account_id HTTP 观测上下文 任务 owner见MetricAccountContextResolver.resolve。两级闸门支持集合ACCOUNT_DIMENSION_SUPPORTED_METRICS定义了哪些指标族可能参与租户标签注入不支持的指标即使配置开启也不会收到account_id标签。allowlist 闸门MetricAccountDimensionPolicy.resolve仅当“启用 指标名被 allowlist 放行 通过活跃账户上限”三者同时满足时才写入真实 id。上限与降级值当活跃账户数达到max_active_accounts默认100后新账户写入__overflow__未解析到 id 时写入__unknown__。白名单通配符仅支持尾随*前缀匹配如openviking_rerank_*、openviking_embedding_*不支持独立*也不支持完整 glob/正则。# openviking/metrics/account_dimension.pyresolve 关键分支 if not self._enabled: return UNKNOWN_ACCOUNT_ID # __unknown__ if not self._is_metric_allowlisted(metric_name): return UNKNOWN_ACCOUNT_ID normalized str(account_id or ).strip() if not normalized: return UNKNOWN_ACCOUNT_ID with self._lock: if normalized in self._active_accounts: return normalized if self._max_active_accounts 0 and len(self._active_accounts) self._max_active_accounts: return OVERFLOW_ACCOUNT_ID # __overflow__ self._active_accounts.add(normalized) return normalizedaccount_id使用建议默认启用但只有 allowlist 中的指标族会收到租户 id。不要将user_id、session_id、resource_uri做成标签。只在一小撮关键面板与告警指标上启用租户维度。metric_allowlist支持有限通配仅尾随*前缀匹配独立*与完整 glob/正则均不支持。5.4 VikingBot 反馈观测指标/metrics还包含源自抓取时对持久化会话数据做聚合的 VikingBot 反馈观测指标。由于 Collector 是从 bot 会话文件重算当前聚合快照而非在线累加计数器这些指标以Gauge形式导出。相关配置bot_data_path见 config.py 的MetricsConfig当配置了server.observability.metrics.bot_data_path时bootstrap.py 才会注册FeedbackCollector# openviking/metrics/bootstrap.py feedback_bot_data_path _resolve_feedback_bot_data_path(config) if feedback_bot_data_path is not None: manager.register(FeedbackCollector(bot_data_pathfeedback_bot_data_path))代表性反馈指标族均为 Gauge标签valid部分含channel指标族含义openviking_feedback_responses_total快照内持久化助手响应总数含旧契约外响应openviking_feedback_tracked_responses_total被当前反馈观测契约覆盖的响应数openviking_feedback_events_total显式反馈事件数openviking_feedback_thumb_up_total/_thumb_down_total点赞/点踩事件数openviking_feedback_coverage有显式反馈的被跟踪响应占比openviking_feedback_thumbs_up_rate/_thumbs_down_rate点赞/点踩占反馈事件比例openviking_feedback_one_turn_resolution_rate单轮解决占比openviking_feedback_reask_rate被追问占比openviking_feedback_channel_*各 channel 的变体典型 PromQL 用法openviking_feedback_coverage{valid1}openviking_feedback_thumbs_down_rate{valid1}openviking_feedback_one_turn_resolution_rate{valid1}检测降级快照valid0表示 Collector 在刷新失败后返回了上一次成功快照max by (job) (openviking_feedback_events_total{valid0})对混合历史数据请用openviking_feedback_tracked_responses_total作为比率面板的分母参考openviking_feedback_responses_total用于展示整体持久化助手响应量含早于当前反馈元数据契约的旧响应。六、设计约束与注意事项结合源码与文档/metrics在设计上遵循以下硬约束运维时应据此规划抓取频率与面板低基数、低成本/metrics面向高频抓取导出指标应保持低基数、低成本account_id仅在有界白名单指标族上启用见上文租户维度策略。刷新有预算PrometheusExporter的refresh_deadline_seconds默认1.0秒刷新失败被吞掉保证端点本身可用。探针类指标受 TTL/SWR 保护bootstrap.py 把 Collector 分为“每次抓取刷新无 TTL纯进程内读如队列/锁计数”与“TTL/SWR 保护可能触及更慢子系统如服务/模型探针、VikingDB 状态、聚合模型用量”两类避免/metrics因某个子系统抖动而不可用。格式边界/metrics返回 Prometheus 文本而非 OpenViking 标准 JSON 封装人类可读快照请用/api/v1/observer/*。告警建议当valid0持续出现时说明 Collector 正在返回上次成功快照刷新失败应作为数据新鲜度告警信号。七、落地检查清单在ov.conf中将server.observability.metrics.enabled置为true如需 OTLP 推送配置exporters.otel默认端口4317/4318。用curl http://localhost:1933/metrics验证 exposition 文本确认text/plain; version0.0.4; charsetutf-8与# HELP/# TYPE前缀。在 Prometheus 中按上文scrape_configs添加抓取任务若网关层保护/metrics在代理/服务发现层补上鉴权。按需配置account_dimension.metric_allowlist仅尾随*前缀通配把租户维度限定在少量关键指标上并用max_active_accounts控制基数上限。用valid1/0区分新鲜数据与降级快照为valid0的持续出现配置新鲜度告警。将面板与告警建立在低基数的请求/检索/模型/探针指标族上分析型统计仍走/api/v1/stats/*。延伸阅读Metrics 概念文档指标族、标签、反馈指标与 PromQL 示例。Metrics API本端点的 API 参考。指标系统设计方案指标系统设计细节。Grafana 演示看板 与 反馈基线看板可直接导入的面板参考。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考