1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

// CORRECT: Base units
var (
    // Time in seconds
    requestDuration = prometheus.NewHistogram(
        prometheus.HistogramOpts{
            Name: "http_request_duration_seconds",
            Help: "HTTP request latency in seconds",
            Buckets: []float64{.001, .005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5},
        },
    )
    
    // Size in bytes
    responseSize = prometheus.NewHistogram(
        prometheus.HistogramOpts{
            Name: "http_response_size_bytes",
            Help: "HTTP response size in bytes",
            Buckets: prometheus.ExponentialBuckets(100, 10, 6),
        },
    )
    
    // Ratio (0.0 to 1.0)
    cacheHitRatio = prometheus.NewGauge(
        prometheus.GaugeOpts{
            Name: "cache_hit_ratio",
            Help: "Cache hit ratio (0.0 to 1.0)",
        },
    )
)
 
// INCORRECT: Don't do this
var (
    // DON'T use milliseconds
    requestDurationMs = prometheus.NewHistogram(
        prometheus.HistogramOpts{
            Name: "http_request_duration_ms",  // Wrong!
            // ...
        },
    )
    
    // DON'T use percentages
    cacheHitPercent = prometheus.NewGauge(
        prometheus.GaugeOpts{
            Name: "cache_hit_percent",  // Wrong!
            // ...
        },
    )
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// Info metrics: expose metadata as labels
// Value is always 1; labels carry the information
 
var buildInfo = prometheus.NewGaugeVec(
    prometheus.GaugeOpts{
        Name: "myapp_build_info",
        Help: "Build information about the running instance",
    },
    []string{"version", "commit_sha", "build_date", "go_version"},
)
 
func init() {
    // Set value to 1, labels carry the actual info
    buildInfo.WithLabelValues(
        "1.2.3",
        "abc123def",
        "2024-01-15",
        runtime.Version(),
    ).Set(1)
}
 
// Query in PromQL:
// myapp_build_info{version="1.2.3"}
// Returns 1 if this version is running
 
// Join with other metrics:
// rate(http_requests_total[5m]) 
//   * on(instance) group_left(version) 
//   myapp_build_info

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

// GOOD: Bounded, meaningful labels
httpRequests := prometheus.NewCounterVec(
    prometheus.CounterOpts{
        Name: "http_requests_total",
        Help: "Total HTTP requests",
    },
    []string{"method", "endpoint", "status_code"},
)
 
// GOOD: Normalize unbounded values
func normalizeEndpoint(path string) string {
    // Convert /users/12345 → /users/:id
    // Convert /orders/abc-123/items/456 → /orders/:id/items/:id
    patterns := []struct {
        regex       *regexp.Regexp
        replacement string
    }{
        {regexp.MustCompile(`/users/[^/]+`), "/users/:id"},
        {regexp.MustCompile(`/orders/[^/]+`), "/orders/:id"},
        {regexp.MustCompile(`/items/[^/]+`), "/items/:id"},
    }
    
    result := path
    for _, p := range patterns {
        result = p.regex.ReplaceAllString(result, p.replacement)
    }
    return result
}
 
// Usage:
func handleRequest(r *http.Request, statusCode int) {
    normalizedPath := normalizeEndpoint(r.URL.Path)
    httpRequests.WithLabelValues(
        r.Method,
        normalizedPath,  // Bounded!
        strconv.Itoa(statusCode),
    ).Inc()
}
 
// BAD: Don't do this
httpRequestsBad := prometheus.NewCounterVec(
    prometheus.CounterOpts{
        Name: "http_requests_total",
        Help: "Total HTTP requests",
    },
    []string{"method", "path", "user_id"},  // path and user_id are unbounded!
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# Namespace: myapp
# Subsystems: http, db, cache, queue
 
myapp_http_requests_total
myapp_http_request_duration_seconds
myapp_http_response_size_bytes
 
myapp_db_query_duration_seconds
myapp_db_connections_active
myapp_db_errors_total
 
myapp_cache_hits_total
myapp_cache_misses_total
myapp_cache_size_bytes
 
myapp_queue_messages_total
myapp_queue_depth
myapp_queue_processing_seconds
 
# Standard exporters use their own namespaces:
node_*           # Node exporter (Linux system metrics)
process_*        # Process metrics (built into client libraries)
go_*             # Go runtime metrics
mysql_*          # MySQL exporter
redis_*          # Redis exporter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

package metrics
 
import (
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promauto"
)
 
// Define namespace and subsystems as constants
const (
    namespace = "myapp"
    
    subsystemHTTP  = "http"
    subsystemDB    = "db"
    subsystemCache = "cache"
)
 
// HTTP metrics
var (
    HTTPRequestsTotal = promauto.NewCounterVec(
        prometheus.CounterOpts{
            Namespace: namespace,
            Subsystem: subsystemHTTP,
            Name:      "requests_total",
            Help:      "Total HTTP requests",
        },
        []string{"method", "endpoint", "status_code"},
    )
    // Result: myapp_http_requests_total
    
    HTTPRequestDuration = promauto.NewHistogramVec(
        prometheus.HistogramOpts{
            Namespace: namespace,
            Subsystem: subsystemHTTP,
            Name:      "request_duration_seconds",
            Help:      "HTTP request duration in seconds",
            Buckets:   prometheus.DefBuckets,
        },
        []string{"method", "endpoint"},
    )
    // Result: myapp_http_request_duration_seconds
)
 
// Database metrics
var (
    DBQueryDuration = promauto.NewHistogramVec(
        prometheus.HistogramOpts{
            Namespace: namespace,
            Subsystem: subsystemDB,
            Name:      "query_duration_seconds",
            Help:      "Database query duration in seconds",
            Buckets:   []float64{.001, .005, .01, .05, .1, .5, 1},
        },
        []string{"query_type"},
    )
    // Result: myapp_db_query_duration_seconds
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

// GOOD: Descriptive HELP strings
var (
    httpRequestsTotal = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Total number of HTTP requests received, labeled by method, endpoint, and status code.",
        },
        []string{"method", "endpoint", "status_code"},
    )
    
    httpRequestDurationSeconds = prometheus.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "http_request_duration_seconds",
            Help:    "HTTP request latency in seconds, from request received to response sent.",
            Buckets: prometheus.DefBuckets,
        },
        []string{"method", "endpoint"},
    )
    
    dbConnectionsActive = prometheus.NewGaugeVec(
        prometheus.GaugeOpts{
            Name: "db_connections_active",
            Help: "Number of currently active database connections by pool name. Includes connections in use and idle.",
        },
        []string{"pool"},
    )
    
    cacheHitRatio = prometheus.NewGaugeVec(
        prometheus.GaugeOpts{
            Name: "cache_hit_ratio",
            Help: "Cache hit ratio over the last minute (0.0 = all misses, 1.0 = all hits). Computed as hits / (hits + misses).",
        },
        []string{"cache_name"},
    )
)
 
