go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0: NewUnstarted

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/exporters/otlp/otlptrace.NewUnstarted in pkg:golang/go.opentelemetry.io/otel/exporters/otlp/otlptrace@v1.43.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.opentelemetry.io/otel/exporters/otlp/otlptrace@v1.43.0
Demonstrate these symbols/APIs:
  - go.opentelemetry.io/otel/exporters/otlp/otlptrace.NewUnstarted
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:2db8b174afb1e438fa80a2f24492b129f903cc038277982be2aaa2d3e8f4acee","contract":["otlptrace.NewUnstarted constructs an unstarted exporter without calling client.Start","otlptrace.NewUnstarted exporter Shutdown returns nil without calling client.Stop when not started","otlptrace.NewUnstarted exporter starts the client upon invoking Start","otlptrace.NewUnstarted exporter returns error when Start is called again after already started","otlptrace.NewUnstarted exporter propagates error when client.Start fails","otlptrace.NewUnstarted exporter transforms and uploads spans via client.UploadTraces","otlptrace.NewUnstarted exporter propagates upload errors encountered during ExportSpans","otlptrace.NewUnstarted exporter shuts down by calling client.Stop"],"goal":"verify go.opentelemetry.io/otel/exporters/otlp/otlptrace.NewUnstarted in pkg:golang/go.opentelemetry.io/otel/exporters/otlp/otlptrace@v1.43.0","kind":"HOW","packages":["pkg:golang/go.opentelemetry.io/otel/exporters/otlp/otlptrace@v1.43.0"],"schemaVersion":1,"symbols":["go.opentelemetry.io/otel/exporters/otlp/otlptrace.NewUnstarted"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/go.opentelemetry.io/otel/exporters/otlp/otlptrace@v1.43.0"],"schemaVersion":1,"subject":"pkg:golang/go.opentelemetry.io/otel/exporters/otlp/otlptrace@v1.43.0","symbols":["go.opentelemetry.io/otel/exporters/otlp/otlptrace.NewUnstarted"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require (
	go.opentelemetry.io/otel v1.43.0
	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0
	go.opentelemetry.io/otel/sdk v1.43.0
	go.opentelemetry.io/otel/trace v1.43.0
	go.opentelemetry.io/proto/otlp v1.10.0
)

require (
	github.com/cespare/xxhash/v2 v2.3.0 // indirect
	github.com/go-logr/logr v1.4.3 // indirect
	github.com/go-logr/stdr v1.2.2 // indirect
	github.com/google/uuid v1.6.0 // indirect
	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
	go.opentelemetry.io/otel/metric v1.43.0 // indirect
	golang.org/x/sys v0.42.0 // indirect
	google.golang.org/protobuf v1.36.11 // 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/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
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/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
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/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0 h1:88Y4s2C8oTui1LGM6bTWkw0ICGcOLCAI5l6zsD1j20k=
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0/go.mod h1:Vl1/iaggsuRlrHf/hfPJPvVag77kKyvrLeD10kpMl+A=
go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
go.opentelemetry.io/proto/otlp v1.10.0 h1:IQRWgT5srOCYfiWnpqUYz9CVmbO8bFmKcwYxpuCSL2g=
go.opentelemetry.io/proto/otlp v1.10.0/go.mod h1:/CV4QoCR/S9yaPj8utp3lvQPoqMtxXdzn7ozvvozVqk=
go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

{
  "schemaVersion": 1,
  "goal": "verify go.opentelemetry.io/otel/exporters/otlp/otlptrace.NewUnstarted in pkg:golang/go.opentelemetry.io/otel/exporters/otlp/otlptrace@v1.43.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.opentelemetry.io/otel/exporters/otlp/otlptrace@v1.43.0"
  ],
  "symbols": [
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace.NewUnstarted"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

package main

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

	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	sdktracetest "go.opentelemetry.io/otel/sdk/trace/tracetest"
	"go.opentelemetry.io/otel/trace"
	tracepb "go.opentelemetry.io/proto/otlp/trace/v1"
)

type mockClient struct {
	mu              sync.Mutex
	started         bool
	stopped         bool
	startCallCount  int
	stopCallCount   int
	uploadCallCount int
	startErr        error
	stopErr         error
	uploadErr       error
	uploadedSpans   []*tracepb.ResourceSpans
}

func (m *mockClient) Start(ctx context.Context) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.startCallCount++
	m.started = true
	if m.startErr != nil {
		return m.startErr
	}
	return nil
}

func (m *mockClient) Stop(ctx context.Context) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.stopCallCount++
	m.stopped = true
	if m.stopErr != nil {
		return m.stopErr
	}
	return nil
}

