Debian Codegraph @

exporters/otlp/otlplog/otlploghttp/config.go

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