snapshot of https://github.com/grpc/grpc-go.git (master, 2026-09-15; blobs > 131072B omitted)

stats/opentelemetry/internal/tracing/carrier.go

@@ -0,0 +1,131 @@
+/*
+ *
+ * Copyright 2024 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+// Package tracing implements the OpenTelemetry carrier for context propagation
+// in gRPC tracing.
+package tracing
+
+import (
+	"context"
+
+	"google.golang.org/grpc/grpclog"
+	"google.golang.org/grpc/metadata"
+)
+
+var logger = grpclog.Component("otel-plugin")
+
+// IncomingCarrier is a TextMapCarrier that uses incoming `context.Context` to
+// retrieve any propagated key-value pairs in text format.
+type IncomingCarrier struct {
+	ctx context.Context
+}
+
+// NewIncomingCarrier creates a new `IncomingCarrier` with the given context.
+// The incoming carrier should be used with propagator's `Extract()` method in
+// the incoming rpc path.
+func NewIncomingCarrier(ctx context.Context) *IncomingCarrier {
+	return &IncomingCarrier{ctx: ctx}
+}
+
+// Get returns the string value associated with the passed key from the
+// carrier's incoming context metadata.
+//
+// It returns an empty string if the key is not present in the carrier's
+// context or if the value associated with the key is empty.
+//
+// If multiple values are present for a key, it returns the last one.
+func (c *IncomingCarrier) Get(key string) string {
+	values := metadata.ValueFromIncomingContext(c.ctx, key)
+	if len(values) == 0 {
+		return ""
+	}
+	return values[len(values)-1]
+}
+
+// Set just logs an error. It implements the `TextMapCarrier` interface but
+// should not be used with `IncomingCarrier`.
+func (c *IncomingCarrier) Set(string, string) {
+	logger.Error("Set() should not be used with IncomingCarrier.")
+}
+
+// Keys returns the keys stored in the carrier's context metadata. It returns
+// keys from incoming context metadata.
+func (c *IncomingCarrier) Keys() []string {
+	md, ok := metadata.FromIncomingContext(c.ctx)
+	if !ok {
+		return nil
+	}
+	keys := make([]string, 0, len(md))
+	for key := range md {
+		keys = append(keys, key)
+	}
+	return keys
+}
+
+// Context returns the underlying context associated with the
+// `IncomingCarrier“.
+func (c *IncomingCarrier) Context() context.Context {
+	return c.ctx
+}
+
+// OutgoingCarrier is a TextMapCarrier that uses outgoing `context.Context` to
+// store any propagated key-value pairs in text format.
+type OutgoingCarrier struct {
+	ctx context.Context
+}
+
+// NewOutgoingCarrier creates a new Carrier with the given context. The
+// outgoing carrier should be used with propagator's `Inject()` method in the
+// outgoing rpc path.
+func NewOutgoingCarrier(ctx context.Context) *OutgoingCarrier {
+	return &OutgoingCarrier{ctx: ctx}
+}
+
+// Get just logs an error and returns an empty string. It implements the
+// `TextMapCarrier` interface but should not be used with `OutgoingCarrier`.
+func (c *OutgoingCarrier) Get(string) string {
+	logger.Error("Get() should not be used with `OutgoingCarrier`")
+	return ""
+}
+
+// Set stores the key-value pair in the carrier's outgoing context metadata.
+//
+// If the key already exists, given value is appended to the last.
+func (c *OutgoingCarrier) Set(key, value string) {
+	c.ctx = metadata.AppendToOutgoingContext(c.ctx, key, value)
+}
+
+// Keys returns the keys stored in the carrier's context metadata. It returns
+// keys from outgoing context metadata.
+func (c *OutgoingCarrier) Keys() []string {
+	md, ok := metadata.FromOutgoingContext(c.ctx)
+	if !ok {
+		return nil
+	}
+	keys := make([]string, 0, len(md))
+	for key := range md {
+		keys = append(keys, key)
+	}
+	return keys
+}
+
+// Context returns the underlying context associated with the
+// `OutgoingCarrier“.
+func (c *OutgoingCarrier) Context() context.Context {
+	return c.ctx
+}

stats/opentelemetry/internal/tracing/carrier_test.go

@@ -0,0 +1,190 @@
+/*
+ *
+ * Copyright 2024 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     htestp://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package tracing
+
+import (
+	"context"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-cmp/cmp/cmpopts"
+	"google.golang.org/grpc/internal/grpctest"
+	"google.golang.org/grpc/metadata"
+)
+
+type s struct {
+	grpctest.Tester
+}
+
+func Test(t *testing.T) {
+	grpctest.RunSubTests(t, s{})
+}
+
+// TestIncomingCarrier verifies that `IncomingCarrier.Get()` returns correct
+// value for the corresponding key in the carrier's context metadata, if key is
+// present. If key is not present, it verifies that empty string is returned.
+//
+// If multiple values are present for a key, it verifies that last value is
+// returned.
+//
+// If key ends with `-bin`, it verifies that a correct binary value is returned
+// in the string format for the binary header.
+func (s) TestIncomingCarrier(t *testing.T) {
+	tests := []struct {
+		name     string
+		md       metadata.MD
+		key      string
+		want     string
+		wantKeys []string
+	}{
+		{
+			name:     "existing key",
+			md:       metadata.Pairs("key1", "value1"),
+			key:      "key1",
+			want:     "value1",
+			wantKeys: []string{"key1"},
+		},
+		{
+			name:     "non-existing key",
+			md:       metadata.Pairs("key1", "value1"),
+			key:      "key2",
+			want:     "",
+			wantKeys: []string{"key1"},
+		},
+		{
+			name:     "empty key",
+			md:       metadata.MD{},
+			key:      "key1",
+			want:     "",
+			wantKeys: []string{},
+		},
+		{
+			name:     "more than one key/value pair",
+			md:       metadata.MD{"key1": []string{"value1"}, "key2": []string{"value2"}},
+			key:      "key2",
+			want:     "value2",
+			wantKeys: []string{"key1", "key2"},
+		},
+		{
+			name:     "more than one value for a key",
+			md:       metadata.MD{"key1": []string{"value1", "value2"}},
+			key:      "key1",
+			want:     "value2",
+			wantKeys: []string{"key1"},
+		},
+		{
+			name:     "grpc-trace-bin key",
+			md:       metadata.Pairs("grpc-trace-bin", string([]byte{0x01, 0x02, 0x03})),
+			key:      "grpc-trace-bin",
+			want:     string([]byte{0x01, 0x02, 0x03}),
+			wantKeys: []string{"grpc-trace-bin"},
+		},
+		{
+			name:     "grpc-trace-bin key with another string key",
+			md:       metadata.MD{"key1": []string{"value1"}, "grpc-trace-bin": []string{string([]byte{0x01, 0x02, 0x03})}},
+			key:      "grpc-trace-bin",
+			want:     string([]byte{0x01, 0x02, 0x03}),
+			wantKeys: []string{"key1", "grpc-trace-bin"},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+			c := NewIncomingCarrier(metadata.NewIncomingContext(ctx, test.md))
+			got := c.Get(test.key)
+			if got != test.want {
+				t.Fatalf("c.Get() = %s, want %s", got, test.want)
+			}
+			if gotKeys := c.Keys(); !cmp.Equal(test.wantKeys, gotKeys, cmpopts.SortSlices(func(a, b string) bool { return a < b })) {
+				t.Fatalf("c.Keys() = keys %v, want %v", gotKeys, test.wantKeys)
+			}
+		})
+	}
+}
+
+// TestOutgoingCarrier verifies that a key-value pair is set in carrier's
+// context metadata using `OutgoingCarrier.Set()`. If key is not present, it
+// verifies that key-value pair is insterted. If key is already present, it
+// verifies that new value is appended at the end of list for the existing key.
+//
+// If key ends with `-bin`, it verifies that a binary value is set for
+// `-bin` header in string format.
+//
+// It also verifies that both existing and newly inserted keys are present in
+// the carrier's context using `Carrier.Keys()`.
+func (s) TestOutgoingCarrier(t *testing.T) {
+	tests := []struct {
+		name      string
+		initialMD metadata.MD
+		setKey    string
+		setValue  string
+		wantValue string // expected value of the set key
+		wantKeys  []string
+	}{
+		{
+			name:      "new key",
+			initialMD: metadata.MD{},
+			setKey:    "key1",
+			setValue:  "value1",
+			wantValue: "value1",
+			wantKeys:  []string{"key1"},
+		},
+		{
+			name:      "add to existing key",
+			initialMD: metadata.MD{"key1": []string{"oldvalue"}},
+			setKey:    "key1",
+			setValue:  "newvalue",
+			wantValue: "newvalue",
+			wantKeys:  []string{"key1"},
+		},
+		{
+			name:      "new key with different existing key",
+			initialMD: metadata.MD{"key2": []string{"value2"}},
+			setKey:    "key1",
+			setValue:  "value1",
+			wantValue: "value1",
+			wantKeys:  []string{"key2", "key1"},
+		},
+		{
+			name:      "grpc-trace-bin binary key",
+			initialMD: metadata.MD{"key1": []string{"value1"}},
+			setKey:    "grpc-trace-bin",
+			setValue:  string([]byte{0x01, 0x02, 0x03}),
+			wantValue: string([]byte{0x01, 0x02, 0x03}),
+			wantKeys:  []string{"key1", "grpc-trace-bin"},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+			c := NewOutgoingCarrier(metadata.NewOutgoingContext(ctx, test.initialMD))
+			c.Set(test.setKey, test.setValue)
+			if gotKeys := c.Keys(); !cmp.Equal(test.wantKeys, gotKeys, cmpopts.SortSlices(func(a, b string) bool { return a < b })) {
+				t.Fatalf("c.Keys() = keys %v, want %v", gotKeys, test.wantKeys)
+			}
+			if md, ok := metadata.FromOutgoingContext(c.Context()); ok && md.Get(test.setKey)[len(md.Get(test.setKey))-1] != test.wantValue {
+				t.Fatalf("got value %s, want %s, for key %s", md.Get(test.setKey)[len(md.Get(test.setKey))-1], test.wantValue, test.setKey)
+			}
+		})
+	}
+}