Debian Codegraph @

exporters/otlp/otlptrace/otlptracegrpc/options.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 "fmt"
8 "time"
9
10 "google.golang.org/grpc"
11 "google.golang.org/grpc/credentials"
12
13 "go.opentelemetry.io/otel"
14 "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc/internal/otlpconfig"
15 "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc/internal/retry"
16 )
17
18 // Option applies an option to the gRPC driver.
19 type Option interface {
20 applyGRPCOption(otlpconfig.Config) otlpconfig.Config
21 }
22
23 func asGRPCOptions(opts []Option) []otlpconfig.GRPCOption {
24 converted := make([]otlpconfig.GRPCOption, len(opts))
25 for i, o := range opts {
26 converted[i] = otlpconfig.NewGRPCOption(o.applyGRPCOption)
27 }
28 return converted
29 }
30
31 // RetryConfig defines configuration for retrying export of span batches that
32 // failed to be received by the target endpoint.
33 //
34 // This configuration does not define any network retry strategy. That is
35 // entirely handled by the gRPC ClientConn.
36 type RetryConfig retry.Config
37
38 type wrappedOption struct {
39 otlpconfig.GRPCOption
40 }
41
42 func (w wrappedOption) applyGRPCOption(cfg otlpconfig.Config) otlpconfig.Config {
43 return w.ApplyGRPCOption(cfg)
44 }
45
46 // WithInsecure disables client transport security for the exporter's gRPC
47 // connection just like grpc.WithInsecure()
48 // (https://pkg.go.dev/google.golang.org/grpc#WithInsecure) does. Note, by
49 // default, client security is required unless WithInsecure is used.
50 //
51 // This option has no effect if WithGRPCConn is used.
52 func WithInsecure() Option {
53 return wrappedOption{otlpconfig.WithInsecure()}
54 }
55
56 // WithEndpoint sets the target endpoint (host and port) the Exporter will
57 // connect to. The provided endpoint should resemble "example.com:4317" (no
58 // scheme or path).
59 //
60 // If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
61 // environment variable is set, and this option is not passed, that variable
62 // value will be used. If both environment variables are set,
63 // OTEL_EXPORTER_OTLP_TRACES_ENDPOINT will take precedence. If an environment
64 // variable is set, and this option is passed, this option will take precedence.
65 //
66 // If both this option and WithEndpointURL are used, the last used option will
67 // take precedence.
68 //
69 // By default, if an environment variable is not set, and this option is not
70 // passed, "localhost:4317" will be used.
71 //
72 // This option has no effect if WithGRPCConn is used.
73 func WithEndpoint(endpoint string) Option {
74 return wrappedOption{otlpconfig.WithEndpoint(endpoint)}
75 }
76
77 // WithEndpointURL sets the target endpoint URL (scheme, host, port, path)
78 // the Exporter will connect to. The provided endpoint URL should resemble
79 // "https://example.com:4318/v1/traces".
80 //
81 // If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
82 // environment variable is set, and this option is not passed, that variable
83 // value will be used. If both environment variables are set,
84 // OTEL_EXPORTER_OTLP_TRACES_ENDPOINT will take precedence. If an environment
85 // variable is set, and this option is passed, this option will take precedence.
86 //
87 // If both this option and WithEndpoint are used, the last used option will
88 // take precedence.
89 //
90 // If an invalid URL is provided, the default value will be kept.
91 //
92 // By default, if an environment variable is not set, and this option is not
93 // passed, "https://localhost:4317/v1/traces" will be used.
94 //
95 // This option has no effect if WithGRPCConn is used.
96 func WithEndpointURL(u string) Option {
97 return wrappedOption{otlpconfig.WithEndpointURL(u)}
98 }
99
100 // WithReconnectionPeriod set the minimum amount of time between connection
101 // attempts to the target endpoint.
102 //
103 // This option has no effect if WithGRPCConn is used.
104 func WithReconnectionPeriod(rp time.Duration) Option {
105 return wrappedOption{otlpconfig.NewGRPCOption(func(cfg otlpconfig.Config) otlpconfig.Config {
106 cfg.ReconnectionPeriod = rp
107 return cfg
108 })}
109 }
110
111 func compressorToCompression(compressor string) otlpconfig.Compression {
112 if compressor == "gzip" {
113 return otlpconfig.GzipCompression
114 }
115
116 otel.Handle(fmt.Errorf("invalid compression type: '%s', using no compression as default", compressor))
117 return otlpconfig.NoCompression
118 }
119
120 // WithCompressor sets the compressor for the gRPC client to use when sending
121 // requests. Supported compressor values: "gzip".
122 func WithCompressor(compressor string) Option {
123 return wrappedOption{otlpconfig.WithCompression(compressorToCompression(compressor))}
124 }
125
126 // WithHeaders will send the provided headers with each gRPC requests.
127 func WithHeaders(headers map[string]string) Option {
128 return wrappedOption{otlpconfig.WithHeaders(headers)}
129 }
130
131 // WithTLSCredentials allows the connection to use TLS credentials when
132 // talking to the server. It takes in grpc.TransportCredentials instead of say
133 // a Certificate file or a tls.Certificate, because the retrieving of these
134 // credentials can be done in many ways e.g. plain file, in code tls.Config or
135 // by certificate rotation, so it is up to the caller to decide what to use.
136 //
137 // This option has no effect if WithGRPCConn is used.
138 func WithTLSCredentials(creds credentials.TransportCredentials) Option {
139 return wrappedOption{otlpconfig.NewGRPCOption(func(cfg otlpconfig.Config) otlpconfig.Config {
140 cfg.Traces.GRPCCredentials = creds
141 return cfg
142 })}
143 }
144
145 // WithServiceConfig defines the default gRPC service config used.
146 //
147 // This option has no effect if WithGRPCConn is used.
148 func WithServiceConfig(serviceConfig string) Option {
149 return wrappedOption{otlpconfig.NewGRPCOption(func(cfg otlpconfig.Config) otlpconfig.Config {
150 cfg.ServiceConfig = serviceConfig
151 return cfg
152 })}
153 }
154
155 // WithDialOption sets explicit grpc.DialOptions to use when making a
156 // connection. The options here are appended to the internal grpc.DialOptions
157 // used so they will take precedence over any other internal grpc.DialOptions
158 // they might conflict with.
159 // The [grpc.WithBlock], [grpc.WithTimeout], and [grpc.WithReturnConnectionError]
160 // grpc.DialOptions are ignored.
161 //
162 // This option has no effect if WithGRPCConn is used.
163 func WithDialOption(opts ...grpc.DialOption) Option {
164 return wrappedOption{otlpconfig.NewGRPCOption(func(cfg otlpconfig.Config) otlpconfig.Config {
165 cfg.DialOptions = opts
166 return cfg
167 })}
168 }
169
170 // WithGRPCConn sets conn as the gRPC ClientConn used for all communication.
171 //
172 // This option takes precedence over any other option that relates to
173 // establishing or persisting a gRPC connection to a target endpoint. Any
174 // other option of those types passed will be ignored.
175 //
176 // It is the callers responsibility to close the passed conn. The client
177 // Shutdown method will not close this connection.
178 func WithGRPCConn(conn *grpc.ClientConn) Option {
179 return wrappedOption{otlpconfig.NewGRPCOption(func(cfg otlpconfig.Config) otlpconfig.Config {
180 cfg.GRPCConn = conn
181 return cfg
182 })}
183 }
184
185 // WithTimeout sets the max amount of time a client will attempt to export a
186 // batch of spans. This takes precedence over any retry settings defined with
187 // WithRetry, once this time limit has been reached the export is abandoned
188 // and the batch of spans is dropped.
189 //
190 // If unset, the default timeout will be set to 10 seconds.
191 func WithTimeout(duration time.Duration) Option {
192 return wrappedOption{otlpconfig.WithTimeout(duration)}
193 }
194
195 // WithRetry sets the retry policy for transient retryable errors that may be
196 // returned by the target endpoint when exporting a batch of spans.
197 //
198 // If the target endpoint responds with not only a retryable error, but
199 // explicitly returns a backoff time in the response. That time will take
200 // precedence over these settings.
201 //
202 // These settings define the retry strategy implemented by the exporter.
203 // These settings do not define any network retry strategy.
204 // That is handled by the gRPC ClientConn.
205 //
206 // If unset, the default retry policy will be used. It will retry the export
207 // 5 seconds after receiving a retryable error and increase exponentially
208 // after each error for no more than a total time of 1 minute.
209 func WithRetry(settings RetryConfig) Option {
210 return wrappedOption{otlpconfig.WithRetry(retry.Config(settings))}
211 }