configgrpc

package module
v0.147.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 2, 2026 License: Apache-2.0 Imports: 34 Imported by: 99

README

gRPC Configuration Settings

gRPC exposes a variety of settings. Several of these settings are available for configuration within individual receivers or exporters. In general, none of these settings should need to be adjusted.

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.

  • balancer_name: Default before v0.103.0 is pick_first, default for v0.103.0 is round_robin. See issue. To restore the previous behavior, set balancer_name to pick_first.
  • compression: Compression type to use among gzip, snappy, zstd, and none.
  • endpoint: Valid value syntax available here
  • tls
  • headers: name/value pairs added to the request
  • keepalive
    • permit_without_stream
    • time
    • timeout
  • read_buffer_size
  • write_buffer_size
  • auth
  • middlewares

Please note that per_rpc_auth which allows the credentials to send for every RPC is now moved to become an extension. Note that this feature isn't about sending the headers only during the initial connection as an authorization header under the headers would do: this is sent for every RPC performed during an established connection.

Example:

exporters:
  otlp_grpc:
    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 Comparison

configgrpc_benchmark_test.go contains benchmarks comparing the supported compression algorithms. It performs compression using gzip, zstd, and snappy compression on small, medium, and large sized log, trace, and metric payloads. Each test case outputs the uncompressed payload size, the compressed payload size, and the average nanoseconds spent on compression.

The following table summarizes the results, including some additional columns computed from the raw data. The benchmarks were performed on an AWS m5.large EC2 instance with an Intel(R) Xeon(R) Platinum 8259CL CPU @ 2.50GHz.

Request Compressor Raw Bytes Compressed bytes Compression ratio Ns / op Mb compressed / second Mb saved / second
lg_log_request gzip 5150 262 19.66 49231 104.61 99.29
lg_metric_request gzip 6800 201 33.83 51816 131.23 127.35
lg_trace_request gzip 9200 270 34.07 65174 141.16 137.02
md_log_request gzip 363 268 1.35 37609 9.65 2.53
md_metric_request gzip 320 145 2.21 30141 10.62 5.81
md_trace_request gzip 451 288 1.57 38270 11.78 4.26
sm_log_request gzip 166 168 0.99 30511 5.44 -0.07
sm_metric_request gzip 185 142 1.30 29055 6.37 1.48
sm_trace_request gzip 233 205 1.14 33466 6.96 0.84
lg_log_request snappy 5150 475 10.84 1915 2,689.30 2,441.25
lg_metric_request snappy 6800 466 14.59 2266 3,000.88 2,795.23
lg_trace_request snappy 9200 644 14.29 3281 2,804.02 2,607.74
md_log_request snappy 363 300 1.21 770.0 471.43 81.82
md_metric_request snappy 320 162 1.98 588.6 543.66 268.43
md_trace_request snappy 451 330 1.37 907.7 496.86 133.30
sm_log_request snappy 166 184 0.90 551.8 300.83 -32.62
sm_metric_request snappy 185 154 1.20 526.3 351.51 58.90
sm_trace_request snappy 233 251 0.93 682.1 341.59 -26.39
lg_log_request zstd 5150 223 23.09 17998 286.14 273.75
lg_metric_request zstd 6800 144 47.22 14289 475.89 465.81
lg_trace_request zstd 9200 208 44.23 17160 536.13 524.01
md_log_request zstd 363 261 1.39 11216 32.36 9.09
md_metric_request zstd 320 145 2.21 9318 34.34 18.78
md_trace_request zstd 451 301 1.50 12583 35.84 11.92
sm_log_request zstd 166 165 1.01 12482 13.30 0.08
sm_metric_request zstd 185 139 1.33 8824 20.97 5.21
sm_trace_request zstd 233 203 1.15 10134 22.99 2.96

Compression ratios will vary in practice as they are highly dependent on the data's information entropy. Compression rates are dependent on the speed of the CPU, and the size of payloads being compressed: smaller payloads compress at slower rates relative to larger payloads, which are able to amortize fixed computation costs over more bytes.

gzip is the only required compression algorithm required for OTLP servers, and is a natural first choice. It is not as fast as snappy, but achieves better compression ratios and has reasonable performance. If your collector is CPU bound and your OTLP server supports it, you may benefit from using snappy compression. If your collector is CPU bound and has a very fast network link, you may benefit from disabling compression, which is the default.

Server Configuration

Receivers leverage server configuration.

Note that transport configuration can also be configured. The default transport type is TCP. For more information, see confignet README.

Documentation

Overview

Package configgrpc defines the configuration settings to create a gRPC client and server.

The configuration structs in this package may be shared across signals, but assume each struct is used for a single protocol and component.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BalancerName added in v0.105.0 

func BalancerName() string

BalancerName returns a string with default load balancer value

Types

type ClientConfig added in v0.94.0 

