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

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

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:296e7791efde444d4c225eb0faeadde8e623b375c1e7d58640fd8d29b1b61fc6","contract":["SpanFromContext returns a non-nil trace.Span from empty context with IsRecording false and invalid SpanContext","ContextWithSpan binds a trace.Span into context and SpanFromContext retrieves it identically","noop.Span implements trace.Span and accepts SetName, SetStatus, SetAttributes, AddEvent, AddLink, RecordError, and End without panic","Embedding noop.Span enables custom trace.Span implementations to override methods and capture span lifecycle events","trace.Span SpanContext retains trace and span identifiers across span lifetime and remains accessible after End"],"goal":"verify go.opentelemetry.io/otel/trace.Span 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.Span"]},"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.Span"],"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

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 (
	"context"

	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/codes"
	"go.opentelemetry.io/otel/trace"
	"go.opentelemetry.io/otel/trace/noop"
)

// ExtractSpan wraps trace.SpanFromContext to retrieve the active span.
func ExtractSpan(ctx context.Context) trace.Span {
	return trace.SpanFromContext(ctx)
}

// InjectSpan wraps trace.ContextWithSpan to bind a span into a context.
func InjectSpan(ctx context.Context, span trace.Span) context.Context {
	return trace.ContextWithSpan(ctx, span)
}

// DefaultNoopSpan returns a no-op span implementation satisfying trace.Span.
func DefaultNoopSpan() trace.Span {
	return noop.Span{}
}

// TrackingSpan embeds noop.Span to implement trace.Span while capturing mutating operations.
type TrackingSpan struct {
	noop.Span
	spanContext trace.SpanContext
	name        string
	statusCode  codes.Code
	statusDesc  string
	recording   bool
	attributes  []attribute.KeyValue
	events      []string
	ended       bool
}

var _ trace.Span = (*TrackingSpan)(nil)

// NewTrackingSpan initializes a TrackingSpan with given context, initial name, and recording state.
func NewTrackingSpan(sc trace.SpanContext, initialName string, recording bool) *TrackingSpan {
	return &TrackingSpan{
		spanContext: sc,
		name:        initialName,
		recording:   recording,
	}
}

func (s *TrackingSpan) SpanContext() trace.SpanContext {
	return s.spanContext
}

func (s *TrackingSpan) IsRecording() bool {
	return s.recording
}

func (s *TrackingSpan) SetName(name string) {
	s.name = name
}

func (s *TrackingSpan) Name() string {
	return s.name
}

func (s *TrackingSpan) SetStatus(code codes.Code, description string) {
	s.statusCode = code
	s.statusDesc = description
}

func (s *TrackingSpan) StatusCode() codes.Code {
	return s.statusCode
}

func (s *TrackingSpan) StatusDescription() string {
	return s.statusDesc
}

func (s *TrackingSpan) SetAttributes(kv ...attribute.KeyValue) {
	s.attributes = append(s.attributes, kv...)
}

func (s *TrackingSpan) Attributes() []attribute.KeyValue {
	return s.attributes
}

func (s *TrackingSpan) AddEvent(name string, _ ...trace.EventOption) {
	s.events = append(s.events, name)
}

func (s *TrackingSpan) Events() []string {
	return s.events
}

func (s *TrackingSpan) End(_ ...trace.SpanEndOption) {
	s.ended = true
}

func (s *TrackingSpan) IsEnded() bool {
	return s.ended
}

// RunSampleOperations performs standard span calls on any trace.Span implementation.
func RunSampleOperations(span trace.Span, opName string) {
	span.SetName(opName)
	span.SetAttributes(attribute.String("test.key", "test.value"))
	span.AddEvent("operation.started")
	span.SetStatus(codes.Ok, "success")
	span.End()
}

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

package main

