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

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 NewSpanContext 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:
  - NewSpanContext

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.

package sample_test

import (
	"testing"

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

func TestNewSpanContext_ValidConfig(t *testing.T) {
	tid, err := trace.TraceIDFromHex("4bf92f3577b34da6a3ce929d0e0e4736")
	if err != nil {
		t.Fatalf("unexpected trace ID parse error: %v", err)
	}
	sid, err := trace.SpanIDFromHex("00f067aa0ba902b7")
	if err != nil {
		t.Fatalf("unexpected span ID parse error: %v", err)
	}

	ts, err := trace.ParseTraceState("congo=t61rcWkgMzE,rojo=00f067aa0ba902b7")
	if err != nil {
		t.Fatalf("unexpected trace state parse error: %v", err)
	}

	cfg := trace.SpanContextConfig{
		TraceID:    tid,
		SpanID:     sid,
		TraceFlags: trace.FlagsSampled,
		TraceState: ts,
		Remote:     true,
	}

	sc := trace.NewSpanContext(cfg)

	if !sc.IsValid() {
		t.Fatalf("expected NewSpanContext to produce a valid SpanContext")
	}
	if !sc.HasTraceID() {
		t.Fatalf("expected HasTraceID to be true")
	}
	if !sc.HasSpanID() {
		t.Fatalf("expected HasSpanID to be true")
	}
	if sc.TraceID() != tid {
		t.Fatalf("expected TraceID %v, got %v", tid, sc.TraceID())
	}
	if sc.SpanID() != sid {
		t.Fatalf("expected SpanID %v, got %v", sid, sc.SpanID())
	}
	if sc.TraceFlags() != trace.FlagsSampled {
		t.Fatalf("expected TraceFlags %v, got %v", trace.FlagsSampled, sc.TraceFlags())
	}
	if !sc.IsSampled() {
		t.Fatalf("expected IsSampled to be true")
	}
	if !sc.IsRemote() {
		t.Fatalf("expected IsRemote to be true")
	}
	if sc.TraceState().String() != ts.String() {
		t.Fatalf("expected TraceState %q, got %q", ts.String(), sc.TraceState().String())
	}
}

func TestNewSpanContext_RequiresBothTraceIDAndSpanIDForValidity(t *testing.T) {
	validTID, _ := trace.TraceIDFromHex("4bf92f3577b34da6a3ce929d0e0e4736")
	validSID, _ := trace.SpanIDFromHex("00f067aa0ba902b7")
	ts, _ := trace.ParseTraceState("rojo=1")

	// Missing SpanID (zero SpanID)
	scNoSID := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID:    validTID,
		SpanID:     trace.SpanID{},
		TraceFlags: trace.FlagsSampled,
		TraceState: ts,
		Remote:     true,
	})
	if scNoSID.IsValid() {
		t.Fatalf("expected NewSpanContext with zero SpanID to have IsValid false")
	}
	if !scNoSID.HasTraceID() {
		t.Fatalf("expected HasTraceID to remain true when valid TraceID is provided")
	}
	if scNoSID.HasSpanID() {
		t.Fatalf("expected HasSpanID to be false when SpanID is zero")
	}
	// NewSpanContext retains configured properties even when IsValid is false
	if !scNoSID.IsRemote() {
		t.Fatalf("expected IsRemote to remain true from config")
	}
	if scNoSID.TraceFlags() != trace.FlagsSampled {
		t.Fatalf("expected TraceFlags to retain FlagsSampled")
	}
	if scNoSID.TraceState().String() != "rojo=1" {
		t.Fatalf("expected TraceState to retain configured state")
	}

	// Missing TraceID (zero TraceID)
	scNoTID := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID:    trace.TraceID{},
		SpanID:     validSID,
		TraceFlags: trace.FlagsSampled,
		TraceState: ts,
		Remote:     true,
	})
	if scNoTID.IsValid() {
		t.Fatalf("expected NewSpanContext with zero TraceID to have IsValid false")
	}
	if scNoTID.HasTraceID() {
		t.Fatalf("expected HasTraceID to be false when TraceID is zero")
	}
	if !scNoTID.HasSpanID() {
		t.Fatalf("expected HasSpanID to remain true when valid SpanID is provided")
	}
	if !scNoTID.IsRemote() {
		t.Fatalf("expected IsRemote to remain true from config")
	}
}

