Skip to content

Metrics API Quick Reference

Version: 2.0 (Installation-Wide Reporting)
Last Updated: February 2, 2026

Endpoints at a Glance

Endpoint Method Purpose Persists? IBM? Lock?
/api/metrics/preview GET View unbilled usage ❌ ❌ ❌
/api/metrics/report POST Generate JSON ❌ ❌ ❌
/api/metrics/send POST Persist reports ✅ ❌ ✅
/api/metrics/clear POST Cleanup ❌ ❌ ✅

Common Workflows

View Current Usage

curl http://localhost:8080/api/metrics/preview | jq

Generate and Review Report

# Step 1: Review (no persistence)
curl -X POST http://localhost:8080/api/metrics/report | jq

# Step 2: Persist if satisfied
curl -X POST http://localhost:8080/api/metrics/send | jq

Full Billing Cycle

# 1. Preview unbilled
curl http://localhost:8080/api/metrics/preview | jq

# 2. Send reports
curl -X POST http://localhost:8080/api/metrics/send | jq

# 3. Cleanup
curl -X POST http://localhost:8080/api/metrics/clear | jq

Response Codes

Code Meaning Action
200 OK Success Process response
204 No Content No data to process Normal - nothing to do
409 Conflict Lock held by another operation Wait and retry
500 Internal Server Error System error Check logs

Configuration Quick Start

Minimal Setup

# Required
METRICS_WINDOW_GRANULARITY: MONTH
IBM_METERING_ENABLED: false

IBM Mode

# Required
METRICS_WINDOW_GRANULARITY: HOUR
IBM_METERING_ENABLED: true
IBM_METERING_API_KEY: "your-key"
IBM_METERING_RESOURCE_ID: "your-resource"
IBM_METERING_RESOURCE_INSTANCE_ID: "your-instance"
IBM_METERING_PLAN_ID: "your-plan"

Debug Commands

# System status
curl http://localhost:8080/api/metrics/status | jq

# Check lock
redis-cli GET "EX8:PROD:COMMON:USAGE_METRICS:installation:lock"

# Check persisted UUIDs (tenant 123)
redis-cli SMEMBERS "EX8:PROD:COMMON:USAGE_METRICS:tenant:123:persisted"

# Force unlock (emergency)
redis-cli DEL "EX8:PROD:COMMON:USAGE_METRICS:installation:lock"

Key Concepts in 30 Seconds

  1. Installation-Wide: All operations process ALL tenants
  2. UUID Idempotency: Safe to retry, no duplicates
  3. Closed Windows Only: Only complete billing periods
  4. Distributed Locking: Prevents concurrent operations
  5. Permanent Audit Trail: UUIDs never deleted

Troubleshooting Checklist

  • [ ] Check if leader: curl /api/metrics/status
  • [ ] Check Redis connectivity: redis-cli PING
  • [ ] Check closed windows exist: curl /api/metrics/preview
  • [ ] Check lock status: redis-cli GET ...lock
  • [ ] Check logs: grep ERROR logs/app.log
  • [ ] Trigger pre-compute: curl -X POST /api/metrics/precompute/trigger

For complete documentation, see METRICS_SYSTEM.md