ADR 22_metrics

Architecture Design Record

ADR-22, Metrics

• add health metrics

Have metrics all intialized to 0

Convetions

namespace = mir subsystem = [core|cmd|tlm|cfg|cache]

1. Basic Format:

[namespace]_[subsystem]_[name]_[unit][suffix]

2. Naming Rules:

// Good examples
http_requests_total
api_http_requests_total
myapp_process_cpu_seconds_total
http_request_duration_seconds
http_response_size_bytes
node_memory_usage_bytes
process_cpu_seconds_total

// Bad examples
HttpRequests            // Don't use camelCase
http-requests           // Don't use dashes
1_http_requests        // Don't start with numbers

3. Standard Suffixes:

_total      // for counters
_sum        // for summary
_count      // for summary/histogram
_bucket     // for histogram
_seconds    // for time
_bytes      // for bytes
_ratio      // for ratios/percentages

4. Examples by Metric Type:

// Counter (should end in _total)
prometheus.NewCounter(prometheus.CounterOpts{
    Name: "http_requests_total",
    Help: "Total number of HTTP requests",
})

5. Label Names:
```go
// Good examples
prometheus.NewCounterVec(
    prometheus.CounterOpts{
        Name: "http_requests_total",
        Help: "HTTP requests total",
    },
    []string{"method", "status", "path"}  // Use snake_case for label names
)

// Bad examples
[]string{"Method", "Status"}  // Don't use capitals
[]string{"http-method"}       // Don't use dashes

6. Full Example with Namespace and Subsystem:

prometheus.NewCounter(prometheus.CounterOpts{
    Namespace: "myapp",
    Subsystem: "http",
    Name:      "requests_total",
    Help:      "Total number of HTTP requests",
})
// Results in: myapp_http_requests_total

7. General Guidelines:

- Use snake_case for metric names
- Always include units in the metric name
- Make names self-describing
- Include the measured object in the name
- Use base units (seconds, bytes, meters, etc.)

8. Common Units:

_bytes
_seconds
_ratio
_percent
_count

9. Real-world Examples:

// System metrics
node_cpu_seconds_total
node_memory_bytes_total
node_filesystem_free_bytes

// HTTP metrics
http_requests_total
http_request_duration_seconds
http_response_size_bytes

// Application metrics
app_requests_in_flight
app_request_latency_seconds
app_batch_jobs_queued

10. Label Best Practices:

// Good - low cardinality
"status": ["200", "404", "500"]
"method": ["GET", "POST", "PUT"]
"endpoint": ["/api/v1/users", "/api/v1/products"]

// Bad - high cardinality
"user_id": "123456789"      // Don't use unique IDs
"timestamp": "1234567890"   // Don't use timestamps
"email": "user@example.com" // Don't use unique values

Remember:

• Be consistent across your application
• Make metrics names clear and self-describing
• Follow the unit conventions
• Avoid high cardinality labels
• Document all metrics with good Help text