Prometheus metric exporter

docs/opentelemetry.metrics.rst

@@ -4,4 +4,4 @@ opentelemetry.metrics package
 Module contents
 ---------------
 
-.. automodule:: opentelemetry.metrics
+.. automodule:: opentelemetry.metrics

examples/metrics/prometheus.py

@@ -0,0 +1,53 @@
+# Copyright 2020, OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+This module serves as an example for a simple application using metrics
+Examples show how to recording affects the collection of metrics to be exported
+"""
+import time
+
+from opentelemetry import metrics
+from opentelemetry.ext.prometheus import PrometheusMetricsExporter
+from opentelemetry.sdk.metrics import Counter, Meter
+from opentelemetry.sdk.metrics.export.controller import PushController
+
+# Meter is responsible for creating and recording metrics
+meter = Meter()
+metrics.set_preferred_meter_implementation(meter)
+# exporter to export metrics to Prometheus
+port = 8000
+address = "localhost"
+prefix = "MyAppPrefix"
+exporter = PrometheusMetricsExporter(port, address, prefix)
+# controller collects metrics created from meter and exports it via the
+# exporter every interval
+controller = PushController(meter, exporter, 5)
+
+counter = meter.create_metric(
+    "available memory",
+    "available memory",
+    "bytes",
+    int,
+    Counter,
+    ("environment",),
+)
+
+# Labelsets are used to identify key-values that are associated with a specific
+# metric that you want to record. These are useful for pre-aggregation and can
+# be used to store custom dimensions pertaining to a metric
+label_set = meter.get_label_set({"environment": "staging"})
+
+counter.add(25, label_set)
+input("Press any key to exit...")

ext/opentelemetry-ext-prometheus/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## Unreleased
+

ext/opentelemetry-ext-prometheus/README.rst

@@ -0,0 +1,73 @@
+OpenTelemetry Prometheus Exporter
+=============================
+
+|pypi|
+
+.. |pypi| image:: https://badge.fury.io/py/opentelemetry-ext-prometheus.svg
+   :target: https://pypi.org/project/opentelemetry-ext-prometheus/
+
+This library allows to export metrics data to `Prometheus <https://prometheus.io/>`_.
+
+Installation
+------------
+
+::
+
+     pip install opentelemetry-ext-prometheus
+
+
+Usage
+-----
+
+The **OpenTelemetry Prometheus Exporter** allows to export `OpenTelemetry`_ metrics to `Prometheus`_.
+
+
+.. _Prometheus: https://prometheus.io/
+.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/
+
+.. code:: python
+
+    import time
+
+    from opentelemetry import metrics
+    from opentelemetry.ext.prometheus import PrometheusMetricsExporter
+    from opentelemetry.sdk.metrics import Counter, Meter
+    from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+    from opentelemetry.sdk.metrics.export.controller import PushController
+
+    # Meter is responsible for creating and recording metrics
+    meter = Meter()
+    metrics.set_preferred_meter_implementation(meter)
+    # exporter to export metrics to Prometheus
+    port = 8000
+    address = "localhost"
+    prefix = "MyAppPrefix"
+    exporter = PrometheusMetricsExporter(port, address, prefix)
+    # controller collects metrics created from meter and exports it via the
+    # exporter every interval
+    controller = PushController(meter, exporter, 5)
+
+    counter = meter.create_metric(
+        "available memory",
+        "available memory",
+        "bytes",
+        int,
+        Counter,
+        ("environment",),
+    )
+
+    # Labelsets are used to identify key-values that are associated with a specific
+    # metric that you want to record. These are useful for pre-aggregation and can
+    # be used to store custom dimensions pertaining to a metric
+    label_set = meter.get_label_set({"environment": "staging"})
+
+    counter.add(25, label_set)
+    # We sleep for 5 seconds, exported value should be 25
+    time.sleep(5)
+
+
+References
+----------
+
+* `Prometheus <https://prometheus.io/>`_
+* `OpenTelemetry Project <https://opentelemetry.io/>`_

ext/opentelemetry-ext-prometheus/setup.cfg

@@ -0,0 +1,47 @@
+# Copyright 2020, OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+[metadata]
+name = opentelemetry-ext-prometheus
+description = Prometheus Metric Exporter for OpenTelemetry
+long_description = file: README.rst
+long_description_content_type = text/x-rst
+author = OpenTelemetry Authors
+author_email = cncf-opentelemetry-contributors@lists.cncf.io
+url = https://github.com/open-telemetry/opentelemetry-python/ext/opentelemetry-ext-prometheus
+platforms = any
+license = Apache-2.0
+classifiers =
+    Development Status :: 3 - Alpha
+    Intended Audience :: Developers
+    License :: OSI Approved :: Apache Software License
+    Programming Language :: Python
+    Programming Language :: Python :: 3
+    Programming Language :: Python :: 3.4
+    Programming Language :: Python :: 3.5
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+
+[options]
+python_requires = >=3.4
+package_dir=
+    =src
+packages=find_namespace:
+install_requires =
+    prometheus_client >= 0.5.0, < 1.0.0
+    opentelemetry-api
+    opentelemetry-sdk
+
+[options.packages.find]
+where = src

ext/opentelemetry-ext-prometheus/setup.py

@@ -0,0 +1,26 @@
+# Copyright 2020, OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+
+import setuptools
+
+BASE_DIR = os.path.dirname(__file__)
+VERSION_FILENAME = os.path.join(
+    BASE_DIR, "src", "opentelemetry", "ext", "prometheus", "version.py"
+)
+PACKAGE_INFO = {}
+with open(VERSION_FILENAME) as f:
+    exec(f.read(), PACKAGE_INFO)
+
+setuptools.setup(version=PACKAGE_INFO["__version__"])

ext/opentelemetry-ext-prometheus/src/opentelemetry/ext/prometheus/__init__.py

@@ -0,0 +1,157 @@
+# Copyright 2020, OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Prometheus Metrics Exporter for OpenTelemetry."""
+
+import logging
+import re
+from typing import Sequence
+
+from prometheus_client import start_http_server
+from prometheus_client.core import (
+    REGISTRY,
+    CollectorRegistry,
+    CounterMetricFamily,
+    GaugeMetricFamily,
+    UnknownMetricFamily,
+)
+
+from opentelemetry.metrics import Counter, Gauge, Measure, Metric
+from opentelemetry.sdk.metrics.export import (
+    MetricRecord,
+    MetricsExporter,
+    MetricsExportResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class PrometheusMetricsExporter(MetricsExporter):
+    """Prometheus metric exporter for OpenTelemetry.
+
+    Args:
+        port: The Prometheus port to be used.
+        address: The Prometheus address to be used.
+        prefix: single-word application prefix relevant to the domain the metric belongs to.
+    """
+
+    def __init__(self, port: int = 8000, address: str = "", prefix: str = ""):
+        self._port = port
+        self._address = address
+        self._collector = CustomCollector(prefix)
+
+        start_http_server(port=self._port, addr=str(self._address))
+        REGISTRY.register(self._collector)
+
+    def export(
+        self, metric_records: Sequence[MetricRecord]
+    ) -> MetricsExportResult:
+        self._collector.add_metrics_data(metric_records)
+        return MetricsExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        REGISTRY.unregister(self._collector)
+
+
+class CustomCollector:
+    """ CustomCollector represents the Prometheus Collector object
+        https://github.com/prometheus/client_python#custom-collectors
+    """
+
+    def __init__(self, prefix: str = ""):
+        self._prefix = prefix
+        self._metrics_to_export = []
+
+    def add_metrics_data(self, metric_records: Sequence[MetricRecord]):
+        self._metrics_to_export.append(metric_records)
+
+    def collect(self):
+        """Collect fetches the metrics from OpenTelemetry
+        and delivers them as Prometheus Metrics.
+        Collect is invoked every time a prometheus.Gatherer is run
+        for example when the HTTP endpoint is invoked by Prometheus.
+        """
+
+        for metric_batch in self._metrics_to_export:
+            for metric_record in metric_batch:
+                prometheus_metric = self._translate_to_prometheus(
+                    metric_record
+                )
+                if prometheus_metric:
+                    yield prometheus_metric
+            self._metrics_to_export.remove(metric_batch)
+
+    def _translate_to_prometheus(self, metric_record: MetricRecord):
+        prometheus_metric = None
+        label_values = []
+        label_keys = []
+        for label in metric_record.label_set.labels:
+            for index, label_tuple_value in enumerate(label):
+                # Odd number
+                if index & 1 == 1:
+                    label_values.append(label_tuple_value)
+
+        for label_key in metric_record.metric.label_keys:
+            label_keys.append(sanitize(label_key))
+        metric_name = ""
+        if self._prefix != "":
+            metric_name = self._prefix + "_"
+        metric_name += sanitize(metric_record.metric.name)
+
+        if isinstance(metric_record.metric, Counter):
+            prometheus_metric = CounterMetricFamily(
+                name=metric_name,
+                documentation=metric_record.metric.description,
+                labels=label_keys,
+            )
+            prometheus_metric.add_metric(
+                labels=label_values, value=metric_record.aggregator.check_point
+            )
+
+        elif isinstance(metric_record.metric, Gauge):
+            prometheus_metric = GaugeMetricFamily(
+                name=metric_name,
+                documentation=metric_record.metric.description,
+                labels=label_keys,
+            )
+            prometheus_metric.add_metric(
+                labels=label_values, value=metric_record.aggregator.check_point
+            )
+
+        # TODO: Add support for histograms when supported in OT
+        elif isinstance(metric_record.metric, Measure):
+            prometheus_metric = UnknownMetricFamily(
+                name=metric_name,
+                documentation=metric_record.metric.description,
+                labels=label_keys,
+            )
+            prometheus_metric.add_metric(
+                labels=label_values, value=metric_record.aggregator.check_point
+            )
+
+        else:
+            logger.warning(
+                "Unsupported metric type. %s", type(metric_record.metric)
+            )
+        return prometheus_metric
+
+
+_NON_LETTERS_NOR_DIGITS_RE = re.compile(r"[^\w]", re.UNICODE | re.IGNORECASE)
+
+
+def sanitize(key):
+    """ sanitize the given metric name or label according to Prometheus rule.
+    Replace all characters other than [A-Za-z0-9_] with '_'.
+    """
+    return _NON_LETTERS_NOR_DIGITS_RE.sub("_", key)

ext/opentelemetry-ext-prometheus/src/opentelemetry/ext/prometheus/version.py

@@ -0,0 +1,15 @@
+# Copyright 2020, OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+__version__ = "0.4.dev0"