type ClientConfig struct {
	// The target to which the exporter is going to send traces or metrics,
	// using the gRPC protocol. The valid syntax is described at
	// https://github.com/grpc/grpc/blob/master/doc/naming.md.
	Endpoint string `mapstructure:"endpoint,omitempty"`

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

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

	// The keepalive parameters for gRPC client. See grpc.WithKeepaliveParams.
	// (https://godoc.org/google.golang.org/grpc#WithKeepaliveParams).
	Keepalive configoptional.Optional[KeepaliveClientConfig] `mapstructure:"keepalive,omitempty"`

	// ReadBufferSize for gRPC client. See grpc.WithReadBufferSize.
	// (https://godoc.org/google.golang.org/grpc#WithReadBufferSize).
	ReadBufferSize int `mapstructure:"read_buffer_size,omitempty"`

	// WriteBufferSize for gRPC gRPC. See grpc.WithWriteBufferSize.
	// (https://godoc.org/google.golang.org/grpc#WithWriteBufferSize).
	WriteBufferSize int `mapstructure:"write_buffer_size,omitempty"`

	// WaitForReady parameter configures client to wait for ready state before sending data.
	// (https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md)
	WaitForReady bool `mapstructure:"wait_for_ready,omitempty"`

	// The headers associated with gRPC requests.
	Headers configopaque.MapList `mapstructure:"headers,omitempty"`

	// Sets the balancer in grpclb_policy to discover the servers. Default is pick_first.
	// https://github.com/grpc/grpc-go/blob/master/examples/features/load_balancing/README.md
	BalancerName string `mapstructure:"balancer_name"`

	// WithAuthority parameter configures client to rewrite ":authority" header
	// (godoc.org/google.golang.org/grpc#WithAuthority)
	Authority string `mapstructure:"authority,omitempty"`

	// Auth configuration for outgoing RPCs.
	Auth configoptional.Optional[configauth.Config] `mapstructure:"auth,omitempty"`

	// Middlewares for the gRPC client.
	Middlewares []configmiddleware.Config `mapstructure:"middlewares,omitempty"`
}

ClientConfig defines common settings for a gRPC client configuration.

func NewDefaultClientConfig added in v0.100.0 

func NewDefaultClientConfig() ClientConfig

NewDefaultClientConfig returns a new instance of ClientConfig with default values.

func (*ClientConfig) ToClientConn added in v0.94.0 

func (cc *ClientConfig) ToClientConn(
	ctx context.Context,
	extensions map[component.ID]component.Component,
	settings component.TelemetrySettings,
	extraOpts ...ToClientConnOption,
) (*grpc.ClientConn, error)

ToClientConn creates a client connection to the given target. By default, it's a non-blocking dial (the function won't wait for connections to be established, and connecting happens in the background). To make it a blocking dial, use the WithGrpcDialOption(grpc.WithBlock()) option.

To allow the configuration to reference middleware or authentication extensions, the `extensions` argument should be the output of `host.GetExtensions()`. It may also be `nil` in tests where no such extension is expected to be used.

func (*ClientConfig) Validate added in v0.111.0 

func (cc *ClientConfig) Validate() error

type KeepaliveClientConfig 

type KeepaliveClientConfig struct {
	Time                time.Duration `mapstructure:"time"`
	Timeout             time.Duration `mapstructure:"timeout"`
	PermitWithoutStream bool          `mapstructure:"permit_without_stream,omitempty"`
	// contains filtered or unexported fields
}

KeepaliveClientConfig exposes the keepalive.ClientParameters to be used by the exporter. Refer to the original data-structure for the meaning of each parameter: https://godoc.org/google.golang.org/grpc/keepalive#ClientParameters

func NewDefaultKeepaliveClientConfig added in v0.100.0 

func NewDefaultKeepaliveClientConfig() KeepaliveClientConfig

NewDefaultKeepaliveClientConfig returns a new instance of KeepaliveClientConfig with default values.

type KeepaliveEnforcementPolicy 

type KeepaliveEnforcementPolicy struct {
	MinTime             time.Duration `mapstructure:"min_time,omitempty"`
	PermitWithoutStream bool          `mapstructure:"permit_without_stream,omitempty"`
	// contains filtered or unexported fields
}

KeepaliveEnforcementPolicy allow configuration of the keepalive.EnforcementPolicy. The same default values as keepalive.EnforcementPolicy are applicable and get applied by the server. See https://godoc.org/google.golang.org/grpc/keepalive#EnforcementPolicy for details.

func NewDefaultKeepaliveEnforcementPolicy added in v0.100.0 

func NewDefaultKeepaliveEnforcementPolicy() KeepaliveEnforcementPolicy

NewDefaultKeepaliveEnforcementPolicy creates and returns a new instance of KeepaliveEnforcementPolicy with default settings.

type KeepaliveServerConfig 

type KeepaliveServerConfig struct {
	ServerParameters  configoptional.Optional[KeepaliveServerParameters]  `mapstructure:"server_parameters,omitempty"`
	EnforcementPolicy configoptional.Optional[KeepaliveEnforcementPolicy] `mapstructure:"enforcement_policy,omitempty"`
	// contains filtered or unexported fields
}

