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

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

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

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:

# 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:

Prometheus metrics are disabled.

Example: Prometheus Scrape Config

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/*.

Related Documentation

• System and Monitoring - Health checks, system status, and Observer APIs
• API Overview - Shared conventions for all API endpoints