go.opentelemetry.io/otel/trace v1.24.0: SpanContext

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

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

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:959ee68930a98723e7c35bf8c27a1c2c4b305d1efb22f257ee5e0efb1ef71c9e","contract":["Default uninitialized SpanContext is invalid and has no TraceID or SpanID","NewSpanContext with valid TraceID and SpanID produces a valid SpanContext","NewSpanContext returns an invalid SpanContext if either TraceID or SpanID is zero","IsSampled returns true only when FlagsSampled bit is set in TraceFlags","IsRemote and WithRemote report and toggle remote status correctly","SpanContext Equal returns true for matching contexts and false when attributes differ"],"goal":"verify SpanContext in pkg:golang/go.opentelemetry.io/otel/trace@v1.24.0","kind":"HOW","packages":["pkg:golang/go.opentelemetry.io/otel/trace@v1.24.0"],"schemaVersion":1,"symbols":["SpanContext"]},"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.24.0"],"schemaVersion":1,"subject":"pkg:golang/go.opentelemetry.io/otel/trace@v1.24.0","symbols":["SpanContext"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

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

require go.opentelemetry.io/otel v1.24.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.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
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.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
go.opentelemetry.io/otel v1.24.0 h1:0LAOdjNmQeSTzGBzduGe/rU4tZhMwL5rWgtp9Ku5Jfo=
go.opentelemetry.io/otel v1.24.0/go.mod h1:W7b9Ozg4nkF5tWI5zsXkaKKDjdVjpD4oAt9Qi/MArHo=
go.opentelemetry.io/otel/trace v1.24.0 h1:CsKnnL4dUAr/0llH9FKuc698G04IrpWV0MQA/Y1YELI=
go.opentelemetry.io/otel/trace v1.24.0/go.mod h1:HPc3Xr/cOApsBI154IU0OI0HJexz+aw5uPdbs3UCjNU=
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"
)

// BuildSpanContext constructs a trace.SpanContext with the given hex trace ID, hex span ID, sampled flag, and remote flag.
func BuildSpanContext(traceIDHex, spanIDHex string, sampled bool, remote bool) (trace.SpanContext, error) {
	tid, err := trace.TraceIDFromHex(traceIDHex)
	if err != nil {
		return trace.SpanContext{}, fmt.Errorf("invalid trace ID hex: %w", err)
	}

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

	var flags trace.TraceFlags
	if sampled {
		flags |= trace.FlagsSampled
	}

	cfg := trace.SpanContextConfig{
		TraceID:    tid,
		SpanID:     sid,
		TraceFlags: flags,
		Remote:     remote,
	}

	return trace.NewSpanContext(cfg), nil
}

// BuildSpanContextWithState constructs a SpanContext with TraceState.
func BuildSpanContextWithState(traceIDHex, spanIDHex string, state trace.TraceState) (trace.SpanContext, error) {
	tid, err := trace.TraceIDFromHex(traceIDHex)
	if err != nil {
		return trace.SpanContext{}, fmt.Errorf("invalid trace ID hex: %w", err)
	}

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

	cfg := trace.SpanContextConfig{
		TraceID:    tid,
		SpanID:     sid,
		TraceState: state,
	}

	return trace.NewSpanContext(cfg), nil
}

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

package main

