0
# Info Metrics
1

2
Info metrics provide key-value metadata pairs for build information, version details, configuration data, and other static or semi-static information. They expose labels with a constant value of 1, making them ideal for metadata that doesn't change frequently.
3

4
## Capabilities
5

6
### Info Creation
7

8
Create info metrics using the builder pattern for metadata collection.
9

10
```java { .api }
11
/**
12
 * Create a new Info builder
13
 * @return Builder instance for configuration
14
 */
15
public static Info.Builder build();
16

17
/**
18
 * Create a new Info builder with required fields
19
 * @param name The metric name (will have _info suffix added)
20
 * @param help The help text describing the metadata
21
 * @return Builder instance for configuration
22
 */
23
public static Info.Builder build(String name, String help);
24
```
25

26
**Usage Example:**
27

28
```java
29
import io.prometheus.client.Info;
30

31
// Application build information
32
Info buildInfo = Info.build()
33
    .name("application_build")
34
    .help("Application build information")
35
    .register();
36

37
// Service configuration info
38
Info serviceConfig = Info.build()
39
    .name("service_config")
40
    .help("Service configuration metadata")
41
    .labelNames("service", "environment")
42
    .register();
43
```
44

45
### Info Builder Configuration
46

47
Configure info metrics with labels and metadata structure.
48

49
```java { .api }
50
public static class Builder extends SimpleCollector.Builder<Builder, Info> {
51
    // Note: Info metrics cannot have a unit - throws IllegalStateException
52
    // Inherits: name(), help(), labelNames(), namespace(), subsystem(), 
53
    // register(), create()
54
}
55
```
56

57
**Important**: Info metrics cannot have units. Attempting to set a unit will throw an `IllegalStateException`.
58

59
### Info Operations
60

61
Set metadata information using key-value pairs provided as alternating strings.
62

63
```java { .api }
64
/**
65
 * Set info metadata using alternating key-value pairs
66
 * @param labelPairs Even number of strings as key-value pairs
67
 * @throws IllegalArgumentException if odd number of strings provided
68
 */
69
public void info(String... labelPairs);
70
```
71

72
**Usage Examples:**
73

74
```java
75
// Basic build information
76
buildInfo.info(
77
    "version", "1.2.3",
78
    "commit", "abc123def456", 
79
    "branch", "main",
80
    "build_time", "2024-01-15T10:30:00Z"
81
);
82

83
// Service configuration per environment
84
serviceConfig.labels("user-service", "production").info(
85
    "max_connections", "100",
86
    "timeout_seconds", "30",
87
    "cache_enabled", "true",
88
    "log_level", "INFO"
89
);
90

91
serviceConfig.labels("user-service", "development").info(
92
    "max_connections", "10", 
93
    "timeout_seconds", "60",
94
    "cache_enabled", "false",
95
    "log_level", "DEBUG"
96
);
97
```
98

99
### Labeled Info Operations
100

101
Work with multi-dimensional info metrics using label values.
102

103
```java { .api }
104
/**
105
 * Get info child for specific label values
106
 * @param labelValues Values for each label name (must match count)
107
 * @return Info.Child instance for the label combination
108
 * @throws IllegalArgumentException if wrong number of labels
109
 */
110
public Info.Child labels(String... labelValues);
111

112
/**
113
 * Remove info child for specific label values
114
 * @param labelValues Values identifying the child to remove
115
 */
116
public void remove(String... labelValues);
117

118
/**
119
 * Remove all info children
120
 */
121
public void clear();
122
```
123

124
### Info Child Operations
125

126
Info.Child provides metadata operations for labeled instances.
127

128
```java { .api }
129
public static class Child {
130
    /**
131
     * Set info metadata for this child using key-value pairs
132
     * @param labelPairs Even number of strings as alternating keys and values
133
     * @throws IllegalArgumentException if odd number of strings
134
     */
135
    public void info(String... labelPairs);
136
}
137
```
138

139
**Usage Example:**
140

141
```java
142
// Application component information
143
Info componentInfo = Info.build()
144
    .name("component_info")
145
    .help("Component build and runtime information")
146
    .labelNames("component", "instance")
147
    .register();
148

149
// Set information for different components
150
Info.Child webComponent = componentInfo.labels("web-server", "instance-1");
151
webComponent.info(
152
    "version", "2.1.0",
153
    "port", "8080",
154
    "protocol", "HTTP/1.1",
155
    "worker_threads", "10"
156
);
157

158
Info.Child dbComponent = componentInfo.labels("database", "primary");
159
dbComponent.info(
160
    "version", "PostgreSQL 13.7",
161
    "max_connections", "200", 
162
    "shared_buffers", "256MB",
163
    "maintenance_work_mem", "64MB"
164
);
165

166
// Update info when configuration changes
167
webComponent.info(
168
    "version", "2.1.1",        // Updated version
169
    "port", "8080",
170
    "protocol", "HTTP/2",      // Updated protocol
171
    "worker_threads", "20"     // Updated thread count
172
);
173
```
174

