《后端架构设计·演进与治理》6.2 分布式追踪：采样、上下文传播与成本

// file: internal/platform/obs/sampling.go
// tier: L2
// verify: go test ./internal/platform/obs/ -count=1
package obs

import (
	"context"
	"encoding/binary"
	"encoding/hex"
	"errors"
	"fmt"
	"strconv"
	"strings"
)

// TraceContext is the W3C traceparent payload carried across services.
type TraceContext struct {
	TraceID [16]byte
	SpanID  [8]byte
	Flags   byte
}

func (t TraceContext) Sampled() bool { return t.Flags&0x01 == 1 }

var (
	ErrTraceparent    = errors.New("obs: invalid traceparent")
	ErrNoTraceContext = errors.New("obs: no trace context")
)

// ParseTraceparent accepts only the strict version-00 shape:
// 00-<32 lower hex>-<16 lower hex>-<2 lower hex>.
func ParseTraceparent(s string) (TraceContext, error) {
	var tc TraceContext
	parts := strings.Split(s, "-")
	if len(parts) != 4 || parts[0] != "00" || len(parts[1]) != 32 || len(parts[2]) != 16 || len(parts[3]) != 2 {
		return tc, fmt.Errorf("%w: shape or version", ErrTraceparent)
	}
	for _, part := range parts[1:] {
		if !isLowerHex(part) {
			return tc, fmt.Errorf("%w: non lower-case hex", ErrTraceparent)
		}
	}
	if _, err := hex.Decode(tc.TraceID[:], []byte(parts[1])); err != nil {
		return tc, fmt.Errorf("%w: trace id", ErrTraceparent)
	}
	if _, err := hex.Decode(tc.SpanID[:], []byte(parts[2])); err != nil {
		return tc, fmt.Errorf("%w: span id", ErrTraceparent)
	}
	if tc.TraceID == [16]byte{} || tc.SpanID == [8]byte{} {
		return tc, fmt.Errorf("%w: all-zero id", ErrTraceparent)
	}
	flags, err := strconv.ParseUint(parts[3], 16, 8)
	if err != nil || flags > 1 {
		return tc, fmt.Errorf("%w: undefined flag bits", ErrTraceparent)
	}
	tc.Flags = byte(flags)
	return tc, nil
}

func isLowerHex(s string) bool {
	for i := 0; i < len(s); i++ {
		c := s[i]
		if (c < '0' || c > '9') && (c < 'a' || c > 'f') {
			return false
		}
	}
	return len(s) > 0
}

// FormatTraceparent emits the canonical 55-byte version-00 header.
func FormatTraceparent(tc TraceContext) string {
	return fmt.Sprintf("00-%s-%s-%02x", hex.EncodeToString(tc.TraceID[:]), hex.EncodeToString(tc.SpanID[:]), tc.Flags)
}

// TextMapCarrier is the minimal header bag used by Inject and Extract.
type TextMapCarrier interface {
	Get(key string) string
	Set(key, value string)
}

type MapCarrier map[string]string

func (m MapCarrier) Get(key string) string { return m[key] }
func (m MapCarrier) Set(key, value string) { m[key] = value }

type ctxKey struct{}

func WithTraceContext(ctx context.Context, tc TraceContext) context.Context {
	return context.WithValue(ctx, ctxKey{}, tc)
}

func TraceContextFrom(ctx context.Context) (TraceContext, bool) {
	tc, ok := ctx.Value(ctxKey{}).(TraceContext)
	if !ok || (tc.TraceID == [16]byte{} && tc.SpanID == [8]byte{}) {
		return TraceContext{}, false
	}
	return tc, true
}

type Propagator struct{}

func (Propagator) Inject(ctx context.Context, c TextMapCarrier) error {
	tc, ok := TraceContextFrom(ctx)
	if !ok {
		return ErrNoTraceContext
	}
	c.Set("traceparent", FormatTraceparent(tc))
	return nil
}

func (Propagator) Extract(ctx context.Context, c TextMapCarrier) (context.Context, error) {
	tc, err := ParseTraceparent(c.Get("traceparent"))
	if err != nil {
		return ctx, err
	}
	return WithTraceContext(ctx, tc), nil
}

// Decision is the local sampling outcome for one trace.
type Decision uint8

const (
	Drop Decision = iota
	Sample
)

// Sampler is the head-sampling contract; parent is meaningful only when
// hasParent is true.
type Sampler interface {
	Decide(traceID [16]byte, parent Decision, hasParent bool) Decision
}

type ratioSampler struct{ threshold uint64 }

// ConsistentRatio samples a fixed fraction of trace IDs. Every service that
// uses the same fraction and ID reaches the same decision without coordination.
func ConsistentRatio(fraction float64) Sampler {
	if fraction < 0 {
		fraction = 0
	}
	if fraction > 1 {
		fraction = 1
	}
	const space = uint64(1) << 53
	return ratioSampler{threshold: uint64(fraction * float64(space))}
}

func (s ratioSampler) Decide(id [16]byte, _ Decision, _ bool) Decision {
	// Top 53 bits avoid float64 precision loss and are stable across services.
	if binary.BigEndian.Uint64(id[8:])>>11 < s.threshold {
		return Sample
	}
	return Drop
}

type parentBased struct{ root Sampler }

// ParentBased honours the upstream sampled bit; only root services consult the
// root sampler. This keeps one trace all-or-nothing across services.
func ParentBased(root Sampler) Sampler { return parentBased{root: root} }

