Prometheus OTLP Translator

https://pkg.go.dev/github.com/prometheus/otlptranslator
Admin
Prometheus OTLP Translator is a Go library for converting OpenTelemetry Protocol (OTLP) metric and...
Tokens:4,560
Snippets:37
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install otlptranslator

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Use the go get command to add the library to your project.

```bash
go get github.com/prometheus/otlptranslator
```

--------------------------------

### Use UnitNamer

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Examples of initializing and using the UnitNamer to build compliant unit strings.

```go
namer := UnitNamer{UTF8Allowed: false}
result := namer.Build("s")     // "seconds"
result = namer.Build("By/s")   // "bytes_per_second"
```

```go
namer := UnitNamer{UTF8Allowed: false}
namer.Build("s")           // "seconds"
namer.Build("requests/s")  // "requests_per_second"
namer.Build("1")           // "" (dimensionless)
```

--------------------------------

### Usage of LabelNamer

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Examples demonstrating how to instantiate and use LabelNamer to normalize label strings.

```go
namer := LabelNamer{UTF8Allowed: false}
result := namer.Build("http.method") // "http_method"
```

```go
namer := LabelNamer{UTF8Allowed: false}
namer.Build("http.method")     // "http_method"
namer.Build("123invalid")      // "key_123invalid"
namer.Build("__reserved__")    // "__reserved__" (preserved)
```

--------------------------------

### Quick Start with otlptranslator

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Demonstrates initializing a MetricNamer and translating OTLP metrics and labels to Prometheus format.

```go
package main

import (
    "fmt"
    "github.com/prometheus/otlptranslator"
)

func main() {
    // Create a metric namer using traditional Prometheus name translation, with suffixes added and UTF-8 disallowed.
    strategy := otlptranslator.UnderscoreEscapingWithSuffixes
    namer := otlptranslator.NewMetricNamer("myapp", strategy)

    // Translate OTLP metric to Prometheus format
    metric := otlptranslator.Metric{
        Name: "http.server.request.duration",
        Unit: "s",
        Type: otlptranslator.MetricTypeHistogram,
    }
    fmt.Println(namer.Build(metric)) // Output: myapp_http_server_request_duration_seconds

    // Translate label names
    labelNamer := otlptranslator.LabelNamer{UTF8Allowed: false}
    fmt.Println(labelNamer.Build("http.method")) // Output: http_method
}
```

--------------------------------

### MetricNamer Build Examples

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Demonstrates how MetricNamer applies suffixes based on metric type and unit.

```go
namer := MetricNamer{WithMetricSuffixes: true, UTF8Allowed: false}

// Counter gets _total suffix
counter := Metric{Name: "requests.count", Unit: "1", Type: MetricTypeMonotonicCounter}
result := namer.Build(counter) // "requests_count_total"

// Gauge with unit suffix
gauge := Metric{Name: "memory.usage", Unit: "By", Type: MetricTypeGauge}
result = namer.Build(gauge) // "memory_usage_bytes"
```

--------------------------------

### Configure Translation Options

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Examples of different MetricNamer configurations including compliant mode, pass-through mode, and namespacing.

```go
// Prometheus-compliant mode - supports [a-zA-Z0-9:_]
compliantNamer := otlptranslator.MetricNamer{UTF8Allowed: false, WithMetricSuffixes: true}

// Transparent pass-through mode, aka "NoTranslation"
utf8Namer := otlptranslator.MetricNamer{UTF8Allowed: true, WithMetricSuffixes: false}
utf8Namer = otlptranslator.NewMetricNamer("", otlpTranslator.NoTranslation)

// With namespace and suffixes
productionNamer := otlptranslator.MetricNamer{
    Namespace:          "myservice",
    WithMetricSuffixes: true,
    UTF8Allowed:        false,
}
```

--------------------------------

### MetricNamer Constructor and Build Method

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Signatures for creating a MetricNamer and building metric names.

