Menu

This is documentation for the next version of Agent. For the latest stable release, go to the latest version.

Grafana Agent Flow mode Reference Components reference otelcol.extension.jaeger_remote_sampling
Open source

otelcol.extension.jaeger_remote_sampling

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement.

otelcol.extension.jaeger_remote_sampling serves a specified Jaeger remote sampling document.

NOTE: otelcol.extension.jaeger_remote_sampling is a wrapper over the upstream OpenTelemetry Collector jaegerremotesampling extension. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

Multiple otelcol.extension.jaeger_remote_sampling components can be specified by giving them different labels.

Usage

river
otelcol.extension.jaeger_remote_sampling "LABEL" {
  source {
  }
}

Arguments

otelcol.extension.jaeger_remote_sampling doesn’t support any arguments and is configured fully through inner blocks.

Blocks

The following blocks are supported inside the definition of otelcol.extension.jaeger_remote_sampling:

HierarchyBlockDescriptionRequired
httphttpConfigures the http server to serve Jaeger remote sampling.no
http > tlstlsConfigures TLS for the HTTP server.no
http > corscorsConfigures CORS for the HTTP server.no
grpcgrpcConfigures the grpc server to serve Jaeger remote sampling.no
grpc > tlstlsConfigures TLS for the gRPC server.no
grpc > keepalivekeepaliveConfigures keepalive settings for the configured server.no
grpc > keepalive > server_parametersserver_parametersServer parameters used to configure keepalive settings.no
grpc > keepalive > enforcement_policyenforcement_policyEnforcement policy for keepalive settings.no
sourcesourceConfigures the Jaeger remote sampling document.yes
source > remoteremoteConfigures the gRPC client used to retrieve the Jaeger remote sampling document.no
source > remote > tlstlsConfigures TLS for the gRPC client.no
source > remote > keepalivekeepaliveConfigures keepalive settings for the gRPC client.no

The > symbol indicates deeper levels of nesting. For example, grpc > tls refers to a tls block defined inside a grpc block.

http block

The http block configures an HTTP server which serves the Jaeger remote sampling document.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
endpointstringhost:port to listen for traffic on."0.0.0.0:5778"no
max_request_body_sizestringMaximum request body size the server will allow. No limit when unset.no
include_metadatabooleanPropagate incoming connection metadata to downstream consumers.no

tls block

The tls block configures TLS settings used for a server. If the tls block isn’t provided, TLS won’t be used for connections to the server.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
ca_filestringPath to the CA file.no
cert_filestringPath to the TLS certificate.no
key_filestringPath to the TLS certificate key.no
min_versionstringMinimum acceptable TLS version for connections."TLS 1.2"no
max_versionstringMaximum acceptable TLS version for connections."TLS 1.3"no
reload_intervaldurationFrequency to reload the certificates.no
client_ca_filestringPath to the CA file used to authenticate client certificates.no

cors block

The cors block configures CORS settings for an HTTP server.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
allowed_originslist(string)Allowed values for the Origin header.no
allowed_headerslist(string)Accepted headers from CORS requests.["X-Requested-With"]no
max_agenumberConfigures the Access-Control-Max-Age response header.no

The allowed_headers specifies which headers are acceptable from a CORS request. The following headers are always implicitly allowed:

  • Accept
  • Accept-Language
  • Content-Type
  • Content-Language

If allowed_headers includes "*", all headers will be permitted.

grpc block

The grpc block configures a gRPC server which serves the Jaeger remote sampling document.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
endpointstringhost:port to listen for traffic on."0.0.0.0:14250"no
transportstringTransport to use for the gRPC server."tcp"no
max_recv_msg_sizestringMaximum size of messages the server will accept. 0 disables a limit.no
max_concurrent_streamsnumberLimit the number of concurrent streaming RPC calls.no
read_buffer_sizestringSize of the read buffer the gRPC server will use for reading from clients."512KiB"no
write_buffer_sizestringSize of the write buffer the gRPC server will use for writing to clients.no
include_metadatabooleanPropagate incoming connection metadata to downstream consumers.no

keepalive block

The keepalive block configures keepalive settings for connections to a gRPC server.

keepalive doesn’t support any arguments and is configured fully through inner blocks.

server_parameters block

The server_parameters block controls keepalive and maximum age settings for gRPC servers.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
max_connection_idledurationMaximum age for idle connections."infinity"no
max_connection_agedurationMaximum age for non-idle connections."infinity"no
max_connection_age_gracedurationTime to wait before forcibly closing connections."infinity"no
timedurationHow often to ping inactive clients to check for liveness."2h"no
timeoutdurationTime to wait before closing inactive clients that do not respond to liveness checks."20s"no

enforcement_policy block

The enforcement_policy block configures the keepalive enforcement policy for gRPC servers. The server will close connections from clients that violate the configured policy.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
min_timedurationMinimum time clients should wait before sending a keepalive ping."5m"no
permit_without_streambooleanAllow clients to send keepalive pings when there are no active streams.falseno

source block

