go.opentelemetry.io/otel/trace v1.47.0: NewSpanContext, TraceIDFromHex, SpanIDFromHex

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/go.opentelemetry.io/otel/trace@v1.47.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.opentelemetry.io/otel/trace@v1.47.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:993bc64747e8d3bcbad34cc727a562c0f108e1e7e22fca02b07509f4d72b0cea","contract":["TraceIDFromHex parses valid 32-character lowercase hex and rejects invalid lengths, uppercase hex, and all-zero IDs","SpanIDFromHex parses valid 16-character lowercase hex and rejects invalid lengths, uppercase hex, and all-zero IDs","NewSpanContext creates SpanContext where IsValid requires both valid TraceID and SpanID, while missing either yields invalid SpanContext","TraceFlags WithSampled toggles sampling bit while IsSampled reports flag status and String formats as two-character hex","SpanContext WithRemote, WithTraceFlags, WithTraceID, and WithSpanID return updated copies preserving immutability of the original"],"goal":"verify pkg:golang/go.opentelemetry.io/otel/trace@v1.47.0","kind":"HOW","packages":["pkg:golang/go.opentelemetry.io/otel/trace@v1.47.0"],"schemaVersion":1,"symbols":["go.opentelemetry.io/otel/trace.NewSpanContext","go.opentelemetry.io/otel/trace.TraceIDFromHex","go.opentelemetry.io/otel/trace.SpanIDFromHex","go.opentelemetry.io/otel/trace.SpanContext","go.opentelemetry.io/otel/trace.TraceFlags"]},"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/go.opentelemetry.io/otel/trace@v1.47.0"],"schemaVersion":1,"subject":"pkg:golang/go.opentelemetry.io/otel/trace@v1.47.0","symbols":["go.opentelemetry.io/otel/trace.NewSpanContext","go.opentelemetry.io/otel/trace.TraceIDFromHex","go.opentelemetry.io/otel/trace.SpanIDFromHex","go.opentelemetry.io/otel/trace.SpanContext","go.opentelemetry.io/otel/trace.TraceFlags"],"verifierAdapter":"golang@1"}

module sample

go 1.26.0

require go.opentelemetry.io/otel/trace v1.47.0

require (
	github.com/cespare/xxhash/v2 v2.3.0 // indirect
	go.opentelemetry.io/otel v1.47.0 // indirect
)

github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
go.opentelemetry.io/otel v1.47.0 h1:j7ALJ/zgkS7Z6aeJW09p8VC9804bC+PpeTfCD4XPnOM=
go.opentelemetry.io/otel v1.47.0/go.mod h1:8wS9O2qfXrYrzp6hIF/HOYJJf/wIhFPhR2xLuP+iXQU=
go.opentelemetry.io/otel/trace v1.47.0 h1:JOjX/Oci8K94QHddo+bbfya/Ai/nf6/dt9ZfrFNWSrM=
go.opentelemetry.io/otel/trace v1.47.0/go.mod h1:jNaSLa2PZEYFG6fRjJABAu+bw4FS08uDmPg28lTghu0=
go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/go.opentelemetry.io/otel/trace@v1.47.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.opentelemetry.io/otel/trace@v1.47.0"
  ],
  "symbols": [
    "go.opentelemetry.io/otel/trace.NewSpanContext",
    "go.opentelemetry.io/otel/trace.TraceIDFromHex",
    "go.opentelemetry.io/otel/trace.SpanIDFromHex",
    "go.opentelemetry.io/otel/trace.SpanContext",
    "go.opentelemetry.io/otel/trace.TraceFlags"
  ]
}

package main

import (
	"fmt"
	"os"

	"go.opentelemetry.io/otel/trace"
	"sample"
)

