Skip to content

Add 'translation_strategy' to PrometheusMetricExporter #262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add 'translation_strategy' to PrometheusMetricExporter #262

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ca620fb
Add 'translation_strategy' to PrometheusMetricProducer
ArthurSens Aug 7, 2025
18b991a
Document that translation strategy takes precedence over deprecated o…
ArthurSens Aug 12, 2025
da6072c
Merge branch 'main' into prom-translation-strategy
ArthurSens Aug 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions examples/kitchen-sink.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,9 +202,11 @@ meter_provider:
port: 9464
# Configure Prometheus Exporter to produce metrics without a unit suffix or UNIT metadata.
# If omitted or null, false is used.
# Deprecated: Use .translation_strategy instead.
without_units: false
# Configure Prometheus Exporter to produce metrics without a type suffix.
# If omitted or null, false is used.
# Deprecated: Use .translation_strategy instead.
without_type_suffix: false
# Configure Prometheus Exporter to produce metrics without a scope info metric.
# If omitted or null, false is used.
Expand All @@ -225,6 +227,15 @@ meter_provider:
# If omitted, .included resource attributes are included.
excluded:
- "service.attr1"
# Configure how Prometheus metrics are exposed. Values include:
#
# * 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.
#
# If omitted or null, UnderscoreEscapingWithSuffixes is used.
translation_strategy: UnderscoreEscapingWithSuffixes
# Configure metric producers.
producers:
- # Configure metric producer to be opencensus.
Expand Down
9 changes: 9 additions & 0 deletions schema/meter_provider.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,15 @@
},
"with_resource_constant_labels": {
"$ref": "common.json#/$defs/IncludeExclude"
},
"translation_strategy": {
"type": ["string", "null"],
"enum": [
"UnderscoreEscapingWithSuffixes",
"UnderscoreEscapingWithoutSuffixes",
"NoUTF8EscapingWithSuffixes",
"NoTranslation"
]
}
}
},
Expand Down
13 changes: 13 additions & 0 deletions schema/type_descriptions.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -597,15 +597,28 @@
Configure Prometheus Exporter to produce metrics without a unit suffix or UNIT metadata.

If omitted or null, false is used.

Deprecated: Use .translation_strategy instead.
without_type_suffix: >
Configure Prometheus Exporter to produce metrics without a type suffix.

If omitted or null, false is used.

Deprecated: Use .translation_strategy instead.
without_scope_info: >
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do these get interpreted if they are supplied with a defined translation_strategy?

Should they just be removed?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's something I'd love to discuss. The OTel Collector is already using those fields in their configuration files; if we simply remove them, it would be a breaking change for the collector.

It would be nice to keep both for a while, while we announce the deprecation in the collector for a few releases. In the meantime, I imagine the translation_strategy will always take precedence over the two deprecated fields.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good to me.

Can we document the precedence of translation_strategy here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

Configure Prometheus Exporter to produce metrics without a scope info metric.

If omitted or null, false is used.
with_resource_constant_labels: Configure Prometheus Exporter to add resource attributes as metrics attributes.
translation_strategy: >
Configure how Prometheus metrics are exposed. Values include:

* 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.

If omitted or null, UnderscoreEscapingWithSuffixes is used.
path_patterns:
- .meter_provider.readers[].pull.exporter.prometheus/development
- type: PrometheusIncludeExclude
Expand Down
Loading