go.opentelemetry.io/otel/trace v1.37.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.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.FlagsSampled

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:4177648b91f184f446b86c70595cb19b4abf715edbf683c34dd66ee6c1c611ef","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.37.0","kind":"HOW","packages":["pkg:golang/go.opentelemetry.io/otel/trace@v1.37.0"],"schemaVersion":1,"symbols":["go.opentelemetry.io/otel/trace.FlagsSampled"]},"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.FlagsSampled"],"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

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 (
	"go.opentelemetry.io/otel/trace"
)

// IsSampled checks if the given TraceFlags has the FlagsSampled bit set.
func IsSampled(flags trace.TraceFlags) bool {
	return flags.IsSampled()
}

// MarkSampled returns the TraceFlags with the FlagsSampled bit enabled.
func MarkSampled(flags trace.TraceFlags) trace.TraceFlags {
	return flags.WithSampled(true)
}

// UnmarkSampled returns the TraceFlags with the FlagsSampled bit cleared.
func UnmarkSampled(flags trace.TraceFlags) trace.TraceFlags {
	return flags.WithSampled(false)
}

// NewSampledSpanContext creates a valid SpanContext marked with FlagsSampled.
func NewSampledSpanContext(traceID trace.TraceID, spanID trace.SpanID) trace.SpanContext {
	return trace.NewSpanContext(trace.SpanContextConfig{
		TraceID:    traceID,
		SpanID:     spanID,
		TraceFlags: trace.FlagsSampled,
	})
}

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

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.MarkSampled(zeroFlags)
	if marked != trace.FlagsSampled {
		return fmt.Errorf("sample.MarkSampled failed")
	}
	unmarked := sample.UnmarkSampled(marked)
	if unmarked != zeroFlags {
		return fmt.Errorf("sample.UnmarkSampled 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.NewSampledSpanContext(tid, sid)
	if !helperSC.Equal(scSampled) {
		return fmt.Errorf("sample.NewSampledSpanContext 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
}