Debian Codegraph @

exporters/otlp/otlptrace/otlptracegrpc/client.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 package otlptracegrpc // import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
5
6 import (
7 "context"
8 "errors"
9 "sync"
10 "time"
11
12 coltracepb "go.opentelemetry.io/proto/otlp/collector/trace/v1"
13 tracepb "go.opentelemetry.io/proto/otlp/trace/v1"
14 "google.golang.org/genproto/googleapis/rpc/errdetails"
15 "google.golang.org/grpc"
16 "google.golang.org/grpc/codes"
17 "google.golang.org/grpc/metadata"
18 "google.golang.org/grpc/status"
19
20 "go.opentelemetry.io/otel/exporters/otlp/otlptrace"
21 "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc/internal"
22 "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc/internal/counter"
23 "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc/internal/observ"
24 "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc/internal/otlpconfig"
25 "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc/internal/retry"
26 )
27
28 type client struct {
29 endpoint string
30 dialOpts []grpc.DialOption
31 metadata metadata.MD
32 exportTimeout time.Duration
33 requestFunc retry.RequestFunc
34
35 // stopCtx is used as a parent context for all exports. Therefore, when it
36 // is canceled with the stopFunc all exports are canceled.
37 stopCtx context.Context
38 // stopFunc cancels stopCtx, stopping any active exports.
39 stopFunc context.CancelFunc
40
41 // ourConn keeps track of where conn was created: true if created here on
42 // Start, or false if passed with an option. This is important on Shutdown
43 // as the conn should only be closed if created here on start. Otherwise,
44 // it is up to the processes that passed the conn to close it.
45 ourConn bool
46 conn *grpc.ClientConn
47 tscMu sync.RWMutex
48 tsc coltracepb.TraceServiceClient
49
50 instID int64
51 inst *observ.Instrumentation
52 }
53
54 // Compile time check *client implements otlptrace.Client.
55 var _ otlptrace.Client = (*client)(nil)
56
57 // NewClient creates a new gRPC trace client.
58 func NewClient(opts ...Option) otlptrace.Client {
59 return newClient(opts...)
60 }
61
62 func newClient(opts ...Option) *client {
63 cfg := otlpconfig.NewGRPCConfig(asGRPCOptions(opts)...)
64
65 ctx, cancel := context.WithCancel(context.Background()) //nolint:gosec // cancel called in client shutdown.
66
67 c := &client{
68 endpoint: cfg.Traces.Endpoint,
69 exportTimeout: cfg.Traces.Timeout,
70 requestFunc: cfg.RetryConfig.RequestFunc(retryable),
71 dialOpts: cfg.DialOptions,
72 stopCtx: ctx,
73 stopFunc: cancel,
74 conn: cfg.GRPCConn,
75 instID: counter.NextExporterID(),
76 }
77
78 if len(cfg.Traces.Headers) > 0 {
79 c.metadata = metadata.New(cfg.Traces.Headers)
80 }
81
82 return c
83 }
84
85 // Start establishes a gRPC connection to the collector.
86 func (c *client) Start(context.Context) error {
87 if c.conn == nil {
88 // If the caller did not provide a ClientConn when the client was
89 // created, create one using the configuration they did provide.
90 conn, err := grpc.NewClient(c.endpoint, c.dialOpts...)
91 if err != nil {
92 return err
93 }
94 // Keep track that we own the lifecycle of this conn and need to close
95 // it on Shutdown.
96 c.ourConn = true
97 c.conn = conn
98 }
99
100 // Initialize the instrumentation if not already done.
101 //
102 // Initialize here instead of NewClient to allow any errors to be passed
103 // back to the caller and so that any setup of the environment variables to
104 // enable instrumentation can be set via code.
105 var err error
106 if c.inst == nil {
107 target := c.conn.CanonicalTarget()
108 c.inst, err = observ.NewInstrumentation(c.instID, target)
109 }
110
111 // The otlptrace.Client interface states this method is called just once,
112 // so no need to check if already started.
113 c.tscMu.Lock()
114 c.tsc = coltracepb.NewTraceServiceClient(c.conn)
115 c.tscMu.Unlock()
116
117 return err
118 }
119
120 var errAlreadyStopped = errors.New("the client is already stopped")
121
122 // Stop shuts down the client.
123 //
124 // Any active connections to a remote endpoint are closed if they were created
125 // by the client. Any gRPC connection passed during creation using
126 // WithGRPCConn will not be closed. It is the caller's responsibility to
127 // handle cleanup of that resource.
128 //
129 // This method synchronizes with the UploadTraces method of the client. It
130 // will wait for any active calls to that method to complete unimpeded, or it
131 // will cancel any active calls if ctx expires. If ctx expires, the context
132 // error will be forwarded as the returned error. All client held resources
133 // will still be released in this situation.
134 //
135 // If the client has already stopped, an error will be returned describing
136 // this.
137 func (c *client) Stop(ctx context.Context) error {
138 // Make sure to return context error if the context is done when calling this method.
139 err := ctx.Err()
140
141 // Acquire the c.tscMu lock within the ctx lifetime.
142 acquired := make(chan struct{})
143 go func() {
144 c.tscMu.Lock()
145 close(acquired)
146 }()
147
148 select {
149 case <-ctx.Done():
150 // The Stop timeout is reached. Kill any remaining exports to force
151 // the clear of the lock and save the timeout error to return and
152 // signal the shutdown timed out before cleanly stopping.
153 c.stopFunc()
154 err = ctx.Err()
155
156 // To ensure the client is not left in a dirty state c.tsc needs to be
157 // set to nil. To avoid the race condition when doing this, ensure
158 // that all the exports are killed (initiated by c.stopFunc).
159 <-acquired
160 case <-acquired:
161 }
162 // Hold the tscMu lock for the rest of the function to ensure no new
163 // exports are started.
164 defer c.tscMu.Unlock()
165
166 // The otlptrace.Client interface states this method is called only
167 // once, but there is no guarantee it is called after Start. Ensure the
168 // client is started before doing anything and let the called know if they
169 // made a mistake.
170 if c.tsc == nil {
171 return errAlreadyStopped
172 }
173
174 // Clear c.tsc to signal the client is stopped.
175 c.tsc = nil
176
177 if c.ourConn {
178 closeErr := c.conn.Close()
179 // A context timeout error takes precedence over this error.
180 if err == nil && closeErr != nil {
181 err = closeErr
182 }
183 }
184 return err
185 }
186
187 var errShutdown = errors.New("the client is shutdown")
188
189 // UploadTraces sends a batch of spans.
190 //
191 // Retryable errors from the server will be handled according to any
192 // RetryConfig the client was created with.
193 func (c *client) UploadTraces(ctx context.Context, protoSpans []*tracepb.ResourceSpans) (uploadErr error) {
194 // Hold a read lock to ensure a shut down initiated after this starts does
195 // not abandon the export. This read lock acquire has less priority than a
196 // write lock acquire (i.e. Stop), meaning if the client is shutting down
197 // this will come after the shut down.
198 c.tscMu.RLock()
199 defer c.tscMu.RUnlock()
200
201 if c.tsc == nil {
202 return errShutdown
203 }
204
205 ctx, cancel := c.exportContext(ctx)
206 defer cancel()
207
208 var code codes.Code
209 if c.inst != nil {
210 op := c.inst.ExportSpans(ctx, len(protoSpans))
211 defer func() { op.End(uploadErr, code) }()
212 }
213
214 return c.requestFunc(ctx, func(iCtx context.Context) error {
215 resp, err := c.tsc.Export(iCtx, &coltracepb.ExportTraceServiceRequest{
216 ResourceSpans: protoSpans,
217 })
218 if resp != nil && resp.PartialSuccess != nil {
219 msg := resp.PartialSuccess.GetErrorMessage()
220 n := resp.PartialSuccess.GetRejectedSpans()
221 if n != 0 || msg != "" {
222 e := internal.TracePartialSuccessError(n, msg)
223 uploadErr = errors.Join(uploadErr, e)
224 }
225 }
226 // nil is converted to OK.
227 code = status.Code(err)
228 if code == codes.OK {
229 // Success.
230 return uploadErr
231 }
232 return errors.Join(uploadErr, err)
233 })
234 }
235
236 // exportContext returns a copy of parent with an appropriate deadline and
237 // cancellation function.
238 //
239 // It is the callers responsibility to cancel the returned context once its
240 // use is complete, via the parent or directly with the returned CancelFunc, to
241 // ensure all resources are correctly released.
242 func (c *client) exportContext(parent context.Context) (context.Context, context.CancelFunc) {
243 var (
244 ctx context.Context
245 cancel context.CancelFunc
246 )
247
248 if c.exportTimeout > 0 {
249 ctx, cancel = context.WithTimeoutCause(parent, c.exportTimeout, errors.New("exporter export timeout"))
250 } else {
251 ctx, cancel = context.WithCancel(parent) //nolint:gosec // cancel called by caller when export is complete.
252 }
253
254 if c.metadata.Len() > 0 {
255 md := c.metadata
256 if outMD, ok := metadata.FromOutgoingContext(ctx); ok {
257 md = metadata.Join(md, outMD)
258 }
259
260 ctx = metadata.NewOutgoingContext(ctx, md)
261 }
262
263 // Unify the client stopCtx with the parent.
264 go func() {
265 select {
266 case <-ctx.Done():
267 case <-c.stopCtx.Done():
268 // Cancel the export as the shutdown has timed out.
269 cancel()
270 }
271 }()
272
273 return ctx, cancel
274 }
275
276 // retryable returns if err identifies a request that can be retried and a
277 // duration to wait for if an explicit throttle time is included in err.
278 func retryable(err error) (bool, time.Duration) {
279 s := status.Convert(err)
280 return retryableGRPCStatus(s)
281 }
282
283 func retryableGRPCStatus(s *status.Status) (bool, time.Duration) {
284 switch s.Code() {
285 case codes.Canceled,
286 codes.DeadlineExceeded,
287 codes.Aborted,
288 codes.OutOfRange,
289 codes.Unavailable,
290 codes.DataLoss:
291 // Additionally handle RetryInfo.
292 _, d := throttleDelay(s)
293 return true, d
294 case codes.ResourceExhausted:
295 // Retry only if the server signals that the recovery from resource exhaustion is possible.
296 return throttleDelay(s)
297 }
298
299 // Not a retry-able error.
300 return false, 0
301 }
302
303 // throttleDelay returns of the status is RetryInfo
304 // and the its duration to wait for if an explicit throttle time.
305 func throttleDelay(s *status.Status) (bool, time.Duration) {
306 for _, detail := range s.Details() {
307 if t, ok := detail.(*errdetails.RetryInfo); ok {
308 return true, t.RetryDelay.AsDuration()
309 }
310 }
311 return false, 0
312 }
313
314 // MarshalLog is the marshaling function used by the logging system to represent this Client.
315 func (c *client) MarshalLog() any {
316 return struct {
317 Type string
318 Endpoint string
319 }{
320 Type: "otlptracegrpc",
321 Endpoint: c.endpoint,
322 }
323 }