import (
	"context"
	"errors"
	"fmt"
	"os"

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

func main() {
	// Contract 1: SpanFromContext returns a non-nil trace.Span from empty context with IsRecording false and invalid SpanContext
	emptyCtx := context.Background()
	spanFromEmpty := sample.ExtractSpan(emptyCtx)
	if spanFromEmpty == nil {
		fmt.Fprintf(os.Stderr, "expected non-nil span from empty context\n")
		os.Exit(1)
	}
	if spanFromEmpty.IsRecording() {
		fmt.Fprintf(os.Stderr, "expected span from empty context not to be recording\n")
		os.Exit(1)
	}
	emptySC := spanFromEmpty.SpanContext()
	if emptySC.IsValid() {
		fmt.Fprintf(os.Stderr, "expected SpanContext from empty context to be invalid\n")
		os.Exit(1)
	}

	// Contract 2: ContextWithSpan binds a trace.Span into context and SpanFromContext retrieves it identically
	customSpan := sample.NewTrackingSpan(trace.SpanContext{}, "injected-span", false)
	ctxWithSpan := sample.InjectSpan(emptyCtx, customSpan)
	retrievedSpan := sample.ExtractSpan(ctxWithSpan)
	if retrievedSpan != customSpan {
		fmt.Fprintf(os.Stderr, "expected retrieved span to match the injected span instance\n")
		os.Exit(1)
	}

	// Contract 3: noop.Span implements trace.Span and accepts SetName, SetStatus, SetAttributes, AddEvent, AddLink, RecordError, and End without panic
	var noopSpan trace.Span = sample.DefaultNoopSpan()
	if noopSpan.IsRecording() {
		fmt.Fprintf(os.Stderr, "expected noop.Span IsRecording to be false\n")
		os.Exit(1)
	}
	noopSpan.SetName("test-noop-operation")
	noopSpan.SetStatus(codes.Error, "simulated error")
	noopSpan.SetAttributes(attribute.String("env", "test"))
	noopSpan.AddEvent("noop.event")
	noopSpan.AddLink(trace.Link{})
	noopSpan.RecordError(errors.New("sample error"))
	noopSpan.End()
	if noopSpan.SpanContext().IsValid() {
		fmt.Fprintf(os.Stderr, "expected noop.Span SpanContext to remain invalid\n")
		os.Exit(1)
	}

	// Contract 4: Embedding noop.Span enables custom trace.Span implementations to override methods and capture span lifecycle events
	tid, err := trace.TraceIDFromHex("4bf92f3577b34da6a3ce929d0e0e4736")
	if err != nil {
		fmt.Fprintf(os.Stderr, "invalid trace ID: %v\n", err)
		os.Exit(1)
	}
	sid, err := trace.SpanIDFromHex("00f067aa0ba902b7")
	if err != nil {
		fmt.Fprintf(os.Stderr, "invalid span ID: %v\n", err)
		os.Exit(1)
	}
	validSC := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID:    tid,
		SpanID:     sid,
		TraceFlags: trace.FlagsSampled,
	})
	tracking := sample.NewTrackingSpan(validSC, "operation.original", true)
	var spanInterface trace.Span = tracking
	if !spanInterface.IsRecording() {
		fmt.Fprintf(os.Stderr, "expected tracking span IsRecording to return true\n")
		os.Exit(1)
	}
	sample.RunSampleOperations(spanInterface, "operation.updated")
	if tracking.Name() != "operation.updated" {
		fmt.Fprintf(os.Stderr, "expected updated span name %q, got %q\n", "operation.updated", tracking.Name())
		os.Exit(1)
	}
	if tracking.StatusCode() != codes.Ok {
		fmt.Fprintf(os.Stderr, "expected status code OK, got %v\n", tracking.StatusCode())
		os.Exit(1)
	}
	if len(tracking.Events()) == 0 || tracking.Events()[0] != "operation.started" {
		fmt.Fprintf(os.Stderr, "expected event 'operation.started' recorded\n")
		os.Exit(1)
	}
	if !tracking.IsEnded() {
		fmt.Fprintf(os.Stderr, "expected tracking span to be marked ended\n")
		os.Exit(1)
	}

	// Contract 5: trace.Span SpanContext retains trace and span identifiers across span lifetime and remains accessible after End
	spanInterface.End()
	postEndSC := spanInterface.SpanContext()
	if !postEndSC.IsValid() {
		fmt.Fprintf(os.Stderr, "expected SpanContext to remain valid after End\n")
		os.Exit(1)
	}
	if postEndSC.TraceID() != tid {
		fmt.Fprintf(os.Stderr, "TraceID altered after End: got %s, want %s\n", postEndSC.TraceID(), tid)
		os.Exit(1)
	}
	if postEndSC.SpanID() != sid {
		fmt.Fprintf(os.Stderr, "SpanID altered after End: got %s, want %s\n", postEndSC.SpanID(), sid)
		os.Exit(1)
	}
	if !postEndSC.IsSampled() {
		fmt.Fprintf(os.Stderr, "expected post-End SpanContext to retain sampled flag\n")
		os.Exit(1)
	}

	fmt.Println("All trace.Span contract assertions passed.")
}