prometheus

README

Prometheus Normalization

OpenTelemetry's metric semantic convention is not compatible with Prometheus' own metrics naming convention. This module provides centralized functions to convert OpenTelemetry metrics to Prometheus-compliant metrics. These functions are used by the following components for Prometheus:

• prometheusreceiver
• prometheusexporter
• prometheusremotewriteexporter

Metric name

Full normalization

Warning

This feature can be controlled with feature gate pkg.translator.prometheus.NormalizeName. It is currently enabled by default (beta stage).

Example of how to disable it:

$ otelcol --config=config.yaml --feature-gates=-pkg.translator.prometheus.NormalizeName

List of transformations to convert OpenTelemetry metrics to Prometheus metrics

Case	Transformation	Example
Unsupported characters and extraneous underscores	Replace unsupported characters with underscores (_). Drop redundant, leading and trailing underscores.	(lambda).function.executions(#) → lambda_function_executions
Standard unit	Convert the unit from Unified Code for Units of Measure to Prometheus standard and append	system.filesystem.usage with unit By → system_filesystem_usage_bytes
Non-standard unit (unit is surrounded with {})	Drop the unit	system.network.dropped with unit {packets} → system_network_dropped
Non-standard unit (unit is not surrounded with {})	Append the unit, if not already present, after sanitization (all non-alphanumeric chars are dropped)	system.network.dropped with unit packets → system_network_dropped_packets
Percentages (unit is 1)	Append _ratio (for gauges only)	system.memory.utilization with unit 1 → system_memory_utilization_ratio
Percentages (unit is %)	Replace % with percent _percent	storage.filesystem.utilization with unit % → storage_filesystem_utilization_percent
Rates (unit contains /)	Replace / with per	astro.light.speed with unit m/s → astro_light_speed_meters_per_second
Counter	Append _total	system.processes.created → system_processes_created_total

List of standard OpenTelemetry units that will be translated to Prometheus standard base units:

OpenTelemetry Unit	Corresponding Prometheus Unit
Time
d	days
h	hours
min	minutes
s	seconds
ms	milliseconds
us	microseconds
ns	nanoseconds
Bytes
By	bytes
KiBy	kibibytes
MiBy	mebibytes
GiBy	gibibytes
TiBy	tibibytes
KBy	kilobytes
MBy	megabytes
GBy	gigabytes
TBy	terabytes
SI Units
m	meters
V	volts
A	amperes
J	joules
W	watts
g	grams
Misc.
Cel	celsius
Hz	hertz
%	percent

Note Prometheus also recommends using base units (no kilobytes, or milliseconds, for example) but these functions will not attempt to convert non-base units to base units.

List of transformations performed to convert Prometheus metrics to OpenTelemetry metrics

Case	Transformation	Example
UNIT defined in OpenMetrics format	Drop the unit suffix and set it in the OpenTelemetry metric unit field	system_network_dropped_packets → system_network_dropped with packets unit
Counter	Drop _total suffix	system_processes_created_total→ system_processes_created

Simple normalization

If feature pkg.translator.prometheus.NormalizeName is not enabled, a simple sanitization of the OpenTelemetry metric name is performed to ensure it follows Prometheus naming conventions:

• Drop unsupported characters and replace with underscores (_)
• Remove redundant, leading and trailing underscores
• Ensure metric name doesn't start with a digit by prefixing with an underscore

No processing of the unit is performed, and _total is not appended for Counters.

Labels

OpenTelemetry Attributes are converted to Prometheus labels and normalized to follow the Prometheus labels naming rules.

The following transformations are performed on OpenTelemetry Attributes to produce Prometheus labels:

• Drop unsupported characters and replace with underscores (_)
• Prefix label with key_ if it doesn't start with a letter, except if it's already prefixed with double-underscore (__)

By default, labels that start with a simple underscore (_) are prefixed with key, which is strictly unnecessary to follow Prometheus labels naming rules. This behavior can be disabled with the feature pkg.translator.prometheus.PermissiveLabelSanitization, which must be activated with the feature gate option of the collector:

$ otelcol --config=config.yaml --feature-gates=pkg.translator.prometheus.PermissiveLabelSanitization

Examples:

OpenTelemetry Attribute	Prometheus Label
name	name
host.name	host_name
host_name	host_name
name (of the host)	name__of_the_host_
2 cents	key_2_cents
__name	__name
_name	key_name
_name	_name (if PermissiveLabelSanitization is enabled)

Documentation

Index

• Constants
• func BuildCompliantName(metric pmetric.Metric, namespace string, addMetricSuffixes bool) string
• func CleanUpString(s string) string
• func NormalizeLabel(label string) string
• func RemovePromForbiddenRunes(s string) string
• func TrimPromSuffixes(promName string, metricType pmetric.MetricType, unit string) string
• func UnitWordToUCUM(unit string) string

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 BuildCompliantName

func BuildCompliantName(metric pmetric.Metric, namespace string, addMetricSuffixes bool) string

BuildCompliantName 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 and https://prometheus.io/docs/practices/naming/#metric-and-label-naming

func CleanUpString

func CleanUpString(s string) string

Clean up specified string so it's Prometheus compliant

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_"

Exception is made for double-underscores which are allowed

func RemovePromForbiddenRunes

func RemovePromForbiddenRunes(s string) string

func TrimPromSuffixes

func TrimPromSuffixes(promName string, metricType pmetric.MetricType, unit string) string

TrimPromSuffixes trims type and unit prometheus suffixes from a metric name. Following the OpenTelemetry specs for converting Prometheus Metric points to OTLP.

func UnitWordToUCUM

func UnitWordToUCUM(unit string) string

UnitWordToUCUM converts english unit words to UCUM units: https://ucum.org/ucum#section-Alphabetic-Index-By-Symbol It also handles rates, such as meters_per_second, by translating the first word to UCUM, and the "per" word to UCUM. It joins them with a "/" between.