Skip to content

Commit 71c6c48

Browse files
Set Prometheus SDK Exporter spec to Mixed status (#4969)
Fixes #4927 ## Changes Sets the Prometheus SDK Metrics Exporter spec to `Mixed` status at document level, and splits it into subsections, each marked `Development`. That lets us move toward stabilization incrementally in follow-up issues per subsection, similar to #4860. cc: @ArthurSens * [x] Related issues #4927 * [ ] Related [OTEP(s)](https://github.com/open-telemetry/oteps) # * [ ] Links to the prototypes (when adding or changing features) * [ ] [`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md) file updated for non-trivial changes * For trivial changes, include `[chore]` in the PR title to skip the changelog check * [ ] [Spec compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix/template.yaml) updated if necessary Co-authored-by: Carlos Alberto Cortez <calberto.cortez@gmail.com>
1 parent 2f5ac83 commit 71c6c48

File tree

1 file changed

+88
-0
lines changed

1 file changed

+88
-0
lines changed

specification/metrics/sdk_exporters/prometheus.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,56 @@ linkTitle: Prometheus
44

55
# Metrics Exporter - Prometheus
66

7+
**Status**: [Mixed](../../document-status.md)
8+
9+
<details>
10+
<summary>Table of Contents</summary>
11+
12+
<!-- toc -->
13+
14+
- [Prometheus Exporter Model](#prometheus-exporter-model)
15+
* [Pull Metric Exporter](#pull-metric-exporter)
16+
* [Metric Conversion](#metric-conversion)
17+
* [Client Libraries](#client-libraries)
18+
* [Version and Format](#version-and-format)
19+
- [SDK Metric Output](#sdk-metric-output)
20+
* [Target](#target)
21+
* [Temporality](#temporality)
22+
- [Configuration](#configuration)
23+
* [Host](#host)
24+
* [Port](#port)
25+
* [Default Aggregation](#default-aggregation)
26+
* [Resource Attributes as Metric Attributes](#resource-attributes-as-metric-attributes)
27+
* [Translation Strategy](#translation-strategy)
28+
* [Scope Info](#scope-info)
29+
* [Target Info](#target-info)
30+
- [Content Negotiation](#content-negotiation)
31+
* [Interaction with Translation Strategy](#interaction-with-translation-strategy)
32+
33+
<!-- tocstop -->
34+
35+
</details>
36+
37+
## Prometheus Exporter Model
38+
39+
### Pull Metric Exporter
40+
741
**Status**: [Development](../../document-status.md)
842

943
A Prometheus Exporter MUST be a [Pull Metric Exporter](../sdk.md#pull-metric-exporter)
1044
which responds to HTTP requests with Prometheus metrics in the appropriate format.
1145

46+
### Metric Conversion
47+
48+
**Status**: [Development](../../document-status.md)
49+
1250
OpenTelemetry metrics MUST be converted to Prometheus metrics according to the
1351
[Prometheus Compatibility specification](../../compatibility/prometheus_and_openmetrics.md).
1452

53+
### Client Libraries
54+
55+
**Status**: [Development](../../document-status.md)
56+
1557
A Prometheus Exporter SHOULD use
1658
[Prometheus client libraries](https://prometheus.io/docs/instrumenting/clientlibs/)
1759
for serving Prometheus metrics. This allows the Prometheus client to negotiate
@@ -21,6 +63,10 @@ is used, the OpenTelemetry Prometheus Exporter SHOULD be modeled as a
2163
[custom Collector](https://prometheus.io/docs/instrumenting/writing_clientlibs/#overall-structure)
2264
so it can be used in conjunction with existing Prometheus instrumentation.
2365

66+
### Version and Format
67+
68+
**Status**: [Development](../../document-status.md)
69+
2470
Regardless of whether a Prometheus client library is used, the Prometheus
2571
Exporter MUST support version `0.0.4` of the
2672
[Text-based format](https://github.com/prometheus/docs/blob/main/docs/instrumenting/exposition_formats.md#prometheus-text-format).
@@ -35,34 +81,64 @@ or [OpenMetrics protobuf format](https://github.com/prometheus/OpenMetrics/blob/
3581
A Prometheus Exporter for an OpenTelemetry metrics SDK MUST NOT add
3682
[explicit timestamps on Metric points](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#metric).
3783

84+
## SDK Metric Output
85+
86+
### Target
87+
88+
**Status**: [Development](../../document-status.md)
89+
3890
There MUST be at most one `target` info metric exposed by an SDK
3991
Prometheus exporter.
4092

93+
### Temporality
94+
95+
**Status**: [Development](../../document-status.md)
96+
4197
A Prometheus Exporter MUST set
4298
the [MetricReader](../sdk.md#metricreader) `temporality` as a function of
4399
instrument kind to be `cumulative` for all instrument kinds.
44100

45101
## Configuration
46102

103+
### Host
104+
105+
**Status**: [Development](../../document-status.md)
106+
47107
A Prometheus Exporter SHOULD support a configuration option to set the host
48108
that metrics are served on. The option MAY be named `host`, and MUST be `localhost`
49109
by default.
50110

111+
### Port
112+
113+
**Status**: [Development](../../document-status.md)
114+
51115
A Prometheus Exporter SHOULD support a configuration option to set the port
52116
that metrics are served on. The option MAY be named `port`, and MUST be `9464` by
53117
default.
54118

119+
### Default Aggregation
120+
121+
**Status**: [Development](../../document-status.md)
122+
55123
A Prometheus Exporter SHOULD support a configuration option to set
56124
the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
57125
of instrument kind. This option MAY be named `default_aggregation`, and MUST use
58126
the [default aggregation](../sdk.md#default-aggregation) by default.
59127

128+
### Resource Attributes as Metric Attributes
129+
130+
**Status**: [Development](../../document-status.md)
131+
60132
A Prometheus Exporter MAY offer configuration to add resource attributes as metric attributes.
61133
By default, it MUST NOT add any resource attributes as metric attributes.
62134
The configuration SHOULD allow the user to select which resource attributes to copy (e.g.
63135
include / exclude or regular expression based). Copied Resource attributes MUST NOT be
64136
excluded from the `target` info metric. The option MAY be named `with_resource_constant_labels`.
65137

138+
### Translation Strategy
139+
140+
**Status**: [Development](../../document-status.md)
141+
66142
A Prometheus Exporter MAY support a configuration option that controls the translation of metric names from OpenTelemetry Naming Conventions to [Prometheus Naming conventions](https://prometheus.io/docs/practices/naming/).
67143
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:
68144

@@ -71,20 +147,32 @@ If the Prometheus exporter supports such configuration it MUST be named to somet
71147
- `NoUTF8EscapingWithSuffixes` will disable changing special characters to `_`. Special suffixes like units and `_total` for counters will be attached.
72148
- `NoTranslation`. This strategy bypasses all metric and label name translation, passing them through unaltered.
73149

150+
### Scope Info
151+
152+
**Status**: [Development](../../document-status.md)
153+
74154
A Prometheus Exporter MAY support a configuration option to produce metrics without [scope labels](../../compatibility/prometheus_and_openmetrics.md#instrumentation-scope-1).
75155
The option MAY be named `without_scope_info`, and MUST be `false` by default.
76156

157+
### Target Info
158+
159+
**Status**: [Development](../../document-status.md)
160+
77161
A Prometheus Exporter MAY support a configuration option to produce metrics without a [target info](../../compatibility/prometheus_and_openmetrics.md#resource-attributes-1)
78162
metric. The option MAY be named `without_target_info`, and MUST be `false` by default.
79163

80164
## Content Negotiation
81165

166+
**Status**: [Development](../../document-status.md)
167+
82168
A Prometheus Exporter MUST support content negotiation to allow clients to request
83169
metrics in different formats based on the `Accept` header in HTTP requests. Content
84170
negotiation MUST follow [Prometheus Content Negotiation guidelines](https://prometheus.io/docs/instrumenting/content_negotiation/).
85171

86172
### Interaction with Translation Strategy
87173

174+
**Status**: [Development](../../document-status.md)
175+
88176
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.
89177

90178
Examples:

0 commit comments

Comments
 (0)