func main() {
	// Assertion 1: TraceIDFromHex parses valid 32-character lowercase hex and rejects invalid lengths, uppercase hex, and all-zero IDs
	validTraceHex := "4bf92f3577b34da6a3ce929d0e0e4736"
	tid, err := sample.ParseTraceID(validTraceHex)
	if err != nil {
		fmt.Fprintf(os.Stderr, "assertion 1 failed: ParseTraceID returned error: %v\n", err)
		os.Exit(1)
	}
	if !tid.IsValid() {
		fmt.Fprintf(os.Stderr, "assertion 1 failed: expected valid TraceID\n")
		os.Exit(1)
	}
	if tid.String() != validTraceHex {
		fmt.Fprintf(os.Stderr, "assertion 1 failed: expected %s, got %s\n", validTraceHex, tid.String())
		os.Exit(1)
	}
	for _, invalid := range []string{"", "4bf9", "4bf92f3577b34da6a3ce929d0e0e473", "4bf92f3577b34da6a3ce929d0e0e473600"} {
		if _, err := sample.ParseTraceID(invalid); err == nil {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: expected error for length %q\n", invalid)
			os.Exit(1)
		}
	}
	if _, err := sample.ParseTraceID("4BF92F3577B34DA6A3CE929D0E0E4736"); err == nil {
		fmt.Fprintf(os.Stderr, "assertion 1 failed: expected error for uppercase hex\n")
		os.Exit(1)
	}
	if _, err := sample.ParseTraceID("00000000000000000000000000000000"); err == nil {
		fmt.Fprintf(os.Stderr, "assertion 1 failed: expected error for all-zero ID\n")
		os.Exit(1)
	}

	// Assertion 2: SpanIDFromHex parses valid 16-character lowercase hex and rejects invalid lengths, uppercase hex, and all-zero IDs
	validSpanHex := "00f067aa0ba902b7"
	sid, err := sample.ParseSpanID(validSpanHex)
	if err != nil {
		fmt.Fprintf(os.Stderr, "assertion 2 failed: ParseSpanID returned error: %v\n", err)
		os.Exit(1)
	}
	if !sid.IsValid() {
		fmt.Fprintf(os.Stderr, "assertion 2 failed: expected valid SpanID\n")
		os.Exit(1)
	}
	if sid.String() != validSpanHex {
		fmt.Fprintf(os.Stderr, "assertion 2 failed: expected %s, got %s\n", validSpanHex, sid.String())
		os.Exit(1)
	}
	for _, invalid := range []string{"", "00f0", "00f067aa0ba902b", "00f067aa0ba902b700"} {
		if _, err := sample.ParseSpanID(invalid); err == nil {
			fmt.Fprintf(os.Stderr, "assertion 2 failed: expected error for length %q\n", invalid)
			os.Exit(1)
		}
	}
	if _, err := sample.ParseSpanID("00F067AA0BA902B7"); err == nil {
		fmt.Fprintf(os.Stderr, "assertion 2 failed: expected error for uppercase hex\n")
		os.Exit(1)
	}
	if _, err := sample.ParseSpanID("0000000000000000"); err == nil {
		fmt.Fprintf(os.Stderr, "assertion 2 failed: expected error for all-zero ID\n")
		os.Exit(1)
	}

	// Assertion 3: NewSpanContext creates SpanContext where IsValid requires both valid TraceID and SpanID, while missing either yields invalid SpanContext
	scValid := sample.CreateSpanContext(trace.SpanContextConfig{
		TraceID: tid,
		SpanID:  sid,
	})
	if !scValid.IsValid() {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: expected valid SpanContext\n")
		os.Exit(1)
	}
	if !scValid.HasTraceID() || !scValid.HasSpanID() {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: expected HasTraceID and HasSpanID to be true\n")
		os.Exit(1)
	}
	if scValid.TraceID() != tid || scValid.SpanID() != sid {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: IDs mismatch\n")
		os.Exit(1)
	}

	scNoTrace := sample.CreateSpanContext(trace.SpanContextConfig{SpanID: sid})
	if scNoTrace.IsValid() || scNoTrace.HasTraceID() || !scNoTrace.HasSpanID() {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: expected invalid without TraceID\n")
		os.Exit(1)
	}

	scNoSpan := sample.CreateSpanContext(trace.SpanContextConfig{TraceID: tid})
	if scNoSpan.IsValid() || !scNoSpan.HasTraceID() || scNoSpan.HasSpanID() {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: expected invalid without SpanID\n")
		os.Exit(1)
	}

	scEmpty := sample.CreateSpanContext(trace.SpanContextConfig{})
	if scEmpty.IsValid() || scEmpty.HasTraceID() || scEmpty.HasSpanID() {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: expected empty SpanContext to be invalid\n")
		os.Exit(1)
	}

	// Assertion 4: TraceFlags WithSampled toggles sampling bit while IsSampled reports flag status and String formats as two-character hex
	var flags trace.TraceFlags
	if flags.IsSampled() || flags.String() != "00" {
		fmt.Fprintf(os.Stderr, "assertion 4 failed: zero flags unexpected: %s\n", flags.String())
		os.Exit(1)
	}
	sampled := sample.ToggleSampled(flags, true)
	if !sampled.IsSampled() || sampled != trace.FlagsSampled || sampled.String() != "01" {
		fmt.Fprintf(os.Stderr, "assertion 4 failed: sampled flags unexpected: %s\n", sampled.String())
		os.Exit(1)
	}
	cleared := sample.ToggleSampled(sampled, false)
	if cleared.IsSampled() || cleared.String() != "00" {
		fmt.Fprintf(os.Stderr, "assertion 4 failed: cleared flags unexpected: %s\n", cleared.String())
		os.Exit(1)
	}

	// Assertion 5: SpanContext WithRemote, WithTraceFlags, WithTraceID, and WithSpanID return updated copies preserving immutability of the original
	orig := sample.CreateSpanContext(trace.SpanContextConfig{
		TraceID: tid,
		SpanID:  sid,
		Remote:  false,
	})
	remoteSC := sample.CloneWithRemote(orig, true)
	if !remoteSC.IsRemote() || orig.IsRemote() {
		fmt.Fprintf(os.Stderr, "assertion 5 failed: WithRemote mutation issue\n")
		os.Exit(1)
	}
	flagSC := orig.WithTraceFlags(trace.FlagsSampled)
	if !flagSC.IsSampled() || orig.IsSampled() {
		fmt.Fprintf(os.Stderr, "assertion 5 failed: WithTraceFlags mutation issue\n")
		os.Exit(1)
	}
	tid2, _ := sample.ParseTraceID("0123456789abcdef0123456789abcdef")
	sid2, _ := sample.ParseSpanID("abcdef0123456789")
	traceSC := orig.WithTraceID(tid2)
	if traceSC.TraceID() != tid2 || orig.TraceID() != tid {
		fmt.Fprintf(os.Stderr, "assertion 5 failed: WithTraceID mutation issue\n")
		os.Exit(1)
	}
	spanSC := orig.WithSpanID(sid2)
	if spanSC.SpanID() != sid2 || orig.SpanID() != sid {
		fmt.Fprintf(os.Stderr, "assertion 5 failed: WithSpanID mutation issue\n")
		os.Exit(1)
	}
	if !orig.Equal(sample.CreateSpanContext(trace.SpanContextConfig{TraceID: tid, SpanID: sid, Remote: false})) {
		fmt.Fprintf(os.Stderr, "assertion 5 failed: orig Equal failed\n")
		os.Exit(1)
	}

	fmt.Println("All contract assertions passed successfully.")
}

package sample

import (
	"go.opentelemetry.io/otel/trace"
)

// ParseTraceID wraps trace.TraceIDFromHex to decode a 32-hex trace ID.
func ParseTraceID(hex string) (trace.TraceID, error) {
	return trace.TraceIDFromHex(hex)
}

// ParseSpanID wraps trace.SpanIDFromHex to decode a 16-hex span ID.
func ParseSpanID(hex string) (trace.SpanID, error) {
	return trace.SpanIDFromHex(hex)
}

// CreateSpanContext wraps trace.NewSpanContext to initialize a SpanContext.
func CreateSpanContext(cfg trace.SpanContextConfig) trace.SpanContext {
	return trace.NewSpanContext(cfg)
}

// ToggleSampled wraps trace.TraceFlags.WithSampled to set or clear the sampling bit.
func ToggleSampled(flags trace.TraceFlags, sampled bool) trace.TraceFlags {
	return flags.WithSampled(sampled)
}

// CloneWithRemote wraps trace.SpanContext.WithRemote to produce an updated copy.
func CloneWithRemote(sc trace.SpanContext, remote bool) trace.SpanContext {
	return sc.WithRemote(remote)
}