docs: add API reference for all metric types

docs/content/instrumenting/_index.md

@@ -3,10 +3,20 @@ title: Instrumenting
 weight: 2
 ---
 
-Four types of metric are offered: Counter, Gauge, Summary and Histogram.
-See the documentation on [metric types](http://prometheus.io/docs/concepts/metric_types/)
+Six metric types are available. Pick based on what your value does:
+
+| Type | Value goes | Use for |
+|------|-----------|---------|
+| [Counter](counter/) | only up | requests served, errors, bytes sent |
+| [Gauge](gauge/) | up and down | queue depth, active connections, memory usage |
+| [Histogram](histogram/) | observations in buckets | request latency, request size — when you need quantiles in queries |
+| [Summary](summary/) | observations (count + sum) | request latency, request size — when average is enough |
+| [Info](info/) | static key-value pairs | build version, environment metadata |
+| [Enum](enum/) | one of N states | task state, lifecycle phase |
+
+See the Prometheus documentation on [metric types](https://prometheus.io/docs/concepts/metric_types/)
 and [instrumentation best practices](https://prometheus.io/docs/practices/instrumentation/#counter-vs-gauge-summary-vs-histogram)
-on how to use them.
+for deeper guidance on choosing between Histogram and Summary.
 
 ## Disabling `_created` metrics
 

docs/content/instrumenting/counter.md

@@ -3,12 +3,14 @@ title: Counter
 weight: 1
 ---
 
-Counters go up, and reset when the process restarts.
+A Counter tracks a value that only ever goes up. Use it for things you count — requests
+served, errors raised, bytes sent. When the process restarts, the counter resets to zero.
 
+If your value can go down, use a [Gauge](../gauge/) instead.
 
 ```python
 from prometheus_client import Counter
-c = Counter('my_failures', 'Description of counter')
+c = Counter('my_failures_total', 'Description of counter')
 c.inc()     # Increment by 1
 c.inc(1.6)  # Increment by given value
 ```
@@ -18,17 +20,110 @@ exposing the time series for counter, a `_total` suffix will be added. This is
 for compatibility between OpenMetrics and the Prometheus text format, as OpenMetrics
 requires the `_total` suffix.
 
-There are utilities to count exceptions raised:
+## Constructor
+
+```python
+Counter(name, documentation, labelnames=(), namespace='', subsystem='', unit='', registry=REGISTRY)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | required | Metric name. A `_total` suffix is appended automatically when exposing the time series. |
+| `documentation` | `str` | required | Help text shown in the `/metrics` output and Prometheus UI. |
+| `labelnames` | `Iterable[str]` | `()` | Names of labels for this metric. See [Labels](../labels/). |
+| `namespace` | `str` | `''` | Optional prefix. |
+| `subsystem` | `str` | `''` | Optional middle component. |
+| `unit` | `str` | `''` | Optional unit suffix appended to the metric name. |
+| `registry` | `CollectorRegistry` | `REGISTRY` | Registry to register with. Pass `None` to skip registration, which is useful in tests where you create metrics without wanting them in the global registry. |
+
+`namespace`, `subsystem`, and `name` are joined with underscores to form the full metric name:
+
+```python
+# namespace='myapp', subsystem='http', name='requests_total'
+# produces: myapp_http_requests_total
+Counter('requests_total', 'Total requests', namespace='myapp', subsystem='http')
+```
+
+## Methods
+
+### `inc(amount=1, exemplar=None)`
+
+Increment the counter by the given amount. The amount must be non-negative.
+
+```python
+c.inc()       # increment by 1
+c.inc(5)      # increment by 5
+c.inc(0.7)    # fractional increments are allowed
+```
+
+To attach trace context to an observation, pass an `exemplar` dict. Exemplars are
+only rendered in OpenMetrics format. See [Exemplars](../exemplars/) for details.
+
+```python
+c.inc(exemplar={'trace_id': 'abc123'})
+```
+
+### `reset()`
+
+Reset the counter to zero. Use this when a logical process restarts without
+restarting the actual Python process.
+
+```python
+c.reset()
+```
+
+### `count_exceptions(exception=Exception)`
+
+Count exceptions raised in a block of code or function. Can be used as a
+decorator or context manager. Increments the counter each time an exception
+of the given type is raised.
 
 ```python
 @c.count_exceptions()
 def f():
-  pass
+    pass
 
 with c.count_exceptions():
-  pass
+    pass
 
-# Count only one type of exception
+# Count only a specific exception type
 with c.count_exceptions(ValueError):
-  pass
-```
+    pass
+```
+
+## Labels
+
+See [Labels](../labels/) for how to use `.labels()`, `.remove()`, `.remove_by_labels()`, and `.clear()`.
+
+## Real-world example
+
+Tracking HTTP requests by method and status code in a web application:
+
+```python
+from prometheus_client import Counter, start_http_server
+
+REQUESTS = Counter(
+    'requests_total',
+    'Total HTTP requests received',
+    labelnames=['method', 'status'],
+    namespace='myapp',
+)
+EXCEPTIONS = Counter(
+    'exceptions_total',
+    'Total unhandled exceptions',
+    labelnames=['handler'],
+    namespace='myapp',
+)
+
+def handle_request(method, handler):
+    with EXCEPTIONS.labels(handler=handler).count_exceptions():
+        # ... process the request ...
+        status = '200'
+    REQUESTS.labels(method=method, status=status).inc()
+
+if __name__ == '__main__':
+    start_http_server(8000)  # exposes metrics at http://localhost:8000/metrics
+    # ... start your application ...
+```
+
+This produces time series like `myapp_requests_total{method="GET",status="200"}`.

docs/content/instrumenting/enum.md

@@ -3,11 +3,95 @@ title: Enum
 weight: 6
 ---
 
-Enum tracks which of a set of states something is currently in.
+Enum tracks which of a fixed set of states something is currently in. Only one state is active at a time. Use it for things like task state machines or lifecycle phases.
 
 ```python
 from prometheus_client import Enum
 e = Enum('my_task_state', 'Description of enum',
         states=['starting', 'running', 'stopped'])
 e.state('running')
-```
+```
+
+Enum exposes one time series per state:
+- `<name>{<name>="<state>"}` — 1 if this is the current state, 0 otherwise
+
+The first listed state is the default.
+
+Note: Enum metrics do not work in multiprocess mode.
+
+## Constructor
+
+```python
+Enum(name, documentation, labelnames=(), namespace='', subsystem='', unit='', registry=REGISTRY, states=[])
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | required | Metric name. |
+| `documentation` | `str` | required | Help text shown in the `/metrics` output and Prometheus UI. |
+| `labelnames` | `Iterable[str]` | `()` | Names of labels for this metric. See [Labels](../labels/). The metric name itself cannot be used as a label name. |
+| `namespace` | `str` | `''` | Optional prefix. |
+| `subsystem` | `str` | `''` | Optional middle component. |
+| `unit` | `str` | `''` | Not supported — raises `ValueError`. Enum metrics cannot have a unit. |
+| `registry` | `CollectorRegistry` | `REGISTRY` | Registry to register with. Pass `None` to skip registration, which is useful in tests where you create metrics without wanting them in the global registry. |
+| `states` | `List[str]` | required | The complete list of valid states. Must be non-empty. The first entry is the initial state. |
+
+`namespace`, `subsystem`, and `name` are joined with underscores to form the full metric name:
+
+```python
+# namespace='myapp', subsystem='worker', name='state'
+# produces: myapp_worker_state
+Enum('state', 'Worker state', states=['idle', 'running', 'error'], namespace='myapp', subsystem='worker')
+```
+
+## Methods
+
+### `state(state)`
+
+Set the current state. The value must be one of the strings passed in the `states` list. Raises `ValueError` if the state is not recognized.
+
+```python
+e.state('running')
+e.state('stopped')
+```
+
+## Labels
+
+See [Labels](../labels/) for how to use `.labels()`, `.remove()`, `.remove_by_labels()`, and `.clear()`.
+
+## Real-world example
+
+Tracking the lifecycle state of a background worker:
+
+```python
+from prometheus_client import Enum, start_http_server
+
+WORKER_STATE = Enum(
+    'worker_state',
+    'Current state of the background worker',
+    states=['idle', 'running', 'error'],
+    namespace='myapp',
+)
+
+def process_job():
+    WORKER_STATE.state('running')
+    try:
+        # ... do work ...
+        pass
+    except Exception:
+        WORKER_STATE.state('error')
+        raise
+    finally:
+        WORKER_STATE.state('idle')
+
+if __name__ == '__main__':
+    start_http_server(8000)  # exposes metrics at http://localhost:8000/metrics
+    # ... start your application ...
+```
+
+This produces:
+```
+myapp_worker_state{myapp_worker_state="idle"} 0.0
+myapp_worker_state{myapp_worker_state="running"} 1.0
+myapp_worker_state{myapp_worker_state="error"} 0.0
+```