func TestNewSpanContext_WithMethodsImmutability(t *testing.T) {
	tid1, _ := trace.TraceIDFromHex("4bf92f3577b34da6a3ce929d0e0e4736")
	tid2, _ := trace.TraceIDFromHex("7bf92f3577b34da6a3ce929d0e0e4737")
	sid1, _ := trace.SpanIDFromHex("00f067aa0ba902b7")
	sid2, _ := trace.SpanIDFromHex("00f067aa0ba902b8")

	sc := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID: tid1,
		SpanID:  sid1,
		Remote:  false,
	})

	scRemote := sc.WithRemote(true)
	if !scRemote.IsRemote() {
		t.Fatalf("expected scRemote.IsRemote() to be true")
	}
	if sc.IsRemote() {
		t.Fatalf("expected original sc.IsRemote() to remain false")
	}

	scSampled := sc.WithTraceFlags(trace.FlagsSampled)
	if !scSampled.IsSampled() {
		t.Fatalf("expected scSampled.IsSampled() to be true")
	}
	if sc.IsSampled() {
		t.Fatalf("expected original sc.IsSampled() to remain false")
	}

	scNewTID := sc.WithTraceID(tid2)
	if scNewTID.TraceID() != tid2 {
		t.Fatalf("expected updated TraceID %v", tid2)
	}
	if sc.TraceID() != tid1 {
		t.Fatalf("expected original TraceID %v to remain unchanged", tid1)
	}

	scNewSID := sc.WithSpanID(sid2)
	if scNewSID.SpanID() != sid2 {
		t.Fatalf("expected updated SpanID %v", sid2)
	}
	if sc.SpanID() != sid1 {
		t.Fatalf("expected original SpanID %v to remain unchanged", sid1)
	}
}

func TestNewSpanContext_Equal(t *testing.T) {
	tid, _ := trace.TraceIDFromHex("4bf92f3577b34da6a3ce929d0e0e4736")
	sid, _ := trace.SpanIDFromHex("00f067aa0ba902b7")
	ts, _ := trace.ParseTraceState("rojo=1")

	sc1 := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID:    tid,
		SpanID:     sid,
		TraceFlags: trace.FlagsSampled,
		TraceState: ts,
		Remote:     true,
	})

	sc2 := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID:    tid,
		SpanID:     sid,
		TraceFlags: trace.FlagsSampled,
		TraceState: ts,
		Remote:     true,
	})

	if !sc1.Equal(sc2) {
		t.Fatalf("expected sc1 and sc2 to be Equal")
	}

	scDiffRemote := sc2.WithRemote(false)
	if sc1.Equal(scDiffRemote) {
		t.Fatalf("expected Equal to be false when Remote differs")
	}
}

{"case":{"caseId":"case:sha256:c5250e3cf7146afe604264e0770ce8faaa827d71454524d094c8e9ba0efc342a","contract":["NewSpanContext constructs a valid SpanContext when both valid TraceID and SpanID are provided in SpanContextConfig","NewSpanContext marks SpanContext invalid when either TraceID or SpanID is zero or invalid","NewSpanContext preserves configured Remote, TraceFlags, and TraceState even when IsValid is false due to an invalid ID","WithRemote, WithTraceFlags, WithTraceState, WithTraceID, and WithSpanID return updated copies preserving immutability of the original SpanContext","Equal verifies equality across all SpanContext fields including TraceID, SpanID, TraceFlags, TraceState, and Remote"],"goal":"verify NewSpanContext 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":["NewSpanContext"]},"contractCommand":["go","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":["NewSpanContext"],"verifierAdapter":"golang@1"}

module sample

go 1.22

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

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=

{
  "schemaVersion": 1,
  "goal": "verify NewSpanContext 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": [
    "NewSpanContext"
  ]
}