otlptracehttp

README

OTLP Trace HTTP Exporter

Documentation

Overview

Package otlptracehttp provides an OTLP span exporter using HTTP with protobuf or JSON payloads. By default the telemetry is sent to https://localhost:4318/v1/traces.

Exporter 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/traces" is appended) to which the exporter sends telemetry. The value must contain a scheme ("http" or "https") and 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 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT environment variable and by WithEndpoint, WithEndpointURL, WithInsecure options.

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (default: "https://localhost:4318/v1/traces") - target URL to which the exporter sends telemetry. The value must contain a scheme ("http" or "https") and 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 WithEndpoint, WithEndpointURL, WithInsecure, and WithURLPath options.

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

OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_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 semi-colon delimited metadata is not supported. Example value: "key1=value1,key2=value2". OTEL_EXPORTER_OTLP_TRACES_HEADERS takes precedence over OTEL_EXPORTER_OTLP_HEADERS. The configuration can be overridden by WithHeaders option.

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

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

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

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

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

OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_TRACES_PROTOCOL (default: "http/protobuf") - the transport protocol the exporter uses. For OTLP/HTTP exporters, it indicates the encoding format of the payloads sent to the collector. Supported value: "http/protobuf", "http/json". OTEL_EXPORTER_OTLP_TRACES_PROTOCOL takes precedence over OTEL_EXPORTER_OTLP_PROTOCOL. The configuration can be overridden by WithEncoding option.

Example

package main

import (
	"context"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
	"go.opentelemetry.io/otel/sdk/trace"
)

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

	tracerProvider := trace.NewTracerProvider(trace.WithBatcher(exp))
	defer func() {
		if err := tracerProvider.Shutdown(ctx); err != nil {
			panic(err)
		}
	}()
	otel.SetTracerProvider(tracerProvider)

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

Index

• Constants
• func New(ctx context.Context, opts ...Option) (*otlptrace.Exporter, error)
• func NewClient(opts ...Option) otlptrace.Client
• func NewUnstarted(opts ...Option) *otlptrace.Exporter
• type Compression
• type Encoding
• type HTTPTransportProxyFunc
• type Option
  • func WithCompression(compression Compression) Option
  • func WithEncoding(encoding Encoding) Option
  • func WithEndpoint(endpoint string) Option
  • func WithEndpointURL(u string) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithHeaders(headers map[string]string) Option
  • func WithInsecure() Option
  • func WithMaxRequestSize(size int) Option
  • func WithMaxResponseSize(size int64) 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

Constants

const (
	// NoCompression tells the driver to send payloads without
	// compression.
	NoCompression = Compression(otlpconfig.NoCompression)
	// GzipCompression tells the driver to send payloads after
	// compressing them with gzip.
	GzipCompression = Compression(otlpconfig.GzipCompression)
)

Functions

func New

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

New constructs a new Exporter and starts it.

func NewClient

func NewClient(opts ...Option) otlptrace.Client

NewClient creates a new HTTP trace client.

func NewUnstarted

func NewUnstarted(opts ...Option) *otlptrace.Exporter

NewUnstarted constructs a new Exporter and does not start it.

Types

type Compression

type Compression otlpconfig.Compression

Compression describes the compression used for payloads sent to the collector.

type Encoding

type Encoding int

Encoding describes the encoding used for payloads sent to the collector.

const (
	// EncodingProtobuf tells the driver to send protobuf-encoded payloads.
	EncodingProtobuf Encoding = iota
	// EncodingJSON tells the driver to send JSON-encoded payloads.
	EncodingJSON
)

type HTTPTransportProxyFunc

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

HTTPTransportProxyFunc is a function that resolves which URL to use as 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 HTTP client.

func WithCompression

func WithCompression(compression Compression) Option

WithCompression tells the driver to compress the sent data.

func WithEncoding

func WithEncoding(encoding Encoding) Option

WithEncoding tells the driver to use a specific encoding for the request payload.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint sets the target endpoint (host and port) the Exporter will connect to. The provided endpoint should resemble "example.com:4318" (no scheme or path).

If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_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_TRACES_ENDPOINT will take precedence. If an environment variable is set, and this option is passed, this option will take precedence. Note, both environment variables include the full scheme and path, while WithEndpoint sets only the host and port.

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.

This option has no effect if WithGRPCConn is used.

func WithEndpointURL

func WithEndpointURL(u string) Option

WithEndpointURL sets the target endpoint URL (scheme, host, port, path) the Exporter will connect to.

If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_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_TRACES_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.

The path of the provided URL is used as-is; with one exception: if the URL has no path, it is normalized to the root path ("/"). The default traces path ("/v1/traces") is not appended automatically. Use WithEndpoint if you want that behavior, or pass a URL that includes that path.

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

This option has no effect if WithGRPCConn is used.

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets the HTTP client to used by the exporter.

This option will take precedence over WithProxy, WithTimeout, WithTLSClientConfig options as well as OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE, OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_TRACES_TIMEOUT environment variables.

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

Be aware that passing an HTTP client with transport like 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 allows one to tell the driver to send additional HTTP headers with the payloads. Specifying headers like Content-Length, Content-Encoding and Content-Type may result in a broken driver.

func WithInsecure

func WithInsecure() Option

WithInsecure tells the driver to connect to the collector using the HTTP scheme, instead of HTTPS.

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 WithMaxResponseSize

func WithMaxResponseSize(size int64) Option

WithMaxResponseSize sets the maximum size, in bytes, of an OTLP/HTTP response body, after decompression, that the exporter will read.

By default, a limit of 4 MiB is used. Values less than or equal to zero are ignored. The response-size limit cannot be disabled.

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 configures the retry policy for transient errors that may occurs when exporting traces. An exponential back-off algorithm is used to ensure endpoints are not overwhelmed with retries. If unset, the default retry policy will retry after 5 seconds and increase exponentially after each error for a total of 1 minute.

func WithTLSClientConfig

func WithTLSClientConfig(tlsCfg *tls.Config) Option

WithTLSClientConfig can be used to set up a custom TLS configuration for the client used to send payloads to the collector. Use it if you want to use a custom certificate.

func WithTimeout

func WithTimeout(duration time.Duration) Option

WithTimeout tells the driver the max waiting time for the backend to process each spans batch. If unset, the default will be 10 seconds.

func WithURLPath

func WithURLPath(urlPath string) Option

WithURLPath allows one to override the default URL path used for sending traces. If unset, default ("/v1/traces") will be used.

type RetryConfig

type RetryConfig retry.Config

RetryConfig defines configuration for retrying batches in case of export failure using an exponential backoff.