Improve multiprocessing documentation

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,19 +521,36 @@ 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.
 - 'livesum': Return a single timeseries that is the sum of the values of alive processes.
 - '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.