go.opentelemetry.io/otel/trace v1.37.0: SpanContextConfig

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 go.opentelemetry.io/otel/trace.SpanContextConfig in pkg:golang/go.opentelemetry.io/otel/trace@v1.37.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.opentelemetry.io/otel/trace@v1.37.0
Demonstrate these symbols/APIs:
  - go.opentelemetry.io/otel/trace.SpanContextConfig

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:20601b67b8da7c7c4d304fe677a303fea8c7dcc4a8c0d015192679f123b9b002","contract":["SpanContextConfig initializes a valid SpanContext with TraceID, SpanID, TraceFlags, TraceState, and Remote flag","SpanContextConfig with zero values produces an invalid SpanContext","SpanContextConfig preserves Remote and TraceFlags even when SpanID or TraceID is zero","SpanContextConfig can be extracted from an existing SpanContext matching all field values"],"goal":"verify go.opentelemetry.io/otel/trace.SpanContextConfig in pkg:golang/go.opentelemetry.io/otel/trace@v1.37.0","kind":"HOW","packages":["pkg:golang/go.opentelemetry.io/otel/trace@v1.37.0"],"schemaVersion":1,"symbols":["go.opentelemetry.io/otel/trace.SpanContextConfig"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","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.37.0"],"schemaVersion":1,"subject":"pkg:golang/go.opentelemetry.io/otel/trace@v1.37.0","symbols":["go.opentelemetry.io/otel/trace.SpanContextConfig"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

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

require go.opentelemetry.io/otel v1.37.0 // indirect

github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
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/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
go.opentelemetry.io/otel v1.37.0 h1:9zhNfelUvx0KBfu/gb+ZgeAfAgtWrfHJZcAqFC228wQ=
go.opentelemetry.io/otel v1.37.0/go.mod h1:ehE/umFRLnuLa/vSccNq9oS1ErUlkkK71gMcN34UG8I=
go.opentelemetry.io/otel/trace v1.37.0 h1:HLdcFNbRQBE2imdSEgm/kwqmQj1Or1l/7bW6mxVK7z4=
go.opentelemetry.io/otel/trace v1.37.0/go.mod h1:TlgrlQ+PtQO5XFerSPUYG0JSgGyryXewPGyayAWSBS0=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package sample

import (
	"fmt"

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

// BuildSpanContextConfig constructs a SpanContextConfig from hex IDs and state parameters.
func BuildSpanContextConfig(traceIDHex, spanIDHex string, sampled, remote bool, traceStateRaw string) (trace.SpanContextConfig, error) {
	var cfg trace.SpanContextConfig

	if traceIDHex != "" {
		tid, err := trace.TraceIDFromHex(traceIDHex)
		if err != nil {
			return cfg, fmt.Errorf("invalid trace id: %w", err)
		}
		cfg.TraceID = tid
	}

	if spanIDHex != "" {
		sid, err := trace.SpanIDFromHex(spanIDHex)
		if err != nil {
			return cfg, fmt.Errorf("invalid span id: %w", err)
		}
		cfg.SpanID = sid
	}

	if sampled {
		cfg.TraceFlags = trace.FlagsSampled
	}

	if traceStateRaw != "" {
		ts, err := trace.ParseTraceState(traceStateRaw)
		if err != nil {
			return cfg, fmt.Errorf("invalid trace state: %w", err)
		}
		cfg.TraceState = ts
	}

	cfg.Remote = remote
	return cfg, nil
}

// NewSpanContextFromConfig creates a SpanContext from a SpanContextConfig.
func NewSpanContextFromConfig(cfg trace.SpanContextConfig) trace.SpanContext {
	return trace.NewSpanContext(cfg)
}

// ExtractConfig extracts a SpanContextConfig from an existing SpanContext.
func ExtractConfig(sc trace.SpanContext) trace.SpanContextConfig {
	return trace.SpanContextConfig{
		TraceID:    sc.TraceID(),
		SpanID:     sc.SpanID(),
		TraceFlags: sc.TraceFlags(),
		TraceState: sc.TraceState(),
		Remote:     sc.IsRemote(),
	}
}

{
  "schemaVersion": 1,
  "goal": "verify go.opentelemetry.io/otel/trace.SpanContextConfig in pkg:golang/go.opentelemetry.io/otel/trace@v1.37.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.opentelemetry.io/otel/trace@v1.37.0"
  ],
  "symbols": [
    "go.opentelemetry.io/otel/trace.SpanContextConfig"
  ]
}

package main

import (
	"fmt"
	"os"

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

func main() {
	if err := runTests(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract test failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("All SpanContextConfig contract tests passed successfully.")
}

func runTests() error {
	const (
		validTraceHex = "4bf92f3577b34da6a3ce929d0e0e4736"
		validSpanHex  = "00f067aa0ba902b7"
		rawTraceState = "vendor1=opaqueValue,vendor2=12345"
	)

	// 1. SpanContextConfig initializes a valid SpanContext with TraceID, SpanID, TraceFlags, TraceState, and Remote flag
	cfg, err := sample.BuildSpanContextConfig(validTraceHex, validSpanHex, true, true, rawTraceState)
	if err != nil {
		return fmt.Errorf("failed to build valid SpanContextConfig: %w", err)
	}

	sc := sample.NewSpanContextFromConfig(cfg)
	if !sc.IsValid() {
		return fmt.Errorf("expected SpanContext to be valid")
	}
	if !sc.HasTraceID() {
		return fmt.Errorf("expected SpanContext to have TraceID")
	}
	if !sc.HasSpanID() {
		return fmt.Errorf("expected SpanContext to have SpanID")
	}
	if sc.TraceID() != cfg.TraceID {
		return fmt.Errorf("expected TraceID %v, got %v", cfg.TraceID, sc.TraceID())
	}
	if sc.SpanID() != cfg.SpanID {
		return fmt.Errorf("expected SpanID %v, got %v", cfg.SpanID, sc.SpanID())
	}
	if sc.TraceFlags() != trace.FlagsSampled {
		return fmt.Errorf("expected FlagsSampled, got %v", sc.TraceFlags())
	}
	if !sc.IsSampled() {
		return fmt.Errorf("expected IsSampled to be true")
	}
	if !sc.IsRemote() {
		return fmt.Errorf("expected IsRemote to be true")
	}
	if sc.TraceState().String() != cfg.TraceState.String() {
		return fmt.Errorf("expected TraceState %q, got %q", cfg.TraceState.String(), sc.TraceState().String())
	}

	// 2. SpanContextConfig with zero values produces an invalid SpanContext
	emptyCfg := trace.SpanContextConfig{}
	emptySC := sample.NewSpanContextFromConfig(emptyCfg)
	if emptySC.IsValid() {
		return fmt.Errorf("expected empty SpanContext to be invalid")
	}
	if emptySC.HasTraceID() {
		return fmt.Errorf("expected empty SpanContext not to have TraceID")
	}
	if emptySC.HasSpanID() {
		return fmt.Errorf("expected empty SpanContext not to have SpanID")
	}
	if emptySC.IsSampled() {
		return fmt.Errorf("expected empty SpanContext not to be sampled")
	}
	if emptySC.IsRemote() {
		return fmt.Errorf("expected empty SpanContext not to be remote")
	}

	// 3. SpanContextConfig preserves Remote and TraceFlags even when SpanID or TraceID is zero
	partialCfg := trace.SpanContextConfig{
		TraceID:    cfg.TraceID,
		SpanID:     trace.SpanID{},
		TraceFlags: trace.FlagsSampled,
		Remote:     true,
	}
	partialSC := sample.NewSpanContextFromConfig(partialCfg)
	if partialSC.IsValid() {
		return fmt.Errorf("expected partial SpanContext (zero SpanID) to be invalid")
	}
	if !partialSC.HasTraceID() {
		return fmt.Errorf("expected partial SpanContext to retain TraceID")
	}
	if partialSC.HasSpanID() {
		return fmt.Errorf("expected partial SpanContext to have zero SpanID")
	}
	if !partialSC.IsRemote() {
		return fmt.Errorf("expected partial SpanContext to retain Remote flag")
	}
	if partialSC.TraceFlags() != trace.FlagsSampled {
		return fmt.Errorf("expected partial SpanContext to retain FlagsSampled")
	}

	// 4. SpanContextConfig can be extracted from an existing SpanContext matching all field values
	extracted := sample.ExtractConfig(sc)
	if extracted.TraceID != cfg.TraceID {
		return fmt.Errorf("extracted TraceID mismatch")
	}
	if extracted.SpanID != cfg.SpanID {
		return fmt.Errorf("extracted SpanID mismatch")
	}
	if extracted.TraceFlags != cfg.TraceFlags {
		return fmt.Errorf("extracted TraceFlags mismatch")
	}
	if extracted.TraceState.String() != cfg.TraceState.String() {
		return fmt.Errorf("extracted TraceState mismatch")
	}
	if extracted.Remote != cfg.Remote {
		return fmt.Errorf("extracted Remote mismatch")
	}

	return nil
}