github.com/prometheus/otlptranslator v1.0.0

# pkg:golang/github.com/prometheus/otlptranslator@v1.0.0

This code sample demonstrates translating OpenTelemetry metric and attribute names to Prometheus-compliant formats using `github.com/prometheus/otlptranslator@v1.0.0`.

## Verified Features

1. **TranslationStrategyOption**:
   - `UnderscoreEscapingWithSuffixes`: Escapes invalid characters to underscores and appends type/unit suffixes.
   - `UnderscoreEscapingWithoutSuffixes`: Escapes invalid characters to underscores without appending suffixes.
   - `NoUTF8EscapingWithSuffixes`: Preserves UTF-8 characters while appending suffixes.
   - `NoTranslation`: Preserves incoming metric and label names without translation.

2. **MetricNamer**:
   - Translates metric names according to Prometheus conventions.
   - Appends unit suffixes (e.g., `By` to `_bytes`, `s` to `_seconds`).
   - Appends type suffixes (e.g., `_total` for monotonic counters).
   - Supports namespace prefixing.

3. **LabelNamer**:
   - Replaces dots with underscores when UTF-8 escaping is required.
   - Prepends `key_` to labels starting with digits.
   - Preserves reserved double-underscore labels.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:golang/github.com/prometheus/otlptranslator@v1.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/prometheus/otlptranslator@v1.0.0

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:9558170fbe9a02cf57540af3045af22408a55622edac468e8b5f6df8f9fbc902","contract":["assert UnderscoreEscapingWithSuffixes enables escaping","assert UnderscoreEscapingWithSuffixes enables suffix addition","assert UnderscoreEscapingWithoutSuffixes enables escaping","assert UnderscoreEscapingWithoutSuffixes disables suffix addition","assert NoUTF8EscapingWithSuffixes disables escaping","assert NoUTF8EscapingWithSuffixes enables suffix addition","assert NoTranslation disables escaping","assert NoTranslation disables suffix addition","assert MetricNamer with UnderscoreEscapingWithSuffixes normalizes counter name and appends _total","assert MetricNamer with UnderscoreEscapingWithSuffixes normalizes gauge name and translates By unit to bytes","assert MetricNamer with UnderscoreEscapingWithSuffixes normalizes histogram name and translates s unit to seconds","assert MetricNamer prepends configured namespace to normalized metric name","assert MetricNamer with UnderscoreEscapingWithoutSuffixes escapes characters without appending type or unit suffixes","assert MetricNamer with NoTranslation preserves original metric name unmodified","assert LabelNamer replaces dots with underscores when UTF8Allowed is false","assert LabelNamer prepends key_ to label names starting with digit","assert LabelNamer preserves reserved double underscore label names","assert LabelNamer returns error when label name is empty"],"goal":"verify pkg:golang/github.com/prometheus/otlptranslator@v1.0.0","kind":"HOW","packages":["pkg:golang/github.com/prometheus/otlptranslator@v1.0.0"],"schemaVersion":1},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/prometheus/otlptranslator@v1.0.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/prometheus/otlptranslator@v1.0.0","verifierAdapter":"golang@1"}

module sample

go 1.23.0

require github.com/prometheus/otlptranslator v1.0.0

github.com/prometheus/otlptranslator v1.0.0 h1:s0LJW/iN9dkIH+EnhiD3BlkkP5QVIUVEoIwkU+A6qos=
github.com/prometheus/otlptranslator v1.0.0/go.mod h1:vRYWnXvI6aWGpsdY/mOT/cbeVRBlPWtBNDb7kGR3uKM=

package main

import (
	"fmt"

	"github.com/prometheus/otlptranslator"
)

func main() {
	namer := otlptranslator.NewMetricNamer("myapp", otlptranslator.UnderscoreEscapingWithSuffixes)
	metric := otlptranslator.Metric{
		Name: "http.server.requests",
		Unit: "1",
		Type: otlptranslator.MetricTypeMonotonicCounter,
	}
	promMetric, err := namer.Build(metric)
	if err != nil {
		panic(err)
	}

	labelNamer := otlptranslator.LabelNamer{UTF8Allowed: false}
	promLabel, err := labelNamer.Build("http.status_code")
	if err != nil {
		panic(err)
	}

	fmt.Printf("%s{%s=\"200\"}\n", promMetric, promLabel)
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/github.com/prometheus/otlptranslator@v1.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/prometheus/otlptranslator@v1.0.0"
  ]
}

package main

import (
	"fmt"
	"os"

	"github.com/prometheus/otlptranslator"
)

func assert(cond bool, msg string) {
	if !cond {
		fmt.Fprintf(os.Stderr, "FAIL: %s\n", msg)
		os.Exit(1)
	}
	fmt.Printf("PASS: %s\n", msg)
}