import (
	"fmt"
	"os"

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

func main() {
	// Assertion 1: Default uninitialized SpanContext is invalid and has no TraceID or SpanID
	defaultSC := trace.SpanContext{}
	if defaultSC.IsValid() {
		fmt.Fprintf(os.Stderr, "expected default SpanContext to be invalid\n")
		os.Exit(1)
	}
	if defaultSC.HasTraceID() {
		fmt.Fprintf(os.Stderr, "expected default SpanContext to have no TraceID\n")
		os.Exit(1)
	}
	if defaultSC.HasSpanID() {
		fmt.Fprintf(os.Stderr, "expected default SpanContext to have no SpanID\n")
		os.Exit(1)
	}

	// Assertion 2: NewSpanContext with valid TraceID and SpanID produces a valid SpanContext
	const traceIDStr = "4bf92f3577b34da6a3ce929d0e0e4736"
	const spanIDStr = "00f067aa0ba902b7"
	sc, err := sample.BuildSpanContext(traceIDStr, spanIDStr, true, false)
	if err != nil {
		fmt.Fprintf(os.Stderr, "unexpected error constructing SpanContext: %v\n", err)
		os.Exit(1)
	}
	if !sc.IsValid() {
		fmt.Fprintf(os.Stderr, "expected constructed SpanContext to be valid\n")
		os.Exit(1)
	}
	if !sc.HasTraceID() || sc.TraceID().String() != traceIDStr {
		fmt.Fprintf(os.Stderr, "TraceID mismatch: got %q, want %q\n", sc.TraceID().String(), traceIDStr)
		os.Exit(1)
	}
	if !sc.HasSpanID() || sc.SpanID().String() != spanIDStr {
		fmt.Fprintf(os.Stderr, "SpanID mismatch: got %q, want %q\n", sc.SpanID().String(), spanIDStr)
		os.Exit(1)
	}

	// Assertion 3: NewSpanContext returns an invalid SpanContext if either TraceID or SpanID is zero
	tid, _ := trace.TraceIDFromHex(traceIDStr)
	scNoSpan := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID: tid,
	})
	if scNoSpan.IsValid() {
		fmt.Fprintf(os.Stderr, "expected SpanContext without SpanID to be invalid\n")
		os.Exit(1)
	}
	sid, _ := trace.SpanIDFromHex(spanIDStr)
	scNoTrace := trace.NewSpanContext(trace.SpanContextConfig{
		SpanID: sid,
	})
	if scNoTrace.IsValid() {
		fmt.Fprintf(os.Stderr, "expected SpanContext without TraceID to be invalid\n")
		os.Exit(1)
	}

	// Assertion 4: IsSampled returns true only when FlagsSampled bit is set in TraceFlags
	if !sc.IsSampled() {
		fmt.Fprintf(os.Stderr, "expected sc.IsSampled() to be true\n")
		os.Exit(1)
	}
	unsampledSC, err := sample.BuildSpanContext(traceIDStr, spanIDStr, false, false)
	if err != nil {
		fmt.Fprintf(os.Stderr, "unexpected error constructing unsampled SpanContext: %v\n", err)
		os.Exit(1)
	}
	if unsampledSC.IsSampled() {
		fmt.Fprintf(os.Stderr, "expected unsampledSC.IsSampled() to be false\n")
		os.Exit(1)
	}

	// Assertion 5: IsRemote and WithRemote report and toggle remote status correctly
	if sc.IsRemote() {
		fmt.Fprintf(os.Stderr, "expected sc.IsRemote() to be false initially\n")
		os.Exit(1)
	}
	remoteSC := sc.WithRemote(true)
	if !remoteSC.IsRemote() {
		fmt.Fprintf(os.Stderr, "expected remoteSC.IsRemote() to be true\n")
		os.Exit(1)
	}
	if sc.IsRemote() {
		fmt.Fprintf(os.Stderr, "expected original sc.IsRemote() to still be false\n")
		os.Exit(1)
	}

	// Assertion 6: SpanContext Equal returns true for matching contexts and false when attributes differ
	scCopy, _ := sample.BuildSpanContext(traceIDStr, spanIDStr, true, false)
	if !sc.Equal(scCopy) {
		fmt.Fprintf(os.Stderr, "expected sc.Equal(scCopy) to be true\n")
		os.Exit(1)
	}
	if sc.Equal(remoteSC) {
		fmt.Fprintf(os.Stderr, "expected sc.Equal(remoteSC) to be false due to remote flag difference\n")
		os.Exit(1)
	}
	if sc.Equal(unsampledSC) {
		fmt.Fprintf(os.Stderr, "expected sc.Equal(unsampledSC) to be false due to trace flags difference\n")
		os.Exit(1)
	}

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