KeepaliveServerConfig is the configuration for keepalive.

func NewDefaultKeepaliveServerConfig added in v0.100.0 

func NewDefaultKeepaliveServerConfig() KeepaliveServerConfig

NewDefaultKeepaliveServerConfig returns a new instance of KeepaliveServerConfig with default values.

type KeepaliveServerParameters 

type KeepaliveServerParameters struct {
	MaxConnectionIdle     time.Duration `mapstructure:"max_connection_idle,omitempty"`
	MaxConnectionAge      time.Duration `mapstructure:"max_connection_age,omitempty"`
	MaxConnectionAgeGrace time.Duration `mapstructure:"max_connection_age_grace,omitempty"`
	Time                  time.Duration `mapstructure:"time,omitempty"`
	Timeout               time.Duration `mapstructure:"timeout,omitempty"`
	// contains filtered or unexported fields
}

KeepaliveServerParameters allow configuration of the keepalive.ServerParameters. The same default values as keepalive.ServerParameters are applicable and get applied by the server. See https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters for details.

func NewDefaultKeepaliveServerParameters added in v0.100.0 

func NewDefaultKeepaliveServerParameters() KeepaliveServerParameters

NewDefaultKeepaliveServerParameters creates and returns a new instance of KeepaliveServerParameters with default settings.

type ServerConfig added in v0.94.0 

type ServerConfig struct {
	// Server net.Addr config. For transport only "tcp" and "unix" are valid options.
	NetAddr confignet.AddrConfig `mapstructure:",squash"`

	// Configures the protocol to use TLS.
	// The default value is nil, which will cause the protocol to not use TLS.
	TLS configoptional.Optional[configtls.ServerConfig] `mapstructure:"tls,omitempty"`

	// MaxRecvMsgSizeMiB sets the maximum size (in MiB) of messages accepted by the server.
	MaxRecvMsgSizeMiB int `mapstructure:"max_recv_msg_size_mib,omitempty"`

	// MaxConcurrentStreams sets the limit on the number of concurrent streams to each ServerTransport.
	// It has effect only for streaming RPCs.
	MaxConcurrentStreams uint32 `mapstructure:"max_concurrent_streams,omitempty,omitempty"`

	// ReadBufferSize for gRPC server. See grpc.ReadBufferSize.
	// (https://godoc.org/google.golang.org/grpc#ReadBufferSize).
	ReadBufferSize int `mapstructure:"read_buffer_size,omitempty"`

	// WriteBufferSize for gRPC server. See grpc.WriteBufferSize.
	// (https://godoc.org/google.golang.org/grpc#WriteBufferSize).
	WriteBufferSize int `mapstructure:"write_buffer_size,omitempty"`

	// Keepalive anchor for all the settings related to keepalive.
	Keepalive configoptional.Optional[KeepaliveServerConfig] `mapstructure:"keepalive,omitempty"`

	// Auth for this receiver
	Auth configoptional.Optional[configauth.Config] `mapstructure:"auth,omitempty"`

	// Include propagates the incoming connection's metadata to downstream consumers.
	IncludeMetadata bool `mapstructure:"include_metadata,omitempty"`

	// Middlewares for the gRPC server.
	Middlewares []configmiddleware.Config `mapstructure:"middlewares,omitempty"`
	// contains filtered or unexported fields
}

ServerConfig defines common settings for a gRPC server configuration.

func NewDefaultServerConfig added in v0.100.0 

func NewDefaultServerConfig() ServerConfig

NewDefaultServerConfig returns a new instance of ServerConfig with default values.

func (*ServerConfig) ToServer added in v0.94.0 

func (sc *ServerConfig) ToServer(
	ctx context.Context,
	extensions map[component.ID]component.Component,
	settings component.TelemetrySettings,
	extraOpts ...ToServerOption,
) (*grpc.Server, error)

ToServer returns a grpc.Server for the configuration.

To allow the configuration to reference middleware or authentication extensions, the `extensions` argument should be the output of `host.GetExtensions()`. It may also be `nil` in tests where no such extension is expected to be used.

func (*ServerConfig) Validate added in v0.109.0 

func (sc *ServerConfig) Validate() error

type ToClientConnOption added in v0.110.0 

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

ToClientConnOption is a sealed interface wrapping options for ClientConfig.ToClientConn.

func WithGrpcDialOption added in v0.110.0 

func WithGrpcDialOption(opt grpc.DialOption) ToClientConnOption

WithGrpcDialOption wraps a grpc.DialOption into a ToClientConnOption.

type ToServerOption added in v0.110.0 

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

ToServerOption is a sealed interface wrapping options for ServerConfig.ToServer.

func WithGrpcServerOption added in v0.110.0 

func WithGrpcServerOption(opt grpc.ServerOption) ToServerOption

WithGrpcServerOption wraps a grpc.ServerOption into a ToServerOption.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.