```go
func NewMetricNamer(namespace string, strategy TranslationStrategyOption) MetricNamer
```

```go
func (mn *MetricNamer) Build(metric Metric) (string, error)
```

--------------------------------

### Translate Metric Names

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Shows how to handle metric suffixes and unit conversions using MetricNamer.

```go
namer := otlptranslator.MetricNamer{WithMetricSuffixes: true, UTF8Allowed: false}

// Counter gets _total suffix
counter := otlptranslator.Metric{
    Name: "requests.count", Unit: "1", Type: otlptranslator.MetricTypeMonotonicCounter,
}
fmt.Println(namer.Build(counter)) // requests_count_total

// Gauge with unit conversion
gauge := otlptranslator.Metric{
    Name: "memory.usage", Unit: "By", Type: otlptranslator.MetricTypeGauge,
}
fmt.Println(namer.Build(gauge)) // memory_usage_bytes

// Dimensionless gauge gets _ratio suffix
ratio := otlptranslator.Metric{
    Name: "cpu.utilization", Unit: "1", Type: otlptranslator.MetricTypeGauge,
}
fmt.Println(namer.Build(ratio)) // cpu_utilization_ratio
```

--------------------------------

### Build Unit Name

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Method signature for building a unit name from an OTLP unit string.

```go
func (*UnitNamer) Build(unit string) string
```

--------------------------------

### LabelNamer Build Method

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Signature for the Build method used to normalize labels.

```go
func (ln *LabelNamer) Build(label string) (string, error)
```

--------------------------------

### Translate Labels

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Demonstrates how LabelNamer handles various input strings to ensure Prometheus compliance.

```go
labelNamer := otlptranslator.LabelNamer{UTF8Allowed: false}

labelNamer.Build("http.method")           // http_method
labelNamer.Build("123invalid")            // key_123invalid
labelNamer.Build("_private")              // key_private
labelNamer.Build("__reserved__")          // __reserved__ (preserved)
labelNamer.Build("label@with$symbols")    // label_with_symbols
```

--------------------------------

### Define LabelNamer Struct

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Configuration struct for building Prometheus-compliant label names from OTLP attributes.

```go
type LabelNamer struct {
	UTF8Allowed bool
	// UnderscoreLabelSanitization, if true, enabled prepending 'key' to labels
	// starting with '_'. Reserved labels starting with `__` are not modified.
	//
	// Deprecated: This will be removed in a future version of otlptranslator.
	UnderscoreLabelSanitization bool
	// PreserveMultipleUnderscores enables preserving of multiple
	// consecutive underscores in label names when UTF8Allowed is false.
	// This option is discouraged as it violates the OpenTelemetry to Prometheus
	// specification https://github.com/open-telemetry/opentelemetry-specification/blob/v1.38.0/specification/compatibility/prometheus_and_openmetrics.md#otlp-metric-points-to-prometheus),
	// but may be needed for compatibility with legacy systems that rely on the old behavior.
	PreserveMultipleUnderscores bool
}
```

--------------------------------

### TranslationStrategyOption Constants

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Available strategies for OTLP to Prometheus name translation, ranging from standard escaping to experimental no-translation modes.

