confighttp

README

HTTP Configuration Settings

HTTP exposes a variety of settings. Several of these settings are available for configuration within individual receivers or exporters.

Client Configuration

Exporters leverage client configuration.

Note that client configuration supports TLS configuration, the configuration parameters are also defined under tls like server configuration. For more information, see configtls README.

• endpoint: address:port
• tls
• headers: name/value pairs added to the HTTP request headers
  • certain headers such as Content-Length and Connection are automatically written when needed and values in Header may be ignored.
  • Host header is automatically derived from endpoint value. However, this automatic assignment can be overridden by explicitly setting the Host field in the headers field.
  • if Host header is provided then it overrides Host field in Request which results as an override of Host header value.
• read_buffer_size
• timeout
• write_buffer_size
• compression: Compression type to use among gzip, zstd, snappy, zlib, and deflate.
  • look at the documentation for the server-side of the communication.
  • none will be treated as uncompressed, and any other inputs will cause an error.
• max_idle_conns
• max_idle_conns_per_host
• max_conns_per_host
• idle_conn_timeout
• auth
• disable_keep_alives
• http2_read_idle_timeout
• http2_ping_timeout

Example:

exporter:
  otlphttp:
    endpoint: otelcol2:55690
    auth:
      authenticator: some-authenticator-extension
    tls:
      ca_file: ca.pem
      cert_file: cert.pem
      key_file: key.pem
    headers:
      test1: "value1"
      "test 2": "value 2"
    compression: zstd

Server Configuration

Receivers leverage server configuration.

