Skip to content

Commit 130a4e8

Browse files
k1chikk1chik
authored
docs: add API reference for pushgateway, textfile, and multiprocess (prometheus#1162)
Closes prometheus#1161 Adds parameter tables and formal API reference sections to three pages that previously had examples but no parameter documentation. pushgateway.md: documents push_to_gateway, pushadd_to_gateway, delete_from_gateway, instance_ip_grouping_key, and all four built-in handlers (default, basic_auth, tls_auth, passthrough_redirect). textfile.md: documents write_to_textfile with all four parameters including the previously undocumented escaping and tmpdir, plus atomic write semantics and error behavior. multiprocess/_index.md: documents MultiProcessCollector constructor and mark_process_dead with parameter tables including the previously undocumented path parameter on both. Signed-off-by: k1chik <107162115+k1chik@users.noreply.github.com>
1 parent 2cd1738 commit 130a4e8

3 files changed

Lines changed: 177 additions & 1 deletion

File tree

‎docs/content/exporting/pushgateway.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,3 +85,109 @@ g = Gauge('job_last_success_unixtime', 'Last time a batch job successfully finis
8585
g.set_to_current_time()
8686
push_to_gateway('localhost:9091', job='batchA', registry=registry, handler=my_auth_handler)
8787
```
88+
89+
## API Reference
90+
91+
### `push_to_gateway(gateway, job, registry, grouping_key=None, timeout=30, handler=default_handler, compression=None)`
92+
93+
Pushes metrics to the pushgateway, replacing all metrics with the same job and grouping key.
94+
Uses the HTTP `PUT` method.
95+
96+
| Parameter | Type | Default | Description |
97+
|-----------|------|---------|-------------|
98+
| `gateway` | `str` | required | URL of the pushgateway. If no scheme is provided, `http://` is assumed. |
99+
| `job` | `str` | required | Value for the `job` label attached to all pushed metrics. |
100+
| `registry` | `Collector` | required | Registry whose metrics are pushed. Typically a `CollectorRegistry` instance. |
101+
| `grouping_key` | `Optional[Dict[str, Any]]` | `None` | Additional labels to identify the group. See the [Pushgateway documentation](https://github.com/prometheus/pushgateway/blob/master/README.md) for details. |
102+
| `timeout` | `Optional[float]` | `30` | Seconds before the request is aborted. Pass `None` for no timeout. |
103+
| `handler` | `Callable` | `default_handler` | Function that performs the HTTP request. See [Handlers](#handlers) below. |
104+
| `compression` | `Optional[str]` | `None` | Compress the payload before sending. Accepts `'gzip'` or `'snappy'`. Snappy requires the [`python-snappy`](https://github.com/andrix/python-snappy) package. |
105+
106+
### `pushadd_to_gateway(gateway, job, registry, grouping_key=None, timeout=30, handler=default_handler, compression=None)`
107+
108+
Pushes metrics to the pushgateway, replacing only metrics with the same name, job, and grouping key.
109+
Uses the HTTP `POST` method.
110+
111+
| Parameter | Type | Default | Description |
112+
|-----------|------|---------|-------------|
113+
| `gateway` | `str` | required | URL of the pushgateway. |
114+
| `job` | `str` | required | Value for the `job` label attached to all pushed metrics. |
115+
| `registry` | `Optional[Collector]` | required | Registry whose metrics are pushed. Pass `None` to use the default `REGISTRY`. |
116+
| `grouping_key` | `Optional[Dict[str, Any]]` | `None` | Additional labels to identify the group. |
117+
| `timeout` | `Optional[float]` | `30` | Seconds before the request is aborted. Pass `None` for no timeout. |
118+
| `handler` | `Callable` | `default_handler` | Function that performs the HTTP request. |
119+
| `compression` | `Optional[str]` | `None` | Compress the payload. Accepts `'gzip'` or `'snappy'`. |
120+
121+
### `delete_from_gateway(gateway, job, grouping_key=None, timeout=30, handler=default_handler)`
122+
123+
Deletes metrics from the pushgateway for the given job and grouping key.
124+
Uses the HTTP `DELETE` method. Has no `registry` or `compression` parameters.
125+
126+
| Parameter | Type | Default | Description |
127+
|-----------|------|---------|-------------|
128+
| `gateway` | `str` | required | URL of the pushgateway. |
129+
| `job` | `str` | required | Value for the `job` label identifying the group to delete. |
130+
| `grouping_key` | `Optional[Dict[str, Any]]` | `None` | Additional labels to identify the group. |
131+
| `timeout` | `Optional[float]` | `30` | Seconds before the request is aborted. Pass `None` for no timeout. |
132+
| `handler` | `Callable` | `default_handler` | Function that performs the HTTP request. |
133+
134+
### `instance_ip_grouping_key()`
135+
136+
Returns a grouping key dict with the `instance` label set to the IP address of the current host.
137+
Takes no parameters.
138+
139+
```python
140+
from prometheus_client.exposition import instance_ip_grouping_key
141+
142+
push_to_gateway('localhost:9091', job='batchA', registry=registry,
143+
grouping_key=instance_ip_grouping_key())
144+
```
145+
146+
## Handlers
147+
148+
A handler is a callable with the signature:
149+
150+
```python
151+
def my_handler(url, method, timeout, headers, data):
152+
# url: str — full request URL
153+
# method: str — HTTP method (PUT, POST, DELETE)
154+
# timeout: Optional[float] — seconds before aborting, or None
155+
# headers: List[Tuple[str, str]] — HTTP headers to include
156+
# data: bytes — request body
157+
...
158+
return callable_that_performs_the_request
159+
```
160+
161+
The handler must return a no-argument callable that performs the actual HTTP request and raises
162+
an exception (e.g. `IOError`) on failure. Three built-in handlers are available in
163+
`prometheus_client.exposition`:
164+
165+
### `default_handler`
166+
167+
Standard HTTP/HTTPS handler. Used by default in all push functions.
168+
169+
### `basic_auth_handler(url, method, timeout, headers, data, username=None, password=None)`
170+
171+
Wraps `default_handler` and adds an HTTP Basic Auth header.
172+
173+
| Extra parameter | Type | Default | Description |
174+
|----------------|------|---------|-------------|
175+
| `username` | `Optional[str]` | `None` | HTTP Basic Auth username. |
176+
| `password` | `Optional[str]` | `None` | HTTP Basic Auth password. |
177+
178+
### `tls_auth_handler(url, method, timeout, headers, data, certfile, keyfile, cafile=None, protocol=ssl.PROTOCOL_TLS_CLIENT, insecure_skip_verify=False)`
179+
180+
Performs the request over HTTPS using TLS client certificate authentication.
181+
182+
| Extra parameter | Type | Default | Description |
183+
|----------------|------|---------|-------------|
184+
| `certfile` | `str` | required | Path to the client certificate PEM file. |
185+
| `keyfile` | `str` | required | Path to the client private key PEM file. |
186+
| `cafile` | `Optional[str]` | `None` | Path to a CA certificate file for server verification. Uses system defaults if not set. |
187+
| `protocol` | `int` | `ssl.PROTOCOL_TLS_CLIENT` | SSL/TLS protocol version. |
188+
| `insecure_skip_verify` | `bool` | `False` | Skip server certificate verification. Use only in controlled environments. |
189+
190+
### `passthrough_redirect_handler`
191+
192+
Like `default_handler` but automatically follows redirects for all HTTP methods, including `PUT`
193+
and `POST`. Use only when you control or trust the source of redirect responses.

‎docs/content/exporting/textfile.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,24 @@ write_to_textfile('/configured/textfile/path/raid.prom', registry)
2020
```
2121

2222
A separate registry is used, as the default registry may contain other metrics
23-
such as those from the Process Collector.
23+
such as those from the Process Collector.
24+
25+
## API Reference
26+
27+
### `write_to_textfile(path, registry, escaping='allow-utf-8', tmpdir=None)`
28+
29+
Writes metrics from the registry to a file in Prometheus text format.
30+
31+
The file is written atomically: metrics are first written to a temporary file in the same
32+
directory as `path` (or in `tmpdir` if provided), then renamed into place. This prevents the
33+
Node exporter from reading a partially written file.
34+
35+
| Parameter | Type | Default | Description |
36+
|-----------|------|---------|-------------|
37+
| `path` | `str` | required | Destination file path. Must end in `.prom` for the Node exporter textfile collector to process it. |
38+
| `registry` | `Collector` | required | Registry whose metrics are written. |
39+
| `escaping` | `str` | `'allow-utf-8'` | Escaping scheme for metric and label names. Accepted values: `'allow-utf-8'`, `'underscores'`, `'dots'`, `'values'`. |
40+
| `tmpdir` | `Optional[str]` | `None` | Directory for the temporary file used during the atomic write. Defaults to the same directory as `path`. If provided, must be on the same filesystem as `path`. |
41+
42+
Returns `None`. Raises an exception if the file cannot be written; the temporary file is cleaned
43+
up automatically on failure.

‎docs/content/multiprocess/_index.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,3 +96,53 @@ from prometheus_client import Gauge
9696
# Example gauge
9797
IN_PROGRESS = Gauge("inprogress_requests", "help", multiprocess_mode='livesum')
9898
```
99+
100+
## API Reference
101+
102+
### `MultiProcessCollector(registry, path=None)`
103+
104+
Collector that aggregates metrics written by all processes in the multiprocess directory.
105+
106+
| Parameter | Type | Default | Description |
107+
|-----------|------|---------|-------------|
108+
| `registry` | `CollectorRegistry` | required | Registry to register with. Pass a registry created inside the request context to avoid duplicate metrics. |
109+
| `path` | `Optional[str]` | `None` | Path to the directory containing the per-process metric files. Defaults to the `PROMETHEUS_MULTIPROC_DIR` environment variable. |
110+
111+
Raises `ValueError` if `path` is not set or does not point to an existing directory.
112+
113+
```python
114+
from prometheus_client import multiprocess, CollectorRegistry
115+
116+
def app(environ, start_response):
117+
registry = CollectorRegistry(support_collectors_without_names=True)
118+
multiprocess.MultiProcessCollector(registry)
119+
...
120+
```
121+
122+
To use a custom path instead of the environment variable:
123+
124+
```python
125+
collector = multiprocess.MultiProcessCollector(registry, path='/var/run/prom')
126+
```
127+
128+
### `mark_process_dead(pid, path=None)`
129+
130+
Removes the per-process metric files for a dead process. Call this from your process manager
131+
when a worker exits to prevent stale `live*` gauge values from accumulating.
132+
133+
| Parameter | Type | Default | Description |
134+
|-----------|------|---------|-------------|
135+
| `pid` | `int` | required | PID of the process that has exited. |
136+
| `path` | `Optional[str]` | `None` | Path to the multiprocess directory. Defaults to the `PROMETHEUS_MULTIPROC_DIR` environment variable. |
137+
138+
Returns `None`. Only removes files for `live*` gauge modes (e.g. `livesum`, `liveall`); files
139+
for non-live modes are left in place so their last values remain visible until the directory is
140+
wiped on restart.
141+
142+
```python
143+
# Gunicorn config
144+
from prometheus_client import multiprocess
145+
146+
def child_exit(server, worker):
147+
multiprocess.mark_process_dead(worker.pid)
148+
```

0 commit comments

Comments
 (0)