```go
var (
	// NoUTF8EscapingWithSuffixes will accept metric/label names as they are. Unit
	// and type suffixes may be added to metric names, according to certain rules.
	NoUTF8EscapingWithSuffixes TranslationStrategyOption = "NoUTF8EscapingWithSuffixes"
	// UnderscoreEscapingWithSuffixes is the default option for translating OTLP
	// to Prometheus. This option will translate metric name characters that are
	// not alphanumerics/underscores/colons to underscores, and label name
	// characters that are not alphanumerics/underscores to underscores. Unit and
	// type suffixes may be appended to metric names, according to certain rules.
	UnderscoreEscapingWithSuffixes TranslationStrategyOption = "UnderscoreEscapingWithSuffixes"
	// UnderscoreEscapingWithoutSuffixes translates metric name characters that
	// are not alphanumerics/underscores/colons to underscores, and label name
	// characters that are not alphanumerics/underscores to underscores, but
	// unlike UnderscoreEscapingWithSuffixes it does not append any suffixes to
	// the names.
	UnderscoreEscapingWithoutSuffixes TranslationStrategyOption = "UnderscoreEscapingWithoutSuffixes"
	// NoTranslation (EXPERIMENTAL): disables all translation of incoming metric
	// and label names. This offers a way for the OTLP users to use native metric
	// names, reducing confusion.
	//
	// WARNING: This setting has significant known risks and limitations (see
	// https://prometheus.io/docs/practices/naming/  for details): * Impaired UX
	// when using PromQL in plain YAML (e.g. alerts, rules, dashboard, autoscaling
	// configuration). * Series collisions which in the best case may result in
	// OOO errors, in the worst case a silently malformed time series. For
	// instance, you may end up in situation of ingesting `foo.bar` series with
	// unit `seconds` and a separate series `foo.bar` with unit `milliseconds`.
	//
	// As a result, this setting is experimental and currently, should not be used
	// in production systems.
	//
	// TODO(ArthurSens): Mention `type-and-unit-labels` feature
	// (https://github.com/prometheus/proposals/pull/39) once released, as
	// potential mitigation of the above risks.
	NoTranslation TranslationStrategyOption = "NoTranslation"
)
```

--------------------------------

### UnitNamer.Build

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Converts OTLP unit strings into Prometheus-compliant unit names.

```APIDOC
## func (*UnitNamer) Build

### Description
Processes an OTLP unit string and converts it to a Prometheus-compliant unit name based on the UnitNamer configuration.

### Parameters
- **unit** (string) - Required - The OTLP unit string to convert.

### Returns
- (string) - The converted Prometheus-compliant unit name.
```

--------------------------------

### Translate Units

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Shows how UnitNamer converts OTLP unit strings into standard Prometheus unit names.

```go
unitNamer := otlptranslator.UnitNamer{UTF8Allowed: false}

unitNamer.Build("s")           // seconds
unitNamer.Build("By")          // bytes
unitNamer.Build("requests/s")  // requests_per_second
unitNamer.Build("1")           // "" (dimensionless)
```

--------------------------------

### Define MetricNamer Struct

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Configuration struct for converting OTLP metric names to Prometheus-compliant names.

```go
type MetricNamer struct {
	Namespace          string
	WithMetricSuffixes bool
	UTF8Allowed        bool
}
```

```go
namer := MetricNamer{
	WithMetricSuffixes: true,
	UTF8Allowed:        false,
}

metric := Metric{
	Name: "http.server.duration",
	Unit: "s",
	Type: MetricTypeHistogram,
}

result := namer.Build(metric) // "http_server_duration_seconds"
```

--------------------------------

### Check Translation Strategy Suffixes and Escaping

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Methods to determine if a specific translation strategy requires suffix addition or metric name escaping.

```go
func (o TranslationStrategyOption) ShouldAddSuffixes() bool
```

```go
func (o TranslationStrategyOption) ShouldEscape() bool
```

--------------------------------

### Define OTLP to Prometheus Constants

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Constants representing keys and metric names used for mapping OpenTelemetry concepts like trace IDs, span IDs, and scope metadata to Prometheus.

```go
const (
	// 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"
	// 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"
)
```

--------------------------------

### Define UnitNamer

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Helper struct for converting OTLP unit strings into Prometheus-compliant unit names.

```go
type UnitNamer struct {
	UTF8Allowed bool
}
```

--------------------------------

### func (*MetricNamer) Build

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Builds a Prometheus-compliant metric name based on the provided Metric struct and the MetricNamer configuration.

