From 8dfa10e5ff5cedd15300f7a13387d646c3010314 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Fri, 16 May 2025 14:39:15 -0600 Subject: [PATCH 01/38] Release 0.22.0 Signed-off-by: Chris Marchbanks --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 05b17551..5305e38b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "prometheus_client" -version = "0.21.1" +version = "0.22.0" description = "Python client for the Prometheus monitoring system." readme = "README.md" license = { file = "LICENSE" } From 938b73e0bc2851d30246d572d5cefecf57b02041 Mon Sep 17 00:00:00 2001 From: Wissam Abu Ahmad Date: Wed, 28 May 2025 23:19:39 +0200 Subject: [PATCH 02/38] BugFix: Skip validating and parsing comment lines early (#1108) (#1109) Signed-off-by: Wissam Abu Ahmad --- prometheus_client/parser.py | 6 +++--- tests/test_parser.py | 11 +++++++++++ 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/prometheus_client/parser.py b/prometheus_client/parser.py index 92d66723..0434edf7 100644 --- a/prometheus_client/parser.py +++ b/prometheus_client/parser.py @@ -308,6 +308,9 @@ def build_metric(name: str, documentation: str, typ: str, samples: List[Sample]) continue candidate_name, quoted = '', False if len(parts) > 2: + # Ignore comment tokens + if parts[1] != 'TYPE' and parts[1] != 'HELP': + continue candidate_name, quoted = _unquote_unescape(parts[2]) if not quoted and not _is_valid_legacy_metric_name(candidate_name): raise ValueError @@ -342,9 +345,6 @@ def build_metric(name: str, documentation: str, typ: str, samples: List[Sample]) 'histogram': ['_count', '_sum', '_bucket'], }.get(typ, ['']) allowed_names = [name + n for n in allowed_names] - else: - # Ignore other comment tokens - pass elif line == '': # Ignore blank lines pass diff --git a/tests/test_parser.py b/tests/test_parser.py index 10a2fc90..e18a8782 100644 --- a/tests/test_parser.py +++ b/tests/test_parser.py @@ -120,6 +120,17 @@ def test_blank_lines_and_comments(self): """) self.assertEqualMetrics([CounterMetricFamily("a", "help", value=1)], list(families)) + + def test_comments_parts_are_not_validated_against_legacy_metric_name(self): + # https://github.com/prometheus/client_python/issues/1108 + families = text_string_to_metric_families(""" +# A simple. comment line where third token cannot be matched against METRIC_NAME_RE under validation.py +# 3565 12345/4436467 another random comment line where third token cannot be matched against METRIC_NAME_RE under validation.py +""") + self.assertEqualMetrics([], list(families)) + + + def test_tabs(self): families = text_string_to_metric_families("""#\tTYPE\ta\tcounter #\tHELP\ta\thelp From f294cbbf1dd24ae8936808923d30fafe0a7e519b Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Mon, 2 Jun 2025 08:23:22 -0600 Subject: [PATCH 03/38] Use License Expressions in pyproject.toml (#1111) With the release of PEP-639 the best practice for specifying the license is now to use a license expression in the license field and specify any license files in license-files rather than the table-based approach from PEP-621. Including the license in the classifiers is also no longer allowed when using PEP-639 and has been removed. Signed-off-by: Chris Marchbanks --- pyproject.toml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 5305e38b..b50119ef 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,5 +1,5 @@ [build-system] -requires = ["setuptools"] +requires = ["setuptools>=77.0.0"] build-backend = "setuptools.build_meta" [project] @@ -7,7 +7,11 @@ name = "prometheus_client" version = "0.22.0" description = "Python client for the Prometheus monitoring system." readme = "README.md" -license = { file = "LICENSE" } +license = "Apache-2.0 AND BSD-2-Clause" +license-files = [ + "LICENSE", + "NOTICE", +] requires-python = ">=3.9" authors = [ { name = "The Prometheus Authors", email = "prometheus-developers@googlegroups.com" }, @@ -33,7 +37,6 @@ classifiers = [ "Programming Language :: Python :: Implementation :: CPython", "Programming Language :: Python :: Implementation :: PyPy", "Topic :: System :: Monitoring", - "License :: OSI Approved :: Apache Software License", ] [project.optional-dependencies] From d24220a6c477eef2dfeb12a312e0da66539095e1 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Mon, 2 Jun 2025 08:26:12 -0600 Subject: [PATCH 04/38] Release 0.22.1 Signed-off-by: Chris Marchbanks --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index b50119ef..0c762505 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "prometheus_client" -version = "0.22.0" +version = "0.22.1" description = "Python client for the Prometheus monitoring system." readme = "README.md" license = "Apache-2.0 AND BSD-2-Clause" From 831ed026fe1b02a98c7e2fbef634915ef2e8efc8 Mon Sep 17 00:00:00 2001 From: Owen Williams Date: Tue, 8 Apr 2025 17:29:15 -0400 Subject: [PATCH 05/38] UTF-8 Content Negotiation Part of https://github.com/prometheus/client_python/issues/1013 Signed-off-by: Owen Williams --- prometheus_client/__init__.py | 9 +- prometheus_client/exposition.py | 115 ++++++-- prometheus_client/openmetrics/exposition.py | 145 ++++++++-- prometheus_client/registry.py | 2 +- prometheus_client/validation.py | 4 + tests/openmetrics/test_exposition.py | 163 ++++++++++- tests/test_asgi.py | 6 +- tests/test_exposition.py | 303 ++++++++++++++++++-- tests/test_parser.py | 3 +- tests/test_twisted.py | 3 +- tests/test_wsgi.py | 4 +- tools/simple_client.py | 28 ++ 12 files changed, 707 insertions(+), 78 deletions(-) create mode 100755 tools/simple_client.py diff --git a/prometheus_client/__init__.py b/prometheus_client/__init__.py index 84a7ba82..221ad273 100644 --- a/prometheus_client/__init__.py +++ b/prometheus_client/__init__.py @@ -5,9 +5,10 @@ process_collector, registry, ) from .exposition import ( - CONTENT_TYPE_LATEST, delete_from_gateway, generate_latest, - instance_ip_grouping_key, make_asgi_app, make_wsgi_app, MetricsHandler, - push_to_gateway, pushadd_to_gateway, start_http_server, start_wsgi_server, + CONTENT_TYPE_LATEST, CONTENT_TYPE_PLAIN_0_0_4, CONTENT_TYPE_PLAIN_1_0_0, + delete_from_gateway, generate_latest, instance_ip_grouping_key, + make_asgi_app, make_wsgi_app, MetricsHandler, push_to_gateway, + pushadd_to_gateway, start_http_server, start_wsgi_server, write_to_textfile, ) from .gc_collector import GC_COLLECTOR, GCCollector @@ -33,6 +34,8 @@ 'enable_created_metrics', 'disable_created_metrics', 'CONTENT_TYPE_LATEST', + 'CONTENT_TYPE_PLAIN_0_0_4', + 'CONTENT_TYPE_PLAIN_1_0_0', 'generate_latest', 'MetricsHandler', 'make_wsgi_app', diff --git a/prometheus_client/exposition.py b/prometheus_client/exposition.py index 0bc3632e..8c84ffb5 100644 --- a/prometheus_client/exposition.py +++ b/prometheus_client/exposition.py @@ -1,5 +1,6 @@ import base64 from contextlib import closing +from functools import partial import gzip from http.server import BaseHTTPRequestHandler import os @@ -17,13 +18,16 @@ ) from wsgiref.simple_server import make_server, WSGIRequestHandler, WSGIServer +from packaging.version import Version + from .openmetrics import exposition as openmetrics from .registry import CollectorRegistry, REGISTRY from .utils import floatToGoString -from .validation import _is_valid_legacy_metric_name __all__ = ( 'CONTENT_TYPE_LATEST', + 'CONTENT_TYPE_PLAIN_0_0_4', + 'CONTENT_TYPE_PLAIN_1_0_0', 'delete_from_gateway', 'generate_latest', 'instance_ip_grouping_key', @@ -37,8 +41,13 @@ 'write_to_textfile', ) -CONTENT_TYPE_LATEST = 'text/plain; version=0.0.4; charset=utf-8' -"""Content type of the latest text format""" +CONTENT_TYPE_PLAIN_0_0_4 = 'text/plain; version=0.0.4; charset=utf-8' +"""Content type of the compatibility format""" + +CONTENT_TYPE_PLAIN_1_0_0 = 'text/plain; version=1.0.0; charset=utf-8' +"""Content type of the latest format""" + +CONTENT_TYPE_LATEST = CONTENT_TYPE_PLAIN_1_0_0 class _PrometheusRedirectHandler(HTTPRedirectHandler): @@ -245,14 +254,23 @@ class TmpServer(ThreadingWSGIServer): start_http_server = start_wsgi_server -def generate_latest(registry: CollectorRegistry = REGISTRY) -> bytes: - """Returns the metrics from the registry in latest text format as a string.""" +def generate_latest(registry: CollectorRegistry = REGISTRY, escaping: str = openmetrics.UNDERSCORES) -> bytes: + """ + Generates the exposition format using the basic Prometheus text format. + + Params: + registry: CollectorRegistry to export data from. + escaping: Escaping scheme used for metric and label names. + + Returns: UTF-8 encoded string containing the metrics in text format. + """ def sample_line(samples): if samples.labels: labelstr = '{0}'.format(','.join( + # Label values always support UTF-8 ['{}="{}"'.format( - openmetrics.escape_label_name(k), openmetrics._escape(v)) + openmetrics.escape_label_name(k, escaping), openmetrics._escape(v, openmetrics.ALLOWUTF8, False)) for k, v in sorted(samples.labels.items())])) else: labelstr = '' @@ -260,14 +278,14 @@ def sample_line(samples): if samples.timestamp is not None: # Convert to milliseconds. timestamp = f' {int(float(samples.timestamp) * 1000):d}' - if _is_valid_legacy_metric_name(samples.name): + if escaping != openmetrics.ALLOWUTF8 or openmetrics._is_valid_legacy_metric_name(samples.name): if labelstr: labelstr = '{{{0}}}'.format(labelstr) - return f'{samples.name}{labelstr} {floatToGoString(samples.value)}{timestamp}\n' + return f'{openmetrics.escape_metric_name(samples.name, escaping)}{labelstr} {floatToGoString(samples.value)}{timestamp}\n' maybe_comma = '' if labelstr: maybe_comma = ',' - return f'{{{openmetrics.escape_metric_name(samples.name)}{maybe_comma}{labelstr}}} {floatToGoString(samples.value)}{timestamp}\n' + return f'{{{openmetrics.escape_metric_name(samples.name, escaping)}{maybe_comma}{labelstr}}} {floatToGoString(samples.value)}{timestamp}\n' output = [] for metric in registry.collect(): @@ -290,8 +308,8 @@ def sample_line(samples): mtype = 'untyped' output.append('# HELP {} {}\n'.format( - openmetrics.escape_metric_name(mname), metric.documentation.replace('\\', r'\\').replace('\n', r'\n'))) - output.append(f'# TYPE {openmetrics.escape_metric_name(mname)} {mtype}\n') + openmetrics.escape_metric_name(mname, escaping), metric.documentation.replace('\\', r'\\').replace('\n', r'\n'))) + output.append(f'# TYPE {openmetrics.escape_metric_name(mname, escaping)} {mtype}\n') om_samples: Dict[str, List[str]] = {} for s in metric.samples: @@ -307,20 +325,79 @@ def sample_line(samples): raise for suffix, lines in sorted(om_samples.items()): - output.append('# HELP {} {}\n'.format(openmetrics.escape_metric_name(metric.name + suffix), + output.append('# HELP {} {}\n'.format(openmetrics.escape_metric_name(metric.name + suffix, escaping), metric.documentation.replace('\\', r'\\').replace('\n', r'\n'))) - output.append(f'# TYPE {openmetrics.escape_metric_name(metric.name + suffix)} gauge\n') + output.append(f'# TYPE {openmetrics.escape_metric_name(metric.name + suffix, escaping)} gauge\n') output.extend(lines) return ''.join(output).encode('utf-8') def choose_encoder(accept_header: str) -> Tuple[Callable[[CollectorRegistry], bytes], str]: + # Python client library accepts a narrower range of content-types than + # Prometheus does. accept_header = accept_header or '' + escaping = openmetrics.UNDERSCORES for accepted in accept_header.split(','): if accepted.split(';')[0].strip() == 'application/openmetrics-text': - return (openmetrics.generate_latest, - openmetrics.CONTENT_TYPE_LATEST) - return generate_latest, CONTENT_TYPE_LATEST + toks = accepted.split(';') + version = _get_version(toks) + escaping = _get_escaping(toks) + # Only return an escaping header if we have a good version and + # mimetype. + if not version: + return (partial(openmetrics.generate_latest, escaping=openmetrics.UNDERSCORES), openmetrics.CONTENT_TYPE_LATEST) + if version and Version(version) >= Version('1.0.0'): + return (partial(openmetrics.generate_latest, escaping=escaping), + openmetrics.CONTENT_TYPE_LATEST + '; escaping=' + str(escaping)) + elif accepted.split(';')[0].strip() == 'text/plain': + toks = accepted.split(';') + version = _get_version(toks) + escaping = _get_escaping(toks) + # Only return an escaping header if we have a good version and + # mimetype. + if version and Version(version) >= Version('1.0.0'): + return (partial(generate_latest, escaping=escaping), + CONTENT_TYPE_LATEST + '; escaping=' + str(escaping)) + return generate_latest, CONTENT_TYPE_PLAIN_0_0_4 + + +def _get_version(accept_header: List[str]) -> str: + """Return the version tag from the Accept header. + + If no version is specified, returns empty string.""" + + for tok in accept_header: + if '=' not in tok: + continue + key, value = tok.strip().split('=', 1) + if key == 'version': + return value + return "" + + +def _get_escaping(accept_header: List[str]) -> str: + """Return the escaping scheme from the Accept header. + + If no escaping scheme is specified or the scheme is not one of the allowed + strings, defaults to UNDERSCORES.""" + + for tok in accept_header: + if '=' not in tok: + continue + key, value = tok.strip().split('=', 1) + if key != 'escaping': + continue + if value == openmetrics.ALLOWUTF8: + return openmetrics.ALLOWUTF8 + elif value == openmetrics.UNDERSCORES: + return openmetrics.UNDERSCORES + elif value == openmetrics.DOTS: + return openmetrics.DOTS + elif value == openmetrics.VALUES: + return openmetrics.VALUES + else: + return openmetrics.UNDERSCORES + return openmetrics.UNDERSCORES def gzip_accepted(accept_encoding_header: str) -> bool: @@ -369,7 +446,7 @@ def factory(cls, registry: CollectorRegistry) -> type: return MyMetricsHandler -def write_to_textfile(path: str, registry: CollectorRegistry) -> None: +def write_to_textfile(path: str, registry: CollectorRegistry, escaping: str = openmetrics.ALLOWUTF8) -> None: """Write metrics to the given path. This is intended for use with the Node exporter textfile collector. @@ -377,7 +454,7 @@ def write_to_textfile(path: str, registry: CollectorRegistry) -> None: tmppath = f'{path}.{os.getpid()}.{threading.current_thread().ident}' try: with open(tmppath, 'wb') as f: - f.write(generate_latest(registry)) + f.write(generate_latest(registry, escaping)) # rename(2) is atomic but fails on Windows if the destination file exists if os.name == 'nt': @@ -645,7 +722,7 @@ def _use_gateway( handler( url=url, method=method, timeout=timeout, - headers=[('Content-Type', CONTENT_TYPE_LATEST)], data=data, + headers=[('Content-Type', CONTENT_TYPE_PLAIN_0_0_4)], data=data, )() diff --git a/prometheus_client/openmetrics/exposition.py b/prometheus_client/openmetrics/exposition.py index 84600605..a89acdab 100644 --- a/prometheus_client/openmetrics/exposition.py +++ b/prometheus_client/openmetrics/exposition.py @@ -1,5 +1,8 @@ #!/usr/bin/env python +from io import StringIO +from sys import maxunicode +from typing import Callable from ..utils import floatToGoString from ..validation import ( @@ -8,6 +11,13 @@ CONTENT_TYPE_LATEST = 'application/openmetrics-text; version=1.0.0; charset=utf-8' """Content type of the latest OpenMetrics text format""" +ESCAPING_HEADER_TAG = 'escaping' + + +ALLOWUTF8 = 'allow-utf-8' +UNDERSCORES = 'underscores' +DOTS = 'dots' +VALUES = 'values' def _is_valid_exemplar_metric(metric, sample): @@ -20,34 +30,35 @@ def _is_valid_exemplar_metric(metric, sample): return False -def generate_latest(registry): +def generate_latest(registry, escaping=UNDERSCORES): '''Returns the metrics from the registry in latest text format as a string.''' output = [] for metric in registry.collect(): try: mname = metric.name output.append('# HELP {} {}\n'.format( - escape_metric_name(mname), _escape(metric.documentation))) - output.append(f'# TYPE {escape_metric_name(mname)} {metric.type}\n') + escape_metric_name(mname, escaping), _escape(metric.documentation, ALLOWUTF8, _is_legacy_labelname_rune))) + output.append(f'# TYPE {escape_metric_name(mname, escaping)} {metric.type}\n') if metric.unit: - output.append(f'# UNIT {escape_metric_name(mname)} {metric.unit}\n') + output.append(f'# UNIT {escape_metric_name(mname, escaping)} {metric.unit}\n') for s in metric.samples: - if not _is_valid_legacy_metric_name(s.name): - labelstr = escape_metric_name(s.name) + if escaping == ALLOWUTF8 and not _is_valid_legacy_metric_name(s.name): + labelstr = escape_metric_name(s.name, escaping) if s.labels: labelstr += ', ' else: labelstr = '' - + if s.labels: items = sorted(s.labels.items()) + # Label values always support UTF-8 labelstr += ','.join( ['{}="{}"'.format( - escape_label_name(k), _escape(v)) + escape_label_name(k, escaping), _escape(v, ALLOWUTF8, _is_legacy_labelname_rune)) for k, v in items]) if labelstr: labelstr = "{" + labelstr + "}" - + if s.exemplar: if not _is_valid_exemplar_metric(metric, s): raise ValueError(f"Metric {metric.name} has exemplars, but is not a histogram bucket or counter") @@ -71,9 +82,9 @@ def generate_latest(registry): timestamp = '' if s.timestamp is not None: timestamp = f' {s.timestamp}' - if _is_valid_legacy_metric_name(s.name): + if (escaping != ALLOWUTF8) or _is_valid_legacy_metric_name(s.name): output.append('{}{} {}{}{}\n'.format( - s.name, + _escape(s.name, escaping, _is_legacy_labelname_rune), labelstr, floatToGoString(s.value), timestamp, @@ -94,24 +105,118 @@ def generate_latest(registry): return ''.join(output).encode('utf-8') -def escape_metric_name(s: str) -> str: +def escape_metric_name(s: str, escaping: str = UNDERSCORES) -> str: """Escapes the metric name and puts it in quotes iff the name does not conform to the legacy Prometheus character set. """ - if _is_valid_legacy_metric_name(s): + if len(s) == 0: return s - return '"{}"'.format(_escape(s)) + if escaping == ALLOWUTF8: + if not _is_valid_legacy_metric_name(s): + return '"{}"'.format(_escape(s, escaping, _is_legacy_metric_rune)) + return _escape(s, escaping, _is_legacy_metric_rune) + elif escaping == UNDERSCORES: + if _is_valid_legacy_metric_name(s): + return s + return _escape(s, escaping, _is_legacy_metric_rune) + elif escaping == DOTS: + return _escape(s, escaping, _is_legacy_metric_rune) + elif escaping == VALUES: + if _is_valid_legacy_metric_name(s): + return s + return _escape(s, escaping, _is_legacy_metric_rune) + return s -def escape_label_name(s: str) -> str: +def escape_label_name(s: str, escaping: str = UNDERSCORES) -> str: """Escapes the label name and puts it in quotes iff the name does not conform to the legacy Prometheus character set. """ - if _is_valid_legacy_labelname(s): + if len(s) == 0: return s - return '"{}"'.format(_escape(s)) + if escaping == ALLOWUTF8: + if not _is_valid_legacy_labelname(s): + return '"{}"'.format(_escape(s, escaping, _is_legacy_labelname_rune)) + return _escape(s, escaping, _is_legacy_labelname_rune) + elif escaping == UNDERSCORES: + if _is_valid_legacy_labelname(s): + return s + return _escape(s, escaping, _is_legacy_labelname_rune) + elif escaping == DOTS: + return _escape(s, escaping, _is_legacy_labelname_rune) + elif escaping == VALUES: + if _is_valid_legacy_labelname(s): + return s + return _escape(s, escaping, _is_legacy_labelname_rune) + return s + + +def _escape(s: str, escaping: str, valid_rune_fn: Callable[[str, int], bool]) -> str: + """Performs backslash escaping on backslash, newline, and double-quote characters. + + valid_rune_fn takes the input character and its index in the containing string.""" + if escaping == ALLOWUTF8: + return s.replace('\\', r'\\').replace('\n', r'\n').replace('"', r'\"') + elif escaping == UNDERSCORES: + escaped = StringIO() + for i, b in enumerate(s): + if valid_rune_fn(b, i): + escaped.write(b) + else: + escaped.write('_') + return escaped.getvalue() + elif escaping == DOTS: + escaped = StringIO() + for i, b in enumerate(s): + if b == '_': + escaped.write('__') + elif b == '.': + escaped.write('_dot_') + elif valid_rune_fn(b, i): + escaped.write(b) + else: + escaped.write('__') + return escaped.getvalue() + elif escaping == VALUES: + escaped = StringIO() + escaped.write("U__") + for i, b in enumerate(s): + if b == '_': + escaped.write("__") + elif valid_rune_fn(b, i): + escaped.write(b) + elif not _is_valid_utf8(b): + escaped.write("_FFFD_") + else: + escaped.write('_') + escaped.write(format(ord(b), 'x')) + escaped.write('_') + return escaped.getvalue() + return s + +def _is_legacy_metric_rune(b: str, i: int) -> bool: + return _is_legacy_labelname_rune(b, i) or b == ':' -def _escape(s: str) -> str: - """Performs backslash escaping on backslash, newline, and double-quote characters.""" - return s.replace('\\', r'\\').replace('\n', r'\n').replace('"', r'\"') + +def _is_legacy_labelname_rune(b: str, i: int) -> bool: + if len(b) != 1: + raise ValueError("Input 'b' must be a single character.") + return ( + ('a' <= b <= 'z') + or ('A' <= b <= 'Z') + or (b == '_') + or ('0' <= b <= '9' and i > 0) + ) + + +_SURROGATE_MIN = 0xD800 +_SURROGATE_MAX = 0xDFFF + + +def _is_valid_utf8(s: str) -> bool: + if 0 <= ord(s) < _SURROGATE_MIN: + return True + if _SURROGATE_MAX < ord(s) <= maxunicode: + return True + return False diff --git a/prometheus_client/registry.py b/prometheus_client/registry.py index 694e4bd8..8de4ce91 100644 --- a/prometheus_client/registry.py +++ b/prometheus_client/registry.py @@ -103,7 +103,7 @@ def restricted_registry(self, names: Iterable[str]) -> "RestrictedRegistry": only samples with the given names. Intended usage is: - generate_latest(REGISTRY.restricted_registry(['a_timeseries'])) + generate_latest(REGISTRY.restricted_registry(['a_timeseries']), escaping) Experimental.""" names = set(names) diff --git a/prometheus_client/validation.py b/prometheus_client/validation.py index bf19fc75..7ada5d81 100644 --- a/prometheus_client/validation.py +++ b/prometheus_client/validation.py @@ -51,6 +51,8 @@ def _validate_metric_name(name: str) -> None: def _is_valid_legacy_metric_name(name: str) -> bool: """Returns true if the provided metric name conforms to the legacy validation scheme.""" + if len(name) == 0: + return False return METRIC_NAME_RE.match(name) is not None @@ -94,6 +96,8 @@ def _validate_labelname(l): def _is_valid_legacy_labelname(l: str) -> bool: """Returns true if the provided label name conforms to the legacy validation scheme.""" + if len(l) == 0: + return False if METRIC_LABEL_NAME_RE.match(l) is None: return False return RESERVED_METRIC_LABEL_NAME_RE.match(l) is None diff --git a/tests/openmetrics/test_exposition.py b/tests/openmetrics/test_exposition.py index 124e55e9..9f790642 100644 --- a/tests/openmetrics/test_exposition.py +++ b/tests/openmetrics/test_exposition.py @@ -1,13 +1,18 @@ import time import unittest +import pytest + from prometheus_client import ( CollectorRegistry, Counter, Enum, Gauge, Histogram, Info, Metric, Summary, ) from prometheus_client.core import ( Exemplar, GaugeHistogramMetricFamily, Timestamp, ) -from prometheus_client.openmetrics.exposition import generate_latest +from prometheus_client.openmetrics.exposition import ( + ALLOWUTF8, DOTS, escape_label_name, escape_metric_name, generate_latest, + UNDERSCORES, VALUES, +) class TestGenerateText(unittest.TestCase): @@ -33,12 +38,22 @@ def test_counter(self): c.inc() self.assertEqual(b'# HELP cc A counter\n# TYPE cc counter\ncc_total 1.0\ncc_created 123.456\n# EOF\n', generate_latest(self.registry)) - + def test_counter_utf8(self): c = Counter('cc.with.dots', 'A counter', registry=self.registry) c.inc() self.assertEqual(b'# HELP "cc.with.dots" A counter\n# TYPE "cc.with.dots" counter\n{"cc.with.dots_total"} 1.0\n{"cc.with.dots_created"} 123.456\n# EOF\n', - generate_latest(self.registry)) + generate_latest(self.registry, ALLOWUTF8)) + + def test_counter_utf8_escaped_underscores(self): + c = Counter('utf8.cc', 'A counter', registry=self.registry) + c.inc() + assert b"""# HELP utf8_cc A counter +# TYPE utf8_cc counter +utf8_cc_total 1.0 +utf8_cc_created 123.456 +# EOF +""" == generate_latest(self.registry, UNDERSCORES) def test_counter_total(self): c = Counter('cc_total', 'A counter', registry=self.registry) @@ -282,5 +297,147 @@ def collect(self): """, generate_latest(self.registry)) +@pytest.mark.parametrize("scenario", [ + { + "name": "empty string", + "input": "", + "expectedUnderscores": "", + "expectedDots": "", + "expectedValue": "", + }, + { + "name": "legacy valid metric name", + "input": "no:escaping_required", + "expectedUnderscores": "no:escaping_required", + "expectedDots": "no:escaping__required", + "expectedValue": "no:escaping_required", + }, + { + "name": "metric name with dots", + "input": "mysystem.prod.west.cpu.load", + "expectedUnderscores": "mysystem_prod_west_cpu_load", + "expectedDots": "mysystem_dot_prod_dot_west_dot_cpu_dot_load", + "expectedValue": "U__mysystem_2e_prod_2e_west_2e_cpu_2e_load", + }, + { + "name": "metric name with dots and underscore", + "input": "mysystem.prod.west.cpu.load_total", + "expectedUnderscores": "mysystem_prod_west_cpu_load_total", + "expectedDots": "mysystem_dot_prod_dot_west_dot_cpu_dot_load__total", + "expectedValue": "U__mysystem_2e_prod_2e_west_2e_cpu_2e_load__total", + }, + { + "name": "metric name with dots and colon", + "input": "http.status:sum", + "expectedUnderscores": "http_status:sum", + "expectedDots": "http_dot_status:sum", + "expectedValue": "U__http_2e_status:sum", + }, + { + "name": "metric name with spaces and emoji", + "input": "label with 😱", + "expectedUnderscores": "label_with__", + "expectedDots": "label__with____", + "expectedValue": "U__label_20_with_20__1f631_", + }, + { + "name": "metric name with unicode characters > 0x100", + "input": "花火", + "expectedUnderscores": "__", + "expectedDots": "____", + "expectedValue": "U___82b1__706b_", + }, + { + "name": "metric name with spaces and edge-case value", + "input": "label with \u0100", + "expectedUnderscores": "label_with__", + "expectedDots": "label__with____", + "expectedValue": "U__label_20_with_20__100_", + }, +]) +def test_escape_metric_name(scenario): + input = scenario["input"] + + got = escape_metric_name(input, UNDERSCORES) + assert got == scenario["expectedUnderscores"], f"[{scenario['name']}] Underscore escaping failed" + + got = escape_metric_name(input, DOTS) + assert got == scenario["expectedDots"], f"[{scenario['name']}] Dots escaping failed" + + got = escape_metric_name(input, VALUES) + assert got == scenario["expectedValue"], f"[{scenario['name']}] Value encoding failed" + + +@pytest.mark.parametrize("scenario", [ + { + "name": "empty string", + "input": "", + "expectedUnderscores": "", + "expectedDots": "", + "expectedValue": "", + }, + { + "name": "legacy valid label name", + "input": "no_escaping_required", + "expectedUnderscores": "no_escaping_required", + "expectedDots": "no__escaping__required", + "expectedValue": "no_escaping_required", + }, + { + "name": "label name with dots", + "input": "mysystem.prod.west.cpu.load", + "expectedUnderscores": "mysystem_prod_west_cpu_load", + "expectedDots": "mysystem_dot_prod_dot_west_dot_cpu_dot_load", + "expectedValue": "U__mysystem_2e_prod_2e_west_2e_cpu_2e_load", + }, + { + "name": "label name with dots and underscore", + "input": "mysystem.prod.west.cpu.load_total", + "expectedUnderscores": "mysystem_prod_west_cpu_load_total", + "expectedDots": "mysystem_dot_prod_dot_west_dot_cpu_dot_load__total", + "expectedValue": "U__mysystem_2e_prod_2e_west_2e_cpu_2e_load__total", + }, + { + "name": "label name with dots and colon", + "input": "http.status:sum", + "expectedUnderscores": "http_status_sum", + "expectedDots": "http_dot_status__sum", + "expectedValue": "U__http_2e_status_3a_sum", + }, + { + "name": "label name with spaces and emoji", + "input": "label with 😱", + "expectedUnderscores": "label_with__", + "expectedDots": "label__with____", + "expectedValue": "U__label_20_with_20__1f631_", + }, + { + "name": "label name with unicode characters > 0x100", + "input": "花火", + "expectedUnderscores": "__", + "expectedDots": "____", + "expectedValue": "U___82b1__706b_", + }, + { + "name": "label name with spaces and edge-case value", + "input": "label with \u0100", + "expectedUnderscores": "label_with__", + "expectedDots": "label__with____", + "expectedValue": "U__label_20_with_20__100_", + }, +]) +def test_escape_label_name(scenario): + input = scenario["input"] + + got = escape_label_name(input, UNDERSCORES) + assert got == scenario["expectedUnderscores"], f"[{scenario['name']}] Underscore escaping failed" + + got = escape_label_name(input, DOTS) + assert got == scenario["expectedDots"], f"[{scenario['name']}] Dots escaping failed" + + got = escape_label_name(input, VALUES) + assert got == scenario["expectedValue"], f"[{scenario['name']}] Value encoding failed" + + if __name__ == '__main__': unittest.main() diff --git a/tests/test_asgi.py b/tests/test_asgi.py index 78e24193..eaa195d0 100644 --- a/tests/test_asgi.py +++ b/tests/test_asgi.py @@ -2,7 +2,7 @@ from unittest import skipUnless, TestCase from prometheus_client import CollectorRegistry, Counter -from prometheus_client.exposition import CONTENT_TYPE_LATEST +from prometheus_client.exposition import CONTENT_TYPE_PLAIN_0_0_4 try: # Python >3.5 only @@ -104,7 +104,7 @@ def assert_outputs(self, outputs, metric_name, help_text, increments, compressed # Headers num_of_headers = 2 if compressed else 1 self.assertEqual(len(response_start['headers']), num_of_headers) - self.assertIn((b"Content-Type", CONTENT_TYPE_LATEST.encode('utf8')), response_start['headers']) + self.assertIn((b"Content-Type", CONTENT_TYPE_PLAIN_0_0_4.encode('utf8')), response_start['headers']) if compressed: self.assertIn((b"Content-Encoding", b"gzip"), response_start['headers']) # Body @@ -176,7 +176,7 @@ def test_openmetrics_encoding(self): """Response content type is application/openmetrics-text when appropriate Accept header is in request""" app = make_asgi_app(self.registry) self.seed_app(app) - self.scope["headers"] = [(b"Accept", b"application/openmetrics-text")] + self.scope["headers"] = [(b"Accept", b"application/openmetrics-text; version=1.0.0")] self.send_input({"type": "http.request", "body": b""}) content_type = self.get_response_header_value('Content-Type').split(";")[0] diff --git a/tests/test_exposition.py b/tests/test_exposition.py index 2a3f08cb..3dd5e378 100644 --- a/tests/test_exposition.py +++ b/tests/test_exposition.py @@ -7,9 +7,10 @@ import pytest from prometheus_client import ( - CollectorRegistry, CONTENT_TYPE_LATEST, core, Counter, delete_from_gateway, - Enum, Gauge, generate_latest, Histogram, Info, instance_ip_grouping_key, - Metric, push_to_gateway, pushadd_to_gateway, Summary, + CollectorRegistry, CONTENT_TYPE_LATEST, CONTENT_TYPE_PLAIN_0_0_4, + CONTENT_TYPE_PLAIN_1_0_0, core, Counter, delete_from_gateway, Enum, Gauge, + generate_latest, Histogram, Info, instance_ip_grouping_key, Metric, + push_to_gateway, pushadd_to_gateway, Summary, ) from prometheus_client.core import GaugeHistogramMetricFamily, Timestamp from prometheus_client.exposition import ( @@ -46,8 +47,8 @@ def test_counter(self): # HELP cc_created A counter # TYPE cc_created gauge cc_created 123.456 -""", generate_latest(self.registry)) - +""", generate_latest(self.registry, openmetrics.ALLOWUTF8)) + def test_counter_utf8(self): c = Counter('utf8.cc', 'A counter', registry=self.registry) c.inc() @@ -57,7 +58,18 @@ def test_counter_utf8(self): # HELP "utf8.cc_created" A counter # TYPE "utf8.cc_created" gauge {"utf8.cc_created"} 123.456 -""", generate_latest(self.registry)) +""", generate_latest(self.registry, openmetrics.ALLOWUTF8)) + + def test_counter_utf8_escaped_underscores(self): + c = Counter('utf8.cc', 'A counter', registry=self.registry) + c.inc() + assert b"""# HELP utf8_cc_total A counter +# TYPE utf8_cc_total counter +utf8_cc_total 1.0 +# HELP utf8_cc_created A counter +# TYPE utf8_cc_created gauge +utf8_cc_created 123.456 +""" == generate_latest(self.registry, openmetrics.UNDERSCORES) def test_counter_name_unit_append(self): c = Counter('requests', 'Request counter', unit="total", registry=self.registry) @@ -264,70 +276,70 @@ def test_push(self): push_to_gateway(self.address, "my_job", self.registry) self.assertEqual(self.requests[0][0].command, 'PUT') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') def test_push_schemeless_url(self): push_to_gateway(self.address.replace('http://', ''), "my_job", self.registry) self.assertEqual(self.requests[0][0].command, 'PUT') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') def test_push_with_groupingkey(self): push_to_gateway(self.address, "my_job", self.registry, {'a': 9}) self.assertEqual(self.requests[0][0].command, 'PUT') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job/a/9') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') def test_push_with_groupingkey_empty_label(self): push_to_gateway(self.address, "my_job", self.registry, {'a': ''}) self.assertEqual(self.requests[0][0].command, 'PUT') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job/a@base64/=') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') def test_push_with_complex_groupingkey(self): push_to_gateway(self.address, "my_job", self.registry, {'a': 9, 'b': 'a/ z'}) self.assertEqual(self.requests[0][0].command, 'PUT') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job/a/9/b@base64/YS8geg==') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') def test_push_with_complex_job(self): push_to_gateway(self.address, "my/job", self.registry) self.assertEqual(self.requests[0][0].command, 'PUT') self.assertEqual(self.requests[0][0].path, '/metrics/job@base64/bXkvam9i') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') def test_pushadd(self): pushadd_to_gateway(self.address, "my_job", self.registry) self.assertEqual(self.requests[0][0].command, 'POST') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') def test_pushadd_with_groupingkey(self): pushadd_to_gateway(self.address, "my_job", self.registry, {'a': 9}) self.assertEqual(self.requests[0][0].command, 'POST') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job/a/9') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') def test_delete(self): delete_from_gateway(self.address, "my_job") self.assertEqual(self.requests[0][0].command, 'DELETE') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'') def test_delete_with_groupingkey(self): delete_from_gateway(self.address, "my_job", {'a': 9}) self.assertEqual(self.requests[0][0].command, 'DELETE') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job/a/9') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'') def test_push_with_handler(self): @@ -340,7 +352,7 @@ def my_test_handler(url, method, timeout, headers, data): push_to_gateway(self.address, "my_job", self.registry, handler=my_test_handler) self.assertEqual(self.requests[0][0].command, 'PUT') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][0].headers.get('x-test-header'), 'foobar') self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') @@ -351,7 +363,7 @@ def my_auth_handler(url, method, timeout, headers, data): push_to_gateway(self.address, "my_job_with_basic_auth", self.registry, handler=my_auth_handler) self.assertEqual(self.requests[0][0].command, 'PUT') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job_with_basic_auth') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') def test_push_with_tls_auth_handler(self): @@ -362,7 +374,7 @@ def my_auth_handler(url, method, timeout, headers, data): push_to_gateway(self.address, "my_job_with_tls_auth", self.registry, handler=my_auth_handler) self.assertEqual(self.requests[0][0].command, 'PUT') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job_with_tls_auth') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') def test_push_with_redirect_handler(self): @@ -372,7 +384,7 @@ def my_redirect_handler(url, method, timeout, headers, data): push_to_gateway(self.address, "my_job_with_redirect", self.registry, handler=my_redirect_handler) self.assertEqual(self.requests[0][0].command, 'PUT') self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job_with_redirect') - self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_LATEST) + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') # ensure the redirect preserved request settings from the initial request. @@ -423,7 +435,7 @@ def collect(self): def _expect_metric_exception(registry, expected_error): try: - generate_latest(registry) + generate_latest(registry, openmetrics.ALLOWUTF8) except expected_error as exception: assert isinstance(exception.args[-1], core.Metric) # Got a valid error as expected, return quietly @@ -484,10 +496,251 @@ def test_histogram_metric_families(MetricFamily, registry, buckets, sum_value, e _expect_metric_exception(registry, error) -def test_choose_encoder(): - assert choose_encoder(None) == (generate_latest, CONTENT_TYPE_LATEST) - assert choose_encoder(CONTENT_TYPE_LATEST) == (generate_latest, CONTENT_TYPE_LATEST) - assert choose_encoder(openmetrics.CONTENT_TYPE_LATEST) == (openmetrics.generate_latest, openmetrics.CONTENT_TYPE_LATEST) +class TestChooseEncoder(unittest.TestCase): + def setUp(self): + self.registry = CollectorRegistry() + c = Counter('dotted.counter', 'A counter', registry=self.registry) + c.inc() + + def custom_collector(self, metric_family): + class CustomCollector: + def collect(self): + return [metric_family] + + self.registry.register(CustomCollector()) + + def assert_is_escaped(self, exp): + self.assertRegex(exp, r'.*\ndotted_counter_total 1.0\n.*') + + def assert_is_utf8(self, exp): + self.assertRegex(exp, r'.*\n{"dotted.counter_total"} 1.0\n.*') + + def assert_is_prom(self, exp): + self.assertNotRegex(exp, r'# EOF') + + def assert_is_openmetrics(self, exp): + self.assertRegex(exp, r'# EOF') + + def test_default_encoder(self): + generator, content_type = choose_encoder(None) + assert content_type == CONTENT_TYPE_PLAIN_0_0_4 + exp = generator(self.registry).decode('utf-8') + self.assert_is_escaped(exp) + self.assert_is_prom(exp) + + def test_plain_encoder(self): + generator, content_type = choose_encoder(CONTENT_TYPE_PLAIN_0_0_4) + assert content_type == CONTENT_TYPE_PLAIN_0_0_4 + exp = generator(self.registry).decode('utf-8') + self.assert_is_escaped(exp) + self.assert_is_prom(exp) + + def test_openmetrics_latest(self): + generator, content_type = choose_encoder(openmetrics.CONTENT_TYPE_LATEST) + assert content_type == 'application/openmetrics-text; version=1.0.0; charset=utf-8; escaping=underscores' + exp = generator(self.registry).decode('utf-8') + self.assert_is_escaped(exp) + self.assert_is_openmetrics(exp) + + def test_openmetrics_utf8(self): + generator, content_type = choose_encoder(openmetrics.CONTENT_TYPE_LATEST + '; escaping=allow-utf-8') + assert content_type == openmetrics.CONTENT_TYPE_LATEST + '; escaping=allow-utf-8' + exp = generator(self.registry).decode('utf-8') + self.assert_is_utf8(exp) + self.assert_is_openmetrics(exp) + + def test_openmetrics_dots_escaping(self): + generator, content_type = choose_encoder(openmetrics.CONTENT_TYPE_LATEST + '; escaping=dots') + assert content_type == openmetrics.CONTENT_TYPE_LATEST + '; escaping=dots' + exp = generator(self.registry).decode('utf-8') + self.assertRegex(exp, r'.*\ndotted_dot_counter__total 1.0\n.*') + self.assert_is_openmetrics(exp) + + def test_prom_latest(self): + generator, content_type = choose_encoder(CONTENT_TYPE_LATEST) + assert content_type == CONTENT_TYPE_PLAIN_1_0_0 + '; escaping=underscores' + exp = generator(self.registry).decode('utf-8') + self.assert_is_escaped(exp) + self.assert_is_prom(exp) + + def test_prom_plain_1_0_0(self): + generator, content_type = choose_encoder(CONTENT_TYPE_PLAIN_1_0_0) + assert content_type == CONTENT_TYPE_PLAIN_1_0_0 + '; escaping=underscores' + exp = generator(self.registry).decode('utf-8') + self.assert_is_escaped(exp) + self.assert_is_prom(exp) + + def test_prom_utf8(self): + generator, content_type = choose_encoder(CONTENT_TYPE_PLAIN_1_0_0 + '; escaping=allow-utf-8') + assert content_type == CONTENT_TYPE_PLAIN_1_0_0 + '; escaping=allow-utf-8' + exp = generator(self.registry).decode('utf-8') + self.assert_is_utf8(exp) + self.assert_is_prom(exp) + + def test_prom_dots_escaping(self): + generator, content_type = choose_encoder(CONTENT_TYPE_PLAIN_1_0_0 + '; escaping=dots') + assert content_type == CONTENT_TYPE_PLAIN_1_0_0 + '; escaping=dots' + exp = generator(self.registry).decode('utf-8') + self.assertRegex(exp, r'.*\ndotted_dot_counter__total 1.0\n.*') + self.assert_is_prom(exp) + + def test_openmetrics_no_version(self): + generator, content_type = choose_encoder('application/openmetrics-text; charset=utf-8; escaping=allow-utf-8') + assert content_type == 'application/openmetrics-text; version=1.0.0; charset=utf-8' + exp = generator(self.registry).decode('utf-8') + # No version -- allow-utf-8 rejected. + self.assert_is_escaped(exp) + self.assert_is_openmetrics(exp) + + def test_prom_no_version(self): + generator, content_type = choose_encoder('text/plain; charset=utf-8; escaping=allow-utf-8') + assert content_type == 'text/plain; version=0.0.4; charset=utf-8' + exp = generator(self.registry).decode('utf-8') + # No version -- allow-utf-8 rejected. + self.assert_is_escaped(exp) + self.assert_is_prom(exp) + + +@pytest.mark.parametrize("scenario", [ + { + "name": "empty string", + "input": "", + "expectedUnderscores": "", + "expectedDots": "", + "expectedValue": "", + }, + { + "name": "legacy valid metric name", + "input": "no:escaping_required", + "expectedUnderscores": "no:escaping_required", + "expectedDots": "no:escaping__required", + "expectedValue": "no:escaping_required", + }, + { + "name": "metric name with dots", + "input": "mysystem.prod.west.cpu.load", + "expectedUnderscores": "mysystem_prod_west_cpu_load", + "expectedDots": "mysystem_dot_prod_dot_west_dot_cpu_dot_load", + "expectedValue": "U__mysystem_2e_prod_2e_west_2e_cpu_2e_load", + }, + { + "name": "metric name with dots and underscore", + "input": "mysystem.prod.west.cpu.load_total", + "expectedUnderscores": "mysystem_prod_west_cpu_load_total", + "expectedDots": "mysystem_dot_prod_dot_west_dot_cpu_dot_load__total", + "expectedValue": "U__mysystem_2e_prod_2e_west_2e_cpu_2e_load__total", + }, + { + "name": "metric name with dots and colon", + "input": "http.status:sum", + "expectedUnderscores": "http_status:sum", + "expectedDots": "http_dot_status:sum", + "expectedValue": "U__http_2e_status:sum", + }, + { + "name": "metric name with spaces and emoji", + "input": "label with 😱", + "expectedUnderscores": "label_with__", + "expectedDots": "label__with____", + "expectedValue": "U__label_20_with_20__1f631_", + }, + { + "name": "metric name with unicode characters > 0x100", + "input": "花火", + "expectedUnderscores": "__", + "expectedDots": "____", + "expectedValue": "U___82b1__706b_", + }, + { + "name": "metric name with spaces and edge-case value", + "input": "label with \u0100", + "expectedUnderscores": "label_with__", + "expectedDots": "label__with____", + "expectedValue": "U__label_20_with_20__100_", + }, +]) +def test_escape_metric_name(scenario): + input = scenario["input"] + + got = openmetrics.escape_metric_name(input, openmetrics.UNDERSCORES) + assert got == scenario["expectedUnderscores"], f"[{scenario['name']}] Underscore escaping failed" + + got = openmetrics.escape_metric_name(input, openmetrics.DOTS) + assert got == scenario["expectedDots"], f"[{scenario['name']}] Dots escaping failed" + + got = openmetrics.escape_metric_name(input, openmetrics.VALUES) + assert got == scenario["expectedValue"], f"[{scenario['name']}] Value encoding failed" + + +@pytest.mark.parametrize("scenario", [ + { + "name": "empty string", + "input": "", + "expectedUnderscores": "", + "expectedDots": "", + "expectedValue": "", + }, + { + "name": "legacy valid label name", + "input": "no_escaping_required", + "expectedUnderscores": "no_escaping_required", + "expectedDots": "no__escaping__required", + "expectedValue": "no_escaping_required", + }, + { + "name": "label name with dots", + "input": "mysystem.prod.west.cpu.load", + "expectedUnderscores": "mysystem_prod_west_cpu_load", + "expectedDots": "mysystem_dot_prod_dot_west_dot_cpu_dot_load", + "expectedValue": "U__mysystem_2e_prod_2e_west_2e_cpu_2e_load", + }, + { + "name": "label name with dots and underscore", + "input": "mysystem.prod.west.cpu.load_total", + "expectedUnderscores": "mysystem_prod_west_cpu_load_total", + "expectedDots": "mysystem_dot_prod_dot_west_dot_cpu_dot_load__total", + "expectedValue": "U__mysystem_2e_prod_2e_west_2e_cpu_2e_load__total", + }, + { + "name": "label name with dots and colon", + "input": "http.status:sum", + "expectedUnderscores": "http_status_sum", + "expectedDots": "http_dot_status__sum", + "expectedValue": "U__http_2e_status_3a_sum", + }, + { + "name": "label name with spaces and emoji", + "input": "label with 😱", + "expectedUnderscores": "label_with__", + "expectedDots": "label__with____", + "expectedValue": "U__label_20_with_20__1f631_", + }, + { + "name": "label name with unicode characters > 0x100", + "input": "花火", + "expectedUnderscores": "__", + "expectedDots": "____", + "expectedValue": "U___82b1__706b_", + }, + { + "name": "label name with spaces and edge-case value", + "input": "label with \u0100", + "expectedUnderscores": "label_with__", + "expectedDots": "label__with____", + "expectedValue": "U__label_20_with_20__100_", + }, +]) +def test_escape_label_name(scenario): + input = scenario["input"] + + got = openmetrics.escape_label_name(input, openmetrics.UNDERSCORES) + assert got == scenario["expectedUnderscores"], f"[{scenario['name']}] Underscore escaping failed" + + got = openmetrics.escape_label_name(input, openmetrics.DOTS) + assert got == scenario["expectedDots"], f"[{scenario['name']}] Dots escaping failed" + + got = openmetrics.escape_label_name(input, openmetrics.VALUES) + assert got == scenario["expectedValue"], f"[{scenario['name']}] Value encoding failed" if __name__ == '__main__': diff --git a/tests/test_parser.py b/tests/test_parser.py index e18a8782..66cb5ec1 100644 --- a/tests/test_parser.py +++ b/tests/test_parser.py @@ -6,6 +6,7 @@ HistogramMetricFamily, Metric, Sample, SummaryMetricFamily, ) from prometheus_client.exposition import generate_latest +from prometheus_client.openmetrics.exposition import ALLOWUTF8 from prometheus_client.parser import text_string_to_metric_families @@ -367,7 +368,7 @@ def collect(self): registry = CollectorRegistry() registry.register(TextCollector()) - self.assertEqual(text.encode('utf-8'), generate_latest(registry)) + self.assertEqual(text.encode('utf-8'), generate_latest(registry, ALLOWUTF8)) if __name__ == '__main__': diff --git a/tests/test_twisted.py b/tests/test_twisted.py index e63c903e..730e56ed 100644 --- a/tests/test_twisted.py +++ b/tests/test_twisted.py @@ -1,6 +1,7 @@ from unittest import skipUnless from prometheus_client import CollectorRegistry, Counter, generate_latest +from prometheus_client.openmetrics.exposition import ALLOWUTF8 try: from warnings import filterwarnings @@ -47,6 +48,6 @@ def test_reports_metrics(self): "with a transport that does not have an abortConnection method") d.addCallback(readBody) - d.addCallback(self.assertEqual, generate_latest(self.registry)) + d.addCallback(self.assertEqual, generate_latest(self.registry, ALLOWUTF8)) return d diff --git a/tests/test_wsgi.py b/tests/test_wsgi.py index 2ecfd728..eb2d0566 100644 --- a/tests/test_wsgi.py +++ b/tests/test_wsgi.py @@ -3,7 +3,7 @@ from wsgiref.util import setup_testing_defaults from prometheus_client import CollectorRegistry, Counter, make_wsgi_app -from prometheus_client.exposition import _bake_output, CONTENT_TYPE_LATEST +from prometheus_client.exposition import _bake_output, CONTENT_TYPE_PLAIN_0_0_4 class WSGITest(TestCase): @@ -35,7 +35,7 @@ def assert_outputs(self, outputs, metric_name, help_text, increments, compressed # Headers num_of_headers = 2 if compressed else 1 self.assertEqual(len(self.captured_headers), num_of_headers) - self.assertIn(("Content-Type", CONTENT_TYPE_LATEST), self.captured_headers) + self.assertIn(("Content-Type", CONTENT_TYPE_PLAIN_0_0_4), self.captured_headers) if compressed: self.assertIn(("Content-Encoding", "gzip"), self.captured_headers) # Body diff --git a/tools/simple_client.py b/tools/simple_client.py new file mode 100755 index 00000000..0ccefb73 --- /dev/null +++ b/tools/simple_client.py @@ -0,0 +1,28 @@ +# A simple client that serves random gauges. +# usage: uvicorn tools.simple_client:app --reload + +from fastapi import FastAPI +from fastapi.responses import RedirectResponse +from prometheus_client.asgi import make_asgi_app +from prometheus_client.core import GaugeMetricFamily, REGISTRY +import random + + +class CustomCollector: + def collect(self): + g = GaugeMetricFamily('my.random.utf8.metric', 'Random value', labels=['label.1']) + g.add_metric(['value.1'], random.random()) + g.add_metric(['value.2'], random.random()) + yield g + + +app = FastAPI() + + +@app.get("/") +async def root(): + return RedirectResponse(url="/metrics") + + +REGISTRY.register(CustomCollector()) +app.mount("/metrics", make_asgi_app(REGISTRY)) From 6f19d31e30c2f8bb44afe953ead19a1de1592367 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Thu, 12 Jun 2025 20:06:45 +0200 Subject: [PATCH 06/38] Fix including test data (#1113) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Readd parts of `MANIFEST.in` responsible for including the test data in the source distribution. Without that, setuptools includes only `.py` files from the test tree, leading to test failures. Fixes #1112 Signed-off-by: Michał Górny --- MANIFEST.in | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 MANIFEST.in diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 00000000..9819b942 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,2 @@ +graft tests/certs +graft tests/proc From 09b0826daf006f461b83c1a0bfccfe7dfb742c48 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Thu, 26 Jun 2025 14:25:01 -0600 Subject: [PATCH 07/38] Add benchmark for text_string_to_metric_families Signed-off-by: Chris Marchbanks --- tests/test_parser.py | 54 ++++++++++++++++++++++++++++++++++++++++++++ tox.ini | 1 + 2 files changed, 55 insertions(+) diff --git a/tests/test_parser.py b/tests/test_parser.py index 66cb5ec1..c8b17fa1 100644 --- a/tests/test_parser.py +++ b/tests/test_parser.py @@ -371,5 +371,59 @@ def collect(self): self.assertEqual(text.encode('utf-8'), generate_latest(registry, ALLOWUTF8)) +def test_benchmark_text_string_to_metric_families(benchmark): + text = """# HELP go_gc_duration_seconds A summary of the GC invocation durations. +# TYPE go_gc_duration_seconds summary +go_gc_duration_seconds{quantile="0"} 0.013300656000000001 +go_gc_duration_seconds{quantile="0.25"} 0.013638736 +go_gc_duration_seconds{quantile="0.5"} 0.013759906 +go_gc_duration_seconds{quantile="0.75"} 0.013962066 +go_gc_duration_seconds{quantile="1"} 0.021383540000000003 +go_gc_duration_seconds_sum 56.12904785 +go_gc_duration_seconds_count 7476.0 +# HELP go_goroutines Number of goroutines that currently exist. +# TYPE go_goroutines gauge +go_goroutines 166.0 +# HELP prometheus_local_storage_indexing_batch_duration_milliseconds Quantiles for batch indexing duration in milliseconds. +# TYPE prometheus_local_storage_indexing_batch_duration_milliseconds summary +prometheus_local_storage_indexing_batch_duration_milliseconds{quantile="0.5"} NaN +prometheus_local_storage_indexing_batch_duration_milliseconds{quantile="0.9"} NaN +prometheus_local_storage_indexing_batch_duration_milliseconds{quantile="0.99"} NaN +prometheus_local_storage_indexing_batch_duration_milliseconds_sum 871.5665949999999 +prometheus_local_storage_indexing_batch_duration_milliseconds_count 229.0 +# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds. +# TYPE process_cpu_seconds_total counter +process_cpu_seconds_total 29323.4 +# HELP process_virtual_memory_bytes Virtual memory size in bytes. +# TYPE process_virtual_memory_bytes gauge +process_virtual_memory_bytes 2.478268416e+09 +# HELP prometheus_build_info A metric with a constant '1' value labeled by version, revision, and branch from which Prometheus was built. +# TYPE prometheus_build_info gauge +prometheus_build_info{branch="HEAD",revision="ef176e5",version="0.16.0rc1"} 1.0 +# HELP prometheus_local_storage_chunk_ops_total The total number of chunk operations by their type. +# TYPE prometheus_local_storage_chunk_ops_total counter +prometheus_local_storage_chunk_ops_total{type="clone"} 28.0 +prometheus_local_storage_chunk_ops_total{type="create"} 997844.0 +prometheus_local_storage_chunk_ops_total{type="drop"} 1.345758e+06 +prometheus_local_storage_chunk_ops_total{type="load"} 1641.0 +prometheus_local_storage_chunk_ops_total{type="persist"} 981408.0 +prometheus_local_storage_chunk_ops_total{type="pin"} 32662.0 +prometheus_local_storage_chunk_ops_total{type="transcode"} 980180.0 +prometheus_local_storage_chunk_ops_total{type="unpin"} 32662.0 +# TYPE hist histogram +# HELP hist help +hist_bucket{le="1"} 0 +hist_bucket{le="+Inf"} 3 +hist_count 3 +hist_sum 2 +""" + + @benchmark + def _(): + # We need to convert the generator to a full list in order to + # accurately measure the time to yield everything. + return list(text_string_to_metric_families(text)) + + if __name__ == '__main__': unittest.main() diff --git a/tox.ini b/tox.ini index 157a8bb2..e19b25a3 100644 --- a/tox.ini +++ b/tox.ini @@ -5,6 +5,7 @@ envlist = coverage-clean,py{3.9,3.10,3.11,3.12,3.13,py3.9,3.9-nooptionals},cover deps = coverage pytest + pytest-benchmark attrs {py3.9,pypy3.9}: twisted # NOTE: Pinned due to https://github.com/prometheus/client_python/issues/1020 From fb5f6d7a174195a3720b0080e392dcf98db516a7 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Wed, 2 Jul 2025 10:37:15 -0600 Subject: [PATCH 08/38] When searching for label end start the search after the label start This saves ~10% in the benchmark. Signed-off-by: Chris Marchbanks --- prometheus_client/parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/prometheus_client/parser.py b/prometheus_client/parser.py index 0434edf7..5dff4c09 100644 --- a/prometheus_client/parser.py +++ b/prometheus_client/parser.py @@ -253,7 +253,7 @@ def _parse_sample(text): value, timestamp = _parse_value_and_timestamp(remaining_text) return Sample(name, {}, value, timestamp) name = text[:label_start].strip() - label_end = _next_unquoted_char(text, '}') + label_end = _next_unquoted_char(text[label_start:], '}') + label_start labels = parse_labels(text[label_start + 1:label_end], False) if not name: # Name might be in the labels From 119f1c24de68b0671c8dfed0dc94fdb69566f200 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Wed, 2 Jul 2025 11:36:08 -0600 Subject: [PATCH 09/38] Enumerate over text when finding unquoted char Enumerating rather than using a while loop saves significant CPU when looking for an unquoted character. This ends up improving the benchmark ~20% on its own. Signed-off-by: Chris Marchbanks --- prometheus_client/parser.py | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/prometheus_client/parser.py b/prometheus_client/parser.py index 5dff4c09..bdfb78c6 100644 --- a/prometheus_client/parser.py +++ b/prometheus_client/parser.py @@ -139,27 +139,26 @@ def _next_term(text: str, openmetrics: bool) -> Tuple[str, str]: return term.strip(), sublabels.strip() -def _next_unquoted_char(text: str, chs: str, startidx: int = 0) -> int: +def _next_unquoted_char(text: str, chs: Optional[str], startidx: int = 0) -> int: """Return position of next unquoted character in tuple, or -1 if not found. It is always assumed that the first character being checked is not already inside quotes. """ - i = startidx in_quotes = False if chs is None: chs = string.whitespace - while i < len(text): - if text[i] == '"' and not _is_character_escaped(text, i): + + for i, c in enumerate(text[startidx:]): + if c == '"' and not _is_character_escaped(text, startidx + i): in_quotes = not in_quotes if not in_quotes: - if text[i] in chs: - return i - i += 1 + if c in chs: + return startidx + i return -1 -def _last_unquoted_char(text: str, chs: str) -> int: +def _last_unquoted_char(text: str, chs: Optional[str]) -> int: """Return position of last unquoted character in list, or -1 if not found.""" i = len(text) - 1 in_quotes = False From 2a2ca5276fff6fdc628f1c75dc47d4f186406b0f Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Wed, 2 Jul 2025 11:49:26 -0600 Subject: [PATCH 10/38] Avoid unnecessary iterating across the same term Split the term into the label name and label value portions in one swoop rather than starting from the beginning to find an = character after already going through the full term. This saves ~5% on the benchmark. Signed-off-by: Chris Marchbanks --- prometheus_client/parser.py | 56 ++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 29 deletions(-) diff --git a/prometheus_client/parser.py b/prometheus_client/parser.py index bdfb78c6..ec71b2ab 100644 --- a/prometheus_client/parser.py +++ b/prometheus_client/parser.py @@ -62,44 +62,35 @@ def parse_labels(labels_string: str, openmetrics: bool = False) -> Dict[str, str # The label name is before the equal, or if there's no equal, that's the # metric name. - term, sub_labels = _next_term(sub_labels, openmetrics) - if not term: + name_term, value_term, sub_labels = _next_term(sub_labels, openmetrics) + if not value_term: if openmetrics: raise ValueError("empty term in line: " + labels_string) continue - quoted_name = False - operator_pos = _next_unquoted_char(term, '=') - if operator_pos == -1: - quoted_name = True - label_name = "__name__" - else: - value_start = _next_unquoted_char(term, '=') - label_name, quoted_name = _unquote_unescape(term[:value_start]) - term = term[value_start + 1:] + label_name, quoted_name = _unquote_unescape(name_term) if not quoted_name and not _is_valid_legacy_metric_name(label_name): raise ValueError("unquoted UTF-8 metric name") # Check for missing quotes - term = term.strip() - if not term or term[0] != '"': + if not value_term or value_term[0] != '"': raise ValueError # The first quote is guaranteed to be after the equal. - # Find the last unescaped quote. + # Make sure that the next unescaped quote is the last character. i = 1 - while i < len(term): - i = term.index('"', i) - if not _is_character_escaped(term[:i], i): + while i < len(value_term): + i = value_term.index('"', i) + if not _is_character_escaped(value_term[:i], i): break i += 1 - # The label value is between the first and last quote quote_end = i + 1 - if quote_end != len(term): + if quote_end != len(value_term): raise ValueError("unexpected text after quote: " + labels_string) - label_value, _ = _unquote_unescape(term[:quote_end]) + + label_value, _ = _unquote_unescape(value_term) if label_name == '__name__': _validate_metric_name(label_name) else: @@ -112,11 +103,10 @@ def parse_labels(labels_string: str, openmetrics: bool = False) -> Dict[str, str raise ValueError("Invalid labels: " + labels_string) -def _next_term(text: str, openmetrics: bool) -> Tuple[str, str]: - """Extract the next comma-separated label term from the text. - - Returns the stripped term and the stripped remainder of the string, - including the comma. +def _next_term(text: str, openmetrics: bool) -> Tuple[str, str, str]: + """Extract the next comma-separated label term from the text. The results + are stripped terms for the label name, label value, and then the remainder + of the string including the final , or }. Raises ValueError if the term is empty and we're in openmetrics mode. """ @@ -125,18 +115,26 @@ def _next_term(text: str, openmetrics: bool) -> Tuple[str, str]: if text[0] == ',': text = text[1:] if not text: - return "", "" + return "", "", "" if text[0] == ',': raise ValueError("multiple commas") - splitpos = _next_unquoted_char(text, ',}') + + splitpos = _next_unquoted_char(text, '=,}') + if splitpos >= 0 and text[splitpos] == "=": + labelname = text[:splitpos] + text = text[splitpos + 1:] + splitpos = _next_unquoted_char(text, ',}') + else: + labelname = "__name__" + if splitpos == -1: splitpos = len(text) term = text[:splitpos] if not term and openmetrics: raise ValueError("empty term:", term) - sublabels = text[splitpos:] - return term.strip(), sublabels.strip() + rest = text[splitpos:] + return labelname, term.strip(), rest.strip() def _next_unquoted_char(text: str, chs: Optional[str], startidx: int = 0) -> int: From f915160118d45d868350e1ff2aa608f4b4248abd Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Tue, 8 Jul 2025 09:56:55 -0600 Subject: [PATCH 11/38] Add benchmark for text_string_to_metric_families (#1116) Signed-off-by: Chris Marchbanks --- tests/test_parser.py | 54 ++++++++++++++++++++++++++++++++++++++++++++ tox.ini | 1 + 2 files changed, 55 insertions(+) diff --git a/tests/test_parser.py b/tests/test_parser.py index 66cb5ec1..c8b17fa1 100644 --- a/tests/test_parser.py +++ b/tests/test_parser.py @@ -371,5 +371,59 @@ def collect(self): self.assertEqual(text.encode('utf-8'), generate_latest(registry, ALLOWUTF8)) +def test_benchmark_text_string_to_metric_families(benchmark): + text = """# HELP go_gc_duration_seconds A summary of the GC invocation durations. +# TYPE go_gc_duration_seconds summary +go_gc_duration_seconds{quantile="0"} 0.013300656000000001 +go_gc_duration_seconds{quantile="0.25"} 0.013638736 +go_gc_duration_seconds{quantile="0.5"} 0.013759906 +go_gc_duration_seconds{quantile="0.75"} 0.013962066 +go_gc_duration_seconds{quantile="1"} 0.021383540000000003 +go_gc_duration_seconds_sum 56.12904785 +go_gc_duration_seconds_count 7476.0 +# HELP go_goroutines Number of goroutines that currently exist. +# TYPE go_goroutines gauge +go_goroutines 166.0 +# HELP prometheus_local_storage_indexing_batch_duration_milliseconds Quantiles for batch indexing duration in milliseconds. +# TYPE prometheus_local_storage_indexing_batch_duration_milliseconds summary +prometheus_local_storage_indexing_batch_duration_milliseconds{quantile="0.5"} NaN +prometheus_local_storage_indexing_batch_duration_milliseconds{quantile="0.9"} NaN +prometheus_local_storage_indexing_batch_duration_milliseconds{quantile="0.99"} NaN +prometheus_local_storage_indexing_batch_duration_milliseconds_sum 871.5665949999999 +prometheus_local_storage_indexing_batch_duration_milliseconds_count 229.0 +# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds. +# TYPE process_cpu_seconds_total counter +process_cpu_seconds_total 29323.4 +# HELP process_virtual_memory_bytes Virtual memory size in bytes. +# TYPE process_virtual_memory_bytes gauge +process_virtual_memory_bytes 2.478268416e+09 +# HELP prometheus_build_info A metric with a constant '1' value labeled by version, revision, and branch from which Prometheus was built. +# TYPE prometheus_build_info gauge +prometheus_build_info{branch="HEAD",revision="ef176e5",version="0.16.0rc1"} 1.0 +# HELP prometheus_local_storage_chunk_ops_total The total number of chunk operations by their type. +# TYPE prometheus_local_storage_chunk_ops_total counter +prometheus_local_storage_chunk_ops_total{type="clone"} 28.0 +prometheus_local_storage_chunk_ops_total{type="create"} 997844.0 +prometheus_local_storage_chunk_ops_total{type="drop"} 1.345758e+06 +prometheus_local_storage_chunk_ops_total{type="load"} 1641.0 +prometheus_local_storage_chunk_ops_total{type="persist"} 981408.0 +prometheus_local_storage_chunk_ops_total{type="pin"} 32662.0 +prometheus_local_storage_chunk_ops_total{type="transcode"} 980180.0 +prometheus_local_storage_chunk_ops_total{type="unpin"} 32662.0 +# TYPE hist histogram +# HELP hist help +hist_bucket{le="1"} 0 +hist_bucket{le="+Inf"} 3 +hist_count 3 +hist_sum 2 +""" + + @benchmark + def _(): + # We need to convert the generator to a full list in order to + # accurately measure the time to yield everything. + return list(text_string_to_metric_families(text)) + + if __name__ == '__main__': unittest.main() diff --git a/tox.ini b/tox.ini index 157a8bb2..e19b25a3 100644 --- a/tox.ini +++ b/tox.ini @@ -5,6 +5,7 @@ envlist = coverage-clean,py{3.9,3.10,3.11,3.12,3.13,py3.9,3.9-nooptionals},cover deps = coverage pytest + pytest-benchmark attrs {py3.9,pypy3.9}: twisted # NOTE: Pinned due to https://github.com/prometheus/client_python/issues/1020 From 73680284ce63f0bc0f23cfc42af06e74fd7e3ccf Mon Sep 17 00:00:00 2001 From: Aaditya Dhruv <67942447+aadityadhruv@users.noreply.github.com> Date: Fri, 11 Jul 2025 09:45:15 -0500 Subject: [PATCH 12/38] Add support to `write_to_textfile` for custom tmpdir (#1115) * Add support to write_to_textfile for custom tmpdir While the try/except block does prevent most of the temp files from persisting, if there is a non catchable exception, those temp files continue to pollute the directory. Optionally set the temp directory would let us write to something like /tmp, so the target directory isn't polluted Signed-off-by: Aaditya Dhruv * Modify write_to_textfile to ensure tmpdir is on same filesystem The tmpdir must be on the same filesystem to ensure an atomic operation takes place. If this is not enforced, there could be partial writes which can lead to partial/incorrect metrics being exported Signed-off-by: Aaditya Dhruv --------- Signed-off-by: Aaditya Dhruv --- prometheus_client/exposition.py | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/prometheus_client/exposition.py b/prometheus_client/exposition.py index 8c84ffb5..100e8e2b 100644 --- a/prometheus_client/exposition.py +++ b/prometheus_client/exposition.py @@ -446,12 +446,21 @@ def factory(cls, registry: CollectorRegistry) -> type: return MyMetricsHandler -def write_to_textfile(path: str, registry: CollectorRegistry, escaping: str = openmetrics.ALLOWUTF8) -> None: +def write_to_textfile(path: str, registry: CollectorRegistry, escaping: str = openmetrics.ALLOWUTF8, tmpdir: Optional[str] = None) -> None: """Write metrics to the given path. This is intended for use with the Node exporter textfile collector. - The path must end in .prom for the textfile collector to process it.""" - tmppath = f'{path}.{os.getpid()}.{threading.current_thread().ident}' + The path must end in .prom for the textfile collector to process it. + + An optional tmpdir parameter can be set to determine where the + metrics will be temporarily written to. If not set, it will be in + the same directory as the .prom file. If provided, the path MUST be + on the same filesystem.""" + if tmpdir is not None: + filename = os.path.basename(path) + tmppath = f'{os.path.join(tmpdir, filename)}.{os.getpid()}.{threading.current_thread().ident}' + else: + tmppath = f'{path}.{os.getpid()}.{threading.current_thread().ident}' try: with open(tmppath, 'wb') as f: f.write(generate_latest(registry, escaping)) From f48aea4e7f74b9fc53b98894d2a3ab96f58d0454 Mon Sep 17 00:00:00 2001 From: Arianna Vespri <36129782+vesari@users.noreply.github.com> Date: Wed, 20 Aug 2025 16:00:24 +0200 Subject: [PATCH 13/38] OM text exposition for NH (#1087) * Start implement OM text exposition for nh, add first no obs test * Correct template for nh sample spans, add test * Correct templating and appending for deltas, add longer spans test * Add tests for nh with labels, remove labels sorting * Break down logic classic vs nh samples, add tests for classic-native histograms cohabitation * Move classic sample logic back to where it belongs * Assign nh to value, correct nil values in tests, clean up white spaces * Add logic for exposing nh exemplars * Please linters * Assign nh_exemplars to exemplarstr * Add Any type to metric_family in OM exposition test * Change printing order of nh spans and deltas according to OM 2.0 proposal * Shorten name of spans and deltas as per OM 2.0 proposal * Adapt nh with UTF-8 tests to new testing framework * Update prometheus_client/openmetrics/exposition.py * Update prometheus_client/openmetrics/exposition.py * Eliminate erroneous abbreviation for spans and deltas --------- Signed-off-by: Arianna Vespri Signed-off-by: Arianna Vespri <36129782+vesari@users.noreply.github.com> Co-authored-by: Chris Marchbanks --- prometheus_client/openmetrics/exposition.py | 103 ++++++++--- prometheus_client/samples.py | 23 +-- tests/openmetrics/test_exposition.py | 178 +++++++++++++++++--- 3 files changed, 247 insertions(+), 57 deletions(-) diff --git a/prometheus_client/openmetrics/exposition.py b/prometheus_client/openmetrics/exposition.py index a89acdab..e4178392 100644 --- a/prometheus_client/openmetrics/exposition.py +++ b/prometheus_client/openmetrics/exposition.py @@ -30,6 +30,29 @@ def _is_valid_exemplar_metric(metric, sample): return False +def _compose_exemplar_string(metric, sample, exemplar): + """Constructs an exemplar string.""" + if not _is_valid_exemplar_metric(metric, sample): + raise ValueError(f"Metric {metric.name} has exemplars, but is not a histogram bucket or counter") + labels = '{{{0}}}'.format(','.join( + ['{}="{}"'.format( + k, v.replace('\\', r'\\').replace('\n', r'\n').replace('"', r'\"')) + for k, v in sorted(exemplar.labels.items())])) + if exemplar.timestamp is not None: + exemplarstr = ' # {} {} {}'.format( + labels, + floatToGoString(exemplar.value), + exemplar.timestamp, + ) + else: + exemplarstr = ' # {} {}'.format( + labels, + floatToGoString(exemplar.value), + ) + + return exemplarstr + + def generate_latest(registry, escaping=UNDERSCORES): '''Returns the metrics from the registry in latest text format as a string.''' output = [] @@ -58,44 +81,80 @@ def generate_latest(registry, escaping=UNDERSCORES): for k, v in items]) if labelstr: labelstr = "{" + labelstr + "}" - if s.exemplar: - if not _is_valid_exemplar_metric(metric, s): - raise ValueError(f"Metric {metric.name} has exemplars, but is not a histogram bucket or counter") - labels = '{{{0}}}'.format(','.join( - ['{}="{}"'.format( - k, v.replace('\\', r'\\').replace('\n', r'\n').replace('"', r'\"')) - for k, v in sorted(s.exemplar.labels.items())])) - if s.exemplar.timestamp is not None: - exemplarstr = ' # {} {} {}'.format( - labels, - floatToGoString(s.exemplar.value), - s.exemplar.timestamp, - ) - else: - exemplarstr = ' # {} {}'.format( - labels, - floatToGoString(s.exemplar.value), - ) + exemplarstr = _compose_exemplar_string(metric, s, s.exemplar) else: exemplarstr = '' timestamp = '' if s.timestamp is not None: timestamp = f' {s.timestamp}' + + native_histogram = '' + negative_spans = '' + negative_deltas = '' + positive_spans = '' + positive_deltas = '' + + if s.native_histogram: + # Initialize basic nh template + nh_sample_template = '{{count:{},sum:{},schema:{},zero_threshold:{},zero_count:{}' + + args = [ + s.native_histogram.count_value, + s.native_histogram.sum_value, + s.native_histogram.schema, + s.native_histogram.zero_threshold, + s.native_histogram.zero_count, + ] + + # If there are neg spans, append them and the neg deltas to the template and args + if s.native_histogram.neg_spans: + negative_spans = ','.join([f'{ns[0]}:{ns[1]}' for ns in s.native_histogram.neg_spans]) + negative_deltas = ','.join(str(nd) for nd in s.native_histogram.neg_deltas) + nh_sample_template += ',negative_spans:[{}]' + args.append(negative_spans) + nh_sample_template += ',negative_deltas:[{}]' + args.append(negative_deltas) + + # If there are pos spans, append them and the pos spans to the template and args + if s.native_histogram.pos_spans: + positive_spans = ','.join([f'{ps[0]}:{ps[1]}' for ps in s.native_histogram.pos_spans]) + positive_deltas = ','.join(f'{pd}' for pd in s.native_histogram.pos_deltas) + nh_sample_template += ',positive_spans:[{}]' + args.append(positive_spans) + nh_sample_template += ',positive_deltas:[{}]' + args.append(positive_deltas) + + # Add closing brace + nh_sample_template += '}}' + + # Format the template with the args + native_histogram = nh_sample_template.format(*args) + + if s.native_histogram.nh_exemplars: + for nh_ex in s.native_histogram.nh_exemplars: + nh_exemplarstr = _compose_exemplar_string(metric, s, nh_ex) + exemplarstr += nh_exemplarstr + + value = '' + if s.native_histogram: + value = native_histogram + elif s.value is not None: + value = floatToGoString(s.value) if (escaping != ALLOWUTF8) or _is_valid_legacy_metric_name(s.name): output.append('{}{} {}{}{}\n'.format( _escape(s.name, escaping, _is_legacy_labelname_rune), labelstr, - floatToGoString(s.value), + value, timestamp, - exemplarstr, + exemplarstr )) else: output.append('{} {}{}{}\n'.format( labelstr, - floatToGoString(s.value), + value, timestamp, - exemplarstr, + exemplarstr )) except Exception as exception: exception.args = (exception.args or ('',)) + (metric,) diff --git a/prometheus_client/samples.py b/prometheus_client/samples.py index 16e03c04..994d1281 100644 --- a/prometheus_client/samples.py +++ b/prometheus_client/samples.py @@ -40,6 +40,17 @@ class BucketSpan(NamedTuple): length: int +# Timestamp and exemplar are optional. +# Value can be an int or a float. +# Timestamp can be a float containing a unixtime in seconds, +# a Timestamp object, or None. +# Exemplar can be an Exemplar object, or None. +class Exemplar(NamedTuple): + labels: Dict[str, str] + value: float + timestamp: Optional[Union[float, Timestamp]] = None + + # NativeHistogram is experimental and subject to change at any time. class NativeHistogram(NamedTuple): count_value: float @@ -51,17 +62,7 @@ class NativeHistogram(NamedTuple): neg_spans: Optional[Sequence[BucketSpan]] = None pos_deltas: Optional[Sequence[int]] = None neg_deltas: Optional[Sequence[int]] = None - - -# Timestamp and exemplar are optional. -# Value can be an int or a float. -# Timestamp can be a float containing a unixtime in seconds, -# a Timestamp object, or None. -# Exemplar can be an Exemplar object, or None. -class Exemplar(NamedTuple): - labels: Dict[str, str] - value: float - timestamp: Optional[Union[float, Timestamp]] = None + nh_exemplars: Optional[Sequence[Exemplar]] = None class Sample(NamedTuple): diff --git a/tests/openmetrics/test_exposition.py b/tests/openmetrics/test_exposition.py index 9f790642..b972cadc 100644 --- a/tests/openmetrics/test_exposition.py +++ b/tests/openmetrics/test_exposition.py @@ -1,4 +1,5 @@ import time +from typing import Any import unittest import pytest @@ -7,7 +8,8 @@ CollectorRegistry, Counter, Enum, Gauge, Histogram, Info, Metric, Summary, ) from prometheus_client.core import ( - Exemplar, GaugeHistogramMetricFamily, Timestamp, + BucketSpan, Exemplar, GaugeHistogramMetricFamily, HistogramMetricFamily, + NativeHistogram, Timestamp, ) from prometheus_client.openmetrics.exposition import ( ALLOWUTF8, DOTS, escape_label_name, escape_metric_name, generate_latest, @@ -26,20 +28,20 @@ def setUp(self): def tearDown(self): time.time = self.old_time - def custom_collector(self, metric_family): + def custom_collector(self, metric_family: Any) -> None: class CustomCollector: def collect(self): return [metric_family] self.registry.register(CustomCollector()) - def test_counter(self): + def test_counter(self) -> None: c = Counter('cc', 'A counter', registry=self.registry) c.inc() self.assertEqual(b'# HELP cc A counter\n# TYPE cc counter\ncc_total 1.0\ncc_created 123.456\n# EOF\n', generate_latest(self.registry)) - - def test_counter_utf8(self): + + def test_counter_utf8(self) -> None: c = Counter('cc.with.dots', 'A counter', registry=self.registry) c.inc() self.assertEqual(b'# HELP "cc.with.dots" A counter\n# TYPE "cc.with.dots" counter\n{"cc.with.dots_total"} 1.0\n{"cc.with.dots_created"} 123.456\n# EOF\n', @@ -55,24 +57,24 @@ def test_counter_utf8_escaped_underscores(self): # EOF """ == generate_latest(self.registry, UNDERSCORES) - def test_counter_total(self): + def test_counter_total(self) -> None: c = Counter('cc_total', 'A counter', registry=self.registry) c.inc() self.assertEqual(b'# HELP cc A counter\n# TYPE cc counter\ncc_total 1.0\ncc_created 123.456\n# EOF\n', generate_latest(self.registry)) - def test_counter_unit(self): + def test_counter_unit(self) -> None: c = Counter('cc_seconds', 'A counter', registry=self.registry, unit="seconds") c.inc() self.assertEqual(b'# HELP cc_seconds A counter\n# TYPE cc_seconds counter\n# UNIT cc_seconds seconds\ncc_seconds_total 1.0\ncc_seconds_created 123.456\n# EOF\n', generate_latest(self.registry)) - def test_gauge(self): + def test_gauge(self) -> None: g = Gauge('gg', 'A gauge', registry=self.registry) g.set(17) self.assertEqual(b'# HELP gg A gauge\n# TYPE gg gauge\ngg 17.0\n# EOF\n', generate_latest(self.registry)) - def test_summary(self): + def test_summary(self) -> None: s = Summary('ss', 'A summary', ['a', 'b'], registry=self.registry) s.labels('c', 'd').observe(17) self.assertEqual(b"""# HELP ss A summary @@ -83,7 +85,7 @@ def test_summary(self): # EOF """, generate_latest(self.registry)) - def test_histogram(self): + def test_histogram(self) -> None: s = Histogram('hh', 'A histogram', registry=self.registry) s.observe(0.05) self.assertEqual(b"""# HELP hh A histogram @@ -109,7 +111,135 @@ def test_histogram(self): # EOF """, generate_latest(self.registry)) - def test_histogram_negative_buckets(self): + + def test_native_histogram(self) -> None: + hfm = HistogramMetricFamily("nh", "nh") + hfm.add_sample("nh", {}, 0, None, None, NativeHistogram(24, 100, 0, 0.001, 4, (BucketSpan(0, 2), BucketSpan(1, 2)), (BucketSpan(0, 2), BucketSpan(1, 2)), (2, 1, -3, 3), (2, 1, -2, 3))) + self.custom_collector(hfm) + self.assertEqual(b"""# HELP nh nh +# TYPE nh histogram +nh {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} +# EOF +""", generate_latest(self.registry)) + + def test_nh_histogram_with_exemplars(self) -> None: + hfm = HistogramMetricFamily("nh", "nh") + hfm.add_sample("nh", {}, 0, None, None, NativeHistogram(24, 100, 0, 0.001, 4, (BucketSpan(0, 2), BucketSpan(1, 2)), (BucketSpan(0, 2), BucketSpan(1, 2)), (2, 1, -3, 3), (2, 1, -2, 3), (Exemplar({"trace_id": "KOO5S4vxi0o"}, 0.67), Exemplar({"trace_id": "oHg5SJYRHA0"}, 9.8, float(Timestamp(1520879607, 0.789 * 1e9)))))) + self.custom_collector(hfm) + self.assertEqual(b"""# HELP nh nh +# TYPE nh histogram +nh {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} # {trace_id="KOO5S4vxi0o"} 0.67 # {trace_id="oHg5SJYRHA0"} 9.8 1520879607.789 +# EOF +""", generate_latest(self.registry)) + + def test_nh_no_observation(self) -> None: + hfm = HistogramMetricFamily("nhnoobs", "nhnoobs") + hfm.add_sample("nhnoobs", {}, 0, None, None, NativeHistogram(0, 0, 3, 2.938735877055719e-39, 0)) + self.custom_collector(hfm) + self.assertEqual(b"""# HELP nhnoobs nhnoobs +# TYPE nhnoobs histogram +nhnoobs {count:0,sum:0,schema:3,zero_threshold:2.938735877055719e-39,zero_count:0} +# EOF +""", generate_latest(self.registry)) + + + def test_nh_longer_spans(self) -> None: + hfm = HistogramMetricFamily("nhsp", "Is a basic example of a native histogram with three spans") + hfm.add_sample("nhsp", {}, 0, None, None, NativeHistogram(4, 6, 3, 2.938735877055719e-39, 1, (BucketSpan(0, 1), BucketSpan(7, 1), BucketSpan(4, 1)), None, (1, 0, 0), None)) + self.custom_collector(hfm) + self.assertEqual(b"""# HELP nhsp Is a basic example of a native histogram with three spans +# TYPE nhsp histogram +nhsp {count:4,sum:6,schema:3,zero_threshold:2.938735877055719e-39,zero_count:1,positive_spans:[0:1,7:1,4:1],positive_deltas:[1,0,0]} +# EOF +""", generate_latest(self.registry)) + + def test_native_histogram_utf8(self) -> None: + hfm = HistogramMetricFamily("native{histogram", "Is a basic example of a native histogram") + hfm.add_sample("native{histogram", {}, 0, None, None, NativeHistogram(24, 100, 0, 0.001, 4, (BucketSpan(0, 2), BucketSpan(1, 2)), (BucketSpan(0, 2), BucketSpan(1, 2)), (2, 1, -3, 3), (2, 1, -2, 3))) + self.custom_collector(hfm) + self.assertEqual(b"""# HELP "native{histogram" Is a basic example of a native histogram +# TYPE "native{histogram" histogram +{"native{histogram"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} +# EOF +""", generate_latest(self.registry, ALLOWUTF8)) + + def test_native_histogram_utf8_stress(self) -> None: + hfm = HistogramMetricFamily("native{histogram", "Is a basic example of a native histogram") + hfm.add_sample("native{histogram", {'xx{} # {}': ' EOF # {}}}'}, 0, None, None, NativeHistogram(24, 100, 0, 0.001, 4, (BucketSpan(0, 2), BucketSpan(1, 2)), (BucketSpan(0, 2), BucketSpan(1, 2)), (2, 1, -3, 3), (2, 1, -2, 3))) + self.custom_collector(hfm) + self.assertEqual(b"""# HELP "native{histogram" Is a basic example of a native histogram +# TYPE "native{histogram" histogram +{"native{histogram", "xx{} # {}"=" EOF # {}}}"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} +# EOF +""", generate_latest(self.registry, ALLOWUTF8)) + + def test_native_histogram_with_labels(self) -> None: + hfm = HistogramMetricFamily("hist_w_labels", "Is a basic example of a native histogram with labels") + hfm.add_sample("hist_w_labels", {"foo": "bar", "baz": "qux"}, 0, None, None, NativeHistogram(24, 100, 0, 0.001, 4, (BucketSpan(0, 2), BucketSpan(1, 2)), (BucketSpan(0, 2), BucketSpan(1, 2)), (2, 1, -3, 3), (2, 1, -2, 3))) + self.custom_collector(hfm) + self.assertEqual(b"""# HELP hist_w_labels Is a basic example of a native histogram with labels +# TYPE hist_w_labels histogram +hist_w_labels{baz="qux",foo="bar"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} +# EOF +""", generate_latest(self.registry)) + + def test_native_histogram_with_labels_utf8(self) -> None: + hfm = HistogramMetricFamily("hist.w.labels", "Is a basic example of a native histogram with labels") + hfm.add_sample("hist.w.labels", {"foo": "bar", "baz": "qux"}, 0, None, None, NativeHistogram(24, 100, 0, 0.001, 4, (BucketSpan(0, 2), BucketSpan(1, 2)), (BucketSpan(0, 2), BucketSpan(1, 2)), (2, 1, -3, 3), (2, 1, -2, 3))) + self.custom_collector(hfm) + self.assertEqual(b"""# HELP "hist.w.labels" Is a basic example of a native histogram with labels +# TYPE "hist.w.labels" histogram +{"hist.w.labels", baz="qux",foo="bar"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} +# EOF +""", generate_latest(self.registry, ALLOWUTF8)) + + def test_native_histogram_with_classic_histogram(self) -> None: + hfm = HistogramMetricFamily("hist_w_classic", "Is a basic example of a native histogram coexisting with a classic histogram") + hfm.add_sample("hist_w_classic", {"foo": "bar"}, 0, None, None, NativeHistogram(24, 100, 0, 0.001, 4, (BucketSpan(0, 2), BucketSpan(1, 2)), (BucketSpan(0, 2), BucketSpan(1, 2)), (2, 1, -3, 3), (2, 1, -2, 3))) + hfm.add_sample("hist_w_classic_bucket", {"foo": "bar", "le": "0.001"}, 4.0, None, None, None) + hfm.add_sample("hist_w_classic_bucket", {"foo": "bar", "le": "+Inf"}, 24.0, None, None, None) + hfm.add_sample("hist_w_classic_count", {"foo": "bar"}, 24.0, None, None, None) + hfm.add_sample("hist_w_classic_sum", {"foo": "bar"}, 100.0, None, None, None) + self.custom_collector(hfm) + self.assertEqual(b"""# HELP hist_w_classic Is a basic example of a native histogram coexisting with a classic histogram +# TYPE hist_w_classic histogram +hist_w_classic{foo="bar"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} +hist_w_classic_bucket{foo="bar",le="0.001"} 4.0 +hist_w_classic_bucket{foo="bar",le="+Inf"} 24.0 +hist_w_classic_count{foo="bar"} 24.0 +hist_w_classic_sum{foo="bar"} 100.0 +# EOF +""", generate_latest(self.registry)) + + def test_native_plus_classic_histogram_two_labelsets(self) -> None: + hfm = HistogramMetricFamily("hist_w_classic_two_sets", "Is an example of a native histogram plus a classic histogram with two label sets") + hfm.add_sample("hist_w_classic_two_sets", {"foo": "bar"}, 0, None, None, NativeHistogram(24, 100, 0, 0.001, 4, (BucketSpan(0, 2), BucketSpan(1, 2)), (BucketSpan(0, 2), BucketSpan(1, 2)), (2, 1, -3, 3), (2, 1, -2, 3))) + hfm.add_sample("hist_w_classic_two_sets_bucket", {"foo": "bar", "le": "0.001"}, 4.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_bucket", {"foo": "bar", "le": "+Inf"}, 24.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_count", {"foo": "bar"}, 24.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_sum", {"foo": "bar"}, 100.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets", {"foo": "baz"}, 0, None, None, NativeHistogram(24, 100, 0, 0.001, 4, (BucketSpan(0, 2), BucketSpan(1, 2)), (BucketSpan(0, 2), BucketSpan(1, 2)), (2, 1, -3, 3), (2, 1, -2, 3))) + hfm.add_sample("hist_w_classic_two_sets_bucket", {"foo": "baz", "le": "0.001"}, 4.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_bucket", {"foo": "baz", "le": "+Inf"}, 24.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_count", {"foo": "baz"}, 24.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_sum", {"foo": "baz"}, 100.0, None, None, None) + self.custom_collector(hfm) + self.assertEqual(b"""# HELP hist_w_classic_two_sets Is an example of a native histogram plus a classic histogram with two label sets +# TYPE hist_w_classic_two_sets histogram +hist_w_classic_two_sets{foo="bar"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} +hist_w_classic_two_sets_bucket{foo="bar",le="0.001"} 4.0 +hist_w_classic_two_sets_bucket{foo="bar",le="+Inf"} 24.0 +hist_w_classic_two_sets_count{foo="bar"} 24.0 +hist_w_classic_two_sets_sum{foo="bar"} 100.0 +hist_w_classic_two_sets{foo="baz"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} +hist_w_classic_two_sets_bucket{foo="baz",le="0.001"} 4.0 +hist_w_classic_two_sets_bucket{foo="baz",le="+Inf"} 24.0 +hist_w_classic_two_sets_count{foo="baz"} 24.0 +hist_w_classic_two_sets_sum{foo="baz"} 100.0 +# EOF +""", generate_latest(self.registry)) + + def test_histogram_negative_buckets(self) -> None: s = Histogram('hh', 'A histogram', buckets=[-1, -0.5, 0, 0.5, 1], registry=self.registry) s.observe(-0.5) self.assertEqual(b"""# HELP hh A histogram @@ -125,7 +255,7 @@ def test_histogram_negative_buckets(self): # EOF """, generate_latest(self.registry)) - def test_histogram_exemplar(self): + def test_histogram_exemplar(self) -> None: s = Histogram('hh', 'A histogram', buckets=[1, 2, 3, 4], registry=self.registry) s.observe(0.5, {'a': 'b'}) s.observe(1.5, {'le': '7'}) @@ -145,7 +275,7 @@ def test_histogram_exemplar(self): # EOF """, generate_latest(self.registry)) - def test_counter_exemplar(self): + def test_counter_exemplar(self) -> None: c = Counter('cc', 'A counter', registry=self.registry) c.inc(exemplar={'a': 'b'}) self.assertEqual(b"""# HELP cc A counter @@ -155,7 +285,7 @@ def test_counter_exemplar(self): # EOF """, generate_latest(self.registry)) - def test_untyped_exemplar(self): + def test_untyped_exemplar(self) -> None: class MyCollector: def collect(self): metric = Metric("hh", "help", 'untyped') @@ -167,7 +297,7 @@ def collect(self): with self.assertRaises(ValueError): generate_latest(self.registry) - def test_histogram_non_bucket_exemplar(self): + def test_histogram_non_bucket_exemplar(self) -> None: class MyCollector: def collect(self): metric = Metric("hh", "help", 'histogram') @@ -179,7 +309,7 @@ def collect(self): with self.assertRaises(ValueError): generate_latest(self.registry) - def test_counter_non_total_exemplar(self): + def test_counter_non_total_exemplar(self) -> None: class MyCollector: def collect(self): metric = Metric("cc", "A counter", 'counter') @@ -191,7 +321,7 @@ def collect(self): with self.assertRaises(ValueError): generate_latest(self.registry) - def test_gaugehistogram(self): + def test_gaugehistogram(self) -> None: self.custom_collector( GaugeHistogramMetricFamily('gh', 'help', buckets=[('1.0', 4), ('+Inf', (5))], gsum_value=7)) self.assertEqual(b"""# HELP gh help @@ -203,7 +333,7 @@ def test_gaugehistogram(self): # EOF """, generate_latest(self.registry)) - def test_gaugehistogram_negative_buckets(self): + def test_gaugehistogram_negative_buckets(self) -> None: self.custom_collector( GaugeHistogramMetricFamily('gh', 'help', buckets=[('-1.0', 4), ('+Inf', (5))], gsum_value=-7)) self.assertEqual(b"""# HELP gh help @@ -215,7 +345,7 @@ def test_gaugehistogram_negative_buckets(self): # EOF """, generate_latest(self.registry)) - def test_info(self): + def test_info(self) -> None: i = Info('ii', 'A info', ['a', 'b'], registry=self.registry) i.labels('c', 'd').info({'foo': 'bar'}) self.assertEqual(b"""# HELP ii A info @@ -224,7 +354,7 @@ def test_info(self): # EOF """, generate_latest(self.registry)) - def test_enum(self): + def test_enum(self) -> None: i = Enum('ee', 'An enum', ['a', 'b'], registry=self.registry, states=['foo', 'bar']) i.labels('c', 'd').state('bar') self.assertEqual(b"""# HELP ee An enum @@ -234,7 +364,7 @@ def test_enum(self): # EOF """, generate_latest(self.registry)) - def test_unicode(self): + def test_unicode(self) -> None: c = Counter('cc', '\u4500', ['l'], registry=self.registry) c.labels('\u4500').inc() self.assertEqual(b"""# HELP cc \xe4\x94\x80 @@ -244,7 +374,7 @@ def test_unicode(self): # EOF """, generate_latest(self.registry)) - def test_escaping(self): + def test_escaping(self) -> None: c = Counter('cc', 'A\ncount\\er\"', ['a'], registry=self.registry) c.labels('\\x\n"').inc(1) self.assertEqual(b"""# HELP cc A\\ncount\\\\er\\" @@ -254,7 +384,7 @@ def test_escaping(self): # EOF """, generate_latest(self.registry)) - def test_nonnumber(self): + def test_nonnumber(self) -> None: class MyNumber: def __repr__(self): return "MyNumber(123)" @@ -272,7 +402,7 @@ def collect(self): self.assertEqual(b'# HELP nonnumber Non number\n# TYPE nonnumber unknown\nnonnumber 123.0\n# EOF\n', generate_latest(self.registry)) - def test_timestamp(self): + def test_timestamp(self) -> None: class MyCollector: def collect(self): metric = Metric("ts", "help", 'unknown') From d358f469a7bc2480005775a9be8de30c20c88ab6 Mon Sep 17 00:00:00 2001 From: Kajinami Takashi Date: Wed, 3 Sep 2025 23:29:50 +0900 Subject: [PATCH 14/38] Bump flake8 libraries (#1127) ... to the latest version available now. Also, do not pin bugfix version because any bugfix update is supposed to bring no breaking fix. Signed-off-by: Takashi Kajinami --- tox.ini | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tox.ini b/tox.ini index e19b25a3..bef57f85 100644 --- a/tox.ini +++ b/tox.ini @@ -30,9 +30,9 @@ commands = [testenv:flake8] deps = - flake8==6.0.0 - flake8-docstrings==1.6.0 - flake8-import-order==0.18.2 + flake8~=7.3 + flake8-docstrings~=1.7 + flake8-import-order~=0.19 skip_install = true commands = flake8 prometheus_client/ tests/ From 9e3eb6c7e146d8003d12e24db56f5abfcc0bbef6 Mon Sep 17 00:00:00 2001 From: hack Date: Wed, 3 Sep 2025 16:32:55 +0200 Subject: [PATCH 15/38] Fix bug which caused metric publishing to not accept query string parameters in ASGI app (#1125) * fix query string encoding in asgi app Signed-off-by: hack * isolate the asgi qs encoding bug into a test case Signed-off-by: hacksparr0w --------- Signed-off-by: hack Signed-off-by: hacksparr0w --- prometheus_client/asgi.py | 2 +- tests/test_asgi.py | 48 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 46 insertions(+), 4 deletions(-) diff --git a/prometheus_client/asgi.py b/prometheus_client/asgi.py index e1864b8b..affd9844 100644 --- a/prometheus_client/asgi.py +++ b/prometheus_client/asgi.py @@ -11,7 +11,7 @@ def make_asgi_app(registry: CollectorRegistry = REGISTRY, disable_compression: b async def prometheus_app(scope, receive, send): assert scope.get("type") == "http" # Prepare parameters - params = parse_qs(scope.get('query_string', b'')) + params = parse_qs(scope.get('query_string', b'').decode("utf8")) accept_header = ",".join([ value.decode("utf8") for (name, value) in scope.get('headers') if name.decode("utf8").lower() == 'accept' diff --git a/tests/test_asgi.py b/tests/test_asgi.py index eaa195d0..386ff598 100644 --- a/tests/test_asgi.py +++ b/tests/test_asgi.py @@ -93,6 +93,16 @@ def increment_metrics(self, metric_name, help_text, increments): for _ in range(increments): c.inc() + def assert_metrics(self, output, metric_name, help_text, increments): + self.assertIn("# HELP " + metric_name + "_total " + help_text + "\n", output) + self.assertIn("# TYPE " + metric_name + "_total counter\n", output) + self.assertIn(metric_name + "_total " + str(increments) + ".0\n", output) + + def assert_not_metrics(self, output, metric_name, help_text, increments): + self.assertNotIn("# HELP " + metric_name + "_total " + help_text + "\n", output) + self.assertNotIn("# TYPE " + metric_name + "_total counter\n", output) + self.assertNotIn(metric_name + "_total " + str(increments) + ".0\n", output) + def assert_outputs(self, outputs, metric_name, help_text, increments, compressed): self.assertEqual(len(outputs), 2) response_start = outputs[0] @@ -112,9 +122,8 @@ def assert_outputs(self, outputs, metric_name, help_text, increments, compressed output = gzip.decompress(response_body['body']).decode('utf8') else: output = response_body['body'].decode('utf8') - self.assertIn("# HELP " + metric_name + "_total " + help_text + "\n", output) - self.assertIn("# TYPE " + metric_name + "_total counter\n", output) - self.assertIn(metric_name + "_total " + str(increments) + ".0\n", output) + + self.assert_metrics(output, metric_name, help_text, increments) def validate_metrics(self, metric_name, help_text, increments): """ @@ -190,3 +199,36 @@ def test_plaintext_encoding(self): content_type = self.get_response_header_value('Content-Type').split(";")[0] assert content_type == "text/plain" + + def test_qs_parsing(self): + """Only metrics that match the 'name[]' query string param appear""" + + app = make_asgi_app(self.registry) + metrics = [ + ("asdf", "first test metric", 1), + ("bsdf", "second test metric", 2) + ] + + for m in metrics: + self.increment_metrics(*m) + + for i_1 in range(len(metrics)): + self.seed_app(app) + self.scope['query_string'] = f"name[]={metrics[i_1][0]}_total".encode("utf-8") + self.send_default_request() + + outputs = self.get_all_output() + response_body = outputs[1] + output = response_body['body'].decode('utf8') + + self.assert_metrics(output, *metrics[i_1]) + + for i_2 in range(len(metrics)): + if i_1 == i_2: + continue + + self.assert_not_metrics(output, *metrics[i_2]) + + asyncio.get_event_loop().run_until_complete( + self.communicator.wait() + ) From 3586355e648f1d8a058cdb711bc2ce920ce58ca4 Mon Sep 17 00:00:00 2001 From: Arianna Vespri <36129782+vesari@users.noreply.github.com> Date: Thu, 4 Sep 2025 18:30:41 +0200 Subject: [PATCH 16/38] Emit native histograms only when OM 2.0.0 is requested (#1128) * Emit NH only if OM 2.0.0 is requested Signed-off-by: Arianna Vespri * Adjust logic, add version comparison tests for NH Signed-off-by: Arianna Vespri * Skip nh sample earlier in the logic Signed-off-by: Arianna Vespri --------- Signed-off-by: Arianna Vespri --- prometheus_client/exposition.py | 6 +- prometheus_client/openmetrics/exposition.py | 12 ++- tests/openmetrics/test_exposition.py | 88 +++++++++++++++------ 3 files changed, 79 insertions(+), 27 deletions(-) diff --git a/prometheus_client/exposition.py b/prometheus_client/exposition.py index 100e8e2b..93285804 100644 --- a/prometheus_client/exposition.py +++ b/prometheus_client/exposition.py @@ -345,10 +345,10 @@ def choose_encoder(accept_header: str) -> Tuple[Callable[[CollectorRegistry], by # Only return an escaping header if we have a good version and # mimetype. if not version: - return (partial(openmetrics.generate_latest, escaping=openmetrics.UNDERSCORES), openmetrics.CONTENT_TYPE_LATEST) + return (partial(openmetrics.generate_latest, escaping=openmetrics.UNDERSCORES, version="1.0.0"), openmetrics.CONTENT_TYPE_LATEST) if version and Version(version) >= Version('1.0.0'): - return (partial(openmetrics.generate_latest, escaping=escaping), - openmetrics.CONTENT_TYPE_LATEST + '; escaping=' + str(escaping)) + return (partial(openmetrics.generate_latest, escaping=escaping, version=version), + f'application/openmetrics-text; version={version}; charset=utf-8; escaping=' + str(escaping)) elif accepted.split(';')[0].strip() == 'text/plain': toks = accepted.split(';') version = _get_version(toks) diff --git a/prometheus_client/openmetrics/exposition.py b/prometheus_client/openmetrics/exposition.py index e4178392..bc24c7cf 100644 --- a/prometheus_client/openmetrics/exposition.py +++ b/prometheus_client/openmetrics/exposition.py @@ -4,13 +4,17 @@ from sys import maxunicode from typing import Callable +from packaging.version import Version + from ..utils import floatToGoString from ..validation import ( _is_valid_legacy_labelname, _is_valid_legacy_metric_name, ) CONTENT_TYPE_LATEST = 'application/openmetrics-text; version=1.0.0; charset=utf-8' -"""Content type of the latest OpenMetrics text format""" +"""Content type of the latest OpenMetrics 1.0 text format""" +CONTENT_TYPE_LATEST_2_0 = 'application/openmetrics-text; version=2.0.0; charset=utf-8' +"""Content type of the OpenMetrics 2.0 text format""" ESCAPING_HEADER_TAG = 'escaping' @@ -53,7 +57,7 @@ def _compose_exemplar_string(metric, sample, exemplar): return exemplarstr -def generate_latest(registry, escaping=UNDERSCORES): +def generate_latest(registry, escaping=UNDERSCORES, version="1.0.0"): '''Returns the metrics from the registry in latest text format as a string.''' output = [] for metric in registry.collect(): @@ -89,6 +93,10 @@ def generate_latest(registry, escaping=UNDERSCORES): if s.timestamp is not None: timestamp = f' {s.timestamp}' + # Skip native histogram samples entirely if version < 2.0.0 + if s.native_histogram and Version(version) < Version('2.0.0'): + continue + native_histogram = '' negative_spans = '' negative_deltas = '' diff --git a/tests/openmetrics/test_exposition.py b/tests/openmetrics/test_exposition.py index b972cadc..6c879ec4 100644 --- a/tests/openmetrics/test_exposition.py +++ b/tests/openmetrics/test_exposition.py @@ -83,7 +83,7 @@ def test_summary(self) -> None: ss_sum{a="c",b="d"} 17.0 ss_created{a="c",b="d"} 123.456 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="1.0.0")) def test_histogram(self) -> None: s = Histogram('hh', 'A histogram', registry=self.registry) @@ -109,7 +109,7 @@ def test_histogram(self) -> None: hh_sum 0.05 hh_created 123.456 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="1.0.0")) def test_native_histogram(self) -> None: @@ -120,7 +120,7 @@ def test_native_histogram(self) -> None: # TYPE nh histogram nh {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) def test_nh_histogram_with_exemplars(self) -> None: hfm = HistogramMetricFamily("nh", "nh") @@ -130,7 +130,7 @@ def test_nh_histogram_with_exemplars(self) -> None: # TYPE nh histogram nh {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} # {trace_id="KOO5S4vxi0o"} 0.67 # {trace_id="oHg5SJYRHA0"} 9.8 1520879607.789 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) def test_nh_no_observation(self) -> None: hfm = HistogramMetricFamily("nhnoobs", "nhnoobs") @@ -140,7 +140,7 @@ def test_nh_no_observation(self) -> None: # TYPE nhnoobs histogram nhnoobs {count:0,sum:0,schema:3,zero_threshold:2.938735877055719e-39,zero_count:0} # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) def test_nh_longer_spans(self) -> None: @@ -151,7 +151,7 @@ def test_nh_longer_spans(self) -> None: # TYPE nhsp histogram nhsp {count:4,sum:6,schema:3,zero_threshold:2.938735877055719e-39,zero_count:1,positive_spans:[0:1,7:1,4:1],positive_deltas:[1,0,0]} # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) def test_native_histogram_utf8(self) -> None: hfm = HistogramMetricFamily("native{histogram", "Is a basic example of a native histogram") @@ -161,7 +161,7 @@ def test_native_histogram_utf8(self) -> None: # TYPE "native{histogram" histogram {"native{histogram"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} # EOF -""", generate_latest(self.registry, ALLOWUTF8)) +""", generate_latest(self.registry, ALLOWUTF8, version="2.0.0")) def test_native_histogram_utf8_stress(self) -> None: hfm = HistogramMetricFamily("native{histogram", "Is a basic example of a native histogram") @@ -171,7 +171,7 @@ def test_native_histogram_utf8_stress(self) -> None: # TYPE "native{histogram" histogram {"native{histogram", "xx{} # {}"=" EOF # {}}}"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} # EOF -""", generate_latest(self.registry, ALLOWUTF8)) +""", generate_latest(self.registry, ALLOWUTF8, version="2.0.0")) def test_native_histogram_with_labels(self) -> None: hfm = HistogramMetricFamily("hist_w_labels", "Is a basic example of a native histogram with labels") @@ -181,7 +181,7 @@ def test_native_histogram_with_labels(self) -> None: # TYPE hist_w_labels histogram hist_w_labels{baz="qux",foo="bar"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) def test_native_histogram_with_labels_utf8(self) -> None: hfm = HistogramMetricFamily("hist.w.labels", "Is a basic example of a native histogram with labels") @@ -191,7 +191,7 @@ def test_native_histogram_with_labels_utf8(self) -> None: # TYPE "hist.w.labels" histogram {"hist.w.labels", baz="qux",foo="bar"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} # EOF -""", generate_latest(self.registry, ALLOWUTF8)) +""", generate_latest(self.registry, ALLOWUTF8, version="2.0.0")) def test_native_histogram_with_classic_histogram(self) -> None: hfm = HistogramMetricFamily("hist_w_classic", "Is a basic example of a native histogram coexisting with a classic histogram") @@ -209,7 +209,7 @@ def test_native_histogram_with_classic_histogram(self) -> None: hist_w_classic_count{foo="bar"} 24.0 hist_w_classic_sum{foo="bar"} 100.0 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) def test_native_plus_classic_histogram_two_labelsets(self) -> None: hfm = HistogramMetricFamily("hist_w_classic_two_sets", "Is an example of a native histogram plus a classic histogram with two label sets") @@ -237,7 +237,33 @@ def test_native_plus_classic_histogram_two_labelsets(self) -> None: hist_w_classic_two_sets_count{foo="baz"} 24.0 hist_w_classic_two_sets_sum{foo="baz"} 100.0 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) + + def test_native_plus_classic_histogram_two_labelsets_OM_1(self) -> None: + hfm = HistogramMetricFamily("hist_w_classic_two_sets", "Is an example of a native histogram plus a classic histogram with two label sets in OM 1.0.0") + hfm.add_sample("hist_w_classic_two_sets", {"foo": "bar"}, 0, None, None, NativeHistogram(24, 100, 0, 0.001, 4, (BucketSpan(0, 2), BucketSpan(1, 2)), (BucketSpan(0, 2), BucketSpan(1, 2)), (2, 1, -3, 3), (2, 1, -2, 3))) + hfm.add_sample("hist_w_classic_two_sets_bucket", {"foo": "bar", "le": "0.001"}, 4.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_bucket", {"foo": "bar", "le": "+Inf"}, 24.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_count", {"foo": "bar"}, 24.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_sum", {"foo": "bar"}, 100.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets", {"foo": "baz"}, 0, None, None, NativeHistogram(24, 100, 0, 0.001, 4, (BucketSpan(0, 2), BucketSpan(1, 2)), (BucketSpan(0, 2), BucketSpan(1, 2)), (2, 1, -3, 3), (2, 1, -2, 3))) + hfm.add_sample("hist_w_classic_two_sets_bucket", {"foo": "baz", "le": "0.001"}, 4.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_bucket", {"foo": "baz", "le": "+Inf"}, 24.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_count", {"foo": "baz"}, 24.0, None, None, None) + hfm.add_sample("hist_w_classic_two_sets_sum", {"foo": "baz"}, 100.0, None, None, None) + self.custom_collector(hfm) + self.assertEqual(b"""# HELP hist_w_classic_two_sets Is an example of a native histogram plus a classic histogram with two label sets in OM 1.0.0 +# TYPE hist_w_classic_two_sets histogram +hist_w_classic_two_sets_bucket{foo="bar",le="0.001"} 4.0 +hist_w_classic_two_sets_bucket{foo="bar",le="+Inf"} 24.0 +hist_w_classic_two_sets_count{foo="bar"} 24.0 +hist_w_classic_two_sets_sum{foo="bar"} 100.0 +hist_w_classic_two_sets_bucket{foo="baz",le="0.001"} 4.0 +hist_w_classic_two_sets_bucket{foo="baz",le="+Inf"} 24.0 +hist_w_classic_two_sets_count{foo="baz"} 24.0 +hist_w_classic_two_sets_sum{foo="baz"} 100.0 +# EOF +""", generate_latest(self.registry, version="1.0.0")) def test_histogram_negative_buckets(self) -> None: s = Histogram('hh', 'A histogram', buckets=[-1, -0.5, 0, 0.5, 1], registry=self.registry) @@ -253,7 +279,7 @@ def test_histogram_negative_buckets(self) -> None: hh_count 1.0 hh_created 123.456 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) def test_histogram_exemplar(self) -> None: s = Histogram('hh', 'A histogram', buckets=[1, 2, 3, 4], registry=self.registry) @@ -273,7 +299,7 @@ def test_histogram_exemplar(self) -> None: hh_sum 8.0 hh_created 123.456 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="1.0.0")) def test_counter_exemplar(self) -> None: c = Counter('cc', 'A counter', registry=self.registry) @@ -283,7 +309,7 @@ def test_counter_exemplar(self) -> None: cc_total 1.0 # {a="b"} 1.0 123.456 cc_created 123.456 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="1.0.0")) def test_untyped_exemplar(self) -> None: class MyCollector: @@ -331,7 +357,7 @@ def test_gaugehistogram(self) -> None: gh_gcount 5.0 gh_gsum 7.0 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="1.0.0")) def test_gaugehistogram_negative_buckets(self) -> None: self.custom_collector( @@ -343,7 +369,7 @@ def test_gaugehistogram_negative_buckets(self) -> None: gh_gcount 5.0 gh_gsum -7.0 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="1.0.0")) def test_info(self) -> None: i = Info('ii', 'A info', ['a', 'b'], registry=self.registry) @@ -352,7 +378,7 @@ def test_info(self) -> None: # TYPE ii info ii_info{a="c",b="d",foo="bar"} 1.0 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) def test_enum(self) -> None: i = Enum('ee', 'An enum', ['a', 'b'], registry=self.registry, states=['foo', 'bar']) @@ -362,7 +388,7 @@ def test_enum(self) -> None: ee{a="c",b="d",ee="foo"} 0.0 ee{a="c",b="d",ee="bar"} 1.0 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) def test_unicode(self) -> None: c = Counter('cc', '\u4500', ['l'], registry=self.registry) @@ -372,7 +398,7 @@ def test_unicode(self) -> None: cc_total{l="\xe4\x94\x80"} 1.0 cc_created{l="\xe4\x94\x80"} 123.456 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) def test_escaping(self) -> None: c = Counter('cc', 'A\ncount\\er\"', ['a'], registry=self.registry) @@ -382,7 +408,7 @@ def test_escaping(self) -> None: cc_total{a="\\\\x\\n\\""} 1.0 cc_created{a="\\\\x\\n\\""} 123.456 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="2.0.0")) def test_nonnumber(self) -> None: class MyNumber: @@ -424,7 +450,25 @@ def collect(self): ts{foo="e"} 0.0 123.000456000 ts{foo="f"} 0.0 123.000000456 # EOF -""", generate_latest(self.registry)) +""", generate_latest(self.registry, version="1.0.0")) + + def test_native_histogram_version_comparison(self) -> None: + hfm = HistogramMetricFamily("nh_version", "nh version test") + hfm.add_sample("nh_version", {}, 0, None, None, NativeHistogram(5, 10, 0, 0.01, 2, (BucketSpan(0, 1),), (BucketSpan(0, 1),), (3,), (4,))) + self.custom_collector(hfm) + + # Version 1.0.0 should omit native histogram samples entirely + self.assertEqual(b"""# HELP nh_version nh version test +# TYPE nh_version histogram +# EOF +""", generate_latest(self.registry, version="1.0.0")) + + # Version 2.0.0 should emit native histogram format + self.assertEqual(b"""# HELP nh_version nh version test +# TYPE nh_version histogram +nh_version {count:5,sum:10,schema:0,zero_threshold:0.01,zero_count:2,negative_spans:[0:1],negative_deltas:[4],positive_spans:[0:1],positive_deltas:[3]} +# EOF +""", generate_latest(self.registry, version="2.0.0")) @pytest.mark.parametrize("scenario", [ From 4de31eee009a527ba7a5cda76a4aef403df7ab0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dominik=20S=C3=BC=C3=9F?= Date: Mon, 8 Sep 2025 16:35:19 +0200 Subject: [PATCH 17/38] fix: remove space after comma in openmetrics exposition (#1132) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit OpenMetrics doesn't allow for spaces between labels and prometheus fails with a parsing error. Removing this fixes UTF8 metrics exposition Signed-off-by: Dominik Süß --- prometheus_client/openmetrics/exposition.py | 2 +- tests/openmetrics/test_exposition.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/prometheus_client/openmetrics/exposition.py b/prometheus_client/openmetrics/exposition.py index bc24c7cf..1dc05c5b 100644 --- a/prometheus_client/openmetrics/exposition.py +++ b/prometheus_client/openmetrics/exposition.py @@ -72,7 +72,7 @@ def generate_latest(registry, escaping=UNDERSCORES, version="1.0.0"): if escaping == ALLOWUTF8 and not _is_valid_legacy_metric_name(s.name): labelstr = escape_metric_name(s.name, escaping) if s.labels: - labelstr += ', ' + labelstr += ',' else: labelstr = '' diff --git a/tests/openmetrics/test_exposition.py b/tests/openmetrics/test_exposition.py index 6c879ec4..a3ed0d6e 100644 --- a/tests/openmetrics/test_exposition.py +++ b/tests/openmetrics/test_exposition.py @@ -169,7 +169,7 @@ def test_native_histogram_utf8_stress(self) -> None: self.custom_collector(hfm) self.assertEqual(b"""# HELP "native{histogram" Is a basic example of a native histogram # TYPE "native{histogram" histogram -{"native{histogram", "xx{} # {}"=" EOF # {}}}"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} +{"native{histogram","xx{} # {}"=" EOF # {}}}"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} # EOF """, generate_latest(self.registry, ALLOWUTF8, version="2.0.0")) @@ -189,7 +189,7 @@ def test_native_histogram_with_labels_utf8(self) -> None: self.custom_collector(hfm) self.assertEqual(b"""# HELP "hist.w.labels" Is a basic example of a native histogram with labels # TYPE "hist.w.labels" histogram -{"hist.w.labels", baz="qux",foo="bar"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} +{"hist.w.labels",baz="qux",foo="bar"} {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,negative_spans:[0:2,1:2],negative_deltas:[2,1,-2,3],positive_spans:[0:2,1:2],positive_deltas:[2,1,-3,3]} # EOF """, generate_latest(self.registry, ALLOWUTF8, version="2.0.0")) From 47d2b416d75f5569863e2bb08a15b58218563814 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Mon, 8 Sep 2025 11:23:33 -0600 Subject: [PATCH 18/38] Do not use global when only reading variable (#1133) The global keyword is only necessary when writing to a variable, this will fix the lint failures that came with a newer version of flake8. Signed-off-by: Chris Marchbanks --- prometheus_client/validation.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/prometheus_client/validation.py b/prometheus_client/validation.py index 7ada5d81..6fcc8018 100644 --- a/prometheus_client/validation.py +++ b/prometheus_client/validation.py @@ -16,7 +16,6 @@ def _init_legacy_validation() -> bool: def get_legacy_validation() -> bool: """Return the current status of the legacy validation setting.""" - global _legacy_validation return _legacy_validation @@ -39,7 +38,6 @@ def _validate_metric_name(name: str) -> None: """ if not name: raise ValueError("metric name cannot be empty") - global _legacy_validation if _legacy_validation: if not METRIC_NAME_RE.match(name): raise ValueError("invalid metric name " + name) @@ -63,7 +61,6 @@ def _validate_metric_label_name_token(tok: str) -> None: """ if not tok: raise ValueError("invalid label name token " + tok) - global _legacy_validation quoted = tok[0] == '"' and tok[-1] == '"' if not quoted or _legacy_validation: if not METRIC_LABEL_NAME_RE.match(tok): From b3fbbca891a6c6d07b83a3680919956a3c3ab523 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Thu, 11 Sep 2025 13:45:57 -0600 Subject: [PATCH 19/38] Fix issue parsing double spaces after # HELP/# TYPE (#1134) A regression was reported for 0.22.x where if there are two spaces after HELP or TEXT we would raise a value error. This was caused by having an extra entry in our array of splits due to how we preocess the splits. Signed-off-by: Chris Marchbanks --- prometheus_client/parser.py | 6 ++++++ tests/test_parser.py | 8 ++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/prometheus_client/parser.py b/prometheus_client/parser.py index ec71b2ab..ceca273b 100644 --- a/prometheus_client/parser.py +++ b/prometheus_client/parser.py @@ -186,6 +186,12 @@ def _split_quoted(text, separator, maxsplit=0): tokens[-1] = text[x:] x = len(text) continue + # If the first character is the separator keep going. This happens when + # there are double whitespace characters separating symbols. + if split_pos == x: + x += 1 + continue + if maxsplit > 0 and len(tokens) > maxsplit: tokens[-1] = text[x:] break diff --git a/tests/test_parser.py b/tests/test_parser.py index c8b17fa1..49c4dc8c 100644 --- a/tests/test_parser.py +++ b/tests/test_parser.py @@ -121,7 +121,6 @@ def test_blank_lines_and_comments(self): """) self.assertEqualMetrics([CounterMetricFamily("a", "help", value=1)], list(families)) - def test_comments_parts_are_not_validated_against_legacy_metric_name(self): # https://github.com/prometheus/client_python/issues/1108 families = text_string_to_metric_families(""" @@ -130,7 +129,12 @@ def test_comments_parts_are_not_validated_against_legacy_metric_name(self): """) self.assertEqualMetrics([], list(families)) - + def test_extra_whitespace(self): + families = text_string_to_metric_families("""# TYPE a counter +# HELP a help +a 1 +""") + self.assertEqualMetrics([CounterMetricFamily("a", "help", value=1)], list(families)) def test_tabs(self): families = text_string_to_metric_families("""#\tTYPE\ta\tcounter From b9e78a3f701fd442f57db23701c2021a529a84c3 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Thu, 11 Sep 2025 13:48:45 -0600 Subject: [PATCH 20/38] Release 0.23.0 Signed-off-by: Chris Marchbanks --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 0c762505..af4c7f2f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "prometheus_client" -version = "0.22.1" +version = "0.23.0" description = "Python client for the Prometheus monitoring system." readme = "README.md" license = "Apache-2.0 AND BSD-2-Clause" From f9471403a82de6af93feeac2d38938ca1c384b6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Fri, 12 Sep 2025 21:36:41 +0200 Subject: [PATCH 21/38] fix: Use `asyncio.new_event_loop()` to create event loop for tests (#1138) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix: Use `asyncio.new_event_loop()` to create event loop for tests Replace the use of `asyncio.get_event_loop()` with more appropriate `asyncio.new_event_loop()` to create event loops for testing. The former used to be a wrapper that either returned the currently running event loop or created a new one, but the latter behavior was deprecated and removed in Python 3.14. Since the tests are always run in a synchronous context, and they always run the obtained event loop to completion, just always create a new event loop. Fixes #1137 Signed-off-by: Michał Górny * fix: Remove obsolete asgiref pin Remove the `asgiref` pin linked to #1020. I can't reproduce the issue anymore with the current `asgiref` versions, and the pin actually breaks the tests with the `asyncio` event loop fixes. Signed-off-by: Michał Górny --------- Signed-off-by: Michał Górny --- tests/test_asgi.py | 8 ++++---- tox.ini | 3 --- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/tests/test_asgi.py b/tests/test_asgi.py index 386ff598..86431d21 100644 --- a/tests/test_asgi.py +++ b/tests/test_asgi.py @@ -45,7 +45,7 @@ def setUp(self): def tearDown(self): if self.communicator: - asyncio.get_event_loop().run_until_complete( + asyncio.new_event_loop().run_until_complete( self.communicator.wait() ) @@ -53,7 +53,7 @@ def seed_app(self, app): self.communicator = ApplicationCommunicator(app, self.scope) def send_input(self, payload): - asyncio.get_event_loop().run_until_complete( + asyncio.new_event_loop().run_until_complete( self.communicator.send_input(payload) ) @@ -61,7 +61,7 @@ def send_default_request(self): self.send_input({"type": "http.request", "body": b""}) def get_output(self): - output = asyncio.get_event_loop().run_until_complete( + output = asyncio.new_event_loop().run_until_complete( self.communicator.receive_output(0) ) return output @@ -229,6 +229,6 @@ def test_qs_parsing(self): self.assert_not_metrics(output, *metrics[i_2]) - asyncio.get_event_loop().run_until_complete( + asyncio.new_event_loop().run_until_complete( self.communicator.wait() ) diff --git a/tox.ini b/tox.ini index bef57f85..40337027 100644 --- a/tox.ini +++ b/tox.ini @@ -8,9 +8,6 @@ deps = pytest-benchmark attrs {py3.9,pypy3.9}: twisted - # NOTE: Pinned due to https://github.com/prometheus/client_python/issues/1020 - py3.9: asgiref==3.7 - pypy3.9: asgiref==3.7 commands = coverage run --parallel -m pytest {posargs} [testenv:py3.9-nooptionals] From 266beb2567e0040a5790836c32de5a643d5177e4 Mon Sep 17 00:00:00 2001 From: Ruslan Kuprieiev Date: Thu, 18 Sep 2025 23:09:55 +0300 Subject: [PATCH 22/38] fix: use tuples instead of packaging Version (#1136) Signed-off-by: Ruslan Kuprieiev --- prometheus_client/exposition.py | 8 +++----- prometheus_client/openmetrics/exposition.py | 6 ++---- prometheus_client/utils.py | 12 ++++++++++++ 3 files changed, 17 insertions(+), 9 deletions(-) diff --git a/prometheus_client/exposition.py b/prometheus_client/exposition.py index 93285804..0d471707 100644 --- a/prometheus_client/exposition.py +++ b/prometheus_client/exposition.py @@ -18,11 +18,9 @@ ) from wsgiref.simple_server import make_server, WSGIRequestHandler, WSGIServer -from packaging.version import Version - from .openmetrics import exposition as openmetrics from .registry import CollectorRegistry, REGISTRY -from .utils import floatToGoString +from .utils import floatToGoString, parse_version __all__ = ( 'CONTENT_TYPE_LATEST', @@ -346,7 +344,7 @@ def choose_encoder(accept_header: str) -> Tuple[Callable[[CollectorRegistry], by # mimetype. if not version: return (partial(openmetrics.generate_latest, escaping=openmetrics.UNDERSCORES, version="1.0.0"), openmetrics.CONTENT_TYPE_LATEST) - if version and Version(version) >= Version('1.0.0'): + if version and parse_version(version) >= (1, 0, 0): return (partial(openmetrics.generate_latest, escaping=escaping, version=version), f'application/openmetrics-text; version={version}; charset=utf-8; escaping=' + str(escaping)) elif accepted.split(';')[0].strip() == 'text/plain': @@ -355,7 +353,7 @@ def choose_encoder(accept_header: str) -> Tuple[Callable[[CollectorRegistry], by escaping = _get_escaping(toks) # Only return an escaping header if we have a good version and # mimetype. - if version and Version(version) >= Version('1.0.0'): + if version and parse_version(version) >= (1, 0, 0): return (partial(generate_latest, escaping=escaping), CONTENT_TYPE_LATEST + '; escaping=' + str(escaping)) return generate_latest, CONTENT_TYPE_PLAIN_0_0_4 diff --git a/prometheus_client/openmetrics/exposition.py b/prometheus_client/openmetrics/exposition.py index 1dc05c5b..5e69e463 100644 --- a/prometheus_client/openmetrics/exposition.py +++ b/prometheus_client/openmetrics/exposition.py @@ -4,9 +4,7 @@ from sys import maxunicode from typing import Callable -from packaging.version import Version - -from ..utils import floatToGoString +from ..utils import floatToGoString, parse_version from ..validation import ( _is_valid_legacy_labelname, _is_valid_legacy_metric_name, ) @@ -94,7 +92,7 @@ def generate_latest(registry, escaping=UNDERSCORES, version="1.0.0"): timestamp = f' {s.timestamp}' # Skip native histogram samples entirely if version < 2.0.0 - if s.native_histogram and Version(version) < Version('2.0.0'): + if s.native_histogram and parse_version(version) < (2, 0, 0): continue native_histogram = '' diff --git a/prometheus_client/utils.py b/prometheus_client/utils.py index 0d2b0948..87b75ca8 100644 --- a/prometheus_client/utils.py +++ b/prometheus_client/utils.py @@ -1,4 +1,5 @@ import math +from typing import Union INF = float("inf") MINUS_INF = float("-inf") @@ -22,3 +23,14 @@ def floatToGoString(d): mantissa = f'{s[0]}.{s[1:dot]}{s[dot + 1:]}'.rstrip('0.') return f'{mantissa}e+0{dot - 1}' return s + + +def parse_version(version_str: str) -> tuple[Union[int, str], ...]: + version: list[Union[int, str]] = [] + for part in version_str.split('.'): + try: + version.append(int(part)) + except ValueError: + version.append(part) + + return tuple(version) From 8746c49a76a7929795fab7b593b1c44dc8c972d2 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Thu, 18 Sep 2025 14:45:49 -0600 Subject: [PATCH 23/38] Release 0.23.1 Signed-off-by: Chris Marchbanks --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index af4c7f2f..86988592 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "prometheus_client" -version = "0.23.0" +version = "0.23.1" description = "Python client for the Prometheus monitoring system." readme = "README.md" license = "Apache-2.0 AND BSD-2-Clause" From 10db862c7a300e98e4529e26d969d2afd40d6811 Mon Sep 17 00:00:00 2001 From: Lexi Robinson Date: Fri, 19 Sep 2025 18:43:45 +0100 Subject: [PATCH 24/38] Add an AIOHTTP exporter (#1139) * Always run the asgi tests Since the client now requires a minimum of Python 3.9, we don't need to have this feature gate in place any more Signed-off-by: Lexi Robinson * Add an AIOHTTP exporter Unfortunately the AIOHTTP library doesn't support ASGI and apparently has no plans to do so which makes the ASGI exporter not suitable for anyone using it to run their python server. Where possible this commit follows the existing ASGI implementation and runs the same tests for consistency. Signed-off-by: Lexi Robinson --------- Signed-off-by: Lexi Robinson --- docs/content/exporting/http/aiohttp.md | 23 +++ prometheus_client/aiohttp/__init__.py | 5 + prometheus_client/aiohttp/exposition.py | 39 +++++ pyproject.toml | 3 + tests/test_aiohttp.py | 192 ++++++++++++++++++++++++ tests/test_asgi.py | 19 +-- tox.ini | 3 + 7 files changed, 270 insertions(+), 14 deletions(-) create mode 100644 docs/content/exporting/http/aiohttp.md create mode 100644 prometheus_client/aiohttp/__init__.py create mode 100644 prometheus_client/aiohttp/exposition.py create mode 100644 tests/test_aiohttp.py diff --git a/docs/content/exporting/http/aiohttp.md b/docs/content/exporting/http/aiohttp.md new file mode 100644 index 00000000..726b92cb --- /dev/null +++ b/docs/content/exporting/http/aiohttp.md @@ -0,0 +1,23 @@ +--- +title: AIOHTTP +weight: 6 +--- + +To use Prometheus with a [AIOHTTP server](https://docs.aiohttp.org/en/stable/web.html), +there is `make_aiohttp_handler` which creates a handler. + +```python +from aiohttp import web +from prometheus_client.aiohttp import make_aiohttp_handler + +app = web.Application() +app.router.add_get("/metrics", make_aiohttp_handler()) +``` + +By default, this handler will instruct AIOHTTP to automatically compress the +response if requested by the client. This behaviour can be disabled by passing +`disable_compression=True` when creating the app, like this: + +```python +app.router.add_get("/metrics", make_aiohttp_handler(disable_compression=True)) +``` diff --git a/prometheus_client/aiohttp/__init__.py b/prometheus_client/aiohttp/__init__.py new file mode 100644 index 00000000..9e5da157 --- /dev/null +++ b/prometheus_client/aiohttp/__init__.py @@ -0,0 +1,5 @@ +from .exposition import make_aiohttp_handler + +__all__ = [ + "make_aiohttp_handler", +] diff --git a/prometheus_client/aiohttp/exposition.py b/prometheus_client/aiohttp/exposition.py new file mode 100644 index 00000000..914fb26f --- /dev/null +++ b/prometheus_client/aiohttp/exposition.py @@ -0,0 +1,39 @@ +from __future__ import annotations + +from aiohttp import hdrs, web +from aiohttp.typedefs import Handler + +from ..exposition import _bake_output +from ..registry import CollectorRegistry, REGISTRY + + +def make_aiohttp_handler( + registry: CollectorRegistry = REGISTRY, + disable_compression: bool = False, +) -> Handler: + """Create a aiohttp handler which serves the metrics from a registry.""" + + async def prometheus_handler(request: web.Request) -> web.Response: + # Prepare parameters + params = {key: request.query.getall(key) for key in request.query.keys()} + accept_header = ",".join(request.headers.getall(hdrs.ACCEPT, [])) + accept_encoding_header = "" + # Bake output + status, headers, output = _bake_output( + registry, + accept_header, + accept_encoding_header, + params, + # use AIOHTTP's compression + disable_compression=True, + ) + response = web.Response( + status=int(status.split(" ")[0]), + headers=headers, + body=output, + ) + if not disable_compression: + response.enable_compression() + return response + + return prometheus_handler diff --git a/pyproject.toml b/pyproject.toml index 86988592..2078c314 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -43,6 +43,9 @@ classifiers = [ twisted = [ "twisted", ] +aiohttp = [ + "aiohttp", +] [project.urls] Homepage = "https://github.com/prometheus/client_python" diff --git a/tests/test_aiohttp.py b/tests/test_aiohttp.py new file mode 100644 index 00000000..e4fa368b --- /dev/null +++ b/tests/test_aiohttp.py @@ -0,0 +1,192 @@ +from __future__ import annotations + +import gzip +from typing import TYPE_CHECKING +from unittest import skipUnless + +from prometheus_client import CollectorRegistry, Counter +from prometheus_client.exposition import CONTENT_TYPE_PLAIN_0_0_4 + +try: + from aiohttp import ClientResponse, hdrs, web + from aiohttp.test_utils import AioHTTPTestCase + + from prometheus_client.aiohttp import make_aiohttp_handler + + AIOHTTP_INSTALLED = True +except ImportError: + if TYPE_CHECKING: + assert False + + from unittest import IsolatedAsyncioTestCase as AioHTTPTestCase + + AIOHTTP_INSTALLED = False + + +class AioHTTPTest(AioHTTPTestCase): + @skipUnless(AIOHTTP_INSTALLED, "AIOHTTP is not installed") + def setUp(self) -> None: + self.registry = CollectorRegistry() + + async def get_application(self) -> web.Application: + app = web.Application() + # The AioHTTPTestCase requires that applications be static, so we need + # both versions to be available so the test can choose between them + app.router.add_get("/metrics", make_aiohttp_handler(self.registry)) + app.router.add_get( + "/metrics_uncompressed", + make_aiohttp_handler(self.registry, disable_compression=True), + ) + return app + + def increment_metrics( + self, + metric_name: str, + help_text: str, + increments: int, + ) -> None: + c = Counter(metric_name, help_text, registry=self.registry) + for _ in range(increments): + c.inc() + + def assert_metrics( + self, + output: str, + metric_name: str, + help_text: str, + increments: int, + ) -> None: + self.assertIn("# HELP " + metric_name + "_total " + help_text + "\n", output) + self.assertIn("# TYPE " + metric_name + "_total counter\n", output) + self.assertIn(metric_name + "_total " + str(increments) + ".0\n", output) + + def assert_not_metrics( + self, + output: str, + metric_name: str, + help_text: str, + increments: int, + ) -> None: + self.assertNotIn("# HELP " + metric_name + "_total " + help_text + "\n", output) + self.assertNotIn("# TYPE " + metric_name + "_total counter\n", output) + self.assertNotIn(metric_name + "_total " + str(increments) + ".0\n", output) + + async def assert_outputs( + self, + response: ClientResponse, + metric_name: str, + help_text: str, + increments: int, + ) -> None: + self.assertIn( + CONTENT_TYPE_PLAIN_0_0_4, + response.headers.getall(hdrs.CONTENT_TYPE), + ) + output = await response.text() + self.assert_metrics(output, metric_name, help_text, increments) + + async def validate_metrics( + self, + metric_name: str, + help_text: str, + increments: int, + ) -> None: + """ + AIOHTTP handler serves the metrics from the provided registry. + """ + self.increment_metrics(metric_name, help_text, increments) + async with self.client.get("/metrics") as response: + response.raise_for_status() + await self.assert_outputs(response, metric_name, help_text, increments) + + async def test_report_metrics_1(self): + await self.validate_metrics("counter", "A counter", 2) + + async def test_report_metrics_2(self): + await self.validate_metrics("counter", "Another counter", 3) + + async def test_report_metrics_3(self): + await self.validate_metrics("requests", "Number of requests", 5) + + async def test_report_metrics_4(self): + await self.validate_metrics("failed_requests", "Number of failed requests", 7) + + async def test_gzip(self): + # Increment a metric. + metric_name = "counter" + help_text = "A counter" + increments = 2 + self.increment_metrics(metric_name, help_text, increments) + + async with self.client.get( + "/metrics", + auto_decompress=False, + headers={hdrs.ACCEPT_ENCODING: "gzip"}, + ) as response: + response.raise_for_status() + self.assertIn(hdrs.CONTENT_ENCODING, response.headers) + self.assertIn("gzip", response.headers.getall(hdrs.CONTENT_ENCODING)) + body = await response.read() + output = gzip.decompress(body).decode("utf8") + self.assert_metrics(output, metric_name, help_text, increments) + + async def test_gzip_disabled(self): + # Increment a metric. + metric_name = "counter" + help_text = "A counter" + increments = 2 + self.increment_metrics(metric_name, help_text, increments) + + async with self.client.get( + "/metrics_uncompressed", + auto_decompress=False, + headers={hdrs.ACCEPT_ENCODING: "gzip"}, + ) as response: + response.raise_for_status() + self.assertNotIn(hdrs.CONTENT_ENCODING, response.headers) + output = await response.text() + self.assert_metrics(output, metric_name, help_text, increments) + + async def test_openmetrics_encoding(self): + """Response content type is application/openmetrics-text when appropriate Accept header is in request""" + async with self.client.get( + "/metrics", + auto_decompress=False, + headers={hdrs.ACCEPT: "application/openmetrics-text; version=1.0.0"}, + ) as response: + response.raise_for_status() + self.assertEqual( + response.headers.getone(hdrs.CONTENT_TYPE).split(";", maxsplit=1)[0], + "application/openmetrics-text", + ) + + async def test_plaintext_encoding(self): + """Response content type is text/plain when Accept header is missing in request""" + async with self.client.get("/metrics") as response: + response.raise_for_status() + self.assertEqual( + response.headers.getone(hdrs.CONTENT_TYPE).split(";", maxsplit=1)[0], + "text/plain", + ) + + async def test_qs_parsing(self): + """Only metrics that match the 'name[]' query string param appear""" + + metrics = [("asdf", "first test metric", 1), ("bsdf", "second test metric", 2)] + + for m in metrics: + self.increment_metrics(*m) + + for i_1 in range(len(metrics)): + async with self.client.get( + "/metrics", + params={"name[]": f"{metrics[i_1][0]}_total"}, + ) as response: + output = await response.text() + self.assert_metrics(output, *metrics[i_1]) + + for i_2 in range(len(metrics)): + if i_1 == i_2: + continue + + self.assert_not_metrics(output, *metrics[i_2]) diff --git a/tests/test_asgi.py b/tests/test_asgi.py index 86431d21..d4933cec 100644 --- a/tests/test_asgi.py +++ b/tests/test_asgi.py @@ -1,19 +1,11 @@ +import asyncio import gzip -from unittest import skipUnless, TestCase +from unittest import TestCase -from prometheus_client import CollectorRegistry, Counter -from prometheus_client.exposition import CONTENT_TYPE_PLAIN_0_0_4 - -try: - # Python >3.5 only - import asyncio +from asgiref.testing import ApplicationCommunicator - from asgiref.testing import ApplicationCommunicator - - from prometheus_client import make_asgi_app - HAVE_ASYNCIO_AND_ASGI = True -except ImportError: - HAVE_ASYNCIO_AND_ASGI = False +from prometheus_client import CollectorRegistry, Counter, make_asgi_app +from prometheus_client.exposition import CONTENT_TYPE_PLAIN_0_0_4 def setup_testing_defaults(scope): @@ -33,7 +25,6 @@ def setup_testing_defaults(scope): class ASGITest(TestCase): - @skipUnless(HAVE_ASYNCIO_AND_ASGI, "Don't have asyncio/asgi installed.") def setUp(self): self.registry = CollectorRegistry() self.captured_status = None diff --git a/tox.ini b/tox.ini index 40337027..2c9873ec 100644 --- a/tox.ini +++ b/tox.ini @@ -3,11 +3,13 @@ envlist = coverage-clean,py{3.9,3.10,3.11,3.12,3.13,py3.9,3.9-nooptionals},cover [testenv] deps = + asgiref coverage pytest pytest-benchmark attrs {py3.9,pypy3.9}: twisted + {py3.9,pypy3.9}: aiohttp commands = coverage run --parallel -m pytest {posargs} [testenv:py3.9-nooptionals] @@ -44,6 +46,7 @@ commands = [testenv:mypy] deps = pytest + aiohttp asgiref mypy==0.991 skip_install = true From 378510b8ae91d23383cd1c7e0be180b374a1c84c Mon Sep 17 00:00:00 2001 From: Hazel Shen Date: Tue, 28 Oct 2025 23:56:43 +0800 Subject: [PATCH 25/38] Add remove_matching() method for metric label deletion (#1121) * Add remove_matching() method for metric label deletion Signed-off-by: Hazel * Rename function name, and the parameter's name Signed-off-by: Hazel * Make remove_by_labels() consistent with remove(): return None Signed-off-by: Hazel --------- Signed-off-by: Hazel Co-authored-by: Hazel --- prometheus_client/metrics.py | 33 +++++++++++++++++++++++++++++++++ tests/test_core.py | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) diff --git a/prometheus_client/metrics.py b/prometheus_client/metrics.py index b9f25ffc..39daac2d 100644 --- a/prometheus_client/metrics.py +++ b/prometheus_client/metrics.py @@ -203,6 +203,39 @@ def remove(self, *labelvalues: Any) -> None: if labelvalues in self._metrics: del self._metrics[labelvalues] + def remove_by_labels(self, labels: dict[str, str]) -> None: + """Remove all series whose labelset partially matches the given labels.""" + if 'prometheus_multiproc_dir' in os.environ or 'PROMETHEUS_MULTIPROC_DIR' in os.environ: + warnings.warn( + "Removal of labels has not been implemented in multi-process mode yet.", + UserWarning + ) + + if not self._labelnames: + raise ValueError('No label names were set when constructing %s' % self) + + if not isinstance(labels, dict): + raise TypeError("labels must be a dict of {label_name: label_value}") + + if not labels: + return # no operation + + invalid = [k for k in labels.keys() if k not in self._labelnames] + if invalid: + raise ValueError( + 'Unknown label names: %s; expected %s' % (invalid, self._labelnames) + ) + + pos_filter = {self._labelnames.index(k): str(v) for k, v in labels.items()} + + with self._lock: + # list(...) to avoid "dictionary changed size during iteration" + for lv in list(self._metrics.keys()): + if all(lv[pos] == want for pos, want in pos_filter.items()): + # pop with default avoids KeyError if concurrently removed + self._metrics.pop(lv, None) + + def clear(self) -> None: """Remove all labelsets from the metric""" if 'prometheus_multiproc_dir' in os.environ or 'PROMETHEUS_MULTIPROC_DIR' in os.environ: diff --git a/tests/test_core.py b/tests/test_core.py index 284bce09..c7c9c14f 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -630,6 +630,40 @@ def test_labels_coerced_to_string(self): self.counter.remove(None) self.assertEqual(None, self.registry.get_sample_value('c_total', {'l': 'None'})) + def test_remove_by_labels(self): + from prometheus_client import Counter + + c = Counter('c2', 'help', ['tenant', 'endpoint'], registry=self.registry) + c.labels('acme', '/').inc() + c.labels('acme', '/checkout').inc() + c.labels('globex', '/').inc() + + ret = c.remove_by_labels({'tenant': 'acme'}) + self.assertIsNone(ret) + + self.assertIsNone(self.registry.get_sample_value('c2_total', {'tenant': 'acme', 'endpoint': '/'})) + self.assertIsNone(self.registry.get_sample_value('c2_total', {'tenant': 'acme', 'endpoint': '/checkout'})) + self.assertEqual(1, self.registry.get_sample_value('c2_total', {'tenant': 'globex', 'endpoint': '/'})) + + + def test_remove_by_labels_invalid_label_name(self): + from prometheus_client import Counter + c = Counter('c3', 'help', ['tenant', 'endpoint'], registry=self.registry) + c.labels('acme', '/').inc() + with self.assertRaises(ValueError): + c.remove_by_labels({'badkey': 'x'}) + + + def test_remove_by_labels_empty_is_noop(self): + from prometheus_client import Counter + c = Counter('c4', 'help', ['tenant', 'endpoint'], registry=self.registry) + c.labels('acme', '/').inc() + + ret = c.remove_by_labels({}) + self.assertIsNone(ret) + # Ensure the series is still present + self.assertEqual(1, self.registry.get_sample_value('c4_total', {'tenant': 'acme', 'endpoint': '/'})) + def test_non_string_labels_raises(self): class Test: __str__ = None From 1783ca87acbed1d45ebaa124b7b22244f9c9c2e8 Mon Sep 17 00:00:00 2001 From: Naoyuki Sano Date: Wed, 29 Oct 2025 00:58:27 +0900 Subject: [PATCH 26/38] Add support for Python 3.14 (#1142) * Add Python version 3.14 to CircleCI config Signed-off-by: Naoyuki Sano * Update tox.ini Signed-off-by: Naoyuki Sano * Add support for Python 3.14 in pyproject.toml Signed-off-by: Naoyuki Sano * Update pyproject.toml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Naoyuki Sano --------- Signed-off-by: Naoyuki Sano Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .circleci/config.yml | 1 + pyproject.toml | 1 + tox.ini | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 4eaf808f..f29bd265 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -80,6 +80,7 @@ workflows: - "3.11" - "3.12" - "3.13" + - "3.14" - test_nooptionals: matrix: parameters: diff --git a/pyproject.toml b/pyproject.toml index 2078c314..1d8527a0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -34,6 +34,7 @@ classifiers = [ "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", "Programming Language :: Python :: Implementation :: CPython", "Programming Language :: Python :: Implementation :: PyPy", "Topic :: System :: Monitoring", diff --git a/tox.ini b/tox.ini index 2c9873ec..ccf95cc2 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,5 @@ [tox] -envlist = coverage-clean,py{3.9,3.10,3.11,3.12,3.13,py3.9,3.9-nooptionals},coverage-report,flake8,isort,mypy +envlist = coverage-clean,py{3.9,3.10,3.11,3.12,3.13,3.14,py3.9,3.9-nooptionals},coverage-report,flake8,isort,mypy [testenv] deps = From e8f8bae6554de11ebffffcc878ab19abd67528f2 Mon Sep 17 00:00:00 2001 From: Hazel Shen Date: Tue, 18 Nov 2025 04:52:35 +0800 Subject: [PATCH 27/38] fix(multiprocess): avoid double-building child metric names (#1035) (#1146) * fix(multiprocess): avoid double-building child metric names (#1035) Signed-off-by: hazel-shen * test: ensure child metrics retain parent namespace/subsystem/unit Signed-off-by: hazel-shen --------- Signed-off-by: hazel-shen --- prometheus_client/metrics.py | 22 ++++++- tests/test_multiprocess.py | 110 +++++++++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+), 3 deletions(-) diff --git a/prometheus_client/metrics.py b/prometheus_client/metrics.py index 39daac2d..4c53b26b 100644 --- a/prometheus_client/metrics.py +++ b/prometheus_client/metrics.py @@ -109,6 +109,10 @@ def __init__(self: T, registry: Optional[CollectorRegistry] = REGISTRY, _labelvalues: Optional[Sequence[str]] = None, ) -> None: + + self._original_name = name + self._namespace = namespace + self._subsystem = subsystem self._name = _build_full_name(self._type, name, namespace, subsystem, unit) self._labelnames = _validate_labelnames(self, labelnames) self._labelvalues = tuple(_labelvalues or ()) @@ -176,13 +180,25 @@ def labels(self: T, *labelvalues: Any, **labelkwargs: Any) -> T: labelvalues = tuple(str(l) for l in labelvalues) with self._lock: if labelvalues not in self._metrics: + + original_name = getattr(self, '_original_name', self._name) + namespace = getattr(self, '_namespace', '') + subsystem = getattr(self, '_subsystem', '') + unit = getattr(self, '_unit', '') + + child_kwargs = dict(self._kwargs) if self._kwargs else {} + for k in ('namespace', 'subsystem', 'unit'): + child_kwargs.pop(k, None) + self._metrics[labelvalues] = self.__class__( - self._name, + original_name, documentation=self._documentation, labelnames=self._labelnames, - unit=self._unit, + namespace=namespace, + subsystem=subsystem, + unit=unit, _labelvalues=labelvalues, - **self._kwargs + **child_kwargs ) return self._metrics[labelvalues] diff --git a/tests/test_multiprocess.py b/tests/test_multiprocess.py index 77fd3d81..e7ca154e 100644 --- a/tests/test_multiprocess.py +++ b/tests/test_multiprocess.py @@ -396,6 +396,116 @@ def test_remove_clear_warning(self): assert "Removal of labels has not been implemented" in str(w[0].message) assert issubclass(w[-1].category, UserWarning) assert "Clearing labels has not been implemented" in str(w[-1].message) + + def test_child_name_is_built_once_with_namespace_subsystem_unit(self): + """ + Repro for #1035: + In multiprocess mode, child metrics must NOT rebuild the full name + (namespace/subsystem/unit) a second time. The exported family name should + be built once, and Counter samples should use "_total". + """ + from prometheus_client import Counter + + class CustomCounter(Counter): + def __init__( + self, + name, + documentation, + labelnames=(), + namespace="mydefaultnamespace", + subsystem="mydefaultsubsystem", + unit="", + registry=None, + _labelvalues=None + ): + # Intentionally provide non-empty defaults to trigger the bug path. + super().__init__( + name=name, + documentation=documentation, + labelnames=labelnames, + namespace=namespace, + subsystem=subsystem, + unit=unit, + registry=registry, + _labelvalues=_labelvalues) + + # Create a Counter with explicit namespace/subsystem/unit + c = CustomCounter( + name='m', + documentation='help', + labelnames=('status', 'method'), + namespace='ns', + subsystem='ss', + unit='seconds', # avoid '_total_total' confusion + registry=None, # not registered in local registry in multiprocess mode + ) + + # Create two labeled children + c.labels(status='200', method='GET').inc() + c.labels(status='404', method='POST').inc() + + # Collect from the multiprocess collector initialized in setUp() + metrics = {m.name: m for m in self.collector.collect()} + + # Family name should be built once (no '_total' in family name) + expected_family = 'ns_ss_m_seconds' + self.assertIn(expected_family, metrics, f"missing family {expected_family}") + + # Counter samples must use '_total' + mf = metrics[expected_family] + sample_names = {s.name for s in mf.samples} + self.assertTrue( + all(name == expected_family + '_total' for name in sample_names), + f"unexpected sample names: {sample_names}" + ) + + # Ensure no double-built prefix sneaks in (the original bug) + bad_prefix = 'mydefaultnamespace_mydefaultsubsystem_' + all_names = {mf.name, *sample_names} + self.assertTrue( + all(not n.startswith(bad_prefix) for n in all_names), + f"found double-built name(s): {[n for n in all_names if n.startswith(bad_prefix)]}" + ) + + def test_child_preserves_parent_context_for_subclasses(self): + """ + Ensure child metrics preserve parent's namespace/subsystem/unit information + so that subclasses can correctly use these parameters in their logic. + """ + class ContextAwareCounter(Counter): + def __init__(self, + name, + documentation, + labelnames=(), + namespace="", + subsystem="", + unit="", + **kwargs): + self.context = { + 'namespace': namespace, + 'subsystem': subsystem, + 'unit': unit + } + super().__init__(name, documentation, + labelnames=labelnames, + namespace=namespace, + subsystem=subsystem, + unit=unit, + **kwargs) + + parent = ContextAwareCounter('m', 'help', + labelnames=['status'], + namespace='prod', + subsystem='api', + unit='seconds', + registry=None) + + child = parent.labels(status='200') + + # Verify that child retains parent's context + self.assertEqual(child.context['namespace'], 'prod') + self.assertEqual(child.context['subsystem'], 'api') + self.assertEqual(child.context['unit'], 'seconds') class TestMmapedDict(unittest.TestCase): From a264ec0d85600decfb0681d00ed1566186bebfb3 Mon Sep 17 00:00:00 2001 From: Colin Watson Date: Wed, 26 Nov 2025 19:39:29 +0000 Subject: [PATCH 28/38] Don't interleave histogram metrics in multi-process collector (#1148) The OpenMetrics exposition format requires that samples for a given Metric (i.e. metric name and label set) are not interleaved, but the way that the multi-process collector handled accumulating histogram metrics could end up interleaving them. Restructure it slightly to guarantee that all the samples for a given Metric are kept together. Fixes: #1147 Signed-off-by: Colin Watson --- prometheus_client/multiprocess.py | 51 +++++++++++++--------- tests/test_multiprocess.py | 70 +++++++++++++++++++++++++++---- 2 files changed, 94 insertions(+), 27 deletions(-) diff --git a/prometheus_client/multiprocess.py b/prometheus_client/multiprocess.py index 2682190a..db55874e 100644 --- a/prometheus_client/multiprocess.py +++ b/prometheus_client/multiprocess.py @@ -88,32 +88,42 @@ def _parse_key(key): @staticmethod def _accumulate_metrics(metrics, accumulate): for metric in metrics.values(): - samples = defaultdict(float) - sample_timestamps = defaultdict(float) + samples = defaultdict(lambda: defaultdict(float)) + sample_timestamps = defaultdict(lambda: defaultdict(float)) buckets = defaultdict(lambda: defaultdict(float)) - samples_setdefault = samples.setdefault for s in metric.samples: name, labels, value, timestamp, exemplar, native_histogram_value = s + + if ( + metric.type == 'gauge' + and metric._multiprocess_mode in ( + 'min', 'livemin', + 'max', 'livemax', + 'sum', 'livesum', + 'mostrecent', 'livemostrecent', + ) + ): + labels = tuple(l for l in labels if l[0] != 'pid') + if metric.type == 'gauge': - without_pid_key = (name, tuple(l for l in labels if l[0] != 'pid')) if metric._multiprocess_mode in ('min', 'livemin'): - current = samples_setdefault(without_pid_key, value) + current = samples[labels].setdefault((name, labels), value) if value < current: - samples[without_pid_key] = value + samples[labels][(name, labels)] = value elif metric._multiprocess_mode in ('max', 'livemax'): - current = samples_setdefault(without_pid_key, value) + current = samples[labels].setdefault((name, labels), value) if value > current: - samples[without_pid_key] = value + samples[labels][(name, labels)] = value elif metric._multiprocess_mode in ('sum', 'livesum'): - samples[without_pid_key] += value + samples[labels][(name, labels)] += value elif metric._multiprocess_mode in ('mostrecent', 'livemostrecent'): - current_timestamp = sample_timestamps[without_pid_key] + current_timestamp = sample_timestamps[labels][name] timestamp = float(timestamp or 0) if current_timestamp < timestamp: - samples[without_pid_key] = value - sample_timestamps[without_pid_key] = timestamp + samples[labels][(name, labels)] = value + sample_timestamps[labels][name] = timestamp else: # all/liveall - samples[(name, labels)] = value + samples[labels][(name, labels)] = value elif metric.type == 'histogram': # A for loop with early exit is faster than a genexpr @@ -127,10 +137,10 @@ def _accumulate_metrics(metrics, accumulate): break else: # did not find the `le` key # _sum/_count - samples[(name, labels)] += value + samples[labels][(name, labels)] += value else: # Counter and Summary. - samples[(name, labels)] += value + samples[labels][(name, labels)] += value # Accumulate bucket values. if metric.type == 'histogram': @@ -143,14 +153,17 @@ def _accumulate_metrics(metrics, accumulate): ) if accumulate: acc += value - samples[sample_key] = acc + samples[labels][sample_key] = acc else: - samples[sample_key] = value + samples[labels][sample_key] = value if accumulate: - samples[(metric.name + '_count', labels)] = acc + samples[labels][(metric.name + '_count', labels)] = acc # Convert to correct sample format. - metric.samples = [Sample(name_, dict(labels), value) for (name_, labels), value in samples.items()] + metric.samples = [] + for _, samples_by_labels in samples.items(): + for (name_, labels), value in samples_by_labels.items(): + metric.samples.append(Sample(name_, dict(labels), value)) return metrics.values() def collect(self): diff --git a/tests/test_multiprocess.py b/tests/test_multiprocess.py index e7ca154e..c2f71d26 100644 --- a/tests/test_multiprocess.py +++ b/tests/test_multiprocess.py @@ -276,10 +276,8 @@ def add_label(key, value): Sample('g', add_label('pid', '1'), 1.0), ]) - metrics['h'].samples.sort( - key=lambda x: (x[0], float(x[1].get('le', 0))) - ) expected_histogram = [ + Sample('h_sum', labels, 6.0), Sample('h_bucket', add_label('le', '0.005'), 0.0), Sample('h_bucket', add_label('le', '0.01'), 0.0), Sample('h_bucket', add_label('le', '0.025'), 0.0), @@ -296,7 +294,66 @@ def add_label(key, value): Sample('h_bucket', add_label('le', '10.0'), 2.0), Sample('h_bucket', add_label('le', '+Inf'), 2.0), Sample('h_count', labels, 2.0), - Sample('h_sum', labels, 6.0), + ] + + self.assertEqual(metrics['h'].samples, expected_histogram) + + def test_collect_histogram_ordering(self): + pid = 0 + values.ValueClass = MultiProcessValue(lambda: pid) + labels = {i: i for i in 'abcd'} + + def add_label(key, value): + l = labels.copy() + l[key] = value + return l + + h = Histogram('h', 'help', labelnames=['view'], registry=None) + + h.labels(view='view1').observe(1) + + pid = 1 + + h.labels(view='view1').observe(5) + h.labels(view='view2').observe(1) + + metrics = {m.name: m for m in self.collector.collect()} + + expected_histogram = [ + Sample('h_sum', {'view': 'view1'}, 6.0), + Sample('h_bucket', {'view': 'view1', 'le': '0.005'}, 0.0), + Sample('h_bucket', {'view': 'view1', 'le': '0.01'}, 0.0), + Sample('h_bucket', {'view': 'view1', 'le': '0.025'}, 0.0), + Sample('h_bucket', {'view': 'view1', 'le': '0.05'}, 0.0), + Sample('h_bucket', {'view': 'view1', 'le': '0.075'}, 0.0), + Sample('h_bucket', {'view': 'view1', 'le': '0.1'}, 0.0), + Sample('h_bucket', {'view': 'view1', 'le': '0.25'}, 0.0), + Sample('h_bucket', {'view': 'view1', 'le': '0.5'}, 0.0), + Sample('h_bucket', {'view': 'view1', 'le': '0.75'}, 0.0), + Sample('h_bucket', {'view': 'view1', 'le': '1.0'}, 1.0), + Sample('h_bucket', {'view': 'view1', 'le': '2.5'}, 1.0), + Sample('h_bucket', {'view': 'view1', 'le': '5.0'}, 2.0), + Sample('h_bucket', {'view': 'view1', 'le': '7.5'}, 2.0), + Sample('h_bucket', {'view': 'view1', 'le': '10.0'}, 2.0), + Sample('h_bucket', {'view': 'view1', 'le': '+Inf'}, 2.0), + Sample('h_count', {'view': 'view1'}, 2.0), + Sample('h_sum', {'view': 'view2'}, 1.0), + Sample('h_bucket', {'view': 'view2', 'le': '0.005'}, 0.0), + Sample('h_bucket', {'view': 'view2', 'le': '0.01'}, 0.0), + Sample('h_bucket', {'view': 'view2', 'le': '0.025'}, 0.0), + Sample('h_bucket', {'view': 'view2', 'le': '0.05'}, 0.0), + Sample('h_bucket', {'view': 'view2', 'le': '0.075'}, 0.0), + Sample('h_bucket', {'view': 'view2', 'le': '0.1'}, 0.0), + Sample('h_bucket', {'view': 'view2', 'le': '0.25'}, 0.0), + Sample('h_bucket', {'view': 'view2', 'le': '0.5'}, 0.0), + Sample('h_bucket', {'view': 'view2', 'le': '0.75'}, 0.0), + Sample('h_bucket', {'view': 'view2', 'le': '1.0'}, 1.0), + Sample('h_bucket', {'view': 'view2', 'le': '2.5'}, 1.0), + Sample('h_bucket', {'view': 'view2', 'le': '5.0'}, 1.0), + Sample('h_bucket', {'view': 'view2', 'le': '7.5'}, 1.0), + Sample('h_bucket', {'view': 'view2', 'le': '10.0'}, 1.0), + Sample('h_bucket', {'view': 'view2', 'le': '+Inf'}, 1.0), + Sample('h_count', {'view': 'view2'}, 1.0), ] self.assertEqual(metrics['h'].samples, expected_histogram) @@ -347,10 +404,8 @@ def add_label(key, value): m.name: m for m in self.collector.merge(files, accumulate=False) } - metrics['h'].samples.sort( - key=lambda x: (x[0], float(x[1].get('le', 0))) - ) expected_histogram = [ + Sample('h_sum', labels, 6.0), Sample('h_bucket', add_label('le', '0.005'), 0.0), Sample('h_bucket', add_label('le', '0.01'), 0.0), Sample('h_bucket', add_label('le', '0.025'), 0.0), @@ -366,7 +421,6 @@ def add_label(key, value): Sample('h_bucket', add_label('le', '7.5'), 0.0), Sample('h_bucket', add_label('le', '10.0'), 0.0), Sample('h_bucket', add_label('le', '+Inf'), 0.0), - Sample('h_sum', labels, 6.0), ] self.assertEqual(metrics['h'].samples, expected_histogram) From 13df12421e1ba9c621246b9084229e24fda4074e Mon Sep 17 00:00:00 2001 From: Colin Watson Date: Wed, 26 Nov 2025 19:41:33 +0000 Subject: [PATCH 29/38] Relax registry type annotations for exposition (#1149) * Turn Collector into a Protocol We require Python >= 3.9 now, so there's no reason to avoid this any more. Signed-off-by: Colin Watson * Relax registry type annotations for exposition Anything with a suitable `collect` method will do: for instance, it's sometimes useful to be able to define a class whose `collect` method yields all metrics from a registry whose names have a given prefix, and such a class doesn't need to inherit from `CollectorRegistry`. Signed-off-by: Colin Watson --------- Signed-off-by: Colin Watson --- prometheus_client/aiohttp/exposition.py | 4 ++-- prometheus_client/asgi.py | 4 ++-- prometheus_client/bridge/graphite.py | 4 ++-- prometheus_client/exposition.py | 28 ++++++++++++------------- prometheus_client/registry.py | 13 +++++------- 5 files changed, 25 insertions(+), 28 deletions(-) diff --git a/prometheus_client/aiohttp/exposition.py b/prometheus_client/aiohttp/exposition.py index 914fb26f..c1ae254d 100644 --- a/prometheus_client/aiohttp/exposition.py +++ b/prometheus_client/aiohttp/exposition.py @@ -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.""" diff --git a/prometheus_client/asgi.py b/prometheus_client/asgi.py index affd9844..6e527ca9 100644 --- a/prometheus_client/asgi.py +++ b/prometheus_client/asgi.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): diff --git a/prometheus_client/bridge/graphite.py b/prometheus_client/bridge/graphite.py index 8cadbedc..235324b2 100755 --- a/prometheus_client/bridge/graphite.py +++ b/prometheus_client/bridge/graphite.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, diff --git a/prometheus_client/exposition.py b/prometheus_client/exposition.py index 0d471707..9cb74faa 100644 --- a/prometheus_client/exposition.py +++ b/prometheus_client/exposition.py @@ -19,7 +19,7 @@ from wsgiref.simple_server import make_server, WSGIRequestHandler, WSGIServer from .openmetrics import exposition as openmetrics -from .registry import CollectorRegistry, REGISTRY +from .registry import Collector, REGISTRY from .utils import floatToGoString, parse_version __all__ = ( @@ -118,7 +118,7 @@ def _bake_output(registry, accept_header, accept_encoding_header, params, disabl return '200 OK', headers, output -def make_wsgi_app(registry: CollectorRegistry = REGISTRY, disable_compression: bool = False) -> Callable: +def make_wsgi_app(registry: Collector = REGISTRY, disable_compression: bool = False) -> Callable: """Create a WSGI app which serves the metrics from a registry.""" def prometheus_app(environ, start_response): @@ -223,7 +223,7 @@ def _get_ssl_ctx( def start_wsgi_server( port: int, addr: str = '0.0.0.0', - registry: CollectorRegistry = REGISTRY, + registry: Collector = REGISTRY, certfile: Optional[str] = None, keyfile: Optional[str] = None, client_cafile: Optional[str] = None, @@ -252,12 +252,12 @@ class TmpServer(ThreadingWSGIServer): start_http_server = start_wsgi_server -def generate_latest(registry: CollectorRegistry = REGISTRY, escaping: str = openmetrics.UNDERSCORES) -> bytes: +def generate_latest(registry: Collector = REGISTRY, escaping: str = openmetrics.UNDERSCORES) -> bytes: """ Generates the exposition format using the basic Prometheus text format. Params: - registry: CollectorRegistry to export data from. + registry: Collector to export data from. escaping: Escaping scheme used for metric and label names. Returns: UTF-8 encoded string containing the metrics in text format. @@ -330,7 +330,7 @@ def sample_line(samples): return ''.join(output).encode('utf-8') -def choose_encoder(accept_header: str) -> Tuple[Callable[[CollectorRegistry], bytes], str]: +def choose_encoder(accept_header: str) -> Tuple[Callable[[Collector], bytes], str]: # Python client library accepts a narrower range of content-types than # Prometheus does. accept_header = accept_header or '' @@ -408,7 +408,7 @@ def gzip_accepted(accept_encoding_header: str) -> bool: class MetricsHandler(BaseHTTPRequestHandler): """HTTP handler that gives metrics from ``REGISTRY``.""" - registry: CollectorRegistry = REGISTRY + registry: Collector = REGISTRY def do_GET(self) -> None: # Prepare parameters @@ -429,7 +429,7 @@ def log_message(self, format: str, *args: Any) -> None: """Log nothing.""" @classmethod - def factory(cls, registry: CollectorRegistry) -> type: + def factory(cls, registry: Collector) -> type: """Returns a dynamic MetricsHandler class tied to the passed registry. """ @@ -444,7 +444,7 @@ def factory(cls, registry: CollectorRegistry) -> type: return MyMetricsHandler -def write_to_textfile(path: str, registry: CollectorRegistry, escaping: str = openmetrics.ALLOWUTF8, tmpdir: Optional[str] = None) -> None: +def write_to_textfile(path: str, registry: Collector, escaping: str = openmetrics.ALLOWUTF8, tmpdir: Optional[str] = None) -> None: """Write metrics to the given path. This is intended for use with the Node exporter textfile collector. @@ -592,7 +592,7 @@ def tls_auth_handler( def push_to_gateway( gateway: str, job: str, - registry: CollectorRegistry, + registry: Collector, grouping_key: Optional[Dict[str, Any]] = None, timeout: Optional[float] = 30, handler: Callable = default_handler, @@ -603,7 +603,7 @@ def push_to_gateway( 'http://pushgateway.local', or 'pushgateway.local'. Scheme defaults to 'http' if none is provided `job` is the job label to be attached to all pushed metrics - `registry` is an instance of CollectorRegistry + `registry` is a Collector, normally an instance of CollectorRegistry `grouping_key` please see the pushgateway documentation for details. Defaults to None `timeout` is how long push will attempt to connect before giving up. @@ -641,7 +641,7 @@ def push_to_gateway( def pushadd_to_gateway( gateway: str, job: str, - registry: Optional[CollectorRegistry], + registry: Optional[Collector], grouping_key: Optional[Dict[str, Any]] = None, timeout: Optional[float] = 30, handler: Callable = default_handler, @@ -652,7 +652,7 @@ def pushadd_to_gateway( 'http://pushgateway.local', or 'pushgateway.local'. Scheme defaults to 'http' if none is provided `job` is the job label to be attached to all pushed metrics - `registry` is an instance of CollectorRegistry + `registry` is a Collector, normally an instance of CollectorRegistry `grouping_key` please see the pushgateway documentation for details. Defaults to None `timeout` is how long push will attempt to connect before giving up. @@ -702,7 +702,7 @@ def _use_gateway( method: str, gateway: str, job: str, - registry: Optional[CollectorRegistry], + registry: Optional[Collector], grouping_key: Optional[Dict[str, Any]], timeout: Optional[float], handler: Callable, diff --git a/prometheus_client/registry.py b/prometheus_client/registry.py index 8de4ce91..9934117d 100644 --- a/prometheus_client/registry.py +++ b/prometheus_client/registry.py @@ -1,24 +1,21 @@ -from abc import ABC, abstractmethod import copy from threading import Lock -from typing import Dict, Iterable, List, Optional +from typing import Dict, Iterable, List, Optional, Protocol from .metrics_core import Metric -# Ideally this would be a Protocol, but Protocols are only available in Python >= 3.8. -class Collector(ABC): - @abstractmethod +class Collector(Protocol): def collect(self) -> Iterable[Metric]: - pass + """Collect metrics.""" -class _EmptyCollector(Collector): +class _EmptyCollector: def collect(self) -> Iterable[Metric]: return [] -class CollectorRegistry(Collector): +class CollectorRegistry: """Metric collector registry. Collectors must have a no-argument method 'collect' that returns a list of From 7b9959209492c06968785c66bc6ea2316d156f91 Mon Sep 17 00:00:00 2001 From: ritesh-avesha <104001014+ritesh-avesha@users.noreply.github.com> Date: Fri, 12 Dec 2025 22:30:45 +0530 Subject: [PATCH 30/38] Added compression support in pushgateway (#1144) * feat(): Added compression support in pushgateway Signed-off-by: ritesh-avesha * fix(): Incorporated changes for PR review comments Signed-off-by: ritesh-avesha * fix(): Incorporated changes for PR review comments, lint issues Signed-off-by: ritesh-avesha * fix(): lint issues Signed-off-by: ritesh-avesha --------- Signed-off-by: ritesh-avesha --- docs/content/exporting/pushgateway.md | 14 ++++++ prometheus_client/exposition.py | 66 +++++++++++++++++++++++---- tests/test_exposition.py | 25 ++++++++++ tox.ini | 1 + 4 files changed, 96 insertions(+), 10 deletions(-) diff --git a/docs/content/exporting/pushgateway.md b/docs/content/exporting/pushgateway.md index bf5eb112..d9f9a945 100644 --- a/docs/content/exporting/pushgateway.md +++ b/docs/content/exporting/pushgateway.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 diff --git a/prometheus_client/exposition.py b/prometheus_client/exposition.py index 9cb74faa..ca06d916 100644 --- a/prometheus_client/exposition.py +++ b/prometheus_client/exposition.py @@ -9,7 +9,9 @@ import ssl import sys import threading -from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, Union +from typing import ( + Any, Callable, Dict, List, Literal, Optional, Sequence, Tuple, Union, +) from urllib.error import HTTPError from urllib.parse import parse_qs, quote_plus, urlparse from urllib.request import ( @@ -22,6 +24,13 @@ from .registry import Collector, REGISTRY from .utils import floatToGoString, parse_version +try: + import snappy # type: ignore + SNAPPY_AVAILABLE = True +except ImportError: + snappy = None # type: ignore + SNAPPY_AVAILABLE = False + __all__ = ( 'CONTENT_TYPE_LATEST', 'CONTENT_TYPE_PLAIN_0_0_4', @@ -46,6 +55,7 @@ """Content type of the latest format""" CONTENT_TYPE_LATEST = CONTENT_TYPE_PLAIN_1_0_0 +CompressionType = Optional[Literal['gzip', 'snappy']] class _PrometheusRedirectHandler(HTTPRedirectHandler): @@ -596,6 +606,7 @@ def push_to_gateway( grouping_key: Optional[Dict[str, Any]] = None, timeout: Optional[float] = 30, handler: Callable = default_handler, + compression: CompressionType = None, ) -> None: """Push metrics to the given pushgateway. @@ -632,10 +643,12 @@ def push_to_gateway( failure. 'content' is the data which should be used to form the HTTP Message Body. + `compression` selects the payload compression. Supported values are 'gzip' + and 'snappy'. Defaults to None (no compression). This overwrites all metrics with the same job and grouping_key. This uses the PUT HTTP method.""" - _use_gateway('PUT', gateway, job, registry, grouping_key, timeout, handler) + _use_gateway('PUT', gateway, job, registry, grouping_key, timeout, handler, compression) def pushadd_to_gateway( @@ -645,6 +658,7 @@ def pushadd_to_gateway( grouping_key: Optional[Dict[str, Any]] = None, timeout: Optional[float] = 30, handler: Callable = default_handler, + compression: CompressionType = None, ) -> None: """PushAdd metrics to the given pushgateway. @@ -663,10 +677,12 @@ def pushadd_to_gateway( will be carried out by a default handler. See the 'prometheus_client.push_to_gateway' documentation for implementation requirements. + `compression` selects the payload compression. Supported values are 'gzip' + and 'snappy'. Defaults to None (no compression). This replaces metrics with the same name, job and grouping_key. This uses the POST HTTP method.""" - _use_gateway('POST', gateway, job, registry, grouping_key, timeout, handler) + _use_gateway('POST', gateway, job, registry, grouping_key, timeout, handler, compression) def delete_from_gateway( @@ -706,6 +722,7 @@ def _use_gateway( grouping_key: Optional[Dict[str, Any]], timeout: Optional[float], handler: Callable, + compression: CompressionType = None, ) -> None: gateway_url = urlparse(gateway) # See https://bugs.python.org/issue27657 for details on urlparse in py>=3.7.6. @@ -715,24 +732,53 @@ def _use_gateway( gateway = gateway.rstrip('/') url = '{}/metrics/{}/{}'.format(gateway, *_escape_grouping_key("job", job)) - data = b'' - if method != 'DELETE': - if registry is None: - registry = REGISTRY - data = generate_latest(registry) - if grouping_key is None: grouping_key = {} url += ''.join( '/{}/{}'.format(*_escape_grouping_key(str(k), str(v))) for k, v in sorted(grouping_key.items())) + data = b'' + headers: List[Tuple[str, str]] = [] + if method != 'DELETE': + if registry is None: + registry = REGISTRY + data = generate_latest(registry) + data, headers = _compress_payload(data, compression) + else: + # DELETE requests still need Content-Type header per test expectations + headers = [('Content-Type', CONTENT_TYPE_PLAIN_0_0_4)] + if compression is not None: + raise ValueError('Compression is not supported for DELETE requests.') + handler( url=url, method=method, timeout=timeout, - headers=[('Content-Type', CONTENT_TYPE_PLAIN_0_0_4)], data=data, + headers=headers, data=data, )() +def _compress_payload(data: bytes, compression: CompressionType) -> Tuple[bytes, List[Tuple[str, str]]]: + headers = [('Content-Type', CONTENT_TYPE_PLAIN_0_0_4)] + if compression is None: + return data, headers + + encoding = compression.lower() + if encoding == 'gzip': + headers.append(('Content-Encoding', 'gzip')) + return gzip.compress(data), headers + if encoding == 'snappy': + if not SNAPPY_AVAILABLE: + raise RuntimeError('Snappy compression requires the python-snappy package to be installed.') + headers.append(('Content-Encoding', 'snappy')) + compressor = snappy.StreamCompressor() + compressed = compressor.compress(data) + flush = getattr(compressor, 'flush', None) + if callable(flush): + compressed += flush() + return compressed, headers + raise ValueError(f"Unsupported compression type: {compression}") + + def _escape_grouping_key(k, v): if v == "": # Per https://github.com/prometheus/pushgateway/pull/346. diff --git a/tests/test_exposition.py b/tests/test_exposition.py index 3dd5e378..aceff738 100644 --- a/tests/test_exposition.py +++ b/tests/test_exposition.py @@ -1,3 +1,4 @@ +import gzip from http.server import BaseHTTPRequestHandler, HTTPServer import os import threading @@ -404,6 +405,30 @@ def test_push_with_trailing_slash(self): self.assertNotIn('//', self.requests[0][0].path) + def test_push_with_gzip_compression(self): + push_to_gateway(self.address, "my_job", self.registry, compression='gzip') + request, body = self.requests[0] + self.assertEqual(request.headers.get('content-encoding'), 'gzip') + decompressed = gzip.decompress(body) + self.assertEqual(decompressed, b'# HELP g help\n# TYPE g gauge\ng 0.0\n') + + def test_push_with_snappy_compression(self): + snappy = pytest.importorskip('snappy') + push_to_gateway(self.address, "my_job", self.registry, compression='snappy') + request, body = self.requests[0] + self.assertEqual(request.headers.get('content-encoding'), 'snappy') + decompressor = snappy.StreamDecompressor() + decompressed = decompressor.decompress(body) + flush = getattr(decompressor, 'flush', None) + if callable(flush): + decompressed += flush() + self.assertEqual(decompressed, b'# HELP g help\n# TYPE g gauge\ng 0.0\n') + + def test_push_with_invalid_compression(self): + with self.assertRaisesRegex(ValueError, 'Unsupported compression type'): + push_to_gateway(self.address, "my_job", self.registry, compression='brotli') + self.assertEqual(self.requests, []) + def test_instance_ip_grouping_key(self): self.assertTrue('' != instance_ip_grouping_key()['instance']) diff --git a/tox.ini b/tox.ini index ccf95cc2..45a6baf3 100644 --- a/tox.ini +++ b/tox.ini @@ -10,6 +10,7 @@ deps = attrs {py3.9,pypy3.9}: twisted {py3.9,pypy3.9}: aiohttp + {py3.9}: python-snappy commands = coverage run --parallel -m pytest {posargs} [testenv:py3.9-nooptionals] From e1cdc203b1cf5f15c7b9a64d79fccc7907a62ca3 Mon Sep 17 00:00:00 2001 From: Julie Rymer Date: Mon, 5 Jan 2026 22:59:43 +0100 Subject: [PATCH 31/38] Add Django exporter (#1088) (#1143) Signed-off-by: Julie Rymer --- docs/content/exporting/http/django.md | 47 +++++++++++++++++++++++++ mypy.ini | 2 +- prometheus_client/django/__init__.py | 5 +++ prometheus_client/django/exposition.py | 44 +++++++++++++++++++++++ pyproject.toml | 3 ++ tests/test_django.py | 48 ++++++++++++++++++++++++++ tox.ini | 1 + 7 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 docs/content/exporting/http/django.md create mode 100644 prometheus_client/django/__init__.py create mode 100644 prometheus_client/django/exposition.py create mode 100644 tests/test_django.py diff --git a/docs/content/exporting/http/django.md b/docs/content/exporting/http/django.md new file mode 100644 index 00000000..a900a3a2 --- /dev/null +++ b/docs/content/exporting/http/django.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. diff --git a/mypy.ini b/mypy.ini index fe372d07..3aa142c1 100644 --- a/mypy.ini +++ b/mypy.ini @@ -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 diff --git a/prometheus_client/django/__init__.py b/prometheus_client/django/__init__.py new file mode 100644 index 00000000..280dbfb0 --- /dev/null +++ b/prometheus_client/django/__init__.py @@ -0,0 +1,5 @@ +from .exposition import PrometheusDjangoView + +__all__ = [ + "PrometheusDjangoView", +] diff --git a/prometheus_client/django/exposition.py b/prometheus_client/django/exposition.py new file mode 100644 index 00000000..085e8fcf --- /dev/null +++ b/prometheus_client/django/exposition.py @@ -0,0 +1,44 @@ +import os + +from django.http import HttpResponse +from django.views import View + +import prometheus_client +from prometheus_client import multiprocess +from prometheus_client.exposition import _bake_output +from prometheus_client.registry import registry + + +class PrometheusDjangoView(View): + multiprocess_mode: bool = "PROMETHEUS_MULTIPROC_DIR" in os.environ or "prometheus_multiproc_dir" in os.environ + registry: prometheus_client.CollectorRegistry = None + + def get(self, request, *args, **kwargs): + if self.registry is None: + if self.multiprocess_mode: + self.registry = prometheus_client.CollectorRegistry() + multiprocess.MultiProcessCollector(registry) + else: + self.registry = prometheus_client.REGISTRY + accept_header = request.headers.get("Accept") + accept_encoding_header = request.headers.get("Accept-Encoding") + # Bake output + status, headers, output = _bake_output( + registry=self.registry, + accept_header=accept_header, + accept_encoding_header=accept_encoding_header, + params=request.GET, + disable_compression=False, + ) + status = int(status.split(" ")[0]) + return HttpResponse( + output, + status=status, + headers=headers, + ) + + def options(self, request, *args, **kwargs): + return HttpResponse( + status=200, + headers={"Allow": "OPTIONS,GET"}, + ) diff --git a/pyproject.toml b/pyproject.toml index 1d8527a0..3961482f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -47,6 +47,9 @@ twisted = [ aiohttp = [ "aiohttp", ] +django = [ + "django", +] [project.urls] Homepage = "https://github.com/prometheus/client_python" diff --git a/tests/test_django.py b/tests/test_django.py new file mode 100644 index 00000000..659bb3f6 --- /dev/null +++ b/tests/test_django.py @@ -0,0 +1,48 @@ +from unittest import skipUnless + +from prometheus_client import CollectorRegistry, Counter, generate_latest +from prometheus_client.openmetrics.exposition import ALLOWUTF8 + +try: + import django + from django.test import RequestFactory, TestCase + + from prometheus_client.django import PrometheusDjangoView + + HAVE_DJANGO = True +except ImportError: + from unittest import TestCase + + HAVE_DJANGO = False + +else: + from django.conf import settings + + if not settings.configured: + settings.configure( + DATABASES={ + "default": { + "ENGINE": "django.db.backends.sqlite3", + 'NAME': ':memory:' + } + }, + INSTALLED_APPS=[], + ) + django.setup() + + +class MetricsResourceTest(TestCase): + @skipUnless(HAVE_DJANGO, "Don't have django installed.") + def setUp(self): + self.registry = CollectorRegistry() + self.factory = RequestFactory() + + def test_reports_metrics(self): + c = Counter('cc', 'A counter', registry=self.registry) + c.inc() + + request = self.factory.get("/metrics") + + response = PrometheusDjangoView.as_view(registry=self.registry)(request) + self.assertEqual(response.status_code, 200) + self.assertEqual(response.content, generate_latest(self.registry, ALLOWUTF8)) diff --git a/tox.ini b/tox.ini index 45a6baf3..992bd0a7 100644 --- a/tox.ini +++ b/tox.ini @@ -10,6 +10,7 @@ deps = attrs {py3.9,pypy3.9}: twisted {py3.9,pypy3.9}: aiohttp + {py3.9,pypy3.9}: django {py3.9}: python-snappy commands = coverage run --parallel -m pytest {posargs} From c5024d310fbfcba45a5e9db62e337a3a7930ea16 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Mon, 12 Jan 2026 13:10:03 -0700 Subject: [PATCH 32/38] Release 0.24.0 Signed-off-by: Chris Marchbanks --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 3961482f..d45ef12d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "prometheus_client" -version = "0.23.1" +version = "0.24.0" description = "Python client for the Prometheus monitoring system." readme = "README.md" license = "Apache-2.0 AND BSD-2-Clause" From 6f0e967c1f7a408b75861d6833a8d303874be95d Mon Sep 17 00:00:00 2001 From: Jelle van der Waa Date: Wed, 14 Jan 2026 16:23:36 +0100 Subject: [PATCH 33/38] Pass correct registry to MultiProcessCollector (#1152) `registry` does not exists in prometheus_client.registry, as that causes an ImportError the test was skipped in the 3.9 scenario. Signed-off-by: Jelle van der Waa --- prometheus_client/django/exposition.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/prometheus_client/django/exposition.py b/prometheus_client/django/exposition.py index 085e8fcf..71fc8d8a 100644 --- a/prometheus_client/django/exposition.py +++ b/prometheus_client/django/exposition.py @@ -6,7 +6,6 @@ import prometheus_client from prometheus_client import multiprocess from prometheus_client.exposition import _bake_output -from prometheus_client.registry import registry class PrometheusDjangoView(View): @@ -17,7 +16,7 @@ def get(self, request, *args, **kwargs): if self.registry is None: if self.multiprocess_mode: self.registry = prometheus_client.CollectorRegistry() - multiprocess.MultiProcessCollector(registry) + multiprocess.MultiProcessCollector(self.registry) else: self.registry = prometheus_client.REGISTRY accept_header = request.headers.get("Accept") From f417f6ea8f058165a1934e368fed245e91aafc14 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Wed, 14 Jan 2026 08:24:50 -0700 Subject: [PATCH 34/38] Release 0.24.1 Signed-off-by: Chris Marchbanks --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index d45ef12d..ed3ef389 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "prometheus_client" -version = "0.24.0" +version = "0.24.1" description = "Python client for the Prometheus monitoring system." readme = "README.md" license = "Apache-2.0 AND BSD-2-Clause" From a8541354519d04852d24688845f1d2d495eef59c Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Wed, 21 Jan 2026 16:41:10 -0700 Subject: [PATCH 35/38] Migrate to Github Actions (#1153) * Migrate to Github Actions * Pin github actions versions --------- Signed-off-by: Chris Marchbanks --- .circleci/config.yml | 93 ----------------------- .github/workflows/ci.yaml | 110 ++++++++++++++++++++++++++++ .github/workflows/github-pages.yaml | 18 +++-- 3 files changed, 121 insertions(+), 100 deletions(-) delete mode 100644 .circleci/config.yml create mode 100644 .github/workflows/ci.yaml diff --git a/.circleci/config.yml b/.circleci/config.yml deleted file mode 100644 index f29bd265..00000000 --- a/.circleci/config.yml +++ /dev/null @@ -1,93 +0,0 @@ ---- -version: 2.1 - -executors: - python: - docker: - - image: cimg/python:3.9 - -jobs: - flake8_lint: - executor: python - steps: - - checkout - - run: pip install tox - - run: tox -e flake8 - isort_lint: - executor: python - steps: - - checkout - - run: pip install tox - - run: tox -e isort - mypy_lint: - executor: python - steps: - - checkout - - run: pip install tox - - run: tox -e mypy - test: - parameters: - python: - type: string - docker: - - image: cimg/python:<< parameters.python >> - environment: - TOXENV: "py<< parameters.python >>" - steps: - - checkout - - run: echo 'export PATH=$HOME/.local/bin:$PATH' >> $BASH_ENV - - run: pip install --user tox "virtualenv<20.22.0" - - run: tox - test_nooptionals: - parameters: - python: - type: string - docker: - - image: cimg/python:<< parameters.python >> - environment: - TOXENV: "py<< parameters.python >>-nooptionals" - steps: - - checkout - - run: pip install tox - - run: tox - test_pypy: - parameters: - python: - type: string - docker: - - image: pypy:<< parameters.python >> - environment: - TOXENV: "pypy<< parameters.python >>" - steps: - - checkout - - run: pip install tox - - run: tox - - -workflows: - version: 2 - client_python: - jobs: - - flake8_lint - - isort_lint - - mypy_lint - - test: - matrix: - parameters: - python: - - "3.9.18" - - "3.10" - - "3.11" - - "3.12" - - "3.13" - - "3.14" - - test_nooptionals: - matrix: - parameters: - python: - - "3.9" - - test_pypy: - matrix: - parameters: - python: - - "3.9" diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml new file mode 100644 index 00000000..a7e4e094 --- /dev/null +++ b/.github/workflows/ci.yaml @@ -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 }} diff --git a/.github/workflows/github-pages.yaml b/.github/workflows/github-pages.yaml index 621f2d73..d8db8cbc 100644 --- a/.github/workflows/github-pages.yaml +++ b/.github/workflows/github-pages.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 From 1cf53feae63b6ecb0bd76eee80582a0fba957e09 Mon Sep 17 00:00:00 2001 From: Varun Chawla <34209028+veeceey@users.noreply.github.com> Date: Mon, 9 Feb 2026 07:04:33 -0800 Subject: [PATCH 36/38] Fix server shutdown documentation (#1155) Add server.server_close() call to shutdown example to properly release the port. Without this call, attempting to restart the server on the same port results in "Address already in use" error. Fixes #1068 Signed-off-by: Varun Chawla --- docs/content/exporting/http/_index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/content/exporting/http/_index.md b/docs/content/exporting/http/_index.md index dc1b8f2c..f7a6aac6 100644 --- a/docs/content/exporting/http/_index.md +++ b/docs/content/exporting/http/_index.md @@ -24,6 +24,7 @@ to shutdown the server gracefully: ```python server, t = start_http_server(8000) server.shutdown() +server.server_close() t.join() ``` From 671f75c6f1f04838995fadd57cda21beee01838b Mon Sep 17 00:00:00 2001 From: Varun Chawla <34209028+veeceey@users.noreply.github.com> Date: Mon, 9 Feb 2026 08:05:29 -0800 Subject: [PATCH 37/38] Fix spaces in grouping key values for push_to_gateway (#1156) Use base64 encoding for grouping key values containing spaces, similar to how values with slashes are handled. This prevents spaces from being converted to '+' signs by quote_plus(). Fixes #1064 Signed-off-by: Varun Chawla --- prometheus_client/exposition.py | 3 ++- tests/test_exposition.py | 7 +++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/prometheus_client/exposition.py b/prometheus_client/exposition.py index ca06d916..2d402a0f 100644 --- a/prometheus_client/exposition.py +++ b/prometheus_client/exposition.py @@ -783,8 +783,9 @@ def _escape_grouping_key(k, v): if v == "": # Per https://github.com/prometheus/pushgateway/pull/346. return k + "@base64", "=" - elif '/' in v: + elif '/' in v or ' ' in v: # Added in Pushgateway 0.9.0. + # Use base64 encoding for values containing slashes or spaces return k + "@base64", base64.urlsafe_b64encode(v.encode("utf-8")).decode("utf-8") else: return k, quote_plus(v) diff --git a/tests/test_exposition.py b/tests/test_exposition.py index aceff738..a3c97820 100644 --- a/tests/test_exposition.py +++ b/tests/test_exposition.py @@ -301,6 +301,13 @@ def test_push_with_groupingkey_empty_label(self): self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') + def test_push_with_groupingkey_with_spaces(self): + push_to_gateway(self.address, "my_job", self.registry, {'label': 'value with spaces'}) + self.assertEqual(self.requests[0][0].command, 'PUT') + self.assertEqual(self.requests[0][0].path, '/metrics/job/my_job/label@base64/dmFsdWUgd2l0aCBzcGFjZXM=') + self.assertEqual(self.requests[0][0].headers.get('content-type'), CONTENT_TYPE_PLAIN_0_0_4) + self.assertEqual(self.requests[0][1], b'# HELP g help\n# TYPE g gauge\ng 0.0\n') + def test_push_with_complex_groupingkey(self): push_to_gateway(self.address, "my_job", self.registry, {'a': 9, 'b': 'a/ z'}) self.assertEqual(self.requests[0][0].command, 'PUT') From 8673912276bdca7ddbca5d163eb11422b546bffb Mon Sep 17 00:00:00 2001 From: Mathias Kende Date: Wed, 18 Feb 2026 21:56:45 +0100 Subject: [PATCH 38/38] Support MultiProcessCollector in RestrictedRegistry. (#1150) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Support MultiProcessCollector in RestrictedRegistry. This change makes it so that the RestrictedRegistry will always attempt to collect metrics from a collector for which it couldn’t find any metrics name. Although this can be used generally, this is meant to be used with MultiProcessCollector. This changes the current behavior of the code but should be somehow safe as it enables filtering in case where it was not working previously. If this is an issue, an alternative approach with an explicit flag could be used (set either in the MultiProcessCollector or in the registry). The intent here is to allow collecting a subset of metrics from production fastapi servers (running in multiprocess mode). So not having to change the library usage in these servers is advantageous to have filtering work out-of-the-box with this change. Signed-off-by: Mathias Kende * Make the new support for collectors without names be explicit. This adds a parameters to the constructor of CollectorRegistry to allow that new behavior rather than make it be the default. Signed-off-by: Mathias Kende * Fix comments Signed-off-by: Mathias Kende --------- Signed-off-by: Mathias Kende --- docs/content/multiprocess/_index.md | 7 +++++-- prometheus_client/registry.py | 9 +++++++-- tests/test_asgi.py | 29 +++++++++++++++++++++++++++ tests/test_core.py | 18 +++++++++++++++++ tests/test_multiprocess.py | 31 ++++++++++++++++++++++++++++- 5 files changed, 89 insertions(+), 5 deletions(-) diff --git a/docs/content/multiprocess/_index.md b/docs/content/multiprocess/_index.md index 33507cd9..42ea6a67 100644 --- a/docs/content/multiprocess/_index.md +++ b/docs/content/multiprocess/_index.md @@ -10,9 +10,12 @@ it's common to have processes rather than threads to handle large workloads. To handle this the client library can be put in multiprocess mode. This comes with a number of limitations: -- Registries can not be used as normal, all instantiated metrics are exported +- Registries can not be used as normal: + - all instantiated metrics are collected - Registering metrics to a registry later used by a `MultiProcessCollector` may cause duplicate metrics to be exported + - Filtering on metrics works if and only if the constructor was called with + `support_collectors_without_names=True` and it but might be inefficient. - Custom collectors do not work (e.g. cpu and memory metrics) - Gauges cannot use `set_function` - Info and Enum metrics do not work @@ -49,7 +52,7 @@ MY_COUNTER = Counter('my_counter', 'Description of my counter') # Expose metrics. def app(environ, start_response): - registry = CollectorRegistry() + registry = CollectorRegistry(support_collectors_without_names=True) multiprocess.MultiProcessCollector(registry) data = generate_latest(registry) status = '200 OK' diff --git a/prometheus_client/registry.py b/prometheus_client/registry.py index 9934117d..c2b55d15 100644 --- a/prometheus_client/registry.py +++ b/prometheus_client/registry.py @@ -23,12 +23,15 @@ class CollectorRegistry: exposition formats. """ - def __init__(self, auto_describe: bool = False, target_info: Optional[Dict[str, str]] = None): + def __init__(self, auto_describe: bool = False, target_info: Optional[Dict[str, str]] = None, + support_collectors_without_names: bool = False): self._collector_to_names: Dict[Collector, List[str]] = {} self._names_to_collectors: Dict[str, Collector] = {} self._auto_describe = auto_describe self._lock = Lock() self._target_info: Optional[Dict[str, str]] = {} + self._support_collectors_without_names = support_collectors_without_names + self._collectors_without_names: List[Collector] = [] self.set_target_info(target_info) def register(self, collector: Collector) -> None: @@ -43,6 +46,8 @@ def register(self, collector: Collector) -> None: for name in names: self._names_to_collectors[name] = collector self._collector_to_names[collector] = names + if self._support_collectors_without_names and not names: + self._collectors_without_names.append(collector) def unregister(self, collector: Collector) -> None: """Remove a collector from the registry.""" @@ -145,7 +150,7 @@ def __init__(self, names: Iterable[str], registry: CollectorRegistry): self._registry = registry def collect(self) -> Iterable[Metric]: - collectors = set() + collectors = set(self._registry._collectors_without_names) target_info_metric = None with self._registry._lock: if 'target_info' in self._name_set and self._registry._target_info: diff --git a/tests/test_asgi.py b/tests/test_asgi.py index d4933cec..6e795e21 100644 --- a/tests/test_asgi.py +++ b/tests/test_asgi.py @@ -223,3 +223,32 @@ def test_qs_parsing(self): asyncio.new_event_loop().run_until_complete( self.communicator.wait() ) + + def test_qs_parsing_multi(self): + """Only metrics that match the 'name[]' query string param appear""" + + app = make_asgi_app(self.registry) + metrics = [ + ("asdf", "first test metric", 1), + ("bsdf", "second test metric", 2), + ("csdf", "third test metric", 3) + ] + + for m in metrics: + self.increment_metrics(*m) + + self.seed_app(app) + self.scope['query_string'] = "&".join([f"name[]={m[0]}_total" for m in metrics[0:2]]).encode("utf-8") + self.send_default_request() + + outputs = self.get_all_output() + response_body = outputs[1] + output = response_body['body'].decode('utf8') + + self.assert_metrics(output, *metrics[0]) + self.assert_metrics(output, *metrics[1]) + self.assert_not_metrics(output, *metrics[2]) + + asyncio.new_event_loop().run_until_complete( + self.communicator.wait() + ) diff --git a/tests/test_core.py b/tests/test_core.py index c7c9c14f..66492c6f 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -1024,6 +1024,24 @@ def test_restricted_registry_does_not_call_extra(self): self.assertEqual([m], list(registry.restricted_registry(['s_sum']).collect())) mock_collector.collect.assert_not_called() + def test_restricted_registry_ignore_no_names_collectors(self): + from unittest.mock import MagicMock + registry = CollectorRegistry() + mock_collector = MagicMock() + mock_collector.describe.return_value = [] + registry.register(mock_collector) + self.assertEqual(list(registry.restricted_registry(['metric']).collect()), []) + mock_collector.collect.assert_not_called() + + def test_restricted_registry_collects_no_names_collectors(self): + from unittest.mock import MagicMock + registry = CollectorRegistry(support_collectors_without_names=True) + mock_collector = MagicMock() + mock_collector.describe.return_value = [] + registry.register(mock_collector) + self.assertEqual(list(registry.restricted_registry(['metric']).collect()), []) + mock_collector.collect.assert_called() + def test_restricted_registry_does_not_yield_while_locked(self): registry = CollectorRegistry(target_info={'foo': 'bar'}) Summary('s', 'help', registry=registry).observe(7) diff --git a/tests/test_multiprocess.py b/tests/test_multiprocess.py index c2f71d26..ee0c7423 100644 --- a/tests/test_multiprocess.py +++ b/tests/test_multiprocess.py @@ -52,7 +52,7 @@ def setUp(self): self.tempdir = tempfile.mkdtemp() os.environ['PROMETHEUS_MULTIPROC_DIR'] = self.tempdir values.ValueClass = MultiProcessValue(lambda: 123) - self.registry = CollectorRegistry() + self.registry = CollectorRegistry(support_collectors_without_names=True) self.collector = MultiProcessCollector(self.registry) @property @@ -358,6 +358,35 @@ def add_label(key, value): self.assertEqual(metrics['h'].samples, expected_histogram) + def test_restrict(self): + pid = 0 + values.ValueClass = MultiProcessValue(lambda: pid) + labels = {i: i for i in 'abcd'} + + def add_label(key, value): + l = labels.copy() + l[key] = value + return l + + c = Counter('c', 'help', labelnames=labels.keys(), registry=None) + g = Gauge('g', 'help', labelnames=labels.keys(), registry=None) + + c.labels(**labels).inc(1) + g.labels(**labels).set(1) + + pid = 1 + + c.labels(**labels).inc(1) + g.labels(**labels).set(1) + + metrics = {m.name: m for m in self.registry.restricted_registry(['c_total']).collect()} + + self.assertEqual(metrics.keys(), {'c'}) + + self.assertEqual( + metrics['c'].samples, [Sample('c_total', labels, 2.0)] + ) + def test_collect_preserves_help(self): pid = 0 values.ValueClass = MultiProcessValue(lambda: pid)