| 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 |
} |