Merge branch feature/docs-rework into develop

Author: wolph

README.md

@@ -1,202 +1,201 @@
-# Python StatsD Client
+<h1 align="center">python-statsd</h1>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/wolph/python-statsd/develop/docs/_static/dataflow.svg"
+       alt="Metrics leave your application over UDP, statsd aggregates them, Graphite stores and graphs them"
+       width="880">
+</p>
+
+<p align="center">
+  <a href="https://github.com/WoLpH/python-statsd/actions/workflows/ci.yml"><img src="https://github.com/WoLpH/python-statsd/actions/workflows/ci.yml/badge.svg?branch=master" alt="Test status"></a>
+  <a href="https://github.com/WoLpH/python-statsd/actions/workflows/codeql.yml"><img src="https://github.com/WoLpH/python-statsd/actions/workflows/codeql.yml/badge.svg?branch=develop" alt="CodeQL status"></a>
+  <a href="https://python-statsd.readthedocs.io/"><img src="https://img.shields.io/readthedocs/python-statsd?logo=readthedocs&logoColor=white" alt="Documentation"></a>
+  <a href="https://github.com/WoLpH/python-statsd/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen" alt="Coverage, enforced in CI"></a>
+  <br>
+  <a href="https://pypi.org/project/python-statsd/"><img src="https://img.shields.io/pypi/v/python-statsd.svg?logo=pypi&logoColor=white" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/python-statsd/"><img src="https://img.shields.io/pypi/pyversions/python-statsd.svg?logo=python&logoColor=white" alt="Supported Python versions"></a>
+  <a href="https://pepy.tech/project/python-statsd"><img src="https://static.pepy.tech/badge/python-statsd" alt="Downloads"></a>
+  <a href="https://github.com/WoLpH/python-statsd/blob/develop/LICENSE"><img src="https://img.shields.io/pypi/l/python-statsd.svg" alt="BSD-3-Clause licence"></a>
+  <br>
+  <a href="https://github.com/WoLpH/python-statsd/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/types-mypy%20%7C%20basedpyright%20%7C%20pyrefly%20%7C%20ty-8957e5" alt="Type checked by four checkers in CI"></a>
+  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Linted and formatted with ruff"></a>
+</p>
+
+`python-statsd` is a client for Etsy's statsd server, a front end and proxy
+for the Graphite stats collection and graphing server. It supports Python
+3.10 and newer, and it has no dependencies.
 
