Debian Codegraph @

exporters/otlp/otlplog/otlploggrpc/config.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 package otlploggrpc // import "go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc"
5
6 import (
7 "crypto/tls"
8 "crypto/x509"
9 "errors"
10 "fmt"
11 "net/url"
12 "os"
13 "strconv"
14 "strings"
15 "time"
16 "unicode"
17
18 "google.golang.org/grpc"
19 "google.golang.org/grpc/credentials"
20
21 "go.opentelemetry.io/otel"
22 "go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc/internal/retry"
23 "go.opentelemetry.io/otel/internal/global"
24 )
25
26 // Default values.
27 var (
28 defaultEndpoint = "localhost:4317"
29 defaultTimeout = 10 * time.Second
30 defaultRetryCfg = retry.DefaultConfig
31 )
32
33 // Environment variable keys.
34 var (
35 envEndpoint = []string{
36 "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT",
37 "OTEL_EXPORTER_OTLP_ENDPOINT",
38 }
39 envInsecure = []string{
40 "OTEL_EXPORTER_OTLP_LOGS_INSECURE",
41 "OTEL_EXPORTER_OTLP_INSECURE",
42 }
43
44 envHeaders = []string{
45 "OTEL_EXPORTER_OTLP_LOGS_HEADERS",
46 "OTEL_EXPORTER_OTLP_HEADERS",
47 }
48
49 envCompression = []string{
50 "OTEL_EXPORTER_OTLP_LOGS_COMPRESSION",
51 "OTEL_EXPORTER_OTLP_COMPRESSION",
52 }
53
54 envTimeout = []string{
55 "OTEL_EXPORTER_OTLP_LOGS_TIMEOUT",
56 "OTEL_EXPORTER_OTLP_TIMEOUT",
57 }
58
59 envTLSCert = []string{
60 "OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE",
61 "OTEL_EXPORTER_OTLP_CERTIFICATE",
62 }
63 envTLSClient = []struct {
64 Certificate string
65 Key string
66 }{
67 {
68 "OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE",
69 "OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY",
70 },
71 {
72 "OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE",
73 "OTEL_EXPORTER_OTLP_CLIENT_KEY",
74 },
75 }
76 )
77
78 type fnOpt func(config) config
79
80 func (f fnOpt) applyOption(c config) config { return f(c) }
81
82 // Option applies an option to the Exporter.
83 type Option interface {
84 applyOption(config) config
85 }
86
87 type config struct {
88 endpoint setting[string]
89 insecure setting[bool]
90 tlsCfg setting[*tls.Config]
91 headers setting[map[string]string]
92 compression setting[Compression]
93 timeout setting[time.Duration]
94 retryCfg setting[retry.Config]
95
96 // gRPC configurations
97 gRPCCredentials setting[credentials.TransportCredentials]
98 serviceConfig setting[string]
99 reconnectionPeriod setting[time.Duration]
100 dialOptions setting[[]grpc.DialOption]
101 gRPCConn setting[*grpc.ClientConn]
102 }
103
104 func newConfig(options []Option) config {
105 var c config
106 for _, opt := range options {
107 c = opt.applyOption(c)
108 }
109
110 // Apply environment value and default value
111 c.endpoint = c.endpoint.Resolve(
112 getEnv[string](envEndpoint, convEndpoint),
113 fallback[string](defaultEndpoint),
114 )
115 c.insecure = c.insecure.Resolve(
116 loadInsecureFromEnvEndpoint(envEndpoint),
117 getEnv[bool](envInsecure, convInsecure),
118 )
119 c.tlsCfg = c.tlsCfg.Resolve(
120 loadEnvTLS[*tls.Config](),
121 )
122 c.headers = c.headers.Resolve(
123 getEnv[map[string]string](envHeaders, convHeaders),
124 )
125 c.compression = c.compression.Resolve(
126 getEnv[Compression](envCompression, convCompression),
127 )
128 c.timeout = c.timeout.Resolve(
129 getEnv[time.Duration](envTimeout, convDuration),
130 fallback[time.Duration](defaultTimeout),
131 )
132 c.retryCfg = c.retryCfg.Resolve(
133 fallback[retry.Config](defaultRetryCfg),
134 )
135
136 return c
137 }
138
139 // RetryConfig defines configuration for retrying the export of log data
140 // that failed.
141 //
142 // This configuration does not define any network retry strategy. That is
143 // entirely handled by the gRPC ClientConn.
144 type RetryConfig retry.Config
145
146 // WithInsecure disables client transport security for the Exporter's gRPC
147 // connection, just like grpc.WithInsecure()
148 // (https://pkg.go.dev/google.golang.org/grpc#WithInsecure) does.
149 //
150 // If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
151 // environment variable is set, and this option is not passed, that variable
152 // value will be used to determine client security. If the endpoint has a
153 // scheme of "http" or "unix" client security will be disabled. If both are
154 // set, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT will take precedence.
155 //
156 // By default, if an environment variable is not set, and this option is not
157 // passed, client security will be used.
158 //
159 // This option has no effect if WithGRPCConn is used.
160 func WithInsecure() Option {
161 return fnOpt(func(c config) config {
162 c.insecure = newSetting(true)
163 return c
164 })
165 }
166
167 // WithEndpoint sets the target endpoint the Exporter will connect to.
168 //
169 // If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
170 // environment variable is set, and this option is not passed, that variable
171 // value will be used. If both are set, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
172 // will take precedence.
173 //
174 // If both this option and WithEndpointURL are used, the last used option will
175 // take precedence.
176 //
177 // By default, if an environment variable is not set, and this option is not
178 // passed, "localhost:4317" will be used.
179 //
180 // This option has no effect if WithGRPCConn is used.
181 func WithEndpoint(endpoint string) Option {
182 return fnOpt(func(c config) config {
183 c.endpoint = newSetting(endpoint)
184 return c
185 })
186 }
187
188 // WithEndpointURL sets the target endpoint URL the Exporter will connect to.
189 //
190 // If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
191 // environment variable is set, and this option is not passed, that variable
192 // value will be used. If both are set, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
193 // will take precedence.
194 //
195 // If both this option and WithEndpoint are used, the last used option will
196 // take precedence.
197 //
198 // If an invalid URL is provided, the default value will be kept.
199 //
200 // By default, if an environment variable is not set, and this option is not
201 // passed, "localhost:4317" will be used.
202 //
203 // This option has no effect if WithGRPCConn is used.
204 func WithEndpointURL(rawURL string) Option {
205 u, err := url.Parse(rawURL)
206 if err != nil {
207 global.Error(err, "otlplog: parse endpoint url", "url", rawURL)
208 return fnOpt(func(c config) config { return c })
209 }
210 return fnOpt(func(c config) config {
211 c.endpoint = newSetting(u.Host)
212 c.insecure = insecureFromScheme(c.insecure, u.Scheme)
213 return c
214 })
215 }
216
217 // WithReconnectionPeriod set the minimum amount of time between connection
218 // attempts to the target endpoint.
219 //
220 // This option has no effect if WithGRPCConn is used.
221 func WithReconnectionPeriod(rp time.Duration) Option {
222 return fnOpt(func(c config) config {
223 c.reconnectionPeriod = newSetting(rp)
224 return c
225 })
226 }
227
228 // Compression describes the compression used for exported payloads.
229 type Compression int
230
231 const (
232 // NoCompression represents that no compression should be used.
233 NoCompression Compression = iota
234 // GzipCompression represents that gzip compression should be used.
235 GzipCompression
236 )
237
238 // WithCompressor sets the compressor the gRPC client uses.
239 // Supported compressor values: "gzip".
240 //
241 // If the OTEL_EXPORTER_OTLP_COMPRESSION or
242 // OTEL_EXPORTER_OTLP_LOGS_COMPRESSION environment variable is set, and
243 // this option is not passed, that variable value will be used. That value can
244 // be either "none" or "gzip". If both are set,
245 // OTEL_EXPORTER_OTLP_LOGS_COMPRESSION will take precedence.
246 //
247 // By default, if an environment variable is not set, and this option is not
248 // passed, no compression strategy will be used.
249 //
250 // This option has no effect if WithGRPCConn is used.
251 func WithCompressor(compressor string) Option {
252 return fnOpt(func(c config) config {
253 c.compression = newSetting(compressorToCompression(compressor))
254 return c
255 })
256 }
257
258 // WithHeaders will send the provided headers with each gRPC requests.
259 //
260 // If the OTEL_EXPORTER_OTLP_HEADERS or OTEL_EXPORTER_OTLP_LOGS_HEADERS
261 // environment variable is set, and this option is not passed, that variable
262 // value will be used. The value will be parsed as a list of key value pairs.
263 // These pairs are expected to be in the W3C Correlation-Context format
264 // without additional semi-colon delimited metadata (i.e. "k1=v1,k2=v2"). If
265 // both are set, OTEL_EXPORTER_OTLP_LOGS_HEADERS will take precedence.
266 //
267 // By default, if an environment variable is not set, and this option is not
268 // passed, no user headers will be set.
269 func WithHeaders(headers map[string]string) Option {
270 return fnOpt(func(c config) config {
271 c.headers = newSetting(headers)
272 return c
273 })
274 }
275
276 // WithTLSCredentials sets the gRPC connection to use creds.
277 //
278 // If the OTEL_EXPORTER_OTLP_CERTIFICATE or
279 // OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE environment variable is set, and
280 // this option is not passed, that variable value will be used. The value will
281 // be parsed the filepath of the TLS certificate chain to use. If both are
282 // set, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE will take precedence.
283 //
284 // By default, if an environment variable is not set, and this option is not
285 // passed, no TLS credentials will be used.
286 //
287 // This option has no effect if WithGRPCConn is used.
288 func WithTLSCredentials(credential credentials.TransportCredentials) Option {
289 return fnOpt(func(c config) config {
290 c.gRPCCredentials = newSetting(credential)
291 return c
292 })
293 }
294
295 // WithServiceConfig defines the default gRPC service config used.
296 //
297 // This option has no effect if WithGRPCConn is used.
298 func WithServiceConfig(serviceConfig string) Option {
299 return fnOpt(func(c config) config {
300 c.serviceConfig = newSetting(serviceConfig)
301 return c
302 })
303 }
304
305 // WithDialOption sets explicit grpc.DialOptions to use when establishing a
306 // gRPC connection. The options here are appended to the internal grpc.DialOptions
307 // used so they will take precedence over any other internal grpc.DialOptions
308 // they might conflict with.
309 // The [grpc.WithBlock], [grpc.WithTimeout], and [grpc.WithReturnConnectionError]
310 // grpc.DialOptions are ignored.
311 //
312 // This option has no effect if WithGRPCConn is used.
313 func WithDialOption(opts ...grpc.DialOption) Option {
314 return fnOpt(func(c config) config {
315 c.dialOptions = newSetting(opts)
316 return c
317 })
318 }
319
320 // WithGRPCConn sets conn as the gRPC ClientConn used for all communication.
321 //
322 // This option takes precedence over any other option that relates to
323 // establishing or persisting a gRPC connection to a target endpoint. Any
324 // other option of those types passed will be ignored.
325 //
326 // It is the callers responsibility to close the passed conn. The Exporter
327 // Shutdown method will not close this connection.
328 func WithGRPCConn(conn *grpc.ClientConn) Option {
329 return fnOpt(func(c config) config {
330 c.gRPCConn = newSetting(conn)
331 return c
332 })
333 }
334
335 // WithTimeout sets the max amount of time an Exporter will attempt an export.
336 //
337 // This takes precedence over any retry settings defined by WithRetry. Once
338 // this time limit has been reached the export is abandoned and the log
339 // data is dropped.
340 //
341 // If the OTEL_EXPORTER_OTLP_TIMEOUT or OTEL_EXPORTER_OTLP_LOGS_TIMEOUT
342 // environment variable is set, and this option is not passed, that variable
343 // value will be used. The value will be parsed as an integer representing the
344 // timeout in milliseconds. If both are set,
345 // OTEL_EXPORTER_OTLP_LOGS_TIMEOUT will take precedence.
346 //
347 // By default, if an environment variable is not set, and this option is not
348 // passed, a timeout of 10 seconds will be used.
349 func WithTimeout(duration time.Duration) Option {
350 return fnOpt(func(c config) config {
351 c.timeout = newSetting(duration)
352 return c
353 })
354 }
355
356 // WithRetry sets the retry policy for transient retryable errors that are
357 // returned by the target endpoint.
358 //
359 // If the target endpoint responds with not only a retryable error, but
360 // explicitly returns a backoff time in the response, that time will take
361 // precedence over these settings.
362 //
363 // These settings define the retry strategy implemented by the exporter.
364 // These settings do not define any network retry strategy.
365 // That is handled by the gRPC ClientConn.
366 //
367 // If unset, the default retry policy will be used. It will retry the export
368 // 5 seconds after receiving a retryable error and increase exponentially
369 // after each error for no more than a total time of 1 minute.
370 func WithRetry(rc RetryConfig) Option {
371 return fnOpt(func(c config) config {
372 c.retryCfg = newSetting(retry.Config(rc))
373 return c
374 })
375 }
376
377 // convCompression returns the parsed compression encoded in s. NoCompression
378 // and an errors are returned if s is unknown.
379 func convCompression(s string) (Compression, error) {
380 switch s {
381 case "gzip":
382 return GzipCompression, nil
383 case "none", "":
384 return NoCompression, nil
385 }
386 return NoCompression, fmt.Errorf("unknown compression: %s", s)
387 }
388
389 // convEndpoint converts s from a URL string to an endpoint if s is a valid
390 // URL. Otherwise, "" and an error are returned.
391 func convEndpoint(s string) (string, error) {
392 u, err := url.Parse(s)
393 if err != nil {
394 return "", err
395 }
396 return u.Host, nil
397 }
398
399 // convInsecure converts s from string to bool without case sensitivity.
400 // If s is not valid returns error.
401 func convInsecure(s string) (bool, error) {
402 s = strings.ToLower(s)
403 if s != "true" && s != "false" {
404 return false, fmt.Errorf("can't convert %q to bool", s)
405 }
406
407 return s == "true", nil
408 }
409
410 // loadInsecureFromEnvEndpoint returns a resolver that fetches
411 // insecure setting from envEndpoint is it possible.
412 func loadInsecureFromEnvEndpoint(envEndpoint []string) resolver[bool] {
413 return func(s setting[bool]) setting[bool] {
414 if s.Set {
415 // Passed, valid, options have precedence.
416 return s
417 }
418
419 for _, key := range envEndpoint {
420 if vStr := os.Getenv(key); vStr != "" {
421 u, err := url.Parse(vStr)
422 if err != nil {
423 otel.Handle(fmt.Errorf("invalid %s value %s: %w", key, vStr, err))
424 continue
425 }
426
427 return insecureFromScheme(s, u.Scheme)
428 }
429 }
430 return s
431 }
432 }
433
434 // convHeaders converts the OTel environment variable header value s into a
435 // mapping of header key to value. If s is invalid a partial result and error
436 // are returned.
437 func convHeaders(s string) (map[string]string, error) {
438 out := make(map[string]string)
439 var err error
440 for header := range strings.SplitSeq(s, ",") {
441 rawKey, rawVal, found := strings.Cut(header, "=")
442 if !found {
443 err = errors.Join(err, fmt.Errorf("invalid header: %s", header))
444 continue
445 }
446
447 key := strings.TrimSpace(rawKey)
448
449 // Validate the key.
450 if !isValidHeaderKey(key) {
451 err = errors.Join(err, fmt.Errorf("invalid header key: %s", rawKey))
452 continue
453 }
454
455 // Only decode the value.
456 escVal, e := url.PathUnescape(rawVal)
457 if e != nil {
458 err = errors.Join(err, fmt.Errorf("invalid header value: %s", rawVal))
459 continue
460 }
461 val := strings.TrimSpace(escVal)
462
463 out[key] = val
464 }
465 return out, err
466 }
467
468 // convDuration converts s into a duration of milliseconds. If s does not
469 // contain an integer, 0 and an error are returned.
470 func convDuration(s string) (time.Duration, error) {
471 d, err := strconv.Atoi(s)
472 if err != nil {
473 return 0, err
474 }
475 // OTel durations are defined in milliseconds.
476 return time.Duration(d) * time.Millisecond, nil
477 }
478
479 // loadEnvTLS returns a resolver that loads a *tls.Config from files defined by
480 // the OTLP TLS environment variables. This will load both the rootCAs and
481 // certificates used for mTLS.
482 //
483 // If the filepath defined is invalid or does not contain valid TLS files, an
484 // error is passed to the OTel ErrorHandler and no TLS configuration is
485 // provided.
486 func loadEnvTLS[T *tls.Config]() resolver[T] {
487 return func(s setting[T]) setting[T] {
488 if s.Set {
489 // Passed, valid, options have precedence.
490 return s
491 }
492
493 var rootCAs *x509.CertPool
494 var err error
495 for _, key := range envTLSCert {
496 if v := os.Getenv(key); v != "" {
497 rootCAs, err = loadCertPool(v)
498 break
499 }
500 }
501
502 var certs []tls.Certificate
503 for _, pair := range envTLSClient {
504 cert := os.Getenv(pair.Certificate)
505 key := os.Getenv(pair.Key)
506 if cert != "" && key != "" {
507 var e error
508 certs, e = loadCertificates(cert, key)
509 err = errors.Join(err, e)
510 break
511 }
512 }
513
514 if err != nil {
515 err = fmt.Errorf("failed to load TLS: %w", err)
516 otel.Handle(err)
517 } else if rootCAs != nil || certs != nil {
518 s.Set = true
519 s.Value = &tls.Config{RootCAs: rootCAs, Certificates: certs}
520 }
521 return s
522 }
523 }
524
525 // readFile is used for testing.
526 var readFile = os.ReadFile
527
528 // loadCertPool loads and returns the *x509.CertPool found at path if it exists
529 // and is valid. Otherwise, nil and an error is returned.
530 func loadCertPool(path string) (*x509.CertPool, error) {
531 b, err := readFile(path)
532 if err != nil {
533 return nil, err
534 }
535 cp := x509.NewCertPool()
536 if ok := cp.AppendCertsFromPEM(b); !ok {
537 return nil, errors.New("certificate not added")
538 }
539 return cp, nil
540 }
541
542 // loadCertificates loads and returns the tls.Certificate found at path if it
543 // exists and is valid. Otherwise, nil and an error is returned.
544 func loadCertificates(certPath, keyPath string) ([]tls.Certificate, error) {
545 cert, err := readFile(certPath)
546 if err != nil {
547 return nil, err
548 }
549 key, err := readFile(keyPath)
550 if err != nil {
551 return nil, err
552 }
553 crt, err := tls.X509KeyPair(cert, key)
554 if err != nil {
555 return nil, err
556 }
557 return []tls.Certificate{crt}, nil
558 }
559
560 // insecureFromScheme return setting if the connection should
561 // use client transport security or not.
562 // Empty scheme doesn't force insecure setting.
563 func insecureFromScheme(prev setting[bool], scheme string) setting[bool] {
564 if scheme == "https" {
565 return newSetting(false)
566 } else if scheme != "" {
567 return newSetting(true)
568 }
569
570 return prev
571 }
572
573 func compressorToCompression(compressor string) Compression {
574 c, err := convCompression(compressor)
575 if err != nil {
576 otel.Handle(fmt.Errorf("%w, using no compression as default", err))
577 return NoCompression
578 }
579
580 return c
581 }
582
583 // setting is a configuration setting value.
584 type setting[T any] struct {
585 Value T
586 Set bool
587 }
588
589 // newSetting returns a new setting with the value set.
590 func newSetting[T any](value T) setting[T] {
591 return setting[T]{Value: value, Set: true}
592 }
593
594 // resolver returns an updated setting after applying an resolution operation.
595 type resolver[T any] func(setting[T]) setting[T]
596
597 // Resolve returns a resolved version of s.
598 //
599 // It will apply all the passed fn in the order provided, chaining together the
600 // return setting to the next input. The setting s is used as the initial
601 // argument to the first fn.
602 //
603 // Each fn needs to validate if it should apply given the Set state of the
604 // setting. This will not perform any checks on the set state when chaining
605 // function.
606 func (s setting[T]) Resolve(fn ...resolver[T]) setting[T] {
607 for _, f := range fn {
608 s = f(s)
609 }
610 return s
611 }
612
613 // getEnv returns a resolver that will apply an environment variable value
614 // associated with the first set key to a setting value. The conv function is
615 // used to convert between the environment variable value and the setting type.
616 //
617 // If the input setting to the resolver is set, the environment variable will
618 // not be applied.
619 //
620 // Any error returned from conv is sent to the OTel ErrorHandler and the
621 // setting will not be updated.
622 func getEnv[T any](keys []string, conv func(string) (T, error)) resolver[T] {
623 return func(s setting[T]) setting[T] {
624 if s.Set {
625 // Passed, valid, options have precedence.
626 return s
627 }
628
629 for _, key := range keys {
630 if vStr := os.Getenv(key); vStr != "" {
631 v, err := conv(vStr)
632 if err == nil {
633 s.Value = v
634 s.Set = true
635 break
636 }
637 otel.Handle(fmt.Errorf("invalid %s value %s: %w", key, vStr, err))
638 }
639 }
640 return s
641 }
642 }
643
644 // fallback returns a resolve that will set a setting value to val if it is not
645 // already set.
646 //
647 // This is usually passed at the end of a resolver chain to ensure a default is
648 // applied if the setting has not already been set.
649 func fallback[T any](val T) resolver[T] {
650 return func(s setting[T]) setting[T] {
651 if !s.Set {
652 s.Value = val
653 s.Set = true
654 }
655 return s
656 }
657 }
658
659 func isValidHeaderKey(key string) bool {
660 if key == "" {
661 return false
662 }
663 for _, c := range key {
664 if !isTokenChar(c) {
665 return false
666 }
667 }
668 return true
669 }
670
671 func isTokenChar(c rune) bool {
672 return c <= unicode.MaxASCII && (unicode.IsLetter(c) ||
673 unicode.IsDigit(c) ||
674 c == '!' || c == '#' || c == '$' || c == '%' || c == '&' || c == '\'' || c == '*' ||
675 c == '+' || c == '-' || c == '.' || c == '^' || c == '_' || c == '`' || c == '|' || c == '~')
676 }