0
# Registry System
1

2
The registry system provides centralized management of metrics collection, organization, and retrieval. It serves as the collection point for all metrics and enables custom collectors to be integrated into the monitoring system.
3

4
## Capabilities
5

6
### CollectorRegistry
7

8
The main registry class that manages metric collectors and provides unified access to all metrics. It supports automatic registration, custom collectors, and multiple exposition formats.
9

10
```python { .api }
11
class CollectorRegistry:
12
    def __init__(self, auto_describe: bool = False, target_info: Optional[Dict[str, str]] = None) -> None:
13
        """
14
        Create a new CollectorRegistry.
15
        
16
        Parameters:
17
        - auto_describe: Whether to auto-call describe() on registered collectors
18
        - target_info: Optional target info labels for this registry
19
        """
20
    
21
    def register(self, collector: Collector) -> None:
22
        """
23
        Register a collector with this registry.
24
        
25
        Parameters:
26
        - collector: Collector instance to register
27
        
28
        Raises:
29
        ValueError: If collector is already registered or conflicts with existing collector
30
        """
31
    
32
    def unregister(self, collector: Collector) -> None:
33
        """
34
        Unregister a collector from this registry.
35
        
36
        Parameters:
37
        - collector: Collector instance to unregister
38
        
39
        Raises:
40
        KeyError: If collector is not registered
41
        """
42
    
43
    def collect(self) -> Iterable[Metric]:
44
        """
45
        Collect metrics from all registered collectors.
46
        
47
        Returns:
48
        Iterable of Metric objects from all collectors
49
        """
50
    
51
    def restricted_registry(self, names: Iterable[str]) -> "RestrictedRegistry":
52
        """
53
        Create a restricted view of this registry containing only specified metrics.
54
        
55
        Parameters:
56
        - names: Metric names to include in restricted view
57
        
58
        Returns:
59
        RestrictedRegistry instance
60
        """
61
    
62
    def set_target_info(self, labels: Optional[Dict[str, str]]) -> None:
63
        """
64
        Set target info labels for this registry.
65
        
66
        Parameters:
67
        - labels: Dictionary of target info labels, or None to clear
68
        """
69
    
70
    def get_target_info(self) -> Optional[Dict[str, str]]:
71
        """
72
        Get current target info labels.
73
        
74
        Returns:
75
        Dictionary of target info labels, or None if not set
76
        """
77
    
78
    def get_sample_value(self, name: str, labels: Optional[Dict[str, str]] = None) -> Optional[float]:
79
        """
80
        Get the current sample value for a metric.
81
        
82
        Parameters:
83
        - name: Metric name
84
        - labels: Optional labels dictionary
85
        
86
        Returns:
87
        Current sample value, or None if not found
88
        """
89
```
90

91
**Usage Example:**
92

93
```python
94
from prometheus_client import CollectorRegistry, Counter, Gauge
95

96
# Create custom registry
97
custom_registry = CollectorRegistry()
98

99
# Create metrics with custom registry
100
requests = Counter('requests_total', 'Total requests', registry=custom_registry)
101
memory = Gauge('memory_usage', 'Memory usage', registry=custom_registry)
102

103
# Use metrics
104
requests.inc()
105
memory.set(1024)
106

107
# Get sample values
108
print(custom_registry.get_sample_value('requests_total'))
109
print(custom_registry.get_sample_value('memory_usage'))
110

111
# Create restricted view
112
restricted = custom_registry.restricted_registry(['requests_total'])
113

114
# Set target info
115
custom_registry.set_target_info({
116
    'service': 'my-app',
117
    'version': '1.0.0'
118
})
119
```
120

121
### Global Registry
122

123
The default global registry instance used by all metrics when no specific registry is provided.
124

125
```python { .api }
126
REGISTRY: CollectorRegistry = CollectorRegistry(auto_describe=True)
127
```
128

129
**Usage Example:**
130

131
```python
132
from prometheus_client import REGISTRY, Counter, generate_latest
133

134
# Metrics automatically register with REGISTRY
135
counter = Counter('my_counter', 'My counter')
136
counter.inc()
137

138
# Generate output from global registry
139
metrics_output = generate_latest(REGISTRY)
140
print(metrics_output.decode('utf-8'))
141

142
# Register custom collector with global registry
143
class MyCollector:
144
    def collect(self):
145
        # Return metrics
146
        pass
147

148
REGISTRY.register(MyCollector())
149
```
150

151
### Collector Interface
152

153
The abstract base class for all collectors that can be registered with a registry.
154

155
```python { .api }
156
class Collector:
157
    def collect(self) -> Iterable[Metric]:
158
        """
159
        Collect and return metrics.
160
        
161
        This method must be implemented by all collectors.
162
        
163
        Returns:
164
        Iterable of Metric objects
165
        """
166
    
167
    def describe(self) -> Iterable[Metric]:
168
        """
169
        Describe the metrics that this collector will provide.
170
        
171
        Default implementation returns collect() results.
172
        Override for better performance if metrics are expensive to collect.
173
        
174
        Returns:
175
        Iterable of Metric objects (without samples)
176
        """
177
```
178

179
**Usage Example:**
180

