otlploghttp

README

OTLP Log HTTP Exporter

Documentation

Overview

Package otlploghttp provides an OTLP log exporter. The exporter uses HTTP to transport OTLP protobuf payloads.

Exporter values should be created using New.

The environment variables described below can be used for configuration.

OTEL_EXPORTER_OTLP_ENDPOINT (default: "https://localhost:4318") - target base URL ("/v1/logs" is appended) to which the exporter sends telemetry. The value must contain a scheme ("http" or "https") and a host. The value may additionally contain a port and a path. The value should not contain a query string or fragment. The configuration can be overridden by the OTEL_EXPORTER_OTLP_LOGS_ENDPOINT environment variable and by the WithEndpoint, WithEndpointURL, and WithInsecure options.

OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (default: "https://localhost:4318/v1/logs") - target URL to which the exporter sends telemetry. The value must contain a scheme ("http" or "https") and a host. The value may additionally contain a port and a path. The value should not contain a query string or fragment. The configuration can be overridden by the WithEndpoint, WithEndpointURL, WithInsecure, and WithURLPath options.

OTEL_EXPORTER_OTLP_INSECURE, OTEL_EXPORTER_OTLP_LOGS_INSECURE (default: "false") - setting "true" disables client transport security for the exporter's HTTP connection. OTEL_EXPORTER_OTLP_LOGS_INSECURE takes precedence over OTEL_EXPORTER_OTLP_INSECURE. The configuration can be overridden by the WithInsecure and WithTLSClientConfig options.

OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_LOGS_HEADERS (default: none) - key-value pairs used as headers associated with HTTP requests. The value is expected to be represented in a format matching the W3C Baggage HTTP Header Content Format, except that additional semicolon-delimited metadata is not supported. Example value: "key1=value1,key2=value2". OTEL_EXPORTER_OTLP_LOGS_HEADERS takes precedence over OTEL_EXPORTER_OTLP_HEADERS. The configuration can be overridden by the WithHeaders option.

OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT (default: "10000") - maximum time in milliseconds the OTLP exporter waits for each batch export. OTEL_EXPORTER_OTLP_LOGS_TIMEOUT takes precedence over OTEL_EXPORTER_OTLP_TIMEOUT. The configuration can be overridden by the WithTimeout option.

OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_LOGS_COMPRESSION (default: none) - the compression strategy the exporter uses to compress the HTTP body. Supported value: "gzip". OTEL_EXPORTER_OTLP_LOGS_COMPRESSION takes precedence over OTEL_EXPORTER_OTLP_COMPRESSION. The configuration can be overridden by the WithCompression option.

OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE (default: none) - the filepath to the trusted certificate to use when verifying a server's TLS credentials. OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CERTIFICATE. The configuration can be overridden by the WithTLSClientConfig option.

OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE (default: none) - the filepath to the client's certificate chain to use with the client's private key for mTLS communication in PEM format. OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE. The configuration can be overridden by the WithTLSClientConfig option.

OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY (default: none) - the filepath to the client's private key to use in mTLS communication in PEM format. OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY takes precedence over OTEL_EXPORTER_OTLP_CLIENT_KEY. The configuration can be overridden by the WithTLSClientConfig option.

Example

package main

import (
	"context"

	"go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp"
	"go.opentelemetry.io/otel/log/global"
	"go.opentelemetry.io/otel/sdk/log"
)

func main() {
	ctx := context.Background()
	exp, err := otlploghttp.New(ctx)
	if err != nil {
		panic(err)
	}

	processor := log.NewBatchProcessor(exp)
	provider := log.NewLoggerProvider(log.WithProcessor(processor))
	defer func() {
		if err := provider.Shutdown(ctx); err != nil {
			panic(err)
		}
	}()

	global.SetLoggerProvider(provider)

	// From here, the provider can be used by instrumentation to collect
	// telemetry.
}

Index

• func Version() string
• type Compression
• type Exporter
  • func New(ctx context.Context, options ...Option) (*Exporter, error)
  • func (e *Exporter) Export(ctx context.Context, records []log.Record) error
  • func (*Exporter) ForceFlush(context.Context) error
  • func (e *Exporter) Shutdown(context.Context) error