// BAD: Unhelpful HELP strings
var (
    badMetric1 = prometheus.NewCounter(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "HTTP requests",  // Too vague
        },
    )
    
    badMetric2 = prometheus.NewCounter(
        prometheus.CounterOpts{
            Name: "errors_total",
            Help: "Total errors",  // What kind? Where?
        },
    )
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

#!/usr/bin/env python3
"""
Example metric naming linter - validates conventions
"""
 
import re
import sys
from typing import List, Tuple
 
# Naming convention rules
RULES = {
    "snake_case": r'^[a-z][a-z0-9_]*$',
    "valid_chars": r'^[a-zA-Z_:][a-zA-Z0-9_:]*$',
    "no_double_underscore": r'^(?!.*__)',
    "base_units": ['seconds', 'bytes', 'total', 'ratio', 'celsius'],
    "counter_suffix": '_total',
    "reserved_prefixes": ['__'],
}
 
def lint_metric_name(name: str) -> List[str]:
    """Check a metric name against conventions."""
    errors = []
    
    # Check snake_case
    if not re.match(RULES['snake_case'], name):
        errors.append(f"'{name}' should be snake_case (lowercase with underscores)")
    
    # Check valid characters
    if not re.match(RULES['valid_chars'], name):
        errors.append(f"'{name}' contains invalid characters")
    
    # Check for double underscores
    if not re.match(RULES['no_double_underscore'], name):
        errors.append(f"'{name}' should not contain double underscores")
    
    # Check for reserved prefixes
    for prefix in RULES['reserved_prefixes']:
        if name.startswith(prefix):
            errors.append(f"'{name}' uses reserved prefix '{prefix}'")
    
    return errors
 
def lint_label_name(name: str) -> List[str]:
    """Check a label name against conventions."""
    errors = []
    
    if not re.match(r'^[a-z][a-z0-9_]*$', name):
        errors.append(f"Label '{name}' should be snake_case")
    
    # Check for high-cardinality indicators
    high_cardinality_patterns = ['user_id', 'session_id', 'request_id', 
                                  'transaction_id', 'ip_address', 'email']
    for pattern in high_cardinality_patterns:
        if pattern in name:
            errors.append(f"Label '{name}' may have unbounded cardinality")
    
    return errors
 
def recommend_improvements(name: str) -> List[str]:
    """Suggest improvements to metric names."""
    suggestions = []
    
    # Check for missing unit
    has_unit = any(name.endswith(f'_{unit}') for unit in RULES['base_units'])
    if not has_unit and not name.endswith('_info'):
        suggestions.append(f"Consider adding a unit suffix (e.g., _seconds, _bytes)")
    
    # Check counter suffix
    if 'count' in name or 'total' in name.split('_')[:-1]:
        if not name.endswith('_total'):
            suggestions.append(f"Counter metrics should end with '_total'")
    
    return suggestions
 
# Usage example
if __name__ == '__main__':
    test_metrics = [
        'http_requests_total',           # Good
        'responseTime',                   # Bad: not snake_case
        'http_requests',                  # Should be _total
        'user_session_seconds_total',     # Good
        '__internal_metric',              # Bad: reserved prefix
    ]
    
    for metric in test_metrics:
        errors = lint_metric_name(metric)
        suggestions = recommend_improvements(metric)
        
        print(f"\n{metric}:")
        if errors:
            print(f"  Errors: {errors}")
        if suggestions:
            print(f"  Suggestions: {suggestions}")
        if not errors and not suggestions:
            print(f"  ✓ Passes all checks")