```APIDOC
## func (*MetricNamer) Build(metric Metric) (string, error)

### Description
Builds a metric name for the specified metric. The method applies transformations based on the MetricNamer configuration, such as escaping invalid characters, adding metric suffixes based on type and unit, and handling UTF-8 compliance.

### Parameters
- **metric** (Metric) - Required - The metric object containing Name, Unit, and Type.

### Returns
- **string** - The resulting Prometheus-compliant metric name.
- **error** - An error if the translation fails.
```

--------------------------------

### Define Metric Type Constants

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Enumeration of supported metric types for translation, including counters, gauges, and histograms.

```go
const (
	// MetricTypeUnknown represents an unknown metric type.
	MetricTypeUnknown = iota
	// MetricTypeNonMonotonicCounter represents a counter that is not monotonically increasing, also known as delta counter.
	MetricTypeNonMonotonicCounter
	// MetricTypeMonotonicCounter represents a counter that is monotonically increasing, also known as cumulative counter.
	MetricTypeMonotonicCounter
	// MetricTypeGauge represents a gauge metric.
	MetricTypeGauge
	// MetricTypeHistogram represents a histogram metric.
	MetricTypeHistogram
	// MetricTypeExponentialHistogram represents an exponential histogram metric.
	MetricTypeExponentialHistogram
	// MetricTypeSummary represents a summary metric.
	MetricTypeSummary
)
```

--------------------------------

### Define Metric Struct

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Helper struct representing an OpenTelemetry metric with name, unit, and type.

```go
type Metric struct {
	Name string
	Unit string
	Type MetricType
}
```

```go
metric := Metric{
	Name: "http.server.request.duration",
	Unit: "s",
	Type: MetricTypeHistogram,
}
```

--------------------------------

### Define MetricType

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Representation of OpenTelemetry metric types.

```go
type MetricType int
```

--------------------------------

### TranslationStrategyOption

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Defines how metric and label names are handled during translation. Users can choose between various escaping and suffixing strategies.

```APIDOC
## TranslationStrategyOption

### Description
Constants defining the strategy for translating OTLP metric and label names to Prometheus format.

### Available Options
- **NoUTF8EscapingWithSuffixes**: Accepts names as-is, potentially adding unit/type suffixes.
- **UnderscoreEscapingWithSuffixes**: Default option; replaces non-alphanumeric characters with underscores and appends suffixes.
- **UnderscoreEscapingWithoutSuffixes**: Replaces non-alphanumeric characters with underscores without appending suffixes.
- **NoTranslation**: Disables all translation (Experimental).
```

--------------------------------

### Define TranslationStrategyOption

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Defines the type for translation strategies used to handle metric and label name conversions.

```go
type TranslationStrategyOption string
```

--------------------------------

### func NewMetricNamer

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Creates a new MetricNamer instance configured with a namespace and a translation strategy.

```APIDOC
## func NewMetricNamer(namespace string, strategy TranslationStrategyOption) MetricNamer

### Description
Creates a MetricNamer with the specified namespace (can be blank) and the requested Translation Strategy.

### Parameters
- **namespace** (string) - Required - The namespace to prepend to metric names.
- **strategy** (TranslationStrategyOption) - Required - The translation strategy configuration.
```

--------------------------------

### func (*LabelNamer) Build

Source: https://pkg.go.dev/github.com/prometheus/otlptranslator

Normalizes a specified label string to follow Prometheus label name standards by replacing invalid characters and handling reserved prefixes.

```APIDOC
## func (*LabelNamer) Build(label string) (string, error)

### Description
Normalizes the specified label to follow Prometheus label names standard. Translation rules include replacing invalid characters with underscores, prefixing labels with invalid start characters (numbers or '_') with "key", and preserving double underscore labels.

### Parameters
- **label** (string) - Required - The OTLP attribute name to be translated.

### Returns
- **string** - The normalized Prometheus-compliant label name.
- **error** - An error if the translation fails.
```
Tokens:
Raw