181
```python
182
from prometheus_client import Collector, Metric, REGISTRY
183
import psutil
184

185
class SystemCollector(Collector):
186
    def collect(self):
187
        # CPU usage metric
188
        cpu_metric = Metric('system_cpu_percent', 'CPU usage percentage', 'gauge')
189
        cpu_metric.add_sample('system_cpu_percent', {}, psutil.cpu_percent())
190
        yield cpu_metric
191
        
192
        # Memory usage metric
193
        memory = psutil.virtual_memory()
194
        memory_metric = Metric('system_memory_bytes', 'Memory usage in bytes', 'gauge')
195
        memory_metric.add_sample('system_memory_bytes', {'type': 'used'}, memory.used)
196
        memory_metric.add_sample('system_memory_bytes', {'type': 'available'}, memory.available)
197
        yield memory_metric
198

199
# Register custom collector
200
system_collector = SystemCollector()
201
REGISTRY.register(system_collector)
202

203
# Later, unregister if needed
204
REGISTRY.unregister(system_collector)
205
```
206

207
### Metric Class for Custom Collectors
208

209
The core Metric class used to represent metrics and their samples in custom collectors.
210

211
```python { .api }
212
class Metric:
213
    def __init__(self, name: str, documentation: str, typ: str, unit: str = '') -> None:
214
        """
215
        Create a new Metric.
216
        
217
        Parameters:
218
        - name: Metric name
219
        - documentation: Help text describing the metric
220
        - typ: Metric type ('counter', 'gauge', 'histogram', 'summary', 'info', 'stateset', 'unknown')
221
        - unit: Optional unit suffix
222
        """
223
    
224
    def add_sample(
225
        self, 
226
        name: str, 
227
        labels: Dict[str, str], 
228
        value: float, 
229
        timestamp=None, 
230
        exemplar=None, 
231
        native_histogram=None
232
    ) -> None:
233
        """
234
        Add a sample to this metric.
235
        
236
        Parameters:
237
        - name: Sample name (usually metric name + suffix)
238
        - labels: Dictionary of label names to values
239
        - value: Sample value
240
        - timestamp: Optional timestamp (Unix time)
241
        - exemplar: Optional exemplar for tracing
242
        - native_histogram: Optional native histogram value
243
        """
244
    
245
    # Properties
246
    name: str                    # Metric name
247
    documentation: str           # Help text
248
    type: str                   # Metric type
249
    unit: str                   # Unit suffix
250
    samples: List[Sample]       # List of samples
251
```
252

253
**Usage Example:**
254

255
```python
256
from prometheus_client import Metric
257
import time
258

259
# Create a metric
260
metric = Metric('my_custom_metric', 'A custom metric', 'gauge', unit='bytes')
261

262
# Add samples
263
metric.add_sample('my_custom_metric_bytes', {'instance': 'server1'}, 1024.0)
264
metric.add_sample('my_custom_metric_bytes', {'instance': 'server2'}, 2048.0)
265

266
# Add sample with timestamp
267
metric.add_sample(
268
    'my_custom_metric_bytes', 
269
    {'instance': 'server3'}, 
270
    4096.0, 
271
    timestamp=time.time()
272
)
273

274
# Access metric properties
275
print(f"Name: {metric.name}")
276
print(f"Type: {metric.type}")
277
print(f"Samples: {len(metric.samples)}")
278
```
279

280
### Registry Utilities
281

282
Helper functions for working with registries and metrics.
283

284
```python { .api }
285
def generate_latest(registry: CollectorRegistry = REGISTRY) -> bytes:
286
    """
287
    Generate the latest Prometheus text format output.
288
    
289
    Parameters:
290
    - registry: Registry to collect metrics from
291
    
292
    Returns:
293
    Metrics in Prometheus text format as bytes
294
    """
295
```
296

297
**Usage Example:**
298

299
```python
300
from prometheus_client import CollectorRegistry, Counter, generate_latest
301

302
# Create registry with metrics
303
registry = CollectorRegistry()
304
counter = Counter('test_counter', 'Test counter', registry=registry)
305
counter.inc(42)
306

307
# Generate output
308
output = generate_latest(registry)
309
print(output.decode('utf-8'))
310

311
# Example output:
312
# # HELP test_counter_total Test counter
313
# # TYPE test_counter_total counter
314
# test_counter_total 42.0
315
```
316

317
### Multiprocess Registry Support
318

319
Support for collecting metrics across multiple processes using shared memory.
320

321
```python { .api }
322
class MultiProcessCollector:
323
    def __init__(self, registry, path=None) -> None:
324
        """
325
        Create a MultiProcessCollector.
326
        
327
        Parameters:
328
        - registry: Registry to register with
329
        - path: Path to multiprocess metrics directory (defaults to PROMETHEUS_MULTIPROC_DIR env var)
330
        """
331
    
332
    @staticmethod
333
    def merge(files, accumulate=True):
334
        """
335
        Merge metrics from multiple process files.
336
        
337
        Parameters:
338
        - files: List of file paths containing metrics
339
        - accumulate: Whether to accumulate values across processes
340
        
341
        Returns:
342
        Dictionary of merged metrics
343
        """
344
```
345

346
**Usage Example:**
347

348
```python
349
import os
350
from prometheus_client import CollectorRegistry, Counter
351
from prometheus_client.multiprocess import MultiProcessCollector
352

353
# Set multiprocess directory
354
os.environ['PROMETHEUS_MULTIPROC_DIR'] = '/tmp/prometheus_metrics'
355

356
# Create registry with multiprocess support
357
registry = CollectorRegistry()
358
MultiProcessCollector(registry)
359

360
# Create metrics (will be shared across processes)
361
counter = Counter('worker_tasks', 'Tasks processed by worker', registry=registry)
362

363
# In worker processes
364
counter.inc()  # Each process can increment independently
365

366
# Parent process can collect aggregated metrics
367
from prometheus_client import generate_latest
368
print(generate_latest(registry).decode('utf-8'))
369
```