Custom Metrics

The CustomMetricsController allows tenants to define, register, and query custom metrics beyond the platform's built-in metrics. Custom metrics enable application-level observability for business KPIs, feature usage, and domain-specific measurements.

Register a Custom Metric

Endpoint: POST /api/v1/observability/custom-metrics

curl -X POST http://localhost:8088/api/v1/observability/custom-metrics \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Tenant-ID: 550e8400" \
  -d '{
    "name": "conversation_satisfaction_score",
    "type": "gauge",
    "description": "Average user satisfaction score for AI conversations",
    "unit": "score",
    "labels": ["service", "model"],
    "aggregation": "average"
  }'

CustomMetric Structure

Field	Type	Description
`id`	String	Metric identifier
`name`	String	Metric name (Prometheus-compatible)
`type`	String	`counter`, `gauge`, `histogram`, `summary`
`description`	String	Human-readable description
`unit`	String	Unit of measurement
`labels`	List	Label names for the metric
`aggregation`	String	Default aggregation method
`retentionDays`	int	How long to retain the metric data

Metric Types

Type	Description	Use Case
`counter`	Monotonically increasing value	Total requests, errors, events
`gauge`	Value that can go up or down	Current temperature, queue depth
`histogram`	Distribution of values in buckets	Request duration, payload sizes
`summary`	Quantile calculations	Response time percentiles

Record Metric Data

Endpoint: POST /api/v1/observability/custom-metrics/:metricName/data

curl -X POST http://localhost:8088/api/v1/observability/custom-metrics/conversation_satisfaction_score/data \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Tenant-ID: 550e8400" \
  -d '{
    "value": 4.5,
    "labels": {
      "service": "ai-service",
      "model": "gpt-4"
    },
    "timestamp": "2026-02-12T10:30:00Z"
  }'

Query Custom Metrics

Endpoint: GET /api/v1/observability/custom-metrics/:metricName/query

Parameter	Type	Default	Description
`start`	Instant	1 hour ago	Query start time
`end`	Instant	now	Query end time
`step`	String	`1m`	Step interval
`aggregation`	String	metric default	Aggregation function
`labels`	Map	none	Label filters

Custom Metric Management

Method	Path	Description
`POST`	`/api/v1/observability/custom-metrics`	Register custom metric
`GET`	`/api/v1/observability/custom-metrics`	List custom metrics
`GET`	`/api/v1/observability/custom-metrics/:metricName`	Get metric definition
`DELETE`	`/api/v1/observability/custom-metrics/:metricName`	Delete custom metric
`POST`	`/api/v1/observability/custom-metrics/:metricName/data`	Record metric data
`GET`	`/api/v1/observability/custom-metrics/:metricName/query`	Query metric data

Naming Conventions

Custom metrics should follow Prometheus naming conventions:

Use snake_case
Include a unit suffix (e.g., _seconds, _bytes, _total)
Prefix with a namespace (e.g., matih_custom_)
Avoid high-cardinality labels (keep label values bounded)

Cost Allocation Profiling