Monitoring

Monitoring

niks3 exposes Prometheus metrics at GET /metrics. The endpoint is unauthenticated, like /health; restrict it at the network layer if your server is publicly reachable.

# prometheus.yml
scrape_configs:
  - job_name: niks3
    static_configs:
      - targets: ["niks3.example.com:8080"]

Metrics

Metric	Type	Labels	Description
niks3_cache_objects	gauge	—	Live objects in the cache.
niks3_cache_logical_bytes	gauge	—	Uncompressed size of live objects (not the compressed size stored in S3).
niks3_pending_closures	gauge	—	Uploads in progress, not yet committed.
niks3_http_requests_total	counter	method, route, status	Requests by route and status.
niks3_http_request_duration_seconds	histogram	method, route	Request duration.
niks3_http_requests_in_flight	gauge	—	Requests currently being served.
niks3_db_connections_in_use	gauge	—	Connections acquired from the pool.
niks3_db_connections_max	gauge	—	Maximum pool size.
niks3_gc_runs_total	counter	result	GC runs (succeeded / failed).
niks3_gc_duration_seconds	histogram	—	GC run duration.
niks3_gc_objects_deleted_total	counter	—	Objects deleted by GC.
niks3_gc_last_run_timestamp_seconds	gauge	—	Unix time of last successful GC; absent until one completes after startup.

The standard Go (go_*) and process (process_*) collectors are also exposed.

Example queries

# HTTP error rate
sum(rate(niks3_http_requests_total{status=~"5.."}[5m]))
  / sum(rate(niks3_http_requests_total[5m]))

# 99th percentile request latency by route
histogram_quantile(0.99,
  sum by (le, route) (rate(niks3_http_request_duration_seconds_bucket[5m])))

# Connection pool saturation
niks3_db_connections_in_use / niks3_db_connections_max

# Alert: no successful GC in the last 24h
time() - niks3_gc_last_run_timestamp_seconds > 86400
  or absent(niks3_gc_last_run_timestamp_seconds)