Metrics Exporter - Prometheus
Status: Development
A Prometheus Exporter MUST be a Pull Metric Exporter which responds to HTTP requests with Prometheus metrics in the appropriate format.
OpenTelemetry metrics MUST be converted to Prometheus metrics according to the Prometheus Compatibility specification.
A Prometheus Exporter SHOULD use
Prometheus client libraries
for serving Prometheus metrics. This allows the prometheus client to negotiate
the format
of the response using the Content-Type
header. If a prometheus client library
is used, the OpenTelemetry Prometheus Exporter SHOULD be modeled as a
custom Collector
so it can be used in conjunction with existing Prometheus instrumentation.
Regardless of whether a Prometheus client library is used, the Prometheus
Exporter MUST support version 0.0.4
of the
Text-based format.
A Prometheus Exporter MAY support Exemplars and Exponential Histograms,
which are not currently supported by the Prometheus text format,
by supporting other Protocols, but is not required to implement them.
A Prometheus Exporter for an OpenTelemetry metrics SDK MUST NOT use Prometheus Remote Write format or OpenMetrics protobuf format.
A Prometheus Exporter for an OpenTelemetry metrics SDK MUST NOT add explicit timestamps on Metric points.
There MUST be at most one target
info metric exposed by an SDK
Prometheus exporter.
A Prometheus Exporter MUST set
the MetricReader temporality
as a function of
instrument kind to be cumulative
for all instrument kinds.
Configuration
A Prometheus Exporter SHOULD support a configuration option to set the host
that metrics are served on. The option MAY be named host
, and MUST be localhost
by default.
A Prometheus Exporter SHOULD support a configuration option to set the port
that metrics are served on. The option MAY be named port
, and MUST be 9464
by
default.
A Prometheus Exporter SHOULD support a configuration option to set
the MetricReader default aggregation
as a function
of instrument kind. This option MAY be named default_aggregation
, and MUST use
the default aggregation by default.
A Prometheus Exporter MAY offer configuration to add resource attributes as metric attributes.
By default, it MUST NOT add any resource attributes as metric attributes.
The configuration SHOULD allow the user to select which resource attributes to copy (e.g.
include / exclude or regular expression based). Copied Resource attributes MUST NOT be
excluded from the target
info metric. The option MAY be named with_resource_constant_labels
.
A Prometheus Exporter MAY support a configuration option that controls the translation of metric names from OpenTelemetry Naming Conventions to Prometheus Naming conventions.
If the Prometheus exporter supports such configuration it MUST be named to something that resembles Prometheus configuration option translation_strategy
, and the translation options MUST be:
UnderscoreEscapingWithSuffixes
, the default. This fully escapes metric names for classic Prometheus metric name compatibility, and includes appending type and unit suffixes.UnderscoreEscapingWithoutSuffixes
, metric names will continue to escape special characters to_
, but suffixes won’t be attached.NoUTF8EscapingWithSuffixes
will disable changing special characters to_
. Special suffixes like units and_total
for counters will be attached.NoTranslation
. This strategy bypasses all metric and label name translation, passing them through unaltered.
A Prometheus Exporter MAY support a configuration option to produce metrics without scope labels.
The option MAY be named without_scope_info
, and MUST be false
by default.
A Prometheus Exporter MAY support a configuration option to produce metrics without a target info
metric. The option MAY be named without_target_info
, and MUST be false
by default.
Content Negotiation
A Prometheus Exporter MUST support content negotiation to allow clients to request
metrics in different formats based on the Accept
header in HTTP requests. Content
negotiation MUST follow Prometheus Content Negotiation guidelines.
Interaction with Translation Strategy
Although a Prometheus Exporter MAY be configured with a translation_strategy
for internal metric processing, the final output format and character escaping MUST follow what the content negotiation process determines based on the client’s Accept
header. The content negotiation requirements MUST take precedence over the configured translation strategy when determining the final output format.
Examples:
- If configured with
NoTranslation
but the client requestsescaping=underscores
, the exporter MUST apply underscore escaping. - If configured with
UnderscoreEscapingWithSuffixes
but the client requestsescaping=allow-utf8
, there’s no need to revert what has been translated since the exporter will continue to be compliant.
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!