Merge pull request #768 from prometheus/otlp-translator

otlptranslator: Add dependency free package that translates OTLP data into Prometheus metric/label names

Author: ArthurSens

otlptranslator/constants.go

@@ -0,0 +1,58 @@
+// 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.
+package otlptranslator
+
+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"
+)
+
+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"
+)

otlptranslator/doc.go

@@ -0,0 +1,24 @@
+// 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.
+package otlptranslator

otlptranslator/label_builder.go

@@ -0,0 +1,54 @@
+// 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.
+package otlptranslator
+
+import (
+	"regexp"
+	"strings"
+	"unicode"
+)
+
+var invalidLabelCharRE = regexp.MustCompile(`[^a-zA-Z0-9_]`)
+
+// 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 NormalizeLabel(label string) string {
+	// Trivial case.
+	if len(label) == 0 {
+		return label
+	}
+
+	label = SanitizeLabelName(label)
+
+	// If label starts with a number, prepend with "key_".
+	if unicode.IsDigit(rune(label[0])) {
+		label = "key_" + label
+	} else if strings.HasPrefix(label, "_") && !strings.HasPrefix(label, "__") {
+		label = "key" + label
+	}
+
+	return label
+}
+
+// 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.
+func SanitizeLabelName(name string) string {
+	return invalidLabelCharRE.ReplaceAllString(name, "_")
+}

otlptranslator/label_builder_bench_test.go

@@ -0,0 +1,35 @@
+// 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.
+package otlptranslator
+
+import "testing"
+
+var labelBenchmarkInputs = []string{
+	"",
+	"label:with:colons",
+	"LabelWithCapitalLetters",
+	"label!with&special$chars)",
+	"label_with_foreign_characters_字符",
+	"label.with.dots",
+	"123label",
+	"_label_starting_with_underscore",
+	"__label_starting_with_2underscores",
+}
+
+func BenchmarkNormalizeLabel(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		for _, input := range labelBenchmarkInputs {
+			NormalizeLabel(input)
+		}
+	}
+}

otlptranslator/label_builder_test.go

@@ -0,0 +1,44 @@
+// 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.
+package otlptranslator
+
+import (
+	"fmt"
+	"testing"
+)
+
+func TestNormalizeLabel(t *testing.T) {
+	tests := []struct {
+		label    string
+		expected string
+	}{
+		{"", ""},
+		{"label:with:colons", "label_with_colons"},
+		{"LabelWithCapitalLetters", "LabelWithCapitalLetters"},
+		{"label!with&special$chars)", "label_with_special_chars_"},
+		{"label_with_foreign_characters_字符", "label_with_foreign_characters___"},
+		{"label.with.dots", "label_with_dots"},
+		{"123label", "key_123label"},
+		{"_label_starting_with_underscore", "key_label_starting_with_underscore"},
+		{"__label_starting_with_2underscores", "__label_starting_with_2underscores"},
+	}
+
+	for i, test := range tests {
+		t.Run(fmt.Sprintf("test_%d", i), func(t *testing.T) {
+			result := NormalizeLabel(test.label)
+			if test.expected != result {
+				t.Errorf("expected %s, got %s", test.expected, result)
+			}
+		})
+	}
+}