package otlptranslator

import "github.com/prometheus/common/otlptranslator"

Copyright 2025 The Prometheus 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.

otlptranslator is a dependency free package that contains the logic for translating information, such as metric name, unit and type, from OpenTelemetry metrics to valid Prometheus metric and label names.

Use BuildCompliantMetricName to build a metric name that complies with traditional Prometheus naming conventions. Such conventions exist from a time when Prometheus didn't have support for full UTF-8 characters in metric names. For more details see: https://prometheus.io/docs/practices/naming/

Use BuildMetricName to build a metric name that will be accepted by Prometheus with full UTF-8 support.

Use NormalizeLabel to normalize a label name to a valid format that can be used in Prometheus before UTF-8 characters were supported.

Copyright 2025 The Prometheus 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.

Index ¶

• Constants
• func BuildCompliantMetricName(name, unit string, metricType MetricType, addMetricSuffixes bool) string
• func BuildMetricName(name, unit string, metricType MetricType, addMetricSuffixes bool) string
• func CleanUpString(s string) string
• func NormalizeLabel(label string) string
• func SanitizeLabelName(name string) string
• type MetricType

Constants ¶

const (
	// MetricMetadataTypeKey is the key used to store the original Prometheus
	// type in metric metadata:
	// https://github.com/open-telemetry/opentelemetry-specification/blob/e6eccba97ebaffbbfad6d4358408a2cead0ec2df/specification/compatibility/prometheus_and_openmetrics.md#metric-metadata
	MetricMetadataTypeKey = "prometheus.type"
	// ExemplarTraceIDKey is the key used to store the trace ID in Prometheus
	// exemplars:
	// https://github.com/open-telemetry/opentelemetry-specification/blob/e6eccba97ebaffbbfad6d4358408a2cead0ec2df/specification/compatibility/prometheus_and_openmetrics.md#exemplars
	ExemplarTraceIDKey = "trace_id"
	// ExemplarSpanIDKey is the key used to store the Span ID in Prometheus
	// exemplars:
	// https://github.com/open-telemetry/opentelemetry-specification/blob/e6eccba97ebaffbbfad6d4358408a2cead0ec2df/specification/compatibility/prometheus_and_openmetrics.md#exemplars
	ExemplarSpanIDKey = "span_id"
	// ScopeInfoMetricName is the name of the metric used to preserve scope
	// attributes in Prometheus format:
	// https://github.com/open-telemetry/opentelemetry-specification/blob/e6eccba97ebaffbbfad6d4358408a2cead0ec2df/specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope
	ScopeInfoMetricName = "otel_scope_info"
	// ScopeNameLabelKey is the name of the label key used to identify the name
	// of the OpenTelemetry scope which produced the metric:
	// https://github.com/open-telemetry/opentelemetry-specification/blob/e6eccba97ebaffbbfad6d4358408a2cead0ec2df/specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope
	ScopeNameLabelKey = "otel_scope_name"
	// ScopeVersionLabelKey is the name of the label key used to identify the
	// version of the OpenTelemetry scope which produced the metric:
	// https://github.com/open-telemetry/opentelemetry-specification/blob/e6eccba97ebaffbbfad6d4358408a2cead0ec2df/specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope
	ScopeVersionLabelKey = "otel_scope_version"
	// TargetInfoMetricName is the name of the metric used to preserve resource
	// attributes in Prometheus format:
	// https://github.com/open-telemetry/opentelemetry-specification/blob/e6eccba97ebaffbbfad6d4358408a2cead0ec2df/specification/compatibility/prometheus_and_openmetrics.md#resource-attributes-1
	// It originates from OpenMetrics:
	// https://github.com/OpenObservability/OpenMetrics/blob/1386544931307dff279688f332890c31b6c5de36/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems
	TargetInfoMetricName = "target_info"
)

Functions ¶

func BuildCompliantMetricName ¶

func BuildCompliantMetricName(name, unit string, metricType MetricType, addMetricSuffixes bool) string

BuildCompliantMetricName builds a Prometheus-compliant metric name for the specified metric.

Metric name is prefixed with specified namespace and underscore (if any). Namespace is not cleaned up. Make sure specified namespace follows Prometheus naming convention.

See rules at https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels, https://prometheus.io/docs/practices/naming/#metric-and-label-naming and https://github.com/open-telemetry/opentelemetry-specification/blob/v1.38.0/specification/compatibility/prometheus_and_openmetrics.md#otlp-metric-points-to-prometheus.

func BuildMetricName ¶

func BuildMetricName(name, unit string, metricType MetricType, addMetricSuffixes bool) string

BuildMetricName builds a valid metric name but without following Prometheus naming conventions. It doesn't do any character transformation, it only prefixes the metric name with the namespace, if any, and adds metric type suffixes, e.g. "_total" for counters and unit suffixes.

Differently from BuildCompliantMetricName, it doesn't check for the presence of unit and type suffixes. If "addMetricSuffixes" is true, it will add them anyway.

Please use BuildCompliantMetricName for a metric name that follows Prometheus naming conventions.

func CleanUpString ¶

func CleanUpString(s string) string

CleanUpString cleans up a string so it matches model.LabelNameRE. CleanUpString is usually used to clean up unit strings, but can be used for any string, e.g. namespaces.

func NormalizeLabel ¶

func NormalizeLabel(label string) string

Normalizes the specified label to follow Prometheus label names standard.

See rules at https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels.

Labels that start with non-letter rune will be prefixed with "key_". An exception is made for double-underscores which are allowed.

func SanitizeLabelName ¶

func SanitizeLabelName(name string) string

SanitizeLabelName replaces anything that doesn't match client_label.LabelNameRE with an underscore. Note: this does not handle all Prometheus label name restrictions (such as not starting with a digit 0-9), and hence should only be used if the label name is prefixed with a known valid string.

Types ¶

type MetricType ¶

type MetricType string

const (
	MetricTypeNonMonotonicCounter  MetricType = "non-monotonic-counter"
	MetricTypeMonotonicCounter     MetricType = "monotonic-counter"
	MetricTypeGauge                MetricType = "gauge"
	MetricTypeHistogram            MetricType = "histogram"
	MetricTypeExponentialHistogram MetricType = "exponential-histogram"
	MetricTypeSummary              MetricType = "summary"
	MetricTypeUnknown              MetricType = "unknown"
)

Source Files ¶

constants.go doc.go label_builder.go metric_name_builder.go