ContextQMD
Back to Openviking

Metrics

docs/en/api/09-metrics.md

0.3.143.0 KB
Original Source

Metrics

OpenViking exposes a /metrics endpoint for Prometheus, Grafana Agent, and other monitoring systems that scrape Prometheus exposition text.

Unlike /api/v1/observer/* and /api/v1/stats/*, /metrics is intended for:

  • machine scraping rather than human-oriented inspection
  • Prometheus exposition text rather than the standard JSON API wrapper
  • runtime health and service quality signals rather than business analytics

API Reference

metrics()

Export Prometheus metrics for the current process.

This endpoint is typically scraped by Prometheus on a schedule, but it is also useful for local debugging and manual inspection.

Authentication

  • In the current implementation, /metrics is not wired to get_request_context or other auth dependencies.
  • In other words, based on the current server code, /metrics is effectively a public scrape endpoint.
  • If access control is tightened later through a gateway, reverse proxy, or deployment policy, follow the actual deployment configuration.

HTTP API

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

If your deployment requires gateway- or proxy-level authentication, attach the required headers there, for example:

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

Response Format

On success, the endpoint returns text/plain; version=0.0.4; charset=utf-8 with Prometheus exposition text, for example:

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

When the metrics system is disabled, the endpoint returns:

  • HTTP status code: 404
  • Response body:
text
Prometheus metrics are disabled.

Example: Prometheus Scrape Config

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

If your deployment protects /metrics at the gateway layer, configure the scrape job with the required auth settings through your proxy, service discovery, or Prometheus auth options.

Notes

  • /metrics is meant for frequent scraping, so the exported metrics should remain low-cardinality and low-cost.
  • /metrics returns Prometheus text, not the standard OpenViking {status, result, time} JSON response format.
  • Analytics-oriented statistics such as memory health, staleness, or session extraction should remain under /api/v1/stats/*, not /metrics.
  • For human-readable component snapshots, prefer /api/v1/observer/*.