func (m *mockClient) UploadTraces(ctx context.Context, protoSpans []*tracepb.ResourceSpans) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.uploadCallCount++
	if m.uploadErr != nil {
		return m.uploadErr
	}
	m.uploadedSpans = append(m.uploadedSpans, protoSpans...)
	return nil
}

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

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

	// 1. otlptrace.NewUnstarted constructs an unstarted exporter without calling client.Start
	client1 := &mockClient{}
	exp1 := otlptrace.NewUnstarted(client1)
	if exp1 == nil {
		return errors.New("expected non-nil exporter from NewUnstarted")
	}
	client1.mu.Lock()
	if client1.started || client1.startCallCount != 0 {
		client1.mu.Unlock()
		return errors.New("client.Start was unexpectedly called during NewUnstarted")
	}
	client1.mu.Unlock()

	// 2. otlptrace.NewUnstarted exporter Shutdown returns nil without calling client.Stop when not started
	if err := exp1.Shutdown(ctx); err != nil {
		return fmt.Errorf("unexpected error on Shutdown of unstarted exporter: %w", err)
	}
	client1.mu.Lock()
	if client1.stopped || client1.stopCallCount != 0 {
		client1.mu.Unlock()
		return errors.New("client.Stop was unexpectedly called when shutting down unstarted exporter")
	}
	client1.mu.Unlock()

	// 3. otlptrace.NewUnstarted exporter starts the client upon invoking Start
	if err := exp1.Start(ctx); err != nil {
		return fmt.Errorf("exp1.Start failed: %w", err)
	}
	client1.mu.Lock()
	if !client1.started || client1.startCallCount != 1 {
		client1.mu.Unlock()
		return errors.New("client.Start was not called once on Start invocation")
	}
	client1.mu.Unlock()

	// 4. otlptrace.NewUnstarted exporter returns error when Start is called again after already started
	if err := exp1.Start(ctx); err == nil {
		return errors.New("expected error when calling Start on already started exporter, got nil")
	}

	// 5. otlptrace.NewUnstarted exporter propagates error when client.Start fails
	expectedStartErr := errors.New("initial connection failed")
	client2 := &mockClient{startErr: expectedStartErr}
	exp2 := otlptrace.NewUnstarted(client2)
	if exp2 == nil {
		return errors.New("expected non-nil exporter from NewUnstarted")
	}
	startErr := exp2.Start(ctx)
	if startErr == nil {
		return errors.New("expected error from Start when client.Start fails, got nil")
	}
	if !errors.Is(startErr, expectedStartErr) {
		return fmt.Errorf("expected error %v, got %v", expectedStartErr, startErr)
	}

	// 6. otlptrace.NewUnstarted exporter transforms and uploads spans via client.UploadTraces
	client3 := &mockClient{}
	exp3 := otlptrace.NewUnstarted(client3)
	if err := exp3.Start(ctx); err != nil {
		return fmt.Errorf("exp3.Start failed: %w", err)
	}

	tp := sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(exp3),
	)
	tracer := tp.Tracer("example.com/trace-demo")
	_, span := tracer.Start(ctx, "sample-operation", trace.WithAttributes(
		attribute.String("service.name", "demo-service"),
		attribute.Int("http.status_code", 200),
	))
	span.End()

	if err := tp.ForceFlush(ctx); err != nil {
		return fmt.Errorf("ForceFlush failed: %w", err)
	}

	client3.mu.Lock()
	if len(client3.uploadedSpans) == 0 {
		client3.mu.Unlock()
		return errors.New("expected uploaded spans, got 0")
	}
	resSpan := client3.uploadedSpans[0]
	if len(resSpan.ScopeSpans) == 0 || len(resSpan.ScopeSpans[0].Spans) == 0 {
		client3.mu.Unlock()
		return errors.New("expected spans within uploaded ResourceSpans")
	}
	uploadedSpan := resSpan.ScopeSpans[0].Spans[0]
	if uploadedSpan.Name != "sample-operation" {
		gotName := uploadedSpan.Name
		client3.mu.Unlock()
		return fmt.Errorf("expected span name sample-operation, got %q", gotName)
	}
	client3.mu.Unlock()

	// 7. otlptrace.NewUnstarted exporter propagates upload errors encountered during ExportSpans
	expectedUploadErr := errors.New("collector network failure")
	client4 := &mockClient{uploadErr: expectedUploadErr}
	exp4 := otlptrace.NewUnstarted(client4)
	if err := exp4.Start(ctx); err != nil {
		return fmt.Errorf("exp4.Start failed: %w", err)
	}

	sr := sdktracetest.NewSpanRecorder()
	tpRecorder := sdktrace.NewTracerProvider(sdktrace.WithSpanProcessor(sr))
	trRecorder := tpRecorder.Tracer("recorder-tracer")
	_, recSpan := trRecorder.Start(ctx, "recorded-span")
	recSpan.End()

	endedSpans := sr.Ended()
	if len(endedSpans) == 0 {
		return errors.New("expected recorded ended spans")
	}

	exportErr := exp4.ExportSpans(ctx, endedSpans)
	if exportErr == nil {
		return errors.New("expected error from ExportSpans when upload fails, got nil")
	}
	if !errors.Is(exportErr, expectedUploadErr) {
		return fmt.Errorf("expected upload error %v, got %v", expectedUploadErr, exportErr)
	}

	// 8. otlptrace.NewUnstarted exporter shuts down by calling client.Stop
	if err := exp3.Shutdown(ctx); err != nil {
		return fmt.Errorf("Shutdown failed: %w", err)
	}
	client3.mu.Lock()
	if !client3.stopped || client3.stopCallCount != 1 {
		client3.mu.Unlock()
		return errors.New("client.Stop was not called once on exporter Shutdown")
	}
	client3.mu.Unlock()

	return nil
}