go.opentelemetry.io/otel/trace v1.38.0: ContextWithRemoteSpanContext

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

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

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:d35ae5ece7ca8adacb0dd3f8cd661481f9e4811a7d10a4db61e565d55ff0ebf1","contract":["ContextWithRemoteSpanContext stores a SpanContext in context.Context and forces IsRemote() to true even when the input SpanContext had Remote set to false","SpanContextFromContext and SpanFromContext preserve TraceID, SpanID, TraceFlags, and TraceState from the remote SpanContext","SpanFromContext on a context populated by ContextWithRemoteSpanContext returns a non-recording Span wrapping the remote SpanContext","ContextWithRemoteSpanContext derives a new child context without mutating the parent context and overrides any prior span in the derived context","ContextWithRemoteSpanContext with a zero SpanContext marks the stored context as remote while keeping IsValid false"],"goal":"verify go.opentelemetry.io/otel/trace.ContextWithRemoteSpanContext in pkg:golang/go.opentelemetry.io/otel/trace@v1.38.0","kind":"HOW","packages":["pkg:golang/go.opentelemetry.io/otel/trace@v1.38.0"],"schemaVersion":1,"symbols":["go.opentelemetry.io/otel/trace.ContextWithRemoteSpanContext"]},"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.38.0"],"schemaVersion":1,"subject":"pkg:golang/go.opentelemetry.io/otel/trace@v1.38.0","symbols":["go.opentelemetry.io/otel/trace.ContextWithRemoteSpanContext"],"verifierAdapter":"golang@1"}

module sample

go 1.24.0

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

require go.opentelemetry.io/otel v1.38.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.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
go.opentelemetry.io/otel v1.38.0 h1:RkfdswUDRimDg0m2Az18RKOsnI8UDzppJAtj01/Ymk8=
go.opentelemetry.io/otel v1.38.0/go.mod h1:zcmtmQ1+YmQM9wrNsTGV/q/uyusom3P8RxwExxkZhjM=
go.opentelemetry.io/otel/trace v1.38.0 h1:Fxk5bKrDZJUH+AMyyIXGcFAPah0oRcT+LuNtJrmcNLE=
go.opentelemetry.io/otel/trace v1.38.0/go.mod h1:j1P9ivuFsTceSWe1oY+EeW3sc+Pp42sO++GHkg4wwhs=
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/trace"
)

// AttachRemoteSpanContext stores the given SpanContext as a remote span context in parent.
func AttachRemoteSpanContext(parent context.Context, rsc trace.SpanContext) context.Context {
	return trace.ContextWithRemoteSpanContext(parent, rsc)
}

// NewRemoteContextFromHex constructs a valid SpanContext from hex IDs, flags, and TraceState,
// then binds it into parent via trace.ContextWithRemoteSpanContext.
func NewRemoteContextFromHex(
	parent context.Context,
	traceIDHex string,
	spanIDHex string,
	sampled bool,
	traceStateHeader string,
) (context.Context, trace.SpanContext, error) {
	tid, err := trace.TraceIDFromHex(traceIDHex)
	if err != nil {
		return nil, trace.SpanContext{}, err
	}
	sid, err := trace.SpanIDFromHex(spanIDHex)
	if err != nil {
		return nil, trace.SpanContext{}, err
	}
	var ts trace.TraceState
	if traceStateHeader != "" {
		ts, err = trace.ParseTraceState(traceStateHeader)
		if err != nil {
			return nil, trace.SpanContext{}, err
		}
	}
	var flags trace.TraceFlags
	if sampled {
		flags = trace.FlagsSampled
	}
	sc := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID:    tid,
		SpanID:     sid,
		TraceFlags: flags,
		TraceState: ts,
		Remote:     false,
	})
	ctx := trace.ContextWithRemoteSpanContext(parent, sc)
	return ctx, sc, nil
}

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

package main