func main() {
	// 1. TranslationStrategyOption behavior
	assert(otlptranslator.UnderscoreEscapingWithSuffixes.ShouldEscape() == true, "assert UnderscoreEscapingWithSuffixes enables escaping")
	assert(otlptranslator.UnderscoreEscapingWithSuffixes.ShouldAddSuffixes() == true, "assert UnderscoreEscapingWithSuffixes enables suffix addition")
	assert(otlptranslator.UnderscoreEscapingWithoutSuffixes.ShouldEscape() == true, "assert UnderscoreEscapingWithoutSuffixes enables escaping")
	assert(otlptranslator.UnderscoreEscapingWithoutSuffixes.ShouldAddSuffixes() == false, "assert UnderscoreEscapingWithoutSuffixes disables suffix addition")
	assert(otlptranslator.NoUTF8EscapingWithSuffixes.ShouldEscape() == false, "assert NoUTF8EscapingWithSuffixes disables escaping")
	assert(otlptranslator.NoUTF8EscapingWithSuffixes.ShouldAddSuffixes() == true, "assert NoUTF8EscapingWithSuffixes enables suffix addition")
	assert(otlptranslator.NoTranslation.ShouldEscape() == false, "assert NoTranslation disables escaping")
	assert(otlptranslator.NoTranslation.ShouldAddSuffixes() == false, "assert NoTranslation disables suffix addition")

	// 2. MetricNamer with UnderscoreEscapingWithSuffixes
	namerDefault := otlptranslator.NewMetricNamer("", otlptranslator.UnderscoreEscapingWithSuffixes)

	// Counter gets _total
	counterMetric := otlptranslator.Metric{
		Name: "http.server.requests",
		Unit: "1",
		Type: otlptranslator.MetricTypeMonotonicCounter,
	}
	counterName, err := namerDefault.Build(counterMetric)
	assert(err == nil && counterName == "http_server_requests_total", "assert MetricNamer with UnderscoreEscapingWithSuffixes normalizes counter name and appends _total")

	// Gauge with byte unit
	gaugeMetric := otlptranslator.Metric{
		Name: "system.memory.usage",
		Unit: "By",
		Type: otlptranslator.MetricTypeGauge,
	}
	gaugeName, err := namerDefault.Build(gaugeMetric)
	assert(err == nil && gaugeName == "system_memory_usage_bytes", "assert MetricNamer with UnderscoreEscapingWithSuffixes normalizes gauge name and translates By unit to bytes")

	// Histogram with seconds unit
	histMetric := otlptranslator.Metric{
		Name: "http.server.request.duration",
		Unit: "s",
		Type: otlptranslator.MetricTypeHistogram,
	}
	histName, err := namerDefault.Build(histMetric)
	assert(err == nil && histName == "http_server_request_duration_seconds", "assert MetricNamer with UnderscoreEscapingWithSuffixes normalizes histogram name and translates s unit to seconds")

	// MetricNamer with custom namespace
	namerNamespace := otlptranslator.NewMetricNamer("app", otlptranslator.UnderscoreEscapingWithSuffixes)
	nsName, err := namerNamespace.Build(gaugeMetric)
	assert(err == nil && nsName == "app_system_memory_usage_bytes", "assert MetricNamer prepends configured namespace to normalized metric name")

	// 3. MetricNamer with UnderscoreEscapingWithoutSuffixes
	namerNoSuffixes := otlptranslator.NewMetricNamer("", otlptranslator.UnderscoreEscapingWithoutSuffixes)
	noSuffixName, err := namerNoSuffixes.Build(counterMetric)
	assert(err == nil && noSuffixName == "http_server_requests", "assert MetricNamer with UnderscoreEscapingWithoutSuffixes escapes characters without appending type or unit suffixes")

	// 4. MetricNamer with NoTranslation
	namerNoTrans := otlptranslator.NewMetricNamer("", otlptranslator.NoTranslation)
	noTransName, err := namerNoTrans.Build(histMetric)
	assert(err == nil && noTransName == "http.server.request.duration", "assert MetricNamer with NoTranslation preserves original metric name unmodified")

	// 5. LabelNamer normalization
	labelNamerLegacy := otlptranslator.LabelNamer{UTF8Allowed: false}
	lbl1, err := labelNamerLegacy.Build("http.status_code")
	assert(err == nil && lbl1 == "http_status_code", "assert LabelNamer replaces dots with underscores when UTF8Allowed is false")

	lblDigit, err := labelNamerLegacy.Build("99_bottles")
	assert(err == nil && lblDigit == "key_99_bottles", "assert LabelNamer prepends key_ to label names starting with digit")

	lblReserved, err := labelNamerLegacy.Build("__reserved_label__")
	assert(err == nil && lblReserved == "__reserved_label__", "assert LabelNamer preserves reserved double underscore label names")

	_, errEmpty := labelNamerLegacy.Build("")
	assert(errEmpty != nil, "assert LabelNamer returns error when label name is empty")

	fmt.Println("ALL CONTRACT TESTS PASSED")
}