go.opentelemetry.io/otel/trace v1.44.0: FlagsSampled

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

Use EXACTLY these public packages and versions:
  - pkg:golang/go.opentelemetry.io/otel/trace@v1.44.0
Demonstrate these symbols/APIs:
  - go.opentelemetry.io/otel/trace.FlagsSampled
Required runtime conditions:
  - ecosystem: golang
  - language: go
  - packageManager: go@1.26.6
  - runtime: go@1.26.6

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:f3e20a77c9fbc4565f9be8754dd1039488f202a6a636d40e5e233a4a10cec5d4","contract":["FlagsSampled has byte value 0x01 and reports IsSampled as true.","TraceFlags.WithSampled toggles the FlagsSampled bit on and off.","TraceFlags.String formats FlagsSampled as 01 and unset as 00.","SpanContext created with FlagsSampled reports IsSampled as true and preserves TraceFlags.","SpanContext.WithTraceFlags updates the sampling decision with FlagsSampled."],"goal":"verify go.opentelemetry.io/otel/trace.FlagsSampled in pkg:golang/go.opentelemetry.io/otel/trace@v1.44.0","kind":"HOW","packages":["pkg:golang/go.opentelemetry.io/otel/trace@v1.44.0"],"schemaVersion":1,"symbols":["go.opentelemetry.io/otel/trace.FlagsSampled"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/go.opentelemetry.io/otel/trace@v1.44.0"],"schemaVersion":1,"subject":"pkg:golang/go.opentelemetry.io/otel/trace@v1.44.0","symbols":["go.opentelemetry.io/otel/trace.FlagsSampled"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

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

require (
	github.com/cespare/xxhash/v2 v2.3.0 // indirect
	go.opentelemetry.io/otel v1.44.0 // indirect
)

github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
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.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU=
go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc=
go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk=
go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE=
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 (
	"go.opentelemetry.io/otel/trace"
)

// IsSampled reports whether the given TraceFlags has FlagsSampled set.
func IsSampled(flags trace.TraceFlags) bool {
	return flags.IsSampled()
}

// SetSampled returns the TraceFlags with the FlagsSampled bit configured.
func SetSampled(flags trace.TraceFlags, sampled bool) trace.TraceFlags {
	return flags.WithSampled(sampled)
}

// CreateSampledSpanContext creates a new SpanContext with FlagsSampled configured.
func CreateSampledSpanContext(traceID trace.TraceID, spanID trace.SpanID, sampled bool) trace.SpanContext {
	var flags trace.TraceFlags
	if sampled {
		flags = trace.FlagsSampled
	}
	return trace.NewSpanContext(trace.SpanContextConfig{
		TraceID:    traceID,
		SpanID:     spanID,
		TraceFlags: flags,
	})
}

{
  "schemaVersion": 1,
  "goal": "verify go.opentelemetry.io/otel/trace.FlagsSampled in pkg:golang/go.opentelemetry.io/otel/trace@v1.44.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.opentelemetry.io/otel/trace@v1.44.0"
  ],
  "symbols": [
    "go.opentelemetry.io/otel/trace.FlagsSampled"
  ],
  "runtimeConditions": {
    "ecosystem": "golang",
    "language": "go",
    "packageManager": "go@1.26.6",
    "runtime": "go@1.26.6"
  }
}

package main

import (
	"fmt"
	"os"

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

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

func runContract() error {
	// 1. FlagsSampled has byte value 0x01 and reports IsSampled as true.
	if byte(trace.FlagsSampled) != 0x01 {
		return fmt.Errorf("expected byte(FlagsSampled) == 0x01, got 0x%02x", byte(trace.FlagsSampled))
	}
	if !trace.FlagsSampled.IsSampled() {
		return fmt.Errorf("expected FlagsSampled.IsSampled() to be true")
	}
	if trace.TraceFlags(0x00).IsSampled() {
		return fmt.Errorf("expected zero TraceFlags.IsSampled() to be false")
	}
	if !sample.IsSampled(trace.FlagsSampled) {
		return fmt.Errorf("sample.IsSampled returned false for FlagsSampled")
	}

	// 2. TraceFlags.WithSampled toggles the FlagsSampled bit on and off.
	zeroFlags := trace.TraceFlags(0x00)
	sampledFlags := zeroFlags.WithSampled(true)
	if sampledFlags != trace.FlagsSampled {
		return fmt.Errorf("expected WithSampled(true) to equal FlagsSampled, got %v", sampledFlags)
	}
	if !sampledFlags.IsSampled() {
		return fmt.Errorf("expected WithSampled(true) to report IsSampled() true")
	}

	clearedFlags := sampledFlags.WithSampled(false)
	if clearedFlags != zeroFlags {
		return fmt.Errorf("expected WithSampled(false) to equal 0x00, got %v", clearedFlags)
	}
	if clearedFlags.IsSampled() {
		return fmt.Errorf("expected clearedFlags.IsSampled() to be false")
	}

	marked := sample.SetSampled(zeroFlags, true)
	if marked != trace.FlagsSampled {
		return fmt.Errorf("sample.SetSampled(true) failed")
	}
	unmarked := sample.SetSampled(marked, false)
	if unmarked != zeroFlags {
		return fmt.Errorf("sample.SetSampled(false) failed")
	}

	// 3. TraceFlags.String formats FlagsSampled as 01 and unset as 00.
	if s := trace.FlagsSampled.String(); s != "01" {
		return fmt.Errorf("expected FlagsSampled.String() == '01', got %q", s)
	}
	if s := trace.TraceFlags(0x00).String(); s != "00" {
		return fmt.Errorf("expected zero TraceFlags.String() == '00', got %q", s)
	}

	// 4. SpanContext created with FlagsSampled reports IsSampled as true and preserves TraceFlags.
	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)
	}

	scSampled := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID:    tid,
		SpanID:     sid,
		TraceFlags: trace.FlagsSampled,
	})
	if !scSampled.IsValid() {
		return fmt.Errorf("expected valid SpanContext")
	}
	if !scSampled.IsSampled() {
		return fmt.Errorf("expected scSampled.IsSampled() to be true")
	}
	if scSampled.TraceFlags() != trace.FlagsSampled {
		return fmt.Errorf("expected scSampled.TraceFlags() == FlagsSampled, got %v", scSampled.TraceFlags())
	}

	helperSC := sample.CreateSampledSpanContext(tid, sid, true)
	if !helperSC.Equal(scSampled) {
		return fmt.Errorf("sample.CreateSampledSpanContext produced mismatched SpanContext")
	}

	// 5. SpanContext.WithTraceFlags updates the sampling decision with FlagsSampled.
	scUnsampled := trace.NewSpanContext(trace.SpanContextConfig{
		TraceID: tid,
		SpanID:  sid,
	})
	if scUnsampled.IsSampled() {
		return fmt.Errorf("expected unsampled SpanContext.IsSampled() to be false")
	}

	scUpdated := scUnsampled.WithTraceFlags(trace.FlagsSampled)
	if !scUpdated.IsSampled() {
		return fmt.Errorf("expected updated SpanContext to be sampled")
	}
	if scUpdated.TraceFlags() != trace.FlagsSampled {
		return fmt.Errorf("expected updated SpanContext TraceFlags == FlagsSampled, got %v", scUpdated.TraceFlags())
	}

	return nil
}