func (p parentBased) Decide(id [16]byte, parent Decision, hasParent bool) Decision {
	if hasParent {
		if parent == Sample {
			return Sample
		}
		return Drop
	}
	return p.root.Decide(id, Drop, false)
}

// file: internal/platform/obs/sampling_test.go
// tier: L2
// verify: go test ./internal/platform/obs/ -count=1
package obs

import (
	"context"
	"encoding/binary"
	"testing"
)

const validTraceparent = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"

func TestTraceparent(t *testing.T) {
	tc, err := ParseTraceparent(validTraceparent)
	if err != nil || !tc.Sampled() || FormatTraceparent(tc) != validTraceparent {
		t.Fatalf("round trip: %+v %v", tc, err)
	}
	bad := []string{
		"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7",
		"00-4BF92F3577B34DA6A3CE929D0E0E4736-00f067aa0ba902b7-01",
		"00-00000000000000000000000000000000-00f067aa0ba902b7-01",
		"00-4bf92f3577b34da6a3ce929d0e0e4736-0000000000000000-01",
		"ff-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
		"01-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
		"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-03",
	}
	for _, in := range bad {
		if _, err := ParseTraceparent(in); err == nil {
			t.Fatalf("accepted %q", in)
		}
	}
	t.Logf("valid=%s rejected=%d", FormatTraceparent(tc), len(bad))
}

func splitmix64(x uint64) uint64 {
	x += 0x9e3779b97f4a7c15
	x = (x ^ (x >> 30)) * 0xbf58476d1ce4e5b9
	x = (x ^ (x >> 27)) * 0x94d049bb133111eb
	return x ^ (x >> 31)
}

func traceID(seed uint64) [16]byte {
	var id [16]byte
	binary.BigEndian.PutUint64(id[:8], splitmix64(seed))
	binary.BigEndian.PutUint64(id[8:], splitmix64(seed+1))
	return id
}

func TestConsistentRatio(t *testing.T) {
	s := ConsistentRatio(0.10)
	hits := 0
	for i := uint64(1); i <= 100000; i++ {
		id := traceID(i)
		if s.Decide(id, Drop, false) != s.Decide(id, Drop, false) {
			t.Fatalf("trace %d flipped", i)
		}
		if s.Decide(id, Drop, false) == Sample {
			hits++
		}
	}
	share := float64(hits) / 100000
	if share < 0.09 || share > 0.11 {
		t.Fatalf("share = %.4f", share)
	}
	t.Logf("trace_ids=100000 fraction=0.10 sampled=%d share=%.4f", hits, share)
}

func TestParentBased(t *testing.T) {
	s := ParentBased(ConsistentRatio(0.5))
	id := traceID(42)
	if s.Decide(id, Sample, true) != Sample || s.Decide(id, Drop, true) != Drop {
		t.Fatalf("parent bit ignored")
	}
	if s.Decide(id, Drop, false) != ConsistentRatio(0.5).Decide(id, Drop, false) {
		t.Fatalf("root decision differs")
	}
	t.Logf("parent_sample=sample parent_drop=drop root_sampled=%v", s.Decide(id, Drop, false) == Sample)
}

func TestPropagationChain(t *testing.T) {
	tc, _ := ParseTraceparent(validTraceparent)
	p := Propagator{}
	carrier := MapCarrier{}
	if err := p.Inject(WithTraceContext(context.Background(), tc), carrier); err != nil {
		t.Fatalf("inject: %v", err)
	}
	var got TraceContext
	for i, svc := range []string{"order", "inventory", "payment"} {
		next, err := p.Extract(context.Background(), carrier)
		if err != nil {
			t.Fatalf("%s: %v", svc, err)
		}
		var ok bool
		got, ok = TraceContextFrom(next)
		if !ok || got.TraceID != tc.TraceID || !got.Sampled() {
			t.Fatalf("%s lost trace context", svc)
		}
		child := got
		for j := range child.SpanID {
			child.SpanID[j] = byte(i*8 + j + 1)
		}
		carrier = MapCarrier{}
		if err := p.Inject(WithTraceContext(context.Background(), child), carrier); err != nil {
			t.Fatalf("%s inject: %v", svc, err)
		}
	}
	t.Logf("hops=3 trace_id=%x sampled=%v header=%s", got.TraceID[8:], got.Sampled(), carrier.Get("traceparent"))
}

$ go version
go version go1.26.0 darwin/arm64
$ gofmt -l .
$ go vet ./...
$ go test ./internal/platform/obs/ -count=1 -v -run 'TestTraceparent|TestConsistentRatio|TestParentBased|TestPropagationChain'
=== RUN   TestTraceparent
    sampling_test.go:33: valid=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 rejected=7
--- PASS: TestTraceparent (0.00s)
=== RUN   TestConsistentRatio
    sampling_test.go:66: trace_ids=100000 fraction=0.10 sampled=10021 share=0.1002
--- PASS: TestConsistentRatio (0.00s)
=== RUN   TestParentBased
    sampling_test.go:78: parent_sample=sample parent_drop=drop root_sampled=false
--- PASS: TestParentBased (0.00s)
=== RUN   TestPropagationChain
    sampling_test.go:108: hops=3 trace_id=a3ce929d0e0e4736 sampled=true header=00-4bf92f3577b34da6a3ce929d0e0e4736-1112131415161718-01
--- PASS: TestPropagationChain (0.00s)
PASS
ok  	archlab/internal/platform/obs	0.237s