• type HTTPTransportProxyFunc
• type Option
  • func WithCompression(compression Compression) Option
  • func WithEndpoint(endpoint string) Option
  • func WithEndpointURL(rawURL string) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithHeaders(headers map[string]string) Option
  • func WithInsecure() Option
  • func WithMaxRequestSize(size int) Option
  • func WithProxy(pf HTTPTransportProxyFunc) Option
  • func WithRetry(rc RetryConfig) Option
  • func WithTLSClientConfig(tlsCfg *tls.Config) Option
  • func WithTimeout(duration time.Duration) Option
  • func WithURLPath(urlPath string) Option
• type RetryConfig

Examples

• Package

Functions

func Version

func Version() string

Version is the current release version of the OpenTelemetry OTLP over HTTP/protobuf logs exporter in use.

Types

type Compression

type Compression int

Compression describes the compression used for exported payloads.

const (
	// NoCompression indicates that no compression is used.
	NoCompression Compression = iota
	// GzipCompression indicates that gzip compression is used.
	GzipCompression
)

type Exporter

type Exporter struct {
	// contains filtered or unexported fields
}

Exporter is an OpenTelemetry log exporter. It transports log data encoded as OTLP protobufs using HTTP. Exporter must be created with New.

func New

func New(ctx context.Context, options ...Option) (*Exporter, error)

New returns a new Exporter.

Use the Exporter with a log.BatchProcessor or another processor that exports records asynchronously.

func (*Exporter) Export

func (e *Exporter) Export(ctx context.Context, records []log.Record) error

Export transforms and transmits log records to an OTLP receiver. It returns log.ErrExporterShutdown if called after Shutdown.

func (*Exporter) ForceFlush

func (*Exporter) ForceFlush(context.Context) error

ForceFlush does nothing. The Exporter holds no state.

func (*Exporter) Shutdown

func (e *Exporter) Shutdown(context.Context) error

Shutdown shuts down the Exporter. Calls to Export after Shutdown return log.ErrExporterShutdown. Calls to ForceFlush perform no operation.

type HTTPTransportProxyFunc

type HTTPTransportProxyFunc func(*http.Request) (*url.URL, error)

HTTPTransportProxyFunc is a function that resolves which URL to use as a proxy for a given request. This type is compatible with http.Transport.Proxy and can be used to set a custom proxy function to the OTLP HTTP client.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option applies an option to the Exporter.

func WithCompression

func WithCompression(compression Compression) Option

WithCompression sets the compression strategy the Exporter will use to compress the HTTP body.

If the OTEL_EXPORTER_OTLP_COMPRESSION or OTEL_EXPORTER_OTLP_LOGS_COMPRESSION environment variable is set, and this option is not passed, that variable value will be used. That value can be either "none" or "gzip". If both are set, OTEL_EXPORTER_OTLP_LOGS_COMPRESSION will take precedence.

By default, if an environment variable is not set, and this option is not passed, no compression strategy will be used.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint sets the target endpoint the Exporter will connect to. This endpoint is specified as a host and optional port; no path or scheme should be included (see WithInsecure and WithURLPath).

If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT environment variable is set, and this option is not passed, that variable value will be used. If both environment variables are set, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT will take precedence. If an environment variable is set, and this option is passed, this option will take precedence.

If both this option and WithEndpointURL are used, the last used option will take precedence.

By default, if an environment variable is not set, and this option is not passed, "localhost:4318" will be used.

func WithEndpointURL

func WithEndpointURL(rawURL string) Option

WithEndpointURL sets the target endpoint URL the Exporter will connect to.

If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT environment variable is set, and this option is not passed, that variable value will be used. If both environment variables are set, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT will take precedence. If an environment variable is set, and this option is passed, this option will take precedence.

If both this option and WithEndpoint are used, the last used option will take precedence.

If an invalid URL is provided, the default value will be kept.

