diff --git a/README.md b/README.md index 586f5315..3e4a8bb0 100644 --- a/README.md +++ b/README.md @@ -489,31 +489,25 @@ This comes with a number of limitations: There's several steps to getting this working: -**One**: Gunicorn deployment +**1. Gunicorn deployment**: The `prometheus_multiproc_dir` environment variable must be set to a directory that the client library can use for metrics. This directory must be wiped between Gunicorn runs (before startup is recommended). -Put the following in the config file: -```python -from prometheus_client import multiprocess +This environment variable should be set from a start-up shell script, +and not directly from Python (otherwise it may not propagate to child processes). -def child_exit(server, worker): - multiprocess.mark_process_dead(worker.pid) -``` +**2. Metrics collector**: + +The application must initialize a new `CollectorRegistry`, +and store the multi-process collector inside. -**Two**: Inside the application ```python from prometheus_client import multiprocess -from prometheus_client import generate_latest, CollectorRegistry, CONTENT_TYPE_LATEST, Gauge - -# Example gauge. -IN_PROGRESS = Gauge("inprogress_requests", "help", multiprocess_mode='livesum') - +from prometheus_client import generate_latest, CollectorRegistry, CONTENT_TYPE_LATEST # Expose metrics. -@IN_PROGRESS.track_inprogress() def app(environ, start_response): registry = CollectorRegistry() multiprocess.MultiProcessCollector(registry) @@ -527,12 +521,21 @@ def app(environ, start_response): return iter([data]) ``` -**Three**: Instrumentation +**3. Gunicorn configuration**: + +The `gunicorn` configuration file needs to include the following function: + +```python +from prometheus_client import multiprocess + +def child_exit(server, worker): + multiprocess.mark_process_dead(worker.pid) +``` -Counters, Summarys and Histograms work as normal. +**4. Metrics tuning (Gauge)**: -Gauges have several modes they can run in, which can be selected with the -`multiprocess_mode` parameter. +When `Gauge` metrics are used, additional tuning needs to be performed. +Gauges have several modes they can run in, which can be selected with the `multiprocess_mode` parameter. - 'all': Default. Return a timeseries per process alive or dead. - 'liveall': Return a timeseries per process that is still alive. @@ -540,6 +543,14 @@ Gauges have several modes they can run in, which can be selected with the - 'max': Return a single timeseries that is the maximum of the values of all processes, alive or dead. - 'min': Return a single timeseries that is the minimum of the values of all processes, alive or dead. +```python +from prometheus_client import Gauge + +# Example gauge +IN_PROGRESS = Gauge("inprogress_requests", "help", multiprocess_mode='livesum') +``` + + ## Parser The Python client supports parsing the Prometheus text format.