Configuration blocks on Grafana Labs

argument block

Wed, 29 Jan 2025 11:00:55 +0000

argument block

argument is an optional configuration block used to specify parameterized input to a custom component. argument blocks must be given a label which determines the name of the argument.

The argument block may only be specified inside the definition of a declare block.

Note
In classic modules, the argument block is valid as a top-level block in a classic module. Classic modules are deprecated and scheduled to be removed in the release after v0.40.

Example

argument "ARGUMENT_NAME" {}

Arguments

Note
For clarity, “argument” in this section refers to arguments which can be given to the argument block. “Module argument” refers to the argument being defined for a module, determined by the label of the argument block.

The following arguments are supported:

Name	Type	Description	Default	Required
`comment`	`string`	Description for the argument.	`false`	no
`default`	`any`	Default value for the argument.	`null`	no
`optional`	`bool`	Whether the argument may be omitted.	`false`	no

By default, all module arguments are required. The optional argument can be used to mark the module argument as optional. When optional is true, the initial value for the module argument is specified by default.

Exported fields

The following fields are exported and can be referenced by other components:

Name	Type	Description
`value`	`any`	The current value of the argument.

If you use a custom component, you are responsible for determining the values for arguments. Other expressions within a custom component may use argument.ARGUMENT_NAME.value to retrieve the value you provide.

Example

This example creates a custom component that self-collects process metrics and forwards them to an argument specified by the user of the custom component:

declare "self_collect" {
  argument "metrics_output" {
    optional = false
    comment  = "Where to send collected metrics."
  }

  prometheus.scrape "selfmonitor" {
    targets = [{
      __address__ = "127.0.0.1:12345",
    }]

    forward_to = [argument.metrics_output.value]
  }
}

declare block

Wed, 29 Jan 2025 11:00:55 +0000

declare block

declare is an optional configuration block used to define a new [custom component][]. declare blocks must be given a label that determines the name of the custom component.

Example

declare "COMPONENT_NAME" {
    COMPONENT_DEFINITION
}

Arguments

The declare block has no predefined schema for its arguments. The body of the declare block is used as the component definition. The body can contain the following:

argument blocks
export blocks
declare blocks
import blocks
Component definitions (either built-in or custom components)

The declare block may not contain any configuration blocks that aren’t listed above.

Exported fields

The declare block has no predefined schema for its exports. The fields exported by the declare block are determined by the export blocks found in its definition.

Example

This example creates and uses a custom component that self-collects process metrics and forwards them to an argument specified by the user of the custom component:

declare "self_collect" {
  argument "metrics_output" {
    optional = false
    comment  = "Where to send collected metrics."
  }

  prometheus.scrape "selfmonitor" {
    targets = [{
      __address__ = "127.0.0.1:12345",
    }]

    forward_to = [argument.metrics_output.value]
  }
}

self_collect "example" {
  metrics_output = prometheus.remote_write.example.receiver
}

prometheus.remote_write "example" {
  endpoint {
    url = REMOTE_WRITE_URL
  }
}

export block

Wed, 29 Jan 2025 11:00:55 +0000

export block

export is an optional configuration block used to specify an emitted value of a custom component. export blocks must be given a label which determine the name of the export.

The export block may only be specified inside the definition of a declare block.

Note
In classic modules, the export block is valid as a top-level block in a classic module. Classic modules are deprecated and scheduled to be removed in the release after v0.40.

Example