• cors: Configure CORS, allowing the receiver to accept traces from web browsers, even if the receiver is hosted at a different origin. If left blank or set to null, CORS will not be enabled.
  • allowed_origins: A list of origins allowed to send requests to the receiver. An origin may contain a wildcard (*) to replace 0 or more characters (e.g., https://*.example.com). To allow any origin, set to ["*"]. If no origins are listed, CORS will not be enabled.
  • allowed_headers: Allow CORS requests to include headers outside the default safelist. By default, safelist headers and X-Requested-With will be allowed. To allow any request header, set to ["*"].
  • max_age: Sets the value of the Access-Control-Max-Age header, allowing clients to cache the response to CORS preflight requests. If not set, browsers use a default of 5 seconds.
• endpoint: Valid value syntax available here
• max_request_body_size: configures the maximum allowed body size in bytes for a single request. Default: 0 (no restriction)
• tls
• auth

You can enable attribute processor to append any http header to span's attribute using custom key. You also need to enable the "include_metadata"

Example:

receivers:
  otlp:
    protocols:
      http:
        include_metadata: true
        auth:
          authenticator: some-authenticator-extension
        cors:
          allowed_origins:
            - https://foo.bar.com
            - https://*.test.com
          allowed_headers:
            - Example-Header
          max_age: 7200
        endpoint: 0.0.0.0:55690
processors:
  attributes:
    actions:
      - key: http.client_ip
        from_context: X-Forwarded-For
        action: upsert

Documentation

Overview

Package confighttp defines the configuration settings for creating an HTTP client and server.

Index

• type CORSConfig
• type ClientConfig
  • func NewDefaultClientConfig() ClientConfig
  • func (hcs *ClientConfig) ToClient(ctx context.Context, host component.Host, settings component.TelemetrySettings) (*http.Client, error)
  • func (hcs *ClientConfig) ToClientContext(ctx context.Context, host component.Host, settings component.TelemetrySettings) (*http.Client, error)
• type ServerConfig
  • func (hss *ServerConfig) ToListener(ctx context.Context) (net.Listener, error)
  • func (hss *ServerConfig) ToListenerContext(ctx context.Context) (net.Listener, error)
  • func (hss *ServerConfig) ToServer(_ context.Context, host component.Host, settings component.TelemetrySettings, ...) (*http.Server, error)
  • func (hss *ServerConfig) ToServerContext(ctx context.Context, host component.Host, settings component.TelemetrySettings, ...) (*http.Server, error)
• type ToServerOption
  • func WithDecoder(key string, dec func(body io.ReadCloser) (io.ReadCloser, error)) ToServerOption
  • func WithErrorHandler(...) ToServerOption

Examples

• ServerConfig

Types

type CORSConfig

type CORSConfig struct {
	// AllowedOrigins sets the allowed values of the Origin header for
	// HTTP/JSON requests to an OTLP receiver. An origin may contain a
	// wildcard (*) to replace 0 or more characters (e.g.,
	// "http://*.domain.com", or "*" to allow any origin).
	AllowedOrigins []string `mapstructure:"allowed_origins"`

	// AllowedHeaders sets what headers will be allowed in CORS requests.
	// The Accept, Accept-Language, Content-Type, and Content-Language
	// headers are implicitly allowed. If no headers are listed,
	// X-Requested-With will also be accepted by default. Include "*" to
	// allow any request header.
	AllowedHeaders []string `mapstructure:"allowed_headers"`

	// MaxAge sets the value of the Access-Control-Max-Age response header.
	// Set it to the number of seconds that browsers should cache a CORS
	// preflight response for.
	MaxAge int `mapstructure:"max_age"`
}

CORSConfig configures a receiver for HTTP cross-origin resource sharing (CORS). See the underlying https://github.com/rs/cors package for details.

type ClientConfig

type ClientConfig struct {
	// The target URL to send data to (e.g.: http://some.url:9411/v1/traces).
	Endpoint string `mapstructure:"endpoint"`

	// ProxyURL setting for the collector
	ProxyURL string `mapstructure:"proxy_url"`

	// TLSSetting struct exposes TLS client configuration.
	TLSSetting configtls.ClientConfig `mapstructure:"tls"`

	// ReadBufferSize for HTTP client. See http.Transport.ReadBufferSize.
	ReadBufferSize int `mapstructure:"read_buffer_size"`

	// WriteBufferSize for HTTP client. See http.Transport.WriteBufferSize.
	WriteBufferSize int `mapstructure:"write_buffer_size"`

	// Timeout parameter configures `http.Client.Timeout`.
	Timeout time.Duration `mapstructure:"timeout"`

	// Additional headers attached to each HTTP request sent by the client.
	// Existing header values are overwritten if collision happens.
	// Header values are opaque since they may be sensitive.
	Headers map[string]configopaque.String `mapstructure:"headers"`

	// Custom Round Tripper to allow for individual components to intercept HTTP requests
	CustomRoundTripper func(next http.RoundTripper) (http.RoundTripper, error)

	// Auth configuration for outgoing HTTP calls.
	Auth *configauth.Authentication `mapstructure:"auth"`

	// The compression key for supported compression types within collector.
	Compression configcompression.Type `mapstructure:"compression"`

	// MaxIdleConns is used to set a limit to the maximum idle HTTP connections the client can keep open.
	// There's an already set value, and we want to override it only if an explicit value provided
	MaxIdleConns *int `mapstructure:"max_idle_conns"`

	// MaxIdleConnsPerHost is used to set a limit to the maximum idle HTTP connections the host can keep open.
	// There's an already set value, and we want to override it only if an explicit value provided
	MaxIdleConnsPerHost *int `mapstructure:"max_idle_conns_per_host"`

	// MaxConnsPerHost limits the total number of connections per host, including connections in the dialing,
	// active, and idle states.
	// There's an already set value, and we want to override it only if an explicit value provided
	MaxConnsPerHost *int `mapstructure:"max_conns_per_host"`

	// IdleConnTimeout is the maximum amount of time a connection will remain open before closing itself.
	// There's an already set value, and we want to override it only if an explicit value provided
	IdleConnTimeout *time.Duration `mapstructure:"idle_conn_timeout"`

	// DisableKeepAlives, if true, disables HTTP keep-alives and will only use the connection to the server
	// for a single HTTP request.
	//
	// WARNING: enabling this option can result in significant overhead establishing a new HTTP(S)
	// connection for every request. Before enabling this option please consider whether changes
	// to idle connection settings can achieve your goal.
	DisableKeepAlives bool `mapstructure:"disable_keep_alives"`

	// This is needed in case you run into
	// https://github.com/golang/go/issues/59690
	// https://github.com/golang/go/issues/36026
	// HTTP2ReadIdleTimeout if the connection has been idle for the configured value send a ping frame for health check
	// 0s means no health check will be performed.
	HTTP2ReadIdleTimeout time.Duration `mapstructure:"http2_read_idle_timeout"`
	// HTTP2PingTimeout if there's no response to the ping within the configured value, the connection will be closed.
	// If not set or set to 0, it defaults to 15s.
	HTTP2PingTimeout time.Duration `mapstructure:"http2_ping_timeout"`
}

ClientConfig defines settings for creating an HTTP client.

func NewDefaultClientConfig

func NewDefaultClientConfig() ClientConfig

NewDefaultClientConfig returns ClientConfig type object with the default values of 'MaxIdleConns' and 'IdleConnTimeout'. Other config options are not added as they are initialized with 'zero value' by GoLang as default. We encourage to use this function to create an object of ClientConfig.

func (*ClientConfig) ToClient

func (hcs *ClientConfig) ToClient(ctx context.Context, host component.Host, settings component.TelemetrySettings) (*http.Client, error)

ToClient creates an HTTP client.

func (*ClientConfig) ToClientContext

func (hcs *ClientConfig) ToClientContext(ctx context.Context, host component.Host, settings component.TelemetrySettings) (*http.Client, error)

Deprecated: [v0.99.0] Use ToClient instead.

type ServerConfig

type ServerConfig struct {
	// Endpoint configures the listening address for the server.
	Endpoint string `mapstructure:"endpoint"`

	// TLSSetting struct exposes TLS client configuration.
	TLSSetting *configtls.ServerConfig `mapstructure:"tls"`

	// CORS configures the server for HTTP cross-origin resource sharing (CORS).
	CORS *CORSConfig `mapstructure:"cors"`

	// Auth for this receiver
	Auth *configauth.Authentication `mapstructure:"auth"`

	// MaxRequestBodySize sets the maximum request body size in bytes
	MaxRequestBodySize int64 `mapstructure:"max_request_body_size"`

	// IncludeMetadata propagates the client metadata from the incoming requests to the downstream consumers
	// Experimental: *NOTE* this option is subject to change or removal in the future.
	IncludeMetadata bool `mapstructure:"include_metadata"`

	// Additional headers attached to each HTTP response sent to the client.
	// Header values are opaque since they may be sensitive.
	ResponseHeaders map[string]configopaque.String `mapstructure:"response_headers"`
}

ServerConfig defines settings for creating an HTTP server.

Example

settings := ServerConfig{
	Endpoint: "localhost:443",
}
s, err := settings.ToServer(
	context.Background(),
	componenttest.NewNopHost(),
	componenttest.NewNopTelemetrySettings(),
	http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
if err != nil {
	panic(err)
}

l, err := settings.ToListener(context.Background())
if err != nil {
	panic(err)
}
if err = s.Serve(l); err != nil {
	panic(err)
}

func (*ServerConfig) ToListener

func (hss *ServerConfig) ToListener(ctx context.Context) (net.Listener, error)

ToListener creates a net.Listener.

func (*ServerConfig) ToListenerContext

func (hss *ServerConfig) ToListenerContext(ctx context.Context) (net.Listener, error)

Deprecated: [v0.99.0] Use ToListener instead.

func (*ServerConfig) ToServer

func (hss *ServerConfig) ToServer(_ context.Context, host component.Host, settings component.TelemetrySettings, handler http.Handler, opts ...ToServerOption) (*http.Server, error)

ToServer creates an http.Server from settings object.

func (*ServerConfig) ToServerContext

func (hss *ServerConfig) ToServerContext(ctx context.Context, host component.Host, settings component.TelemetrySettings, handler http.Handler, opts ...ToServerOption) (*http.Server, error)

Deprecated: [v0.99.0] Use ToServer instead.

type ToServerOption

type ToServerOption func(opts *toServerOptions)

ToServerOption is an option to change the behavior of the HTTP server returned by ServerConfig.ToServer().

func WithDecoder

func WithDecoder(key string, dec func(body io.ReadCloser) (io.ReadCloser, error)) ToServerOption

WithDecoder provides support for additional decoders to be configured by the caller.

func WithErrorHandler

func WithErrorHandler(e func(w http.ResponseWriter, r *http.Request, errorMsg string, statusCode int)) ToServerOption

WithErrorHandler overrides the HTTP error handler that gets invoked when there is a failure inside httpContentDecompressor.