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

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.ContextWithSpan 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.ContextWithSpan

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:29861eb78d39eb0990f80517638d21276543d934b5f6a9d5cc0d923f4d6dd2be","contract":["SpanFromContext returns a non-nil noopSpan on untraced context","ContextWithSpan stores a Span in the context and SpanFromContext retrieves it","ContextWithSpan with nil Span safely yields a non-nil noopSpan via SpanFromContext without panicking","ContextWithSpan preserves unrelated context values across span injection","SpanContextFromContext returns the SpanContext of the span stored by ContextWithSpan"],"goal":"verify go.opentelemetry.io/otel/trace.ContextWithSpan 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.ContextWithSpan"]},"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.37.0"],"schemaVersion":1,"subject":"pkg:golang/go.opentelemetry.io/otel/trace@v1.37.0","symbols":["go.opentelemetry.io/otel/trace.ContextWithSpan"],"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

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=

package sample

import (
	"context"

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

// SpanHolder demonstrates storing and retrieving spans in a Go context using ContextWithSpan.
type SpanHolder struct{}

// NewSpanHolder creates a new SpanHolder.
func NewSpanHolder() *SpanHolder {
	return &SpanHolder{}
}

// WithSpan attaches the provided span to the context using trace.ContextWithSpan.
func (h *SpanHolder) WithSpan(parent context.Context, span trace.Span) context.Context {
	return trace.ContextWithSpan(parent, span)
}

// Span extracts the span from the context using trace.SpanFromContext.
func (h *SpanHolder) Span(ctx context.Context) trace.Span {
	return trace.SpanFromContext(ctx)
}

// SpanContext extracts the SpanContext from the context using trace.SpanContextFromContext.
func (h *SpanHolder) SpanContext(ctx context.Context) trace.SpanContext {
	return trace.SpanContextFromContext(ctx)
}

// HasActiveSpan returns true if ctx contains a span with a valid SpanContext.
func (h *SpanHolder) HasActiveSpan(ctx context.Context) bool {
	span := trace.SpanFromContext(ctx)
	if span == nil {
		return false
	}
	return span.SpanContext().IsValid()
}

{
  "schemaVersion": 1,
  "goal": "verify go.opentelemetry.io/otel/trace.ContextWithSpan 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.ContextWithSpan"
  ]
}

package main

import (
	"context"
	"fmt"
	"os"

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

type customTestSpan struct {
	noop.Span
	sc trace.SpanContext
}

func (s customTestSpan) SpanContext() trace.SpanContext {
	return s.sc
}

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

func runContract() error {
	ctx := context.Background()

	// 1. SpanFromContext returns a non-nil noopSpan on untraced context
	untracedSpan := trace.SpanFromContext(ctx)
	if untracedSpan == nil {
		return fmt.Errorf("expected non-nil span on untraced context, got nil")
	}
	if untracedSpan.IsRecording() {
		return fmt.Errorf("expected untraced span IsRecording() to be false")
	}
	if untracedSpan.SpanContext().IsValid() {
		return fmt.Errorf("expected untraced span SpanContext.IsValid() to be false")
	}

	// 2. ContextWithSpan stores a Span in the context and SpanFromContext retrieves it
	tid, err := trace.TraceIDFromHex("4bf92f3577b34da6a3ce929d0e0e4736")
	if err != nil {
		return fmt.Errorf("TraceIDFromHex failed: %w", err)
	}
	sid, err := trace.SpanIDFromHex("00f067aa0ba902b7")
	if err != nil {
		return fmt.Errorf("SpanIDFromHex failed: %w", err)
	}
	sc := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID:    tid,
		SpanID:     sid,
		TraceFlags: trace.FlagsSampled,
	})
	if !sc.IsValid() {
		return fmt.Errorf("expected constructed SpanContext to be valid")
	}

	testSpan := customTestSpan{sc: sc}
	ctxWithSpan := trace.ContextWithSpan(ctx, testSpan)

	retrieved := trace.SpanFromContext(ctxWithSpan)
	if retrieved == nil {
		return fmt.Errorf("SpanFromContext returned nil for context with span")
	}
	if !retrieved.SpanContext().Equal(sc) {
		return fmt.Errorf("retrieved SpanContext mismatch: expected %v, got %v", sc, retrieved.SpanContext())
	}

	// 3. ContextWithSpan with nil Span safely yields a non-nil noopSpan via SpanFromContext without panicking
	ctxWithNil := trace.ContextWithSpan(ctx, nil)
	nilSpan := trace.SpanFromContext(ctxWithNil)
	if nilSpan == nil {
		return fmt.Errorf("expected non-nil noopSpan when ContextWithSpan given nil, got nil")
	}
	if nilSpan.SpanContext().IsValid() {
		return fmt.Errorf("expected invalid SpanContext when ContextWithSpan given nil")
	}

	// 4. ContextWithSpan preserves unrelated context values across span injection
	type contextKey string
	const testKey contextKey = "sample-key"
	const testVal = "sample-value"

	baseCtx := context.WithValue(ctx, testKey, testVal)
	wrappedCtx := trace.ContextWithSpan(baseCtx, testSpan)

	val := wrappedCtx.Value(testKey)
	if val != testVal {
		return fmt.Errorf("expected context value %q, got %v", testVal, val)
	}

	// In the absence of an SDK, noop tracer preserves parent SpanContext from context
	tp := noop.NewTracerProvider()
	tracer := tp.Tracer("test")
	_, childSpan := tracer.Start(wrappedCtx, "child")
	childCtx := trace.ContextWithSpan(wrappedCtx, childSpan)
	if !trace.SpanFromContext(childCtx).SpanContext().Equal(sc) {
		return fmt.Errorf("child span from noop tracer should preserve parent span context")
	}

	// 5. SpanContextFromContext returns the SpanContext of the span stored by ContextWithSpan
	extractedSC := trace.SpanContextFromContext(ctxWithSpan)
	if !extractedSC.Equal(sc) {
		return fmt.Errorf("SpanContextFromContext returned %v, expected %v", extractedSC, sc)
	}

	// 6. Integrates with sample package helper
	holder := sample.NewSpanHolder()
	helperCtx := holder.WithSpan(ctx, testSpan)
	if !holder.HasActiveSpan(helperCtx) {
		return fmt.Errorf("expected HasActiveSpan to return true for helperCtx")
	}
	if !holder.Span(helperCtx).SpanContext().Equal(sc) {
		return fmt.Errorf("holder.Span returned incorrect SpanContext")
	}
	if !holder.SpanContext(helperCtx).Equal(sc) {
		return fmt.Errorf("holder.SpanContext returned incorrect SpanContext")
	}

	return nil
}