175
## Important Notes
176

177
### Info Metric Naming
178

179
Info metrics automatically handle the `_info` suffix:
180
- If you specify `build_info` as the name, it becomes `build` internally
181
- When exported, it appears as `build_info` for Prometheus compatibility
182
- Choose meaningful names that indicate the type of metadata
183

184
### Key-Value Pair Requirements
185

186
The `info()` method requires an even number of strings:
187
- Odd-positioned strings (1st, 3rd, 5th, etc.) are label names
188
- Even-positioned strings (2nd, 4th, 6th, etc.) are label values
189
- Must provide at least one key-value pair
190
- Label names must follow Prometheus naming conventions
191

192
```java
193
// Valid usage
194
info.info("key1", "value1", "key2", "value2");
195

196
// Invalid - throws IllegalArgumentException
197
info.info("key1", "value1", "key2"); // Missing value for key2
198
info.info("key1");                   // Missing value for key1
199
```
200

201
### Label Naming Considerations
202

203
- Use descriptive label names that clearly identify the metadata
204
- Avoid label names that conflict with reserved Prometheus labels
205
- Consider standardizing label names across your application
206
- Keep label names consistent with your metrics naming conventions
207

208
### Common Use Cases
209

210
```java
211
// Application metadata
212
Info appInfo = Info.build()
213
    .name("application")
214
    .help("Application metadata")
215
    .register();
216

217
appInfo.info(
218
    "name", "user-management-service",
219
    "version", "3.2.1",
220
    "git_commit", "a1b2c3d4e5f6",
221
    "build_date", "2024-01-15",
222
    "java_version", System.getProperty("java.version"),
223
    "spring_boot_version", "2.7.8"
224
);
225

226
// Infrastructure information
227
Info infraInfo = Info.build()
228
    .name("infrastructure")
229
    .help("Infrastructure and deployment information")
230
    .labelNames("environment", "region")
231
    .register();
232

233
infraInfo.labels("production", "us-east-1").info(
234
    "kubernetes_version", "1.25.4",
235
    "node_count", "12",
236
    "cluster_name", "prod-cluster",
237
    "ingress_controller", "nginx-1.5.1"
238
);
239

240
// Feature flags and configuration
241
Info featureFlags = Info.build()
242
    .name("feature_flags")
243
    .help("Feature flag states")
244
    .labelNames("service")
245
    .register();
246

247
featureFlags.labels("user-service").info(
248
    "new_auth_enabled", "true",
249
    "rate_limiting_enabled", "false", 
250
    "cache_version", "v2",
251
    "experimental_features", "disabled"
252
);
253

254
// Database configuration
255
Info dbConfig = Info.build()
256
    .name("database_config")
257
    .help("Database configuration and settings")
258
    .labelNames("database_name", "role")
259
    .register();
260

261
dbConfig.labels("users_db", "primary").info(
262
    "engine", "PostgreSQL",
263
    "version", "14.5",
264
    "max_connections", "100",
265
    "shared_preload_libraries", "pg_stat_statements",
266
    "timezone", "UTC"
267
);
268
```
269

270
### Thread Safety
271

272
All info operations are thread-safe:
273

274
```java
275
// Safe concurrent access
276
Info concurrentInfo = Info.build()
277
    .name("concurrent_metadata")
278
    .help("Thread-safe info metric")
279
    .register();
280

281
// Multiple threads can safely update
282
concurrentInfo.info("key1", "value1"); // Thread 1
283
concurrentInfo.info("key2", "value2"); // Thread 2
284
```
285

286
### Performance Considerations
287

288
- Info metrics are lightweight and optimized for infrequent updates
289
- Setting info overwrites all previous key-value pairs for that metric instance
290
- Use labels sparingly to avoid high cardinality
291
- Info metrics are typically updated once at startup or during configuration changes
292

293
### Integration with Monitoring
294

295
Info metrics are particularly useful for:
296
- **Alerting Context**: Providing build/version information in alert notifications
297
- **Dashboard Annotations**: Showing deployment information on monitoring dashboards  
298
- **Troubleshooting**: Correlating issues with specific versions or configurations
299
- **Compliance**: Tracking software versions and configurations for audit purposes