import (
	"context"
	"fmt"
	"os"

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

func failf(format string, args ...any) {
	fmt.Fprintf(os.Stderr, format+"\n", args...)
	os.Exit(1)
}

func main() {
	baseCtx := context.Background()

	// Contract 1: ContextWithRemoteSpanContext stores a SpanContext in context.Context and forces IsRemote() to true even when the input SpanContext had Remote set to false
	remoteCtx, inputSC, err := sample.NewRemoteContextFromHex(
		baseCtx,
		"4bf92f3577b34da6a3ce929d0e0e4736",
		"00f067aa0ba902b7",
		true,
		"vendor1=opaqueValue1,vendor2=opaqueValue2",
	)
	if err != nil {
		failf("NewRemoteContextFromHex failed: %v", err)
	}
	if inputSC.IsRemote() {
		failf("expected input SpanContext before ContextWithRemoteSpanContext to have IsRemote() == false")
	}

	extractedSC := trace.SpanContextFromContext(remoteCtx)
	if !extractedSC.IsValid() {
		failf("expected extracted SpanContext to be valid")
	}
	if !extractedSC.IsRemote() {
		failf("expected ContextWithRemoteSpanContext to force IsRemote() == true on stored SpanContext")
	}

	// Contract 2: SpanContextFromContext and SpanFromContext preserve TraceID, SpanID, TraceFlags, and TraceState from the remote SpanContext
	if extractedSC.TraceID() != inputSC.TraceID() {
		failf("TraceID mismatch: got %s, want %s", extractedSC.TraceID(), inputSC.TraceID())
	}
	if extractedSC.SpanID() != inputSC.SpanID() {
		failf("SpanID mismatch: got %s, want %s", extractedSC.SpanID(), inputSC.SpanID())
	}
	if !extractedSC.IsSampled() || extractedSC.TraceFlags() != trace.FlagsSampled {
		failf("TraceFlags mismatch: got %v, want %v", extractedSC.TraceFlags(), trace.FlagsSampled)
	}
	if extractedSC.TraceState().String() != "vendor1=opaqueValue1,vendor2=opaqueValue2" {
		failf("TraceState mismatch: got %q", extractedSC.TraceState().String())
	}

	// Contract 3: SpanFromContext on a context populated by ContextWithRemoteSpanContext returns a non-recording Span wrapping the remote SpanContext
	span := trace.SpanFromContext(remoteCtx)
	if span == nil {
		failf("expected non-nil Span from SpanFromContext")
	}
	if span.IsRecording() {
		failf("expected SpanFromContext on remote span context to return non-recording span (IsRecording() == false)")
	}
	if !span.SpanContext().Equal( inputSC.WithRemote(true) ) {
		failf("expected Span.SpanContext() to equal inputSC.WithRemote(true)")
	}

	// Contract 4: ContextWithRemoteSpanContext derives a new child context without mutating the parent context and overrides any prior span in the derived context
	if trace.SpanContextFromContext(baseCtx).IsValid() {
		failf("expected parent context to remain unmodified with invalid SpanContext")
	}

	secondTID, err := trace.TraceIDFromHex("11111111111111111111111111111111")
	if err != nil {
		failf("unexpected error parsing second TraceID: %v", err)
	}
	secondSID, err := trace.SpanIDFromHex("2222222222222222")
	if err != nil {
		failf("unexpected error parsing second SpanID: %v", err)
	}
	secondSC := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID:    secondTID,
		SpanID:     secondSID,
		TraceFlags: 0x00,
		Remote:     true,
	})
	overriddenCtx := sample.AttachRemoteSpanContext(remoteCtx, secondSC)
	overriddenExtracted := trace.SpanContextFromContext(overriddenCtx)
	if !overriddenExtracted.Equal(secondSC) {
		failf("expected overridden context to hold second remote SpanContext")
	}
	if overriddenExtracted.IsSampled() {
		failf("expected unsampled remote SpanContext to have IsSampled() == false")
	}
	if !trace.SpanContextFromContext(remoteCtx).Equal(inputSC.WithRemote(true)) {
		failf("expected previous remoteCtx to remain unchanged after deriving overriddenCtx")
	}

	// Contract 5: ContextWithRemoteSpanContext with a zero SpanContext marks the stored context as remote while keeping IsValid false
	emptyRemoteCtx := sample.AttachRemoteSpanContext(baseCtx, trace.SpanContext{})
	emptyRemoteSC := trace.SpanContextFromContext(emptyRemoteCtx)
	if emptyRemoteSC.IsValid() {
		failf("expected zero SpanContext passed to ContextWithRemoteSpanContext to remain invalid")
	}
	if !emptyRemoteSC.IsRemote() {
		failf("expected zero SpanContext passed to ContextWithRemoteSpanContext to have IsRemote() == true")
	}

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