By default, if an environment variable is not set, and this option is not passed, "localhost:4318" will be used.

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets the HTTP client to be used by the exporter.

This option will take precedence over the WithProxy, WithTimeout, and WithTLSClientConfig options, as well as the OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE, OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT environment variables.

Timeout and all other fields of the passed http.Client are left intact.

Be aware that passing an HTTP client with a transport such as go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp.NewTransport can cause the client to be instrumented twice and cause infinite recursion.

func WithHeaders

func WithHeaders(headers map[string]string) Option

WithHeaders sends the provided headers with each HTTP request.

If the OTEL_EXPORTER_OTLP_HEADERS or OTEL_EXPORTER_OTLP_LOGS_HEADERS environment variable is set, and this option is not passed, that variable value will be used. The value will be parsed as a list of key-value pairs. These pairs are expected to be in the W3C Correlation-Context format without additional semicolon-delimited metadata (i.e. "k1=v1,k2=v2"). If both are set, OTEL_EXPORTER_OTLP_LOGS_HEADERS will take precedence.

By default, if an environment variable is not set, and this option is not passed, no user headers will be set.

func WithInsecure

func WithInsecure() Option

WithInsecure disables client transport security for the Exporter's HTTP connection.

If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT environment variable is set, and this option is not passed, that variable value will be used to determine client security. If the endpoint has a scheme of "http" or "unix", client security will be disabled. If both are set, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT will take precedence.

By default, if an environment variable is not set, and this option is not passed, client security will be used.

func WithMaxRequestSize

func WithMaxRequestSize(size int) Option

WithMaxRequestSize sets the maximum size, in bytes, of a serialized export request, before compression, that the exporter will send.

If size is less than or equal to zero, no request-size limit is applied. Disabling the limit is not recommended because it can lead to excessive resource consumption or abuse.

func WithProxy

func WithProxy(pf HTTPTransportProxyFunc) Option

WithProxy sets the Proxy function the client will use to determine the proxy to use for an HTTP request. If this option is not used, the client will use http.ProxyFromEnvironment.

func WithRetry

func WithRetry(rc RetryConfig) Option

WithRetry sets the retry policy for transient retryable errors that are returned by the target endpoint.

If the target endpoint responds with a retryable error and explicitly returns a backoff time in the response, that time will take precedence over these settings.

If unset, the default retry policy will be used. It will retry the export 5 seconds after receiving a retryable error, with the time between retries increasing exponentially after each error, for no more than 1 minute total.

func WithTLSClientConfig

func WithTLSClientConfig(tlsCfg *tls.Config) Option

WithTLSClientConfig sets the TLS configuration the Exporter will use for HTTP requests.

If the OTEL_EXPORTER_OTLP_CERTIFICATE or OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE environment variable is set, and this option is not passed, that variable value will be used. The value will be parsed as the filepath of the TLS certificate chain to use. If both are set, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE will take precedence.

By default, if an environment variable is not set, and this option is not passed, the system default configuration is used.

func WithTimeout

func WithTimeout(duration time.Duration) Option

WithTimeout sets the maximum amount of time an Exporter will attempt an export.

This takes precedence over any retry settings defined by WithRetry. Once this time limit has been reached, the export is abandoned and the log data is dropped.

If the OTEL_EXPORTER_OTLP_TIMEOUT or OTEL_EXPORTER_OTLP_LOGS_TIMEOUT environment variable is set, and this option is not passed, that variable value will be used. The value will be parsed as an integer representing the timeout in milliseconds. If both are set, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT will take precedence.

By default, if an environment variable is not set, and this option is not passed, a timeout of 10 seconds will be used.

func WithURLPath

func WithURLPath(urlPath string) Option

WithURLPath sets the URL path the Exporter will send requests to.

If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT environment variable is set, and this option is not passed, the path contained in that variable value will be used. If both are set, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT will take precedence.

By default, if an environment variable is not set, and this option is not passed, "/v1/logs" will be used.

type RetryConfig

type RetryConfig retry.Config

RetryConfig defines configuration for retrying failed exports of log data.