Merge branch 'prometheus:master' into restrict-multiprocess

Author: mathias-kende

.circleci/config.yml

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  flake8_lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Python
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: '3.9'
+      - name: Install tox
+        run: pip install tox
+      - name: Run flake8
+        run: tox -e flake8
+
+  isort_lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Python
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: '3.9'
+      - name: Install tox
+        run: pip install tox
+      - name: Run isort
+        run: tox -e isort
+
+  mypy_lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Python
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: '3.9'
+      - name: Install tox
+        run: pip install tox
+      - name: Run mypy
+        run: tox -e mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pip install --user tox "virtualenv<20.22.0"
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+      - name: Set tox environment
+        id: toxenv
+        run: |
+          VERSION="${{ matrix.python-version }}"
+          # Extract major.minor version (strip patch if present)
+          TOX_VERSION=$(echo "$VERSION" | cut -d. -f1,2)
+          echo "toxenv=py${TOX_VERSION}" >> $GITHUB_OUTPUT
+      - name: Run tests
+        run: tox
+        env:
+          TOXENV: ${{ steps.toxenv.outputs.toxenv }}
+
+  test_nooptionals:
+    runs-on: ubuntu-latest
+    env:
+      PYTHON_VERSION: '3.9'
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Python
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - name: Install tox
+        run: pip install tox
+      - name: Run tests without optional dependencies
+        run: tox
+        env:
+          TOXENV: py${{ env.PYTHON_VERSION }}-nooptionals
+
+  test_pypy:
+    runs-on: ubuntu-latest
+    env:
+      PYTHON_VERSION: '3.9'
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up PyPy
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: pypy-${{ env.PYTHON_VERSION }}
+      - name: Install tox
+        run: pip install tox
+      - name: Run tests with PyPy
+        run: tox
+        env:
+          TOXENV: pypy${{ env.PYTHON_VERSION }}

.github/workflows/ci.yaml

@@ -11,9 +11,6 @@ on:
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
-  pages: write
-  id-token: write
-  actions: read
 
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
@@ -32,6 +29,9 @@ jobs:
     runs-on: ubuntu-latest
     env:
       HUGO_VERSION: 0.145.0
+    permissions:
+      pages: write
+      id-token: write
     steps:
       - name: Install Hugo CLI
         run: |
@@ -40,13 +40,13 @@ jobs:
       #- name: Install Dart Sass
       #  run: sudo snap install dart-sass
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           submodules: recursive
           fetch-depth: 0
       - name: Setup Pages
         id: pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
       - name: Install Node.js dependencies
         run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
         working-directory: ./docs
@@ -62,7 +62,7 @@ jobs:
             --baseURL "${{ steps.pages.outputs.base_url }}/"
         working-directory: ./docs
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
         with:
           path: ./docs/public
 
@@ -73,7 +73,11 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     needs: build
+    permissions:
+      pages: write
+      id-token: write
+      actions: read
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.github/workflows/github-pages.yaml

@@ -24,6 +24,7 @@ to shutdown the server gracefully:
 ```python
 server, t = start_http_server(8000)
 server.shutdown()
+server.server_close()
 t.join()
 ```
 

docs/content/exporting/http/_index.md

@@ -0,0 +1,47 @@
+---
+title: Django
+weight: 5
+---
+
+To use Prometheus with [Django](https://www.djangoproject.com/) you can use the provided view class 
+to add a metrics endpoint to your app.
+
+```python
+# urls.py
+
+from django.urls import path
+from prometheus_client.django import PrometheusDjangoView
+
+urlpatterns = [
+    # ... any other urls that you want
+    path("metrics/", PrometheusDjangoView.as_view(), name="prometheus-metrics"),
+    # ... still more urls
+]
+```
+
+By default, Multiprocessing support is activated if environment variable `PROMETHEUS_MULTIPROC_DIR` is set.
+You can override this through the view arguments:
+
+```python
+from django.conf import settings
+
+urlpatterns = [
+    path(
+        "metrics/",
+        PrometheusDjangoView.as_view(
+            multiprocess_mode=settings.YOUR_SETTING  # or any boolean value
+        ),
+        name="prometheus-metrics",
+    ),
+]
+```
+
+Full multiprocessing instructions are provided [here]({{< ref "/multiprocess" >}}).
+
+# django-prometheus
+
+The included `PrometheusDjangoView` is useful if you want to define your own metrics from scratch.
+
+An external package called [django-prometheus](https://github.com/django-commons/django-prometheus/) 
+can be used instead if you want to get a bunch of ready-made monitoring metrics for your Django application
+and easily benefit from utilities such as models monitoring.

docs/content/exporting/http/django.md

@@ -54,6 +54,20 @@ g.set_to_current_time()
 push_to_gateway('localhost:9091', job='batchA', registry=registry, handler=my_auth_handler)
 ```
 
+# Compressing data before sending to pushgateway
+Pushgateway (version >= 1.5.0) supports gzip and snappy compression (v > 1.6.0). This can help in network constrained environments.
+To compress a push request, set the `compression` argument to `'gzip'` or `'snappy'`:
+```python
+push_to_gateway(
+    'localhost:9091',
+    job='batchA',
+    registry=registry,
+    handler=my_auth_handler,
+    compression='gzip',
+)
+```
+Snappy compression requires the optional [`python-snappy`](https://github.com/andrix/python-snappy) package.
+
 TLS Auth is also supported when using the push gateway with a special handler.
 
 ```python

docs/content/exporting/pushgateway.md

@@ -1,5 +1,5 @@
 [mypy]
-exclude = prometheus_client/decorator.py|prometheus_client/twisted|tests/test_twisted.py
+exclude = prometheus_client/decorator.py|prometheus_client/twisted|tests/test_twisted.py|prometheus_client/django|tests/test_django.py
 implicit_reexport = False
 disallow_incomplete_defs = True
 

mypy.ini

@@ -4,11 +4,11 @@
 from aiohttp.typedefs import Handler
 
 from ..exposition import _bake_output
-from ..registry import CollectorRegistry, REGISTRY
+from ..registry import Collector, REGISTRY
 
 
 def make_aiohttp_handler(
-    registry: CollectorRegistry = REGISTRY,
+    registry: Collector = REGISTRY,
     disable_compression: bool = False,
 ) -> Handler:
     """Create a aiohttp handler which serves the metrics from a registry."""

prometheus_client/aiohttp/exposition.py

@@ -2,10 +2,10 @@
 from urllib.parse import parse_qs
 
 from .exposition import _bake_output
-from .registry import CollectorRegistry, REGISTRY
+from .registry import Collector, REGISTRY
 
 
-def make_asgi_app(registry: CollectorRegistry = REGISTRY, disable_compression: bool = False) -> Callable:
+def make_asgi_app(registry: Collector = REGISTRY, disable_compression: bool = False) -> Callable:
     """Create a ASGI app which serves the metrics from a registry."""
 
     async def prometheus_app(scope, receive, send):

prometheus_client/asgi.py

@@ -8,7 +8,7 @@
 from timeit import default_timer
 from typing import Callable, Tuple
 
-from ..registry import CollectorRegistry, REGISTRY
+from ..registry import Collector, REGISTRY
 
 # Roughly, have to keep to what works as a file name.
 # We also remove periods, so labels can be distinguished.
@@ -48,7 +48,7 @@ def run(self):
 class GraphiteBridge:
     def __init__(self,
                  address: Tuple[str, int],
-                 registry: CollectorRegistry = REGISTRY,
+                 registry: Collector = REGISTRY,
                  timeout_seconds: float = 30,
                  _timer: Callable[[], float] = time.time,
                  tags: bool = False,