The source block configures the method of retrieving the Jaeger remote sampling document that is served by the servers specified in the grpc and http blocks.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
filestringA local file containing a Jaeger remote sampling document.""no
reload_intervaldurationThe interval at which to reload the specified file. Leave at 0 to never reload.0no
contentstringA string containing the Jaeger remote sampling contents directly.""no

Exactly one of the file argument, content argument or remote block must be specified.

remote block

The remote block configures the gRPC client used by the component.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
endpointstringhost:port to send telemetry data to.yes
compressionstringCompression mechanism to use for requests."gzip"no
read_buffer_sizestringSize of the read buffer the gRPC client to use for reading server responses.no
write_buffer_sizestringSize of the write buffer the gRPC client to use for writing requests."512KiB"no
wait_for_readybooleanWaits for gRPC connection to be in the READY state before sending data.falseno
headersmap(string)Additional headers to send with the request.{}no
balancer_namestringWhich gRPC client-side load balancer to use for requests.pick_firstno
authoritystringOverrides the default :authority header in gRPC requests from the gRPC client.no
authcapsule(otelcol.Handler)Handler from an otelcol.auth component to use for authenticating requests.no

By default, requests are compressed with gzip. The compression argument controls which compression mechanism to use. Supported strings are:

  • "gzip"
  • "zlib"
  • "deflate"
  • "snappy"
  • "zstd"

If compression is set to "none" or an empty string "", no compression is used.

The supported values for balancer_name are listed in the gRPC documentation on Load balancing:

  • pick_first: Tries to connect to the first address, uses it for all RPCs if it connects, or tries the next address if it fails (and keeps doing that until one connection is successful). Because of this, all the RPCs will be sent to the same backend.
  • round_robin: Connects to all the addresses it sees and sends an RPC to each backend one at a time in order. For example, the first RPC is sent to backend-1, the second RPC is sent to backend-2, and the third RPC is sent to backend-1.

The :authority header in gRPC specifies the host to which the request is being sent. It’s similar to the Host header in HTTP requests. By default, the value for :authority is derived from the endpoint URL used for the gRPC call. Overriding :authority could be useful when routing traffic using a proxy like Envoy, which makes routing decisions based on the value of the :authority header.

An HTTP proxy can be configured through the following environment variables:

  • HTTPS_PROXY
  • NO_PROXY

The HTTPS_PROXY environment variable specifies a URL to use for proxying requests. Connections to the proxy are established via the HTTP CONNECT method.

The NO_PROXY environment variable is an optional list of comma-separated hostnames for which the HTTPS proxy should not be used. Each hostname can be provided as an IP address (1.2.3.4), an IP address in CIDR notation (1.2.3.4/8), a domain name (example.com), or *. A domain name matches that domain and all subdomains. A domain name with a leading “.” (.example.com) matches subdomains only. NO_PROXY is only read when HTTPS_PROXY is set.

Because otelcol.extension.jaeger_remote_sampling uses gRPC, the configured proxy server must be able to handle and proxy HTTP/2 traffic.

tls client block

The tls block configures TLS settings used for the connection to the gRPC server.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
ca_filestringPath to the CA file.no
ca_pemstringCA PEM-encoded text to validate the server with.no
cert_filestringPath to the TLS certificate.no
cert_pemstringCertificate PEM-encoded text for client authentication.no
insecure_skip_verifybooleanIgnores insecure server TLS certificates.no
insecurebooleanDisables TLS when connecting to the configured server.no
key_filestringPath to the TLS certificate key.no
key_pemsecretKey PEM-encoded text for client authentication.no
max_versionstringMaximum acceptable TLS version for connections."TLS 1.3"no
min_versionstringMinimum acceptable TLS version for connections."TLS 1.2"no
reload_intervaldurationThe duration after which the certificate is reloaded."0s"no
server_namestringVerifies the hostname of server certificates when set.no

If the server doesn’t support TLS, you must set the insecure argument to true.

To disable tls for connections to the server, set the insecure argument to true.

If reload_interval is set to "0s", the certificate never reloaded.

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

  • ca_pem and ca_file
  • cert_pem and cert_file
  • key_pem and key_file

keepalive client block

The keepalive block configures keepalive settings for gRPC client connections.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
ping_waitdurationHow often to ping the server after no activity.no
ping_response_timeoutdurationTime to wait before closing inactive connections if the server does not respond to a ping.no
ping_without_streambooleanSend pings even if there is no active stream request.no

Component health

otelcol.extension.jaeger_remote_sampling is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.extension.jaeger_remote_sampling does not expose any component-specific debug information.

Examples

Serving from a file

This example configures the Jaeger remote sampling extension to load a local json document and serve it over the default http port of 5778. Currently this config style exists for consistency with upstream Opentelemetry Collector components and may be removed.

river
otelcol.extension.jaeger_remote_sampling "example" {
  http {
  }
  source {
    file             = "/path/to/jaeger-sampling.json"
    reload_interval  = "10s"
  }
}

Serving from another component

This example uses the output of a component to determine what sampling rules to serve:

river
local.file "sampling" {
  filename  = "/path/to/jaeger-sampling.json"
}

otelcol.extension.jaeger_remote_sampling "example" {
  http {
  }
  source {
    content = local.file.sampling.content
  }
}