-[![Test Status](https://github.com/WoLpH/python-statsd/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/WoLpH/python-statsd/actions/workflows/ci.yml)
-[![PyPI version](https://img.shields.io/pypi/v/python-statsd.svg)](https://pypi.org/project/python-statsd/)
-[![Supported Python versions](https://img.shields.io/pypi/pyversions/python-statsd.svg)](https://pypi.org/project/python-statsd/)
-
-`python-statsd` is a client for Etsy's statsd server, a front end/proxy for
-the Graphite stats collection and graphing server. It supports Python 3.10+
-and has no dependencies.
-
-## Note on the package name
+```bash
+pip install python-statsd
+```
 
-This package installs the `statsd` Python module and is published on PyPI as
-`python-statsd`. There is a different project published on PyPI as `statsd`
-(jsocol's client) which *also* installs a `statsd` module. Installing both in
-one environment will break either or both. Install exactly one of the two.
+```python
+import statsd
 
-## Links
+counter = statsd.Counter('app')
+counter += 1
 
-- The source: https://github.com/WoLpH/python-statsd
-- Project page: https://pypi.org/project/python-statsd/
-- Reporting bugs: https://github.com/WoLpH/python-statsd/issues
-- Documentation: https://python-statsd.readthedocs.io/
-- My blog: https://wol.ph/
-- Statsd: https://github.com/etsy/statsd
-- Graphite: https://graphiteapp.org/
+with statsd.Timer('app').time('render'):
+    pass  # the work you are measuring
+```
 
-## Install
+Two metrics, two UDP packets, nothing blocking. A statsd server that is
+down costs you graphs rather than requests.
 
-```bash
-pip install python-statsd
-```
+## What goes on the wire
 
-or with uv:
+Every line under `udp :8125 <` in this recording is a packet the client
+sent, caught by a real listener on the other end:
 
-```bash
-uv pip install python-statsd
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/wolph/python-statsd/develop/docs/_static/demo.gif"
+       alt="A terminal session sending a counter, a gauge, a timer and a sampled counter, with each UDP payload printed as it arrives"
+       width="880">
+</p>
 
-## Usage
+Note the last one. At `sample_rate=0.5` four increments produced a single
+packet, and it carries `|@0.5` so the server knows to multiply back up.
 
-### Basic Usage
+## The metric types
 
-#### Timers
+| Type | A burst of values becomes | Reach for it when |
+| --- | --- | --- |
+| `Counter` | their sum | you are counting events |
+| `Gauge` | the last one | you are reporting a level |
+| `Timer` | mean, median, percentiles | you are measuring duration |
+| `Average` | their mean | the server should average samples |
+| `Raw` | stored as sent | you already did the summarising |
 
 ```python
 import statsd
 
-timer = statsd.Timer('MyApplication')
-timer.start()
-# do something here
-timer.stop('SomeTimer')
-```
+counter = statsd.Counter('app')
+counter.increment('requests')  # app.requests:1|c
 
-Or as a context manager (the metric is also sent when the block raises an
-exception):
+gauge = statsd.Gauge('app')
+gauge.send('queue_depth', 42)  # app.queue_depth:42|g
 
-```python
-import statsd
+average = statsd.Average('app')
+average.send('batch', 123)  # app.batch:123|a
 
-with statsd.Timer('MyApplication').time('SomeTimer'):
-    pass  # do something here
+raw = statsd.Raw('app')
+raw.send('summary', 42, timestamp=1234567890)  # app.summary:42|r|1234567890
 ```
 
-Or as a decorator:
+Timers come in three forms, and the context manager is the one to reach
+for, because it reports the block that raised as well as the block that
+did not:
 
 ```python
 import statsd
 
-timer = statsd.Timer('MyApplication')
+timer = statsd.Timer('app')
+
+with timer.time('render'):
+    pass  # the work you are measuring
 
 
 @timer.decorate
-def some_function():
-    pass  # resulting timer name: MyApplication.some_function
+def render_page():  # sends app.render_page
+    pass
 ```
 
-#### Counters
+Names build themselves when you nest clients, which keeps the string
+formatting out of your call sites:
 
 ```python
 import statsd
 
-counter = statsd.Counter('MyApplication')
-# do something here
-counter += 1
-```
-
-#### Gauge
-
-```python
-import statsd
+app = statsd.Client('app')
+queries = app.get_client('database').get_client('queries', statsd.Counter)
 
-gauge = statsd.Gauge('MyApplication')
-# do something here
-gauge.send('SomeName', 42)
+queries.increment()  # app.database.queries:1|c
 ```
 
-#### Raw
+## See it working
 
-Raw values should be e.g. pre-summarised data or other data that will get
-passed directly to carbon. This can be used as a time and bandwidth-saving
-mechanism: sending a lot of samples could use a lot of bandwidth (more b/w is
-used in udp headers than data for a gauge, for instance).
+The repository ships a compose file with statsd, Graphite and Grafana, so
+you can watch a metric arrive instead of taking anyone's word for it:
 
-```python
-import statsd
-
-raw = statsd.Raw('MyApplication')
-# do something here
-raw.send('SomeName', 42, timestamp=1234567890)
+```bash
+docker compose up -d
+uv run python examples/send_metrics.py --seconds 120
 ```
 
-The raw type wants a timestamp in seconds since the epoch (the standard unix
-timestamp, e.g. the output of `date +%s`). If you leave it out or pass `None`
-the current time is used.
-
-#### Average
+Then open <http://localhost:3000>. Grafana comes up with the datasource
+configured and this dashboard loaded, no login in the way:
 
-```python
-import statsd
+<p align="center">
+  <img src="https://raw.githubusercontent.com/wolph/python-statsd/develop/docs/_static/grafana.png"
+       alt="A Grafana dashboard showing request rate, render time percentiles, queue depth and packets received"
+       width="880">
+</p>
 
-average = statsd.Average('MyApplication')
-# do something here
-average.send('SomeName', 123)
-```
+That screenshot is the stack in this repository, fed by
+`examples/send_metrics.py` through this client. The
+[local stack guide](https://python-statsd.readthedocs.io/en/latest/local-stack.html)
+covers how statsd renames your metrics on the way through, and what to
+check when nothing shows up.
 
-#### Connection settings
+## Configuration
 
-If you need some settings other than the defaults for your `Connection`, you
-can use `Connection.set_defaults()`:
+Set the defaults once at startup and every client built afterwards follows:
 
 ```python
 import statsd
 
-statsd.Connection.set_defaults(
-    host='localhost', port=8125, sample_rate=1, disabled=False
-)
+statsd.Connection.set_defaults(host='localhost', port=8125, sample_rate=1)
 ```
 
-Every interaction with statsd after these are set will use whatever you
-specify, unless you explicitly create a different `Connection` to use
-(described below).
-
-Defaults:
-
-- `host` = `'localhost'`
-- `port` = `8125`
-- `sample_rate` = `1`
-- `disabled` = `False`
-
-## Advanced Usage
+Or build connections yourself when one destination is not enough:
 
 ```python
 import statsd
 
-# Open a connection to `server` on port `1234` with a
-# `50%` sample rate
-statsd_connection = statsd.Connection(
-    host='server',
-    port=1234,
-    sample_rate=0.5,
-)
+connection = statsd.Connection(host='statsd-1', port=8125, sample_rate=0.1)
+statsd.Counter('app.requests', connection).increment()
+```
 
-# Create a client for this application
-statsd_client = statsd.Client(__name__, statsd_connection)
+One trap worth knowing before it costs you an afternoon: a falsy argument
+means "use the default", so `Connection(sample_rate=0)` sends everything.
+Pass `disabled=True` to send nothing.
 
+## Documentation
 
-class SomeClass:
-    def __init__(self):
-        # Create a client specific for this class
-        self.statsd_client = statsd_client.get_client(type(self).__name__)
+Full documentation is at
+[python-statsd.readthedocs.io](https://python-statsd.readthedocs.io/).
 
-    def do_something(self):
-        # Create a `timer` client
-        timer = self.statsd_client.get_client(class_=statsd.Timer)
+- [Metrics](https://python-statsd.readthedocs.io/en/latest/metrics.html):
+  the five types, how to choose, and the exact bytes each one writes
+- [Connections](https://python-statsd.readthedocs.io/en/latest/connections.html):
+  destinations, sampling, disabling, failure behaviour, threads and forks
+- [Patterns](https://python-statsd.readthedocs.io/en/latest/patterns.html):
+  naming, cardinality, client trees, WSGI and Celery integration
+- [Local stack](https://python-statsd.readthedocs.io/en/latest/local-stack.html):
+  docker compose, and how to debug a metric that never arrives
 
-        # start the measurement
-        timer.start()
+For Django, use [django-statsd](https://github.com/wolph/django-statsd),
+the sister project built on this client. It times views and reports the
+queries per request without you writing any of it.
 
-        # do something
-        timer.intermediate('intermediate_value')
+## Note on the package name
 
-        # do something else
-        timer.stop('total')
-```
+This project is published on PyPI as `python-statsd` and installs a module
+called `statsd`. A different project, jsocol's client, is published as
+`statsd` and installs a module called `statsd` as well. Installing both in
+one environment leaves you with whichever was written last, so pick one.
 
-If there is a need to turn *OFF* the service and avoid sending UDP messages,
-the `Connection` class can be disabled with the `disabled` argument:
+## Contributing
 
-```python
-import statsd
+Bug reports and patches are welcome, and `CONTRIBUTING.md` covers the
+development setup: `uv sync --all-extras`, `uv run pytest`, and
+`uv run tox -p auto` to run everything CI runs. Every code sample in this
+README and in the documentation is executed by the test suite, so a change
+in behaviour tends to tell you which paragraph it just made wrong.
 
-statsd_connection = statsd.Connection(
-    host='server',
-    port=1234,
-    sample_rate=0.5,
-    disabled=True,
-)
-```
+## Links
 
-If logging's level is set to debug the `Connection` object will inform it is
-not sending UDP messages anymore.
+- Source: <https://github.com/WoLpH/python-statsd>
+- Issues: <https://github.com/WoLpH/python-statsd/issues>
+- Statsd: <https://github.com/etsy/statsd>
+- Graphite: <https://graphiteapp.org/>

docker-compose.yml

@@ -0,0 +1,40 @@
+# A local statsd, Graphite and Grafana stack for trying python-statsd out.
+#
+#   docker compose up -d
+#   uv run python examples/send_metrics.py --seconds 120
+#
+# Grafana opens on http://localhost:3000 with a provisioned dashboard and
+# no login. Graphite's own interface is on http://localhost:8080.
+
+services:
+  graphite:
+    image: graphiteapp/graphite-statsd:latest
+    container_name: python-statsd-graphite
+    restart: unless-stopped
+    ports:
+      # Every port is overridable, so the stack fits next to whatever
+      # else you are already running: GRAPHITE_HTTP_PORT=8081 docker compose up
+      - '${GRAPHITE_HTTP_PORT:-8080}:80' # Graphite web and its render API
+      - '${STATSD_PORT:-8125}:8125/udp' # statsd, where this client sends
+      - '${STATSD_ADMIN_PORT:-8126}:8126' # statsd admin interface
+    environment:
+      # Ten-second flushes so a graph appears while you are still watching.
+      STATSD_INTERVAL: '10000'
+
+  grafana:
+    image: grafana/grafana:latest
+    container_name: python-statsd-grafana
+    restart: unless-stopped
+    depends_on:
+      - graphite
+    ports:
+      - '${GRAFANA_PORT:-3000}:3000'
+    environment:
+      GF_AUTH_ANONYMOUS_ENABLED: 'true'
+      GF_AUTH_ANONYMOUS_ORG_ROLE: Admin
+      GF_AUTH_DISABLE_LOGIN_FORM: 'true'
+      GF_USERS_DEFAULT_THEME: dark
+      GF_DASHBOARDS_DEFAULT_HOME_DASHBOARD_PATH: /var/lib/grafana/dashboards/python-statsd.json
+    volumes:
+      - ./examples/grafana/provisioning:/etc/grafana/provisioning:ro
+      - ./examples/grafana/dashboards:/var/lib/grafana/dashboards:ro