export "ARGUMENT_NAME" {
  value = ARGUMENT_VALUE
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`value`	`any`	Value to export.		yes

The value argument determines what the value of the export is. To expose an exported field of another component, set value to an expression that references that exported value.

Exported fields

The export block doesn’t export any fields.

Example

This example creates a custom component where the output of discovering Kubernetes pods and nodes are exposed to the user:

declare "pods_and_nodes" {
  discovery.kubernetes "pods" {
    role = "pod"
  }

  discovery.kubernetes "nodes" {
    role = "nodes"
  }

  export "kubernetes_resources" {
    value = concat(
      discovery.kubernetes.pods.targets,
      discovery.kubernetes.nodes.targets,
    )
  }
}

http block

Wed, 29 Jan 2025 11:00:55 +0000

http block

http is an optional configuration block used to customize how the Grafana Agent Flow HTTP server functions. http is specified without a label and can only be provided once per configuration file.

Example

http {
  tls {
    cert_file = env("TLS_CERT_FILE_PATH")
    key_file  = env("TLS_KEY_FILE_PATH")
  }
}

Arguments

The http block supports no arguments and is configured completely through inner blocks.

Blocks

The following blocks are supported inside the definition of http:

Hierarchy	Block	Description	Required
tls	tls	Define TLS settings for the HTTP server.	no
tls > windows_certificate_filter	windows_certificate_filter	Configure Windows certificate store for all certificates.	no
tls > windows_certificate_filter > client	client	Configure client certificates for Windows certificate filter.	no
tls > windows_certificate_filter > server	server	Configure server certificates for Windows certificate filter.	no

tls block

The tls block configures TLS settings for the HTTP server.

Warning
If you add the tls block and reload the configuration when Grafana Agent Flow is running, existing connections will continue communicating over plaintext. Similarly, if you remove the tls block and reload the configuration when Grafana Agent Flow is running, existing connections will continue communicating over TLS.

To ensure all connections use TLS, configure the tls block before you start Grafana Agent Flow.

Name	Type	Description	Default	Required
`cert_pem`	`string`	PEM data of the server TLS certificate.	`""`	conditionally
`cert_file`	`string`	Path to the server TLS certificate on disk.	`""`	conditionally
`key_pem`	`string`	PEM data of the server TLS key.	`""`	conditionally
`key_file`	`string`	Path to the server TLS key on disk.	`""`	conditionally
`client_ca_pem`	`string`	PEM data of the client CA to validate requests against.	`""`	no
`client_ca_file`	`string`	Path to the client CA file on disk to validate requests against.	`""`	no
`client_auth_type`	`string`	Client authentication to use.	`"NoClientCert"`	no
`cipher_suites`	`list(string)`	Set of cipher suites to use.	`[]`	no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`min_version`	`string`	Oldest TLS version to accept from clients.	`""`	no
`max_version`	`string`	Newest TLS version to accept from clients.	`""`	no

When the tls block is specified, arguments for the TLS certificate (using cert_pem or cert_file) and for the TLS key (using key_pem or key_file) are required.

The following pairs of arguments are mutually exclusive, and only one may be configured at a time:

cert_pem and cert_file
key_pem and key_file
client_ca_pem and client_ca_file

The client_auth_type argument determines whether to validate client certificates. The default value, NoClientCert, indicates that the client certificate is not validated. The client_ca_pem and client_ca_file arguments may only be configured when client_auth_type is not NoClientCert.

The following values are accepted for client_auth_type:

NoClientCert: client certificates are neither requested nor validated.
RequestClientCert: requests clients to send an optional certificate. Certificates provided by clients are not validated.
RequireAnyClientCert: requires at least one certificate from clients. Certificates provided by clients are not validated.
VerifyClientCertIfGiven: requests clients to send an optional certificate. If a certificate is sent, it must be valid.
RequireAndVerifyClientCert: requires clients to send a valid certificate.

The client_ca_pem or client_ca_file arguments may be used to perform client certificate validation. These arguments may only be provided when client_auth_type is not set to NoClientCert.

The cipher_suites argument determines what cipher suites to use. If you don’t provide cipher suite, a default list is used. The set of cipher suites specified may be from the following:

Cipher	Allowed in `boringcrypto` builds
`TLS_RSA_WITH_AES_128_CBC_SHA`	no
`TLS_RSA_WITH_AES_256_CBC_SHA`	no
`TLS_RSA_WITH_AES_128_GCM_SHA256`	no
`TLS_RSA_WITH_AES_256_GCM_SHA384`	no
`TLS_AES_128_GCM_SHA256`	no
`TLS_AES_256_GCM_SHA384`	no
`TLS_CHACHA20_POLY1305_SHA256`	no
`TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`	no
`TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`	no
`TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`	no
`TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`	no
`TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`	yes
`TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`	yes
`TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`	yes
`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`	yes
`TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`	no
`TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`	no

The curve_preferences argument determines the set of elliptic curves to prefer during a handshake in preference order. If not provided, a default list is used. The set of elliptic curves specified may be from the following:

Curve	Allowed in `boringcrypto` builds
`CurveP256`	yes
`CurveP384`	yes
`CurveP521`	yes
`X25519`	no

The min_version and max_version arguments determine the oldest and newest TLS version that’s acceptable from clients. If you don’t provide the min and max TLS version, a default value is used.

The following versions are recognized:

TLS13 for TLS 1.3
TLS12 for TLS 1.2
TLS11 for TLS 1.1
TLS10 for TLS 1.0

The windows_certificate_filter block is used to configure retrieving certificates from the built-in Windows certificate store. When you use the windows_certificate_filter block the following TLS settings are overridden and cause an error if defined.

cert_pem
cert_file
key_pem
key_file
client_ca
client_ca_file

Warning
This feature is only available on Windows.

TLS min and max may not be compatible with the certificate stored in the Windows certificate store. The windows_certificate_filter serves the certificate even if it isn’t compatible with the specified TLS version.

server block

The server block is used to find the certificate to check the signer. If multiple certificates are found, the windows_certificate_filter chooses the certificate with the expiration farthest in the future.

Name	Type	Description	Default	Required
`store`	`string`	Name of the system store to look for the server Certificate, for example, LocalMachine, CurrentUser.	`""`	yes
`system_store`	`string`	Name of the store to look for the server Certificate, for example, My, CA.	`""`	yes
`issuer_common_names`	`list(string)`	Issuer common names to check against.		no
`template_id`	`string`	Server Template ID to match in ASN1 format, for example, “1.2.3”.	`""`	no
`refresh_interval`	`string`	How often to check for a new server certificate.	`"5m"`	no

client block

The client block is used to check the certificate presented to the server.

Name	Type	Description	Default	Required
`issuer_common_names`	`list(string)`	Issuer common names to check against.		no
`subject_regex`	`string`	Regular expression to match Subject name.	`""`	no
`template_id`	`string`	Client Template ID to match in ASN1 format, for example, “1.2.3”.	`""`	no

import.file

Wed, 18 Jun 2025 15:04:54 +0000

import.file

BETA: This is a beta component. Beta components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case.

The import.file block imports custom components from a file or a directory and exposes them to the importer. import.file blocks must be given a label that determines the namespace where custom components are exposed.

Imported directories are treated as single modules to support composability. That means that you can define a custom component in one file and use it in another custom component in another file in the same directory.

Usage

import.file "NAMESPACE" {
  filename = PATH_NAME
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`filename`	`string`	Path of the file or directory on disk to watch.		yes
`detector`	`string`	Which file change detector to use (fsnotify, poll).	`"fsnotify"`	no
`poll_frequency`	`duration`	How often to poll for file changes.	`"1m"`	no

File change detectors

File change detectors detect when the file needs to be re-read from disk. local.file supports two detectors: fsnotify and poll.

fsnotify

The fsnotify detector subscribes to filesystem events, which indicate when the watched file is updated. This detector requires a filesystem that supports events at the operating system level. Network-based filesystems like NFS or FUSE won’t work.

The component re-reads the watched file when a filesystem event is received. This re-read happens for any filesystem event related to the file, including a permissions change.

fsnotify also polls for changes to the file with the configured poll_frequency as a fallback.

fsnotify stops receiving filesystem events if the watched file has been deleted, renamed, or moved. The subscription is re-established on the next poll once the watched file exists again.

poll

The poll file change detector causes the watched file to be re-read every poll_frequency, regardless of whether the file changed.

Example

This example imports a module from a file and instantiates a custom component from the import that adds two numbers:

declare "add" {
  argument "a" {}
  argument "b" {}

  export "sum" {
    value = argument.a.value + argument.b.value
  }
}

import.git

Wed, 29 Jan 2025 11:00:55 +0000

import.git

The import.git block imports custom components from a Git repository and exposes them to the importer. import.git blocks must be given a label that determines the namespace where custom components are exposed.

Usage

import.git "NAMESPACE" {
  repository = "GIT_REPOSTORY"
  path       = "PATH_TO_MODULE"
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`repository`	`string`	The Git repository address to retrieve the module from.		yes
`revision`	`string`	The Git revision to retrieve the module from.	`"HEAD"`	no
`path`	`string`	The path in the repository where the module is stored.		yes
`pull_frequency`	`duration`	The frequency to pull the repository for updates.	`"60s"`	no

The repository attribute must be set to a repository address that would be recognized by Git with a git clone REPOSITORY_ADDRESS command, such as https://github.com/grafana/agent.git.

You must set the repository attribute to a repository address that Git would recognize with a git clone REPOSITORY_ADDRESS command, such as https://github.com/grafana/agent.git.

When provided, the revision attribute must be set to a valid branch, tag, or commit SHA within the repository.

You must set the path attribute to a path accessible from the repository’s root. It can either be a River file such as FILE_NAME.river or DIR_NAME/FILE_NAME.river or a directory containing River files such as DIR_NAME or . if the River files are stored at the root of the repository.

If pull_frequency isn’t "0s", the Git repository is pulled for updates at the frequency specified. If it’s set to "0s", the Git repository is pulled once on init.

Warning
Pulling hosted Git repositories too often can result in throttling.

Blocks

The following blocks are supported inside the definition of import.git:

Hierarchy	Block	Description	Required
basic_auth	basic_auth	Configure basic_auth for authenticating to the repository.	no
ssh_key	ssh_key	Configure an SSH Key for authenticating to the repository.	no

basic_auth block

Name	Type	Description	Required
`password_file`	`string`	File containing the basic auth password.	no
`password`	`secret`	Basic auth password.	no
`username`	`string`	Basic auth username.	no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

ssh_key block

Name	Type	Description	Required
`username`	`string`	SSH username.	yes
`key`	`secret`	SSH private key.	no
`key_file`	`string`	SSH private key path.	no
`passphrase`	`secret`	Passphrase for SSH key if needed.	no

Examples

This example imports custom components from a Git repository and uses a custom component to add two numbers:

import.git "math" {
  repository = "https://github.com/wildum/module.git"
  revision   = "master"
  path       = "math.river"
}

math.add "default" {
  a = 15
  b = 45
}

This example imports custom components from a directory in a Git repository and uses a custom component to add two numbers:

import.git "math" {
  repository = "https://github.com/wildum/module.git"
  revision   = "master"
  path       = "modules"
}

math.add "default" {
  a = 15
  b = 45
}

import.http

Wed, 29 Jan 2025 11:00:55 +0000

import.http

import.http retrieves a module from an HTTP server.

Usage

import.http "LABEL" {
  url = URL
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`url`	`string`	URL to poll.		yes
`method`	`string`	Define the HTTP method for the request.	`"GET"`	no
`headers`	`map(string)`	Custom headers for the request.	`{}`	no
`poll_frequency`	`duration`	Frequency to poll the URL.	`"1m"`	no
`poll_timeout`	`duration`	Timeout when polling the URL.	`"10s"`	no

Example

This example imports custom components from an HTTP response and instantiates a custom component for adding two numbers:

declare "add" {
  argument "a" {}
  argument "b" {}

  export "sum" {
    value = argument.a.value + argument.b.value
  }
}

import.string

Wed, 29 Jan 2025 11:00:55 +0000

import.string

The import.string block imports custom components from a string and exposes them to the importer. import.string blocks must be given a label that determines the namespace where custom components are exposed.

Usage

import.string "NAMESPACE" {
  content = CONTENT
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`content`	`secret` or `string`	The contents of the module to import as a secret or string.		yes

content is a string that contains the configuration of the module to import. content is typically loaded by using the exports of another component. For example,

local.file.LABEL.content
remote.http.LABEL.content
remote.s3.LABEL.content

Example

This example imports a module from the content of a file stored in an S3 bucket and instantiates a custom component from the import that adds two numbers:

remote.s3 "module" {
  path = "s3://test-bucket/module.river"
}

import.string "math" {
  content = remote.s3.module.content
}

math.add "default" {
  a = 15
  b = 45
}

logging block

Wed, 29 Jan 2025 11:00:55 +0000

logging block

logging is an optional configuration block used to customize how Grafana Agent Flow produces log messages. logging is specified without a label and can only be provided once per configuration file.

Example

logging {
  level  = "info"
  format = "logfmt"
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`level`	`string`	Level at which log lines should be written	`"info"`	no
`format`	`string`	Format to use for writing log lines	`"logfmt"`	no
`write_to`	`list(LogsReceiver)`	List of receivers to send log entries to		no

Log level

The following strings are recognized as valid log levels:

"error": Only write logs at the error level.
"warn": Only write logs at the warn level or above.
"info": Only write logs at info level or above.
"debug": Write all logs, including debug level logs.

Log format

The following strings are recognized as valid log line formats:

"logfmt": Write logs as logfmt lines.
"json": Write logs as JSON objects.

Log receivers

The write_to argument allows Grafana Agent Flow to tee its log entries to one or more loki.* component log receivers in addition to the default location. This, for example can be the export of a loki.write component to ship log entries directly to Loki, or a loki.relabel component to add a certain label first.

Log location

Grafana Agent Flow writes all logs to stderr.

When running Grafana Agent Flow as a systemd service, view logs written to stderr through journald.

When running Grafana Agent Flow as a container, view logs written to stderr through docker logs or kubectl logs, depending on whether Docker or Kubernetes was used for deploying Grafana Agent Flow.

When running Grafana Agent Flow as a Windows service, logs are instead written as event logs. You can view the logs through Event Viewer.

In other cases, redirect stderr of the Grafana Agent Flow process to a file for logs to persist on disk.

remotecfg block

Wed, 29 Jan 2025 11:00:55 +0000

remotecfg block (beta)

remotecfg is an optional configuration block that enables Grafana Agent Flow to fetch and load the configuration from a remote endpoint. remotecfg is specified without a label and can only be provided once per configuration file.

The API definition for managing and fetching configuration that the remotecfg block uses is available under the Apache 2.0 license.

BETA: The remotecfg enables beta functionality. Beta features are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case.

Example

remotecfg {
	url = "SERVICE_URL"
	basic_auth {
		username      = "USERNAME"
		password_file = "PASSWORD_FILE"
	}

	id             = constants.hostname
	metadata       = {"cluster" = "dev", "namespace" = "otlp-dev"}
	poll_frequency = "5m"
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`url`	`string`	The address of the API to poll for configuration.	`""`	no
`id`	`string`	A self-reported ID.	`see below`	no
`metadata`	`map(string)`	A set of self-reported metadata.	`{}`	no
`poll_frequency`	`duration`	How often to poll the API for new configuration.	`"1m"`	no

If the url is not set, then the service block is a no-op.

If not set, the self-reported id that the Agent uses is a randomly generated, anonymous unique ID (UUID) that is stored as an agent_seed.json file in the Agent’s storage path so that it can persist across restarts.

The id and metadata fields are used in the periodic request sent to the remote endpoint so that the API can decide what configuration to serve.

Blocks

The following blocks are supported inside the definition of remotecfg:

Hierarchy	Block	Description	Required
basic_auth	basic_auth	Configure basic_auth for authenticating to the endpoint.	no
authorization	authorization	Configure generic authorization to the endpoint.	no
oauth2	oauth2	Configure OAuth2 for authenticating to the endpoint.	no
oauth2 > tls_config	tls_config	Configure TLS settings for connecting to the endpoint.	no
tls_config	tls_config	Configure TLS settings for connecting to the endpoint.	no

The > symbol indicates deeper levels of nesting. For example, oauth2 > tls_config refers to a tls_config block defined inside an oauth2 block.

basic_auth block

Name	Type	Description	Required
`password_file`	`string`	File containing the basic auth password.	no
`password`	`secret`	Basic auth password.	no
`username`	`string`	Basic auth username.	no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

authorization block

Name	Type	Description	Required
`credentials_file`	`string`	File containing the secret value.	no
`credentials`	`secret`	Secret value.	no
`type`	`string`	Authorization type, for example, “Bearer”.	no

credential and credentials_file are mutually exclusive, and only one can be provided inside an authorization block.

oauth2 block

Name	Type	Description	Default	Required
`client_id`	`string`	OAuth2 client ID.		no
`client_secret_file`	`string`	File containing the OAuth2 client secret.		no
`client_secret`	`secret`	OAuth2 client secret.		no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.		no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`scopes`	`list(string)`	List of scopes to authenticate with.		no
`token_url`	`string`	URL to fetch the token from.		no

client_secret and client_secret_file are mutually exclusive, and only one can be provided inside an oauth2 block.

The oauth2 block may also contain a separate tls_config sub-block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_from_environment uses the environment variables HTTP_PROXY, HTTPS_PROXY and NO_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO_PROXY. proxy_url and no_proxy must not be configured if proxy_from_environment is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

tls_config block

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

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

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

When min_version is not provided, the minimum acceptable TLS version is inherited from Go’s default minimum version, TLS 1.2. If min_version is provided, it must be set to one of the following strings:

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

tracing block

Wed, 29 Jan 2025 11:00:55 +0000

tracing block

tracing is an optional configuration block used to customize how Grafana Agent Flow produces traces. tracing is specified without a label and can only be provided once per configuration file.

Example

tracing {
  sampling_fraction = 0.1

  write_to = [otelcol.exporter.otlp.tempo.input]
}

otelcol.exporter.otlp "tempo" {
  // Send traces to a locally running Tempo without TLS enabled.
  client {
    endpoint = env("TEMPO_OTLP_ENDPOINT")

    tls {
      insecure = true
    }
  }
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`sampling_fraction`	`number`	Fraction of traces to keep.	`0.1`	no
`write_to`	`list(otelcol.Consumer)`	Inputs from `otelcol` components to send traces to.	`[]`	no

The write_to argument controls which components to send traces to for processing. The elements in the array can be any otelcol component that accept traces, including processors and exporters. When write_to is set to an empty array [], all traces are dropped.

NOTE: Any traces generated before the tracing block has been evaluated, such as at the early start of the process’ lifetime, are dropped.

The sampling_fraction argument controls what percentage of generated traces should be sent to the consumers specified by write_to. When set to 1 or greater, 100% of traces are kept. When set to 0 or lower, 0% of traces are kept.

Blocks

The following blocks are supported inside the definition of tracing:

Hierarchy	Block	Description	Required
sampler	sampler	Define custom sampling on top of the base sampling fraction.	no
sampler > jaeger_remote	jaeger_remote	Retrieve sampling information via a Jaeger remote sampler.	no

The > symbol indicates deeper levels of nesting. For example, sampler > jaeger_remote refers to a jaeger_remote block defined inside an sampler block.

sampler block

The sampler block contains a definition of a custom sampler to use. The sampler block supports no arguments and is controlled fully through inner blocks.

It is invalid to define more than one sampler to use in the sampler block.

jaeger_remote block

The jaeger_remote block configures the retrieval of sampling information through a remote server that exposes Jaeger sampling strategies.

Name	Type	Description	Default	Required
`url`	`string`	URL to retrieve sampling strategies from.	`"http://127.0.0.1:5778/sampling"`	no
`max_operations`	`number`	Limit number of operations which can have custom sampling.	`256`	no
`refresh_interval`	`duration`	Frequency to poll the URL for new sampling strategies.	`"1m"`	no

The remote sampling strategies are retrieved from the URL specified by the url argument, and polled for updates on a timer. The frequency for how often polling occurs is controlled by the refresh_interval argument.

Requests to the remote sampling strategies server are made through an HTTP GET request to the configured url argument. A service=grafana-agent query parameter is always added to the URL to allow the server to respond with service-specific strategies. The HTTP response body is read as JSON matching the schema specified by Jaeger’s strategies.json file.

The max_operations limits the amount of custom span names that can have custom sampling rules. If the remote sampling strategy exceeds the limit, sampling decisions fall back to the default sampler.

Configuration blocks on Grafana Labs

argument block

argument block

Example

Arguments

Exported fields

Example

declare block

declare block

Example

Arguments

Exported fields

Example

export block

export block

Example

Arguments

Exported fields

Example

http block

http block

Example

Arguments

Blocks

tls block

windows certificate filter block

server block

client block

import.file

import.file

Usage

Arguments

File change detectors

fsnotify

poll

Example

import.git

import.git

Usage

Arguments

Blocks

basic_auth block

ssh_key block

Examples

import.http

import.http

Usage

Arguments

Example

import.string

import.string

Usage

Arguments

Example

logging block

logging block

Example

Arguments

Log level

Log format

Log receivers

Log location

remotecfg block

remotecfg block (beta)

Example

Arguments

Blocks

basic_auth block

authorization block

oauth2 block

tls_config block

tracing block

tracing block

Example

Arguments

Blocks

sampler block

jaeger_remote block