opentelemetry-exporter-prometheus-remote-write 0.17b0

Installation

Quickstart

from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.exporter.prometheus_remote_write import (
    PrometheusRemoteWriteMetricsExporter
)

# Sets the global MeterProvider instance
metrics.set_meter_provider(MeterProvider())

# The Meter is responsible for creating and recording metrics. Each meter has a unique name, which we set as the module's name here.
meter = metrics.get_meter(__name__)

exporter = PrometheusRemoteWriteMetricsExporter(endpoint="endpoint_here") # add other params as needed

metrics.get_meter_provider().start_pipeline(meter, exporter, 5)

Examples

This example uses Docker Compose to set up:

1. A Python program that creates 5 instruments with 5 unique aggregators and a randomized load generator

2. An instance of Cortex to recieve the metrics data

3. An instance of Grafana to visualizse the exported data

Configuring the Exporter

The exporter can be configured through parameters passed to the constructor. Here are all the options:

• endpoint: url where data will be sent (Required)

• basic_auth: username and password for authentication (Optional)

• headers: additional headers for remote write request as determined by the remote write backend’s API (Optional)

• timeout: timeout for requests to the remote write endpoint in seconds (Optional)

• proxies: dict mapping request proxy protocols to proxy urls (Optional)

• tls_config: configuration for remote write TLS settings (Optional)

Example with all the configuration options:

exporter = PrometheusRemoteWriteMetricsExporter(
    endpoint="http://localhost:9009/api/prom/push",
    timeout=30,
    basic_auth={
        "username": "user",
        "password": "pass123",
    },
    headers={
        "X-Scope-Org-ID": "5",
        "Authorization": "Bearer mytoken123",
    },
    proxies={
        "http": "http://10.10.1.10:3000",
        "https": "http://10.10.1.10:1080",
    },
    tls_config={
        "cert_file": "path/to/file",
        "key_file": "path/to/file",
        "ca_file": "path_to_file",
        "insecure_skip_verify": true, # for developing purposes
    }
)

Securing the Exporter

exporter = PrometheusRemoteWriteMetricsExporter(
    basic_auth={"username": "base64user",  "password": "base64pass"}
)

header = {
    "Authorization": "Bearer mytoken123"
}

Supported Aggregators

Behaviour of these aggregators is outlined in the OpenTelemetry Specification. All aggregators are converted into the timeseries data format. However, method in which they are converted differs from aggregator to aggregator. A map of the conversion methods can be found here.

Error Handling

In general, errors are raised by the calling function. The exception is for failed requests where any error status code is logged as a warning instead.

This is because the exporter does not implement any retry logic as data that failed to export will be dropped.

For example, consider a situation where a user increments a Counter instrument 5 times and an export happens between each increment. If the exports happen like so:

SUCCESS FAIL FAIL SUCCESS SUCCESS
1       2    3    4       5

Then the received data will be:

1 4 5

Contributing

If you would like to learn more about the exporter’s structure and design decisions please view the design document below