Components on Grafana Labs

discovery.docker

Sat, 11 Apr 2026 12:27:38 +0000

discovery.docker

discovery.docker discovers Docker Engine containers and exposes them as targets.

Usage

discovery.docker "LABEL" {
  host = "DOCKER_ENGINE_HOST"
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`host`	`string`	Address of the Docker Daemon to connect to.		yes
`port`	`number`	Port to use for collecting metrics when containers don’t have any port mappings.	`80`	no
`host_networking_host`	`string`	Host to use if the container is in host networking mode.	`"localhost"`	no
`refresh_interval`	`duration`	Frequency to refresh list of containers.	`"1m"`	no

Blocks

The following blocks are supported inside the definition of discovery.docker:

Hierarchy	Block	Description	Required
filter	filter	Filters discoverable resources.	no
http_client_config	http_client_config	HTTP client configuration for docker requests.	no
http_client_config > basic_auth	basic_auth	Configure basic_auth for authenticating to the endpoint.	no
http_client_config > authorization	authorization	Configure generic authorization to the endpoint.	no
http_client_config > oauth2	oauth2	Configure OAuth2 for authenticating to the endpoint.	no
http_client_config > oauth2 > tls_config	tls_config	Configure TLS settings for connecting to the endpoint.	no

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

The filter block configures a filter to pass to the Docker Engine to limit the amount of containers returned. The filter block can be specified multiple times to provide more than one filter.

Name	Type	Description	Default	Required
`name`	`string`	Filter name to use.		yes
`values`	`list(string)`	Values to pass to the filter.		yes

Refer to List containers from the Docker Engine API documentation for the list of supported filters and their meaning.

http_client_config block

The http_client_config block configures settings used to connect to the Docker Engine API server.

Name	Type	Description	Default	Required
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`enable_http_2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

basic_auth block

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

password and password_file are mututally exclusive and only one can be provided inside of a basic_auth block.

authorization block

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

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

oauth2 block

Name	Type	Description	Required
`client_id`	`string`	OAuth2 client ID.	no
`client_secret`	`secret`	OAuth2 client secret.	no
`client_secret_file`	`string`	File containing the OAuth2 client secret.	no
`scopes`	`list(string)`	List of scopes to authenticate with.	no
`token_url`	`string`	URL to fetch the token from.	no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.	no
`proxy_url`	`string`	Optional proxy URL for OAuth2 requests.	no

client_secret and client_secret_file are mututally exclusive and only one can be provided inside of an oauth2 block.

The oauth2 block may also contain its own separate tls_config sub-block.

tls_config block

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

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)

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The set of targets discovered from the docker API.

Each target includes the following labels:

__meta_docker_container_id: ID of the container.
__meta_docker_container_name: Name of the container.
__meta_docker_container_network_mode: Network mode of the container.
__meta_docker_container_label_<labelname>: Each label from the container.
__meta_docker_network_id: ID of the Docker network the container is in.
__meta_docker_network_name: Name of the Docker network the container is in.
__meta_docker_network_ingress: Set to true if the Docker network is an ingress network.
__meta_docker_network_internal: Set to true if the Docker network is an internal network.
__meta_docker_network_label_<labelname>: Each label from the network the container is in.
__meta_docker_network_scope: The scope of the network the container is in.
__meta_docker_network_ip: The IP of the container in the network.
__meta_docker_port_private: The private port on the container.
__meta_docker_port_public: The publicly exposed port from the container, if a port mapping exists.
__meta_docker_port_public_ip: The public IP of the container, if a port mapping exists.

Each discovered container maps to one target per unique combination of networks and port mappings used by the container.

Component health

discovery.docker is only reported as unhealthy when given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

discovery.docker does not expose any component-specific debug information.

Debug metrics

discovery.docker does not expose any component-specific debug metrics.

Examples

Linux or macOS hosts

This example discovers Docker containers when the host machine is macOS or Linux:

discovery.docker "containers" {
  host = "unix:///var/run/docker.sock"
}

Windows hosts

This example discovers Docker containers when the host machine is Windows:

discovery.docker "containers" {
  host = "tcp://localhost:2375"
}

NOTE: This example requires the “Expose daemon on tcp://localhost:2375 without TLS” setting to be enabled in the Docker Engine settings.

discovery.file

Sat, 11 Apr 2026 12:27:38 +0000

discovery.file

discovery.file discovers files on the local filesystem using glob patterns and the doublestar library.

Usage

discovery.file "LABEL" {
  path_targets = [{"__path__" = "DOUBLESTAR_PATH"}]
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`path_targets`	`list(map(string))`	Targets to expand; looks for glob patterns on the `__path__` and `__path_exclude__` keys.		yes
`sync_period`	`duration`	How often to sync filesystem and targets.	`"10s"`	no

path_targets uses doublestar style paths.

/tmp/**/*.log will match all subfolders of tmp and include any files that end in *.log.
/tmp/apache/*.log will match only files in /tmp/apache/ that end in *.log.
/tmp/** will match all subfolders of tmp, tmp itself, and all files.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The set of targets discovered from the filesystem.

Each target includes the following labels:

__path__: Absolute path to the file.

Component health

discovery.file is only reported as unhealthy when given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

discovery.file does not expose any component-specific debug information.

Debug metrics

discovery.file does not expose any component-specific debug metrics.

Examples

This example discovers all files and folders under /tmp/logs. The absolute paths are used by loki.source.file.files targets.

discovery.file "tmp" {
    path_targets = [{"__path__" = "/tmp/logs/**/*.log"}]
}

loki.source.file "files" {
    targets    = discovery.file.tmp.targets
    forward_to = [ /* ... */ ]
}

Kubernetes

This example finds all the logs on pods and monitors them.

discovery.kubernetes "k8s" {
  role = "pod"
}

discovery.relabel "k8s" {
  targets = discovery.kubernetes.k8s.targets
 
  rule {
    source_labels = ["__meta_kubernetes_namespace", "__meta_kubernetes_pod_label_name"]
    target_label  = "job"
    separator     = "/"
  }

  rule {
    source_labels = ["__meta_kubernetes_pod_uid", "__meta_kubernetes_pod_container_name"]
    target_label  = "__path__"
    separator     = "/" 
    replacement   = "/var/log/pods/*$1/*.log"
  } 
}

discovery.file "pods" {
    path_targets = discovery.relabel.k8s.output
}

loki.source.file "pods" {
    targets = discovery.file.pods.targets
    forward_to = [loki.write.endpoint.receiver]
}

loki.write "endpoint" {
    endpoint {
        url = "LOKI_PATH"
        http_client_config {
            basic_auth {
                username = USERNAME
                password = "PASSWORD"
            }
        }
    }
}

discovery.kubernetes

Sat, 11 Apr 2026 12:27:38 +0000

discovery.kubernetes

discovery.kubernetes allows you to find scrape targets from Kubernetes resources. It watches cluster state, and ensures targets are continually synced with what is currently running in your cluster.

If you supply no connection information, this component defaults to an in-cluster config. A kubeconfig file or manual connection settings can be used to override the defaults.

Usage

discovery.kubernetes "LABEL" {
  role = "DISCOVERY_ROLE"
}

Arguments

The following arguments are supported:

Name	Type	Description	Required
`api_server`	`string`	URL of Kubernetes API server.	no
`role`	`string`	Type of Kubernetes resource to query.	yes
`kubeconfig_file`	`string`	Path of kubeconfig file to use for connecting to Kubernetes.	no

The role argument is required to specify what type of targets to discover. role must be one of node, pod, service, endpoints, endpointslice, or ingress.

node role

The node role discovers one target per cluster node with the address defaulting to the HTTP port of the Kubelet daemon. The target address defaults to the first existing address of the Kubernetes node object in the address type order of NodeInternalIP, NodeExternalIP, NodeLegacyHostIP, and NodeHostName.

The following labels are included for discovered nodes:

__meta_kubernetes_node_name: The name of the node object.
__meta_kubernetes_node_provider_id: The cloud provider’s name for the node object.
__meta_kubernetes_node_label_<labelname>: Each label from the node object.
__meta_kubernetes_node_labelpresent_<labelname>: Set to true for each label from the node object.
__meta_kubernetes_node_annotation_<annotationname>: Each annotation from the node object.
__meta_kubernetes_node_annotationpresent_<annotationname>: Set to true for each annotation from the node object.
__meta_kubernetes_node_address_<address_type>: The first address for each node address type, if it exists.

In addition, the instance label for the node will be set to the node name as retrieved from the API server.

service role

The service role discovers a target for each service port for each service. This is generally useful for externally monitoring a service. The address will be set to the Kubernetes DNS name of the service and respective service port.

The following labels are included for discovered services:

__meta_kubernetes_namespace: The namespace of the service object.
__meta_kubernetes_service_annotation_<annotationname>: Each annotation from the service object.
__meta_kubernetes_service_annotationpresent_<annotationname>: true for each annotation of the service object.
__meta_kubernetes_service_cluster_ip: The cluster IP address of the service. This does not apply to services of type ExternalName.
__meta_kubernetes_service_external_name: The DNS name of the service. This only applies to services of type ExternalName.
__meta_kubernetes_service_label_<labelname>: Each label from the service object.
__meta_kubernetes_service_labelpresent_<labelname>: true for each label of the service object.
__meta_kubernetes_service_name: The name of the service object.
__meta_kubernetes_service_port_name: Name of the service port for the target.
__meta_kubernetes_service_port_number: Number of the service port for the target.
__meta_kubernetes_service_port_protocol: Protocol of the service port for the target.
__meta_kubernetes_service_type: The type of the service.

pod role

The pod role discovers all pods and exposes their containers as targets. For each declared port of a container, a single target is generated.

If a container has no specified ports, a port-free target per container is created. These targets must have a port manually injected using a discovery.relabel component before metrics can be collected from them.

The following labels are included for discovered pods:

__meta_kubernetes_namespace: The namespace of the pod object.
__meta_kubernetes_pod_name: The name of the pod object.
__meta_kubernetes_pod_ip: The pod IP of the pod object.
__meta_kubernetes_pod_label_<labelname>: Each label from the pod object.
__meta_kubernetes_pod_labelpresent_<labelname>: true for each label from the pod object.
__meta_kubernetes_pod_annotation_<annotationname>: Each annotation from the pod object.
__meta_kubernetes_pod_annotationpresent_<annotationname>: true for each annotation from the pod object.
__meta_kubernetes_pod_container_init: true if the container is an InitContainer.
__meta_kubernetes_pod_container_name: Name of the container the target address points to.
__meta_kubernetes_pod_container_image: The image the container is using.
__meta_kubernetes_pod_container_port_name: Name of the container port.
__meta_kubernetes_pod_container_port_number: Number of the container port.
__meta_kubernetes_pod_container_port_protocol: Protocol of the container port.
__meta_kubernetes_pod_ready: Set to true or false for the pod’s ready state.
__meta_kubernetes_pod_phase: Set to Pending, Running, Succeeded, Failed or Unknown in the lifecycle.
__meta_kubernetes_pod_node_name: The name of the node the pod is scheduled onto.
__meta_kubernetes_pod_host_ip: The current host IP of the pod object.
__meta_kubernetes_pod_uid: The UID of the pod object.
__meta_kubernetes_pod_controller_kind: Object kind of the pod controller.
__meta_kubernetes_pod_controller_name: Name of the pod controller.

endpoints role

The endpoints role discovers targets from listed endpoints of a service. For each endpoint address one target is discovered per port. If the endpoint is backed by a pod, all container ports of a pod are discovered as targets even if they are not bound to an endpoint port.

The following labels are included for discovered endpoints:

__meta_kubernetes_namespace: The namespace of the endpoints object.
__meta_kubernetes_endpoints_name: The names of the endpoints object.
__meta_kubernetes_endpoints_label_<labelname>: Each label from the endpoints object.
__meta_kubernetes_endpoints_labelpresent_<labelname>: true for each label from the endpoints object.
The following labels are attached for all targets discovered directly from the endpoints list:
- __meta_kubernetes_endpoint_hostname: Hostname of the endpoint.
- __meta_kubernetes_endpoint_node_name: Name of the node hosting the endpoint.
- __meta_kubernetes_endpoint_ready: Set to true or false for the endpoint’s ready state.
- __meta_kubernetes_endpoint_port_name: Name of the endpoint port.
- __meta_kubernetes_endpoint_port_protocol: Protocol of the endpoint port.
- __meta_kubernetes_endpoint_address_target_kind: Kind of the endpoint address target.
- __meta_kubernetes_endpoint_address_target_name: Name of the endpoint address target.
If the endpoints belong to a service, all labels of the service role discovery are attached.
For all targets backed by a pod, all labels of the pod role discovery are attached.

endpointslice role

The endpointslice role discovers targets from existing Kubernetes endpoint slices. For each endpoint address referenced in the EndpointSlice object, one target is discovered. If the endpoint is backed by a pod, all container ports of a pod are discovered as targets even if they are not bound to an endpoint port.

The following labels are included for discovered endpoint slices:

__meta_kubernetes_namespace: The namespace of the endpoints object.
__meta_kubernetes_endpointslice_name: The name of endpoint slice object.
The following labels are attached for all targets discovered directly from the endpoint slice list:
- __meta_kubernetes_endpointslice_address_target_kind: Kind of the referenced object.
- __meta_kubernetes_endpointslice_address_target_name: Name of referenced object.
- __meta_kubernetes_endpointslice_address_type: The IP protocol family of the address of the target.
- __meta_kubernetes_endpointslice_endpoint_conditions_ready: Set to true or false for the referenced endpoint’s ready state.
- __meta_kubernetes_endpointslice_endpoint_topology_kubernetes_io_hostname: Name of the node hosting the referenced endpoint.
- __meta_kubernetes_endpointslice_endpoint_topology_present_kubernetes_io_hostname: true if the referenced object has a kubernetes.io/hostname annotation.
- __meta_kubernetes_endpointslice_port: Port of the referenced endpoint.
- __meta_kubernetes_endpointslice_port_name: Named port of the referenced endpoint.
- __meta_kubernetes_endpointslice_port_protocol: Protocol of the referenced endpoint.
If the endpoints belong to a service, all labels of the service role discovery are attached.
For all targets backed by a pod, all labels of the pod role discovery are attached.

ingress role

The ingress role discovers a target for each path of each ingress. This is generally useful for externally monitoring an ingress. The address will be set to the host specified in the Kubernetes Ingress’s spec block.

The following labels are included for discovered ingress objects:

__meta_kubernetes_namespace: The namespace of the ingress object.
__meta_kubernetes_ingress_name: The name of the ingress object.
__meta_kubernetes_ingress_label_<labelname>: Each label from the ingress object.
__meta_kubernetes_ingress_labelpresent_<labelname>: true for each label from the ingress object.
__meta_kubernetes_ingress_annotation_<annotationname>: Each annotation from the ingress object.
__meta_kubernetes_ingress_annotationpresent_<annotationname>: true for each annotation from the ingress object.
__meta_kubernetes_ingress_class_name: Class name from ingress spec, if present.
__meta_kubernetes_ingress_scheme: Protocol scheme of ingress, https if TLS config is set. Defaults to http.
__meta_kubernetes_ingress_path: Path from ingress spec. Defaults to /.

Blocks

The following blocks are supported inside the definition of discovery.kubernetes:

Hierarchy	Block	Description	Required
namespaces	namespaces	Information about which Kubernetes namespaces to search.	no
selectors	selectors	Information about which Kubernetes namespaces to search.	no
http_client_config	http_client_config	HTTP client configuration for Kubernetes requests.	no
http_client_config > basic_auth	basic_auth	Configure basic_auth for authenticating to the endpoint.	no
http_client_config > authorization	authorization	Configure generic authorization to the endpoint.	no
http_client_config > oauth2	oauth2	Configure OAuth2 for authenticating to the endpoint.	no
http_client_config > oauth2 > tls_config	tls_config	Configure TLS settings for connecting to the endpoint.	no

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

namespaces block

The namespaces block limits the namespaces to discover resources in. If omitted, all namespaces are searched.

Name	Type	Description	Default	Required
`own_namespace`	`bool`	Include the namespace the agent is running in.		no
`names`	`[]string`	List of namespaces to search.		no

selectors block

The selectors block contains optional label and field selectors to limit the discovery process to a subset of resources.

Name	Type	Description	Required
`role`	`string`	Role of the selector.	yes
`label`	`string`	Label selector string.	no
`field`	`string`	Field selector string.	no

See Kubernetes’ documentation for Field selectors and [Labels and selectors][] to learn more about the possible filters that can be used.

Note: Using multiple discovery.kubernetes components with different selectors may result in a bigger load against the Kubernetes API.

Selectors are recommended for retrieving a small set of resources in a very large cluster. Smaller clusters are recommended to avoid selectors in favor of filtering with a discovery.relabel component instead.

http_client_config block

The http_client_config block configures settings used to connect to the Kubernetes API server.

Name	Type	Description	Default	Required
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`enable_http_2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

basic_auth block

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

password and password_file are mututally exclusive and only one can be provided inside of a basic_auth block.

authorization block

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

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

oauth2 block

Name	Type	Description	Required
`client_id`	`string`	OAuth2 client ID.	no
`client_secret`	`secret`	OAuth2 client secret.	no
`client_secret_file`	`string`	File containing the OAuth2 client secret.	no
`scopes`	`list(string)`	List of scopes to authenticate with.	no
`token_url`	`string`	URL to fetch the token from.	no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.	no
`proxy_url`	`string`	Optional proxy URL for OAuth2 requests.	no

client_secret and client_secret_file are mututally exclusive and only one can be provided inside of an oauth2 block.

The oauth2 block may also contain its own separate tls_config sub-block.

tls_config block

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

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

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The set of targets discovered from the Kubernetes API.

Component health

discovery.kubernetes is reported as unhealthy when given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

discovery.kubernetes does not expose any component-specific debug information.

Debug metrics

discovery.kubernetes does not expose any component-specific debug metrics.

Examples

In-cluster discovery

This example uses in-cluster authentication to discover all pods:

discovery.kubernetes "k8s_pods" {
  role = "pod"
}

Kubeconfig authentication

This example uses a kubeconfig file to authenticate to the Kubernetes API:

discovery.kubernetes "k8s_pods" {
  role = "pod"
  kubeconfig_file = "/etc/k8s/kubeconfig.yaml"
}

Limit searched namespaces

This example limits the namespaces where pods are discovered using the namespaces block:

discovery.kubernetes "k8s_pods" {
  role = "pod"
  namespaces {
    names = ["myapp"]
  }
}

discovery.relabel

Sat, 11 Apr 2026 12:27:38 +0000

discovery.relabel

In Flow, targets are defined as sets of key-value pairs called labels.

discovery.relabel rewrites the label set of the input targets by applying one or more relabeling rules. If no rules are defined, then the input targets are exported as-is.

The most common use of discovery.relabel is to filter targets or standardize the target label set that is passed to a downstream component. The rule blocks are applied to the label set of each target in order of their appearance in the configuration file. The configured rules can be retrieved by calling the function in the rules export field.

Target labels which start with a double underscore __ are considered internal, and may be removed by other Flow components prior to telemetry collection. To retain any of these labels, use a labelmap action to remove the prefix, or remap them to a different name. Service discovery mechanisms usually group their labels under __meta_*. For example, the discovery.kubernetes component populates a set of __meta_kubernetes_* labels to provide information about the discovered Kubernetes resources. If a relabeling rule needs to store a label value temporarily, for example as the input to a subsequent step, use the __tmp label name prefix, as it is guaranteed to never be used.

Multiple discovery.relabel components can be specified by giving them different labels.

Usage

discovery.relabel "LABEL" {
  targets = TARGET_LIST

  rule {
    ...
  }

  ...
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`targets`	`list(map(string))`	Targets to relabel		yes

Blocks

The following blocks are supported inside the definition of discovery.relabel:

Hierarchy	Block	Description	Required
rule	rule	Relabeling rules to apply to targets.	no

rule block

The rule block contains the definition of any relabeling rules that can be applied to an input metric. If more than one rule block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a rule. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`source_labels`	`list(string)`	The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.		no
`separator`	`string`	The separator used to concatenate the values present in `source_labels`.	;	no
`regex`	`string`	A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions.	`(.*)`	no
`modulus`	`uint`	A positive integer used to calculate the modulus of the hashed source label values.		no
`target_label`	`string`	Label to which the resulting value will be written to.		no
`replacement`	`string`	The value against which a regex replace is performed, if the regex matches the extracted value. Supports previously captured groups.	$1	no
`action`	`string`	The relabeling action to perform.	replace	no

Here’s a list of the available actions, along with a brief description of their usage.

replace - Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
keep - Keeps metrics where regex matches the string extracted using the source_labels and separator.
drop - Drops metrics where regex matches the string extracted using the source_labels and separator.
hashmod - Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
labeldrop - Matches regex against all label names. Any labels that match are removed from the metric’s label set.
labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the metric’s label set.

Finally, note that the regex capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

Exported fields

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

Name	Type	Description
`output`	`list(map(string))`	The set of targets after applying relabeling.
`rules`	`RelabelRules`	The currently configured relabeling rules.

Component health

discovery.relabel is only reported as unhealthy when given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

discovery.relabel does not expose any component-specific debug information.

Debug metrics

discovery.relabel does not expose any component-specific debug metrics.

Example

discovery.relabel "keep_backend_only" {
  targets = [
    { "__meta_foo" = "foo", "__address__" = "localhost", "instance" = "one",   "app" = "backend"  },
    { "__meta_bar" = "bar", "__address__" = "localhost", "instance" = "two",   "app" = "database" },
    { "__meta_baz" = "baz", "__address__" = "localhost", "instance" = "three", "app" = "frontend" },
  ]

  rule {
    source_labels = ["__address__", "instance"]
    separator     = "/"
    target_label  = "destination"
    action        = "replace"
  }

  rule {
    source_labels = ["app"]
    action        = "keep"
    regex         = "backend"
  }
}

local.file

Sat, 11 Apr 2026 12:27:38 +0000

local.file

local.file exposes the contents of a file on disk to other components. The file will be watched for changes so that its latest content is always exposed.

The most common use of local.file is to load secrets (e.g., API keys) from files.

Multiple local.file components can be specified by giving them different labels.

Usage

local.file "LABEL" {
  filename = FILE_NAME
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`filename`	`string`	Path of the file 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
`is_secret`	`bool`	Marks the file as containing a secret	`false`	no

File change detectors

File change detectors are used for detecting 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 had been updated. This requires a filesystem which supports events at the Operating System level: network-based filesystems like NFS or FUSE won’t work.

When a filesystem event is received, the component will reread the watched file. This will happen for any filesystem event to the file, including a change of permissions.

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

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

poll

The poll file change detector will cause the watched file to be reread every poll_frequency, regardless of whether the file changed.

Exported fields

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

Name	Type	Description
`content`	`string` or `secret`	The contents of the file from the most recent read

The content field will have the secret type only if the is_secret argument was true.

Component health

local.file will be reported as healthy whenever if the watched file was read successfully.

Failing to read the file whenever an update is detected (or after the poll period elapses) will cause the component to be reported as unhealthy. When unhealthy, exported fields will be kept at the last healthy value. The read error will be exposed as a log message and in the debug information for the component.

Debug information

local.file does not expose any component-specific debug information.

Debug metrics

agent_local_file_timestamp_last_accessed_unix_seconds (gauge): The timestamp, in Unix seconds, that the file was last sucessfully accessed.

Example

local.file "secret_key" {
  filename  = "/var/secrets/password.txt"
  is_secret = true
}

loki.process

Sat, 11 Apr 2026 12:27:38 +0000

loki.process

loki.process receives log entries from other loki components, applies one or more processing stages, and forwards the results to the list of receivers in the component’s arguments.

A stage is a multi-purpose block that can parse, transform, and filter log entries before they’re passed to a downstream component. These stages are applied to each log entry in order of their appearance in the configuration file. All stages within a loki.process block have access to the log entry’s label set, the log line, the log timestamp, as well as a shared map of ’extracted’ values so that the results of one stage can be used in a subsequent one.

Multiple loki.process components can be specified by giving them different labels.

Usage

loki.process "LABEL" {
  forward_to = RECEIVER_LIST

  stage {
    ...
  }
  ...
}

Arguments

loki.process supports the following arguments:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	Where to forward log entries after processing.		yes

Blocks

The following blocks are supported inside the definition of loki.process:

Hierarchy	Block	Description	Required
stage	stage	Processing stage to run.	no
stage > docker	docker	Configures a pre-defined Docker log format pipeline.	no
stage > cri	cri	Configures a pre-defined CRI-format pipeline.	no
stage > json	json	Configures a JSON processing stage.	no
stage > logfmt	logfmt	Configures a logfmt processing stage.	no
stage > labels	labels	Configures a labels processing stage.	no
stage > label_keep	label_keep	Configures a `label_keep` processing stage.	no
stage > label_drop	label_drop	Configures a `label_drop` processing stage.	no
stage > static_labels	static_labels	Configures a `static_labels` processing stage.	no
stage > regex	regex	Configures a `regex` processing stage.	no
stage > timestamp	timestamp	Configures a `timestamp` processing stage.	no
stage > output	output	Configures an `output` processing stage.	no
stage > replace	replace	Configures a `replace` processing stage.	no
stage > multiline	multiline	Configures a `multiline` processing stage.	no
stage > match	match	Configures a `match` processing stage.	no
stage > drop	drop	Configures a `drop` processing stage.	no

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

stage block

The stage block describes a single processing step to run log entries through. As such, each block must have exactly one inner block to match the type of stage to configure. Multiple processing stages must be defined in different blocks and are applied on the incoming log entries in top-down order.

The stage block does not support any arguments and is configured only via inner blocks.

docker block

The docker inner block enables a predefined pipeline which reads log lines in the standard format of Docker log files.

The docker block does not support any arguments or inner blocks, so it is always empty.

stage {
	docker {}
}

Docker log entries are formatted as JSON with the following keys:

log: The content of log line
stream: Either stdout or stderr
time: The timestamp string of the log line

Given the following log line, the subsequent key-value pairs are created in the shared map of extracted data:

{"log":"log message\n","stream":"stderr","time":"2019-04-30T02:12:41.8443515Z"}

output: log message\n
stream: stderr
timestamp: 2019-04-30T02:12:41.8443515

cri block

The cri inner block enables a predefined pipeline which reads log lines using the CRI logging format.

The cri block does not support any arguments or inner blocks, so it is always empty.

stage {
	cri {}
}

CRI specifies log lines as single space-delimited values with the following components:

time: The timestamp string of the log
stream: Either stdout or stderr
flags: CRI flags including F or P
log: The contents of the log line

Given the following log line, the subsequent key-value pairs are created in the shared map of extracted data:

"2019-04-30T02:12:41.8443515Z stdout F message"

content: message
stream: stdout
timestamp: 2019-04-30T02:12:41.8443515

json block

The json inner block configures a JSON processing stage that parses incoming log lines or previously extracted values as JSON and uses JMESPath expressions to extract new values from them.

The following arguments are supported:

Name	Type	Description	Default	Required
`expressions`	`map(string)`	Key-value pairs of JMESPath expressions.		yes
`source`	`string`	Source of the data to parse as JSON.	`""`	no
`drop_malformed`	`bool`	Drop lines whose input cannot be parsed as valid JSON.	`false`	no

When configuring a JSON stage, the source field defines the source of data to parse as JSON. By default, this is the log line itself, but it can also be a previously extracted value.

The expressions field is the set of key-value pairs of MESPath expressions to run. The map key defines the name with which the data is extracted, while the map value is the expression used to populate the value.

Here’s a given log line and two JSON stages to run.

{"log":"log message\n","extra":"{\"user\":\"agent\"}"}

loki.process "username" {
	stage {
		json {
			expressions = {output = log, extra = ""}
		}
	}

	stage {
		json {
			source      = "extra"
			expressions = {username = "user"}
		}
	}
}

In this example, the first stage uses the log line as the source and populates these values in the shared map. An empty expression means using the same value as the key (so extra="extra").

output: log message\n
extra: {"user": "agent"}

The second stage uses the value in extra as the input and appends the following key-value pair to the set of extracted data.

username: agent

logfmt block

The logfmt inner block configures a processing stage that reads incoming log lines as logfmt and extracts values from them.

The following arguments are supported:

Name	Type	Description	Default	Required
`mapping`	`map(string)`	Key-value pairs of logmft fields to extract.		yes
`source`	`string`	Source of the data to parse as logfmt.	`""`	no

The source field defines the source of data to parse as logfmt. When source is missing or empty, the stage parses the log line itself, but it can also be used to parse a previously extracted value.

This stage uses the go-logfmt unmarshaler, so that numeric or boolean types are unmarshalled into their correct form. The stage does not perform any other type conversions. If the extracted value is a complex type, it is treated as a string.

Let’s see how this works on the following log line and stages.

time=2012-11-01T22:08:41+00:00 app=loki level=WARN duration=125 message="this is a log line" extra="user=foo"

stage {
	logfmt {
		mapping = { "extra" = "" }
	}
}

stage {
	logfmt {
		mapping = { "username" = "user" }
		source  = "extra"
	}
}

The first stage parses the log line itself and inserts the extra key in the set of extracted data, with the value of user=foo.

The second stage parses the contents of extra and appends the username: foo key-value pair to the set of extracted data.

labels block

The labels inner block configures a labels processing stage that can read data from the extracted values map and set new labels on incoming log entries.

The following arguments are supported:

Name	Type	Description	Default	Required
`values`	`map(string)`	Configures a `labels` processing stage.	`{}`	no

In a labels stage, the map’s keys define the label to set and the values are how to look them up. If the value is empty, it is inferred to be the same as the key.

stage {
	labels {
		values = {
			env  = "",         // Sets up an 'env' label, based on the 'env' extracted value.
			user = "username", // Sets up a 'user' label, based on the 'username' extracted value.
		}
	}
}

label_keep block

The label_keep inner block configures a processing stage that filters the label set of an incoming log entry down to a subset.

The following arguments are supported:

Name	Type	Description	Default	Required
`values`	`list(string)`	Configures a `label_keep` processing stage.	`{}`	no

stage {
	label_keep {
		values = [ "kubernetes_pod_name", "kubernetes_container_name" ]
	}
}

label_drop block

The label_drop inner block configures a processing stage that drops labels from incoming log entries.

The following arguments are supported:

Name	Type	Description	Default	Required
`values`	`list(string)`	Configures a `label_drop` processing stage.	`{}`	no

stage {
	label_drop {
		values = [ "kubernetes_node_name", "kubernetes_namespace" ]
	}
}

static_labels block

The static_labels inner block configures a static_labels processing stage that adds a static set of labels to incoming log entries.

The following arguments are supported:

Name	Type	Description	Default	Required
`values`	`map(string)`	Configures a `static_labels` processing stage.	`{}`	no

stage {
	static_labels {
		values = {
			foo = "fooval",
			bar = "barval",
		}
	}
}

regex block

The regex inner block configures a processing stage that parses log lines using regular expressions and uses named capture groups for adding data into the shared extracted map of values.

The following arguments are supported:

Name	Type	Description	Default	Required
`expression`	`string`	A valid RE2 regular expression. Each capture group must be named.		yes
`source`	`string`	Name from extracted data to parse. If empty, uses the log message.	`""`	no

The expression field needs to be a RE2 regex string. Every matched capture group is added to the extracted map, so it must be named like: (?P<name>re). The name of the capture group is then used as the key in the extracted map for the matched value.

Because of how River strings work, any backslashes in expression must be escaped with a double backslash; for example "\\w" or "\\S+".

If the source is empty or missing, then the stage parses the log line itself. If it’s set, the stage parses a previously extracted value with the same name.

Given the following log line and regex stage, the extracted values are shown below:

2019-01-01T01:00:00.000000001Z stderr P i'm a log message!

stage {
  regex {
    expression = "^(?s)(?P<time>\\S+?) (?P<stream>stdout|stderr) (?P<flags>\\S+?) (?P<content>.*)$"
  }
}


time: 2019-01-01T01:00:00.000000001Z,
stream: stderr,
flags: P,
content: i'm a log message

On the other hand, if the source value is set, then the regex is applied to the value stored in the shared map under that name.

Let’s see what happens when the following log line is put through this two-stage pipeline:

{"timestamp":"2022-01-01T01:00:00.000000001Z"}

stage {
  json {
    expressions = { time = "timestamp" }
  }
}
stage {
  regex {
    expression = "^(?P<year>\\d+)"
    source     = "time"
  }
}

The first stage adds the following key-value pair into the extracted map:

time: 2022-01-01T01:00:00.000000001Z

Then, the regex stage parses the value for time from the shared values and appends the subsequent key-value pair back into the extracted values map:

year: 2022

timestamp block

The timestamp inner block configures a processing stage that sets the timestamp of log entries before they’re forwarded to the next component. When no timestamp stage is set, the log entry timestamp defaults to the time when the log entry was scraped.

The following arguments are supported:

Name	Type	Description	Default	Required
`source`	`string`	Name from extracted values map to use for the timestamp.		yes
`format`	`string`	Determines how to parse the source string.		yes
`fallback_formats`	`list(string)`	Fallback formats to try if the `format` field fails.	`[]`	no
`location`	`string`	IANA Timezone Database location to use when parsing.	`""`	no
`action_on_failure`	`string`	What to do when the timestamp can’t be extracted or parsed.	`"fudge"`	no

The source field defines which value from the shared map of extracted values the stage should attempt to parse as a timestamp.

The format field defines how that source should be parsed.

First off, the format can be set to one of the following shorthand values for commonly-used forms:

ANSIC: Mon Jan _2 15:04:05 2006
UnixDate: Mon Jan _2 15:04:05 MST 2006
RubyDate: Mon Jan 02 15:04:05 -0700 2006
RFC822: 02 Jan 06 15:04 MST
RFC822Z: 02 Jan 06 15:04 -0700
RFC850: Monday, 02-Jan-06 15:04:05 MST
RFC1123: Mon, 02 Jan 2006 15:04:05 MST
RFC1123Z: Mon, 02 Jan 2006 15:04:05 -0700
RFC3339: 2006-01-02T15:04:05-07:00
RFC3339Nano: 2006-01-02T15:04:05.999999999-07:00

Additionally, support for common Unix timestamps is supported with the following format values:

Unix: 1562708916 or with fractions 1562708916.000000123
UnixMs: 1562708916414
UnixUs: 1562708916414123
UnixNs: 1562708916000000123

Otherwise, the field accepts a custom format string that defines how an arbitrary reference point in history should be interpreted by the stage. The arbitrary reference point is Mon Jan 2 15:04:05 -0700 MST 2006.

The string value of the field is passed directly to the layout parameter in Go’s time.Parse function.

If the custom format has no year component, the stage uses the current year, according to the system’s clock.

The following table shows the supported reference values to use when defining a custom format.

Timestamp Component	Format value
Year	06, 2006
Month	1, 01, Jan, January
Day	2, 02, _2 (two digits right justified)
Day of the week	Mon, Monday
Hour	3 (12-hour), 03 (12-hour zero prefixed), 15 (24-hour)
Minute	4, 04
Second	5, 05
Fraction of second	.000 (ms zero prefixed), .000000 (μs), .000000000 (ns), .999 (ms without trailing zeroes), .999999 (μs), .999999999 (ns)
12-hour period	pm, PM
Timezone name	MST
Timezone offset	-0700, -070000 (with seconds), -07, 07:00, -07:00:00 (with seconds)
Timezone ISO-8601	Z0700 (Z for UTC or time offset), Z070000, Z07, Z07:00, Z07:00:00

The fallback_formats field defines one or more format fields to try and parse the timestamp with, if parsing with format fails.

The location field must be a valid IANA Timezone Database location and determines in which timezone the timestamp value is interpreted to be in.

The action_on_failure field defines what should happen when the source field doesn’t exist in the shared extracted map, or if the timestamp parsing fails.

The supported actions are:

fudge (default): Change the timestamp to the last known timestamp, summing up 1 nanosecond (to guarantee log entries ordering).
skip: Do not change the timestamp and keep the time when the log entry was scraped.

The following stage fetches the time value from the shared values map, parses it as a RFC3339 format, and sets it as the log entry’s timestamp.

stage {
	timestamp {
		source = "time"
		format = "RFC3339"
	}
}

output block

The output inner block configures a processing stage that reads from the extracted map and changes the content of the log entry that is forwarded to the next component.

The following arguments are supported:

Name	Type	Description	Default	Required
`source`	`string`	Name from extracted data to use for the log entry.		yes

Let’s see how this works for the following log line and three-stage pipeline:

{"user": "John Doe", "message": "hello, world!"}

stage {
	json {
		expressions = { "user" = "user", "message" = "message" }
	}
}

stage {
	labels {
		values = { "user" = "user" }
	}
}

stage {
	output {
		source = "message"
	}
}

The first stage extracts the following key-value pairs into the shared map:

user: John Doe
message: hello, world!

Then, the second stage adds user="John Doe" to the label set of the log entry, and the final output stage changes the log line from the original JSON to hello, world!.

replace block

The replace inner block configures a stage that parses a log line using a regular expression and replaces the log line contents. Named capture groups in the regex also support adding data into the shared extracted map.

The following arguments are supported:

Name	Type	Description	Required
`expression`	`string`	Name from extracted data to use for the log entry.	yes
`source`	`string`	Source of the data to parse. If empty, it uses the log message.	no
`replace`	`string`	Value replaced by the capture group.	no

The source field defines the source of data to parse using expression. When source is missing or empty, the stage parses the log line itself, but it can also be used to parse a previously extracted value. The replaced value is assigned back to the source key.

The expression must be a valid RE2 regex. Every named capture group (?P<name>re) is set into the extracted map with its name.

Because of how River treats backslashes in double-quoted strings, note that all backslashes in a regex expression must be escaped like "\\w*".

Let’s see how this works with the following log line and stage. Since source is omitted, the replacement occurs on the log line itself.

2023-01-01T01:00:00.000000001Z stderr P i'm a log message who has sensitive information with password xyz!

stage {
	replace {
		expression = "password (\\S+)"
		replace    = "*****"
	}
}

The log line is transformed to

2023-01-01T01:00:00.000000001Z stderr P i'm a log message who has sensitive information with password *****!

If replace is empty, then the captured value is omitted instead.

In the following example, source is defined.

{"time":"2023-01-01T01:00:00.000000001Z", "level": "info", "msg":"11.11.11.11 - \"POST /loki/api/push/ HTTP/1.1\" 200 932 \"-\" \"Mozilla/5.0\"}

stage {
	json {
		expressions = { "level" = "", "msg" = "" }
	}
}

stage {
	replace {
		expression = "\\S+ - \"POST (\\S+) .*"
		source     = "msg"
		replace    = "redacted_url"
	}
}

The JSON stage adds the following key-value pairs into the extracted map:

time: 2023-01-01T01:00:00.000000001Z
level: info
msg: "11.11.11.11 - "POST /loki/api/push/ HTTP/1.1" 200 932 "-" "Mozilla/5.0"

The replace stage acts on the msg value. The capture group matches against /loki/api/push and is replaced by redacted_url.

The msg value is finally transformed into:

msg: "11.11.11.11 - "POST redacted_url HTTP/1.1" 200 932 "-" "Mozilla/5.0"

The replace field can use a set of templating functions, by utilizing Go’s text/template package.

Let’s see how this works with named capture groups with a sample log line and stage.

11.11.11.11 - agent [01/Jan/2023:00:00:01 +0200]

stage {
	replace {
		expression = "^(?P<ip>\\S+) (?P<identd>\\S+) (?P<user>\\S+) \\[(?P<timestamp>[\\w:/]+\\s[+\\-]\\d{4})\\]"
		replace    = "{{ .Value | ToUpper }}"
	}
}

Since source is empty, the regex parses the log line itself and extracts the named capture groups to the shared map of values. The replace field acts on these extracted values and converts them to uppercase:

ip: 11.11.11.11
identd: -
user: FRANK
timestamp: 01/JAN/2023:00:00:01 +0200

and the log line becomes:

11.11.11.11 - FRANK [01/JAN/2023:00:00:01 +0200]

The following list contains available functions with examples of more complex replace fields.

ToLower, ToUpper, Replace, Trim, TrimLeftTrimRight, TrimPrefix, TrimSuffix, TrimSpace, Hash, Sha2Hash, regexReplaceAll, regexReplaceAllLiteral

"{{ if eq .Value \"200\" }}{{ Replace .Value \"200\" \"HttpStatusOk\" -1 }}{{ else }}{{ .Value | ToUpper }}{{ end }}"
"*IP4*{{ .Value | Hash "salt" }}*"

multiline block

The multiline inner block merges multiple lines into a single block before passing it on to the next stage in the pipeline.

The following arguments are supported:

Name	Type	Description	Default	Required
`firstline`	`string`	Name from extracted data to use for the log entry.		yes
`max_wait_time`	`duration`	The maximum time to wait for a multiline block.	`"3s"`	no
`max_lines`	`int`	The maximum number of lines a block can have.	`128`	no

A new block is identified by the RE2 regular expression passed in firstline.

Any line that does not match the expression is considered to be part of the block of the previous match. If no new logs arrive with max_wait_time, the block is sent on. The max_lines field defines the maximum number of lines a block can have. If this is exceeded, a new block is started.

Let’s see how this works in practice with an example stage and a stream of log entries from a Flask web service.

stage {
	multiline {
		firstline     = "^\[\d{4}-\d{2}-\d{2} \d{1,2}:\d{2}:\d{2}\]"
		max_wait_time = "10s"
	}
}

[2023-01-18 17:41:21] "GET /hello HTTP/1.1" 200 -
[2023-01-18 17:41:25] ERROR in app: Exception on /error [GET]
Traceback (most recent call last):
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/app.py", line 2447, in wsgi_app
    response = self.full_dispatch_request()
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/app.py", line 1952, in full_dispatch_request
    rv = self.handle_user_exception(e)
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/app.py", line 1821, in handle_user_exception
    reraise(exc_type, exc_value, tb)
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/_compat.py", line 39, in reraise
    raise value
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/app.py", line 1950, in full_dispatch_request
    rv = self.dispatch_request()
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/app.py", line 1936, in dispatch_request
    return self.view_functions[rule.endpoint](**req.view_args)
  File "/home/pallets/src/deployment_tools/hello.py", line 10, in error
    raise Exception("Sorry, this route always breaks")
Exception: Sorry, this route always breaks
[2023-01-18 17:42:24] "GET /error HTTP/1.1" 500 -
[2023-01-18 17:42:29] "GET /hello HTTP/1.1" 200 -

All ‘blocks’ that form log entries of separate web requests start with a timestamp in square brackets. The stage detects this with the regular expression in firstline to collapse all lines of the traceback into a single block and thus a single Loki log entry.

match block

The match inner block configures a filtering stage that can conditionally either apply a nested set of processing stages or drop an entry when a log entry matches a configurable LogQL stream selector and filter expressions.

The following arguments are supported:

Name	Type	Description	Default	Required
`selector`	`string`	The LogQL stream selector and filter expressions to use.		yes
`pipeline_name`	`string`	A custom name to use for the nested pipeline.	`""`	no
`action`	`string`	The action to take when the selector matches the log line. Supported values are `"keep"` and `"drop"`	`"keep"`	no
`drop_counter_reason`	`string`	A custom reason to report for dropped lines.	`"match_stage"`	no

The match block supports a number of stage inner blocks, like the top-level block. These are used to construct the nested set of stages to run if the selector matches the labels and content of the log entries.

The following blocks are supported inside the definition of stage > match:

Hierarchy	Block	Description	Required
stage	stage	Processing stage to run.	no

If the specified action is "drop", the metric loki_process_dropped_lines_total is incremented with every line dropped. By default, the reason label is "match_stage", but a custom reason can be provided by using the drop_counter_reason argument.

Let’s see this in action, with the following log lines and stages

{ "time":"2023-01-18T17:08:41+00:00", "app":"foo", "component": ["parser","type"], "level" : "WARN", "message" : "app1 log line" }
{ "time":"2023-01-18T17:08:42+00:00", "app":"bar", "component": ["parser","type"], "level" : "ERROR", "message" : "foo noisy error" }

stage {
	json {
		expressions = { "appname" = "app" }
	}
}

stage {
	labels {
		values = { "applbl" = "appname" }
	}
}

stage {
	match {
		selector = '{applbl="foo"}'
		stage {
			json {
				expressions = { "msg" = "message" }
			}
		}
	}
}

stage {
	match {
		selector = '{applbl="qux"}'
		stage {
			json {
				expressions = { "msg" = "msg" }
			}
		}
	}
}

stage {
	match {
		selector = '{applbl="bar"} |~ ".*noisy error.*"'
		action   = "drop"

		drop_counter_reason = "discard_noisy_errors"
	}
}

stage {
	output {
		source = "msg"
	}
}

The first two stages parse the log lines as JSON, decode the app value into the shared extracted map as appname, and use its value as the applbl label.

The third stage uses the LogQL selector to only execute the nested stages on lines where the applbl="foo". So, for the first line, the nested JSON stage adds msg="app1 log line" into the extracted map.

The fourth stage uses the LogQL selector to only execute on lines where applbl="qux"; that means it won’t match any of the input, and the nested JSON stage does not run.

The fifth stage drops entries from lines where applbl is set to ‘bar’ and the line contents matches the regex .*noisy error.*. It also increments the loki_process_dropped_lines_total metric with a label drop_counter_reason="discard_noisy_errors".

The final output stage changes the contents of the log line to be the value of msg from the extracted map. In this case, the first log entry’s content is changed to app1 log line.

drop block

The drop inner block configures a filtering stage that drops log entries based on several options. If multiple options are provided, they’re treated as AND clauses and must all be true for the log entry to be dropped. To drop entries with an OR clause, specify multiple drop blocks in sequence.

The following arguments are supported:

Name	Type	Description	Default	Required
`source`	`string`	Name from extracted data to parse. If empty or not defined, it uses the log message.	`""`	no
`expression`	`string`	A valid RE2 regular expression.	`""`	no
`value`	`string`	If both `source` and `value` are specified, the stage drops lines where `value` exactly matches the source content.	`""`	no
`older_than`	`duration`	If specified, the stage drops lines whose timestamp is older than the current time minus this duration.	`""`	no
`longer_than`	`string`	If specified, the stage drops lines whose size exceeds the configured value.	`""`	no
`drop_counter_reason`	`string`	A custom reason to report for dropped lines.	`"drop_stage"`	no

The expression field needs to be a RE2 regex string. If source is empty or not provided, the regex attempts to match the log line itself. If source is provided, the regex attempts to match the corresponding value from the extracted map.

The value field can only work with values from the extracted map, and must be specified together with source. Entries are dropped when there is an exact match between the two.

Whenever an entry is dropped, the metric loki_process_dropped_lines_total is incremented. By default, the reason label is "drop_stage", but you can provide a custom label using the drop_counter_reason argument.

The following stage drops log entries that contain the word debug and are longer than 1KB.

stage {
	drop {
		expression  = ".*debug.*"
		longer_than = "1KB"
	}
}

On the following example, we define multiple drop blocks so loki.process will drop entries that are either 24h or older, are longer than 8KB, or the extracted value of ‘app’ is equal to foo.

stage {
	drop {
		older_than  = "24h"
		drop_reason = "too old"
	}
}

stage {
	drop {
		older_than  = "8KB"
		drop_reason = "too long"
	}
}

stage {
	drop {
		source = "app"
		value  = "foo"
	}
}

Exported fields

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

Name	Type	Description
`receiver`	`LogsReceiver`	A value that other components can use to send log entries to.

Component health

loki.process is only reported as unhealthy if given an invalid configuration.

Debug information

loki.process does not expose any component-specific debug information.

Debug metrics

loki_process_dropped_lines_total (counter): Number of lines dropped as part of a processing stage.

Example

This example creates a loki.process component that extracts the environment value from a JSON log line and sets it as a label named ’env’.

loki.process "local" {
  forward_to = [loki.write.onprem.receiver]

  stage {
    json {
      expressions = { "extracted_env" = "environment" }
    }
  }

  stage {
    labels = { "env" = "extracted_env" }
  }
}

loki.relabel

Sat, 11 Apr 2026 12:27:38 +0000

loki.relabel

The loki.relabel component rewrites the label set of each log entry passed to its receiver by applying one or more relabeling rules and forwards the results to the list of receivers in the component’s arguments.

If no labels remain after the relabeling rules are applied, then the log entries are dropped.

The most common use of loki.relabel is to filter log entries or standardize the label set that is passed to one or more downstream receivers. The rule blocks are applied to the label set of each log entry in order of their appearance in the configuration file. The configured rules can be retrieved by calling the function in the rules export field.

If you’re looking for a way to process the log entry contents, take a look at the loki.process component instead.

Multiple loki.relabel components can be specified by giving them different labels.

Usage

loki.relabel "LABEL" {
  forward_to = RECEIVER_LIST

  rule {
    ...
  }

  ...
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`forward_to`	`list(receiver)`	Where to forward log entries after relabeling.		yes
`max_cache_size`	`int`	The maximum number of elements to hold in the relabeling cache	10,000	no

Blocks

The following blocks are supported inside the definition of loki.relabel:

Hierarchy	Name	Description	Required
rule	rule	Relabeling rules to apply to received log entries.	no

rule block

The rule block contains the definition of any relabeling rules that can be applied to an input metric. If more than one rule block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a rule. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`source_labels`	`list(string)`	The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.		no
`separator`	`string`	The separator used to concatenate the values present in `source_labels`.	;	no
`regex`	`string`	A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions.	`(.*)`	no
`modulus`	`uint`	A positive integer used to calculate the modulus of the hashed source label values.		no
`target_label`	`string`	Label to which the resulting value will be written to.		no
`replacement`	`string`	The value against which a regex replace is performed, if the regex matches the extracted value. Supports previously captured groups.	$1	no
`action`	`string`	The relabeling action to perform.	replace	no

Here’s a list of the available actions, along with a brief description of their usage.

replace - Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
keep - Keeps metrics where regex matches the string extracted using the source_labels and separator.
drop - Drops metrics where regex matches the string extracted using the source_labels and separator.
hashmod - Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
labeldrop - Matches regex against all label names. Any labels that match are removed from the metric’s label set.
labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the metric’s label set.

Finally, note that the regex capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

Exported fields

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

Name	Type	Description
`receiver`	`receiver`	The input receiver where log lines are sent to be relabeled.
`rules`	`RelabelRules`	The currently configured relabeling rules.

Component health

loki.relabel is only reported as unhealthy if given an invalid configuration. In those cases, exported fields are kept at their last healthy values.

Debug information

loki.relabel does not expose any component-specific debug information.

Debug metrics

loki_relabel_entries_processed (counter): Total number of log entries processed.
loki_relabel_entries_written (counter): Total number of log entries forwarded.
loki_relabel_cache_misses (counter): Total number of cache misses.
loki_relabel_cache_hits (counter): Total number of cache hits.
loki_relabel_cache_size (gauge): Total size of relabel cache.

Example

The following example creates a loki.relabel component that only forwards entries whose ’level’ value is set to ’error'.

loki.relabel "keep_error_only" {
  forward_to = [loki.write.onprem.receiver]

  rule {
    action        = "keep"
    source_labels = ["level"]
    regex         = "error"
  }
}

loki.source.cloudflare

Sat, 11 Apr 2026 12:27:38 +0000

loki.source.cloudflare

loki.source.cloudflare pulls logs from the Cloudflare Logpull API and forwards them to other loki.* components.

These logs contain data related to the connecting client, the request path through the Cloudflare network, and the response from the origin web server and can be useful for enriching existing logs on an origin server.

Multiple loki.source.cloudflare components can be specified by giving them different labels.

Usage

loki.source.cloudflare "LABEL" {
  zone_id   = "ZONE_ID"
  api_token = "API_TOKEN"

  forward_to = RECEIVER_LIST
}

Arguments

loki.source.cloudflare supports the following arguments:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`api_token`	`string`	The API token to authenticate with.		yes
`zone_id`	`string`	The Cloudflare zone ID to use.		yes
`labels`	`map(string)`	The labels to associate with incoming log entries.	`{}`	no
`workers`	`int`	The number of workers to use for parsing logs.	`3`	no
`pull_range`	`duration`	The timeframe to fetch for each pull request.	`"1m"`	no
`fields_type`	`string`	The set of fields to fetch for log entries.	`"default"`	no

By default loki.source.cloudflare fetches logs with the default set of fields. Here are the different sets of fields_type available for selection, and the fields they include:

default includes:

"ClientIP", "ClientRequestHost", "ClientRequestMethod", "ClientRequestURI", "EdgeEndTimestamp", "EdgeResponseBytes", "EdgeRequestHost", "EdgeResponseStatus", "EdgeStartTimestamp", "RayID"

minimal includes all default fields and adds:

"ZoneID", "ClientSSLProtocol", "ClientRequestProtocol", "ClientRequestPath", "ClientRequestUserAgent", "ClientRequestReferer", "EdgeColoCode", "ClientCountry", "CacheCacheStatus", "CacheResponseStatus", "EdgeResponseContentType

extended includes all minimal fields and adds:

"ClientSSLCipher", "ClientASN", "ClientIPClass", "CacheResponseBytes", "EdgePathingOp", "EdgePathingSrc", "EdgePathingStatus", "ParentRayID", "WorkerCPUTime", "WorkerStatus", "WorkerSubrequest", "WorkerSubrequestCount", "OriginIP", "OriginResponseStatus", "OriginSSLProtocol", "OriginResponseHTTPExpires", "OriginResponseHTTPLastModified"

all includes all extended fields and adds:

 "BotScore", "BotScoreSrc", "ClientRequestBytes", "ClientSrcPort", "ClientXRequestedWith", "CacheTieredFill", "EdgeResponseCompressionRatio", "EdgeServerIP", "FirewallMatchesSources", "FirewallMatchesActions", "FirewallMatchesRuleIDs", "OriginResponseBytes", "OriginResponseTime", "ClientDeviceType", "WAFFlags", "WAFMatchedVar", "EdgeColoID", "RequestHeaders", "ResponseHeaders"`k

The component saves the last successfully-fetched timestamp in its positions file. If a position is found in the file for a given zone ID, the component restarts pulling logs from that timestamp. When no position is found, the component starts pulling logs from the current time.

Logs are fetched using multiple workers which request the last available pull_range repeatedly. It is possible to fall behind due to having too many log lines to process for each pull; adding more workers, decreasing the pull range, or decreasing the quantity of fields fetched can mitigate this performance issue.

The last timestamp fetched by the component is recorded in the loki_source_cloudflare_target_last_requested_end_timestamp debug metric.

All incoming Cloudflare log entries are in JSON format. You can make use of the loki.process component and a JSON procssing stage to extract more labels or change the log line format. A sample log looks like this:

{
	"CacheCacheStatus": "miss",
	"CacheResponseBytes": 8377,
	"CacheResponseStatus": 200,
	"CacheTieredFill": false,
	"ClientASN": 786,
	"ClientCountry": "gb",
	"ClientDeviceType": "desktop",
	"ClientIP": "100.100.5.5",
	"ClientIPClass": "noRecord",
	"ClientRequestBytes": 2691,
	"ClientRequestHost": "www.foo.com",
	"ClientRequestMethod": "GET",
	"ClientRequestPath": "/comments/foo/",
	"ClientRequestProtocol": "HTTP/1.0",
	"ClientRequestReferer": "https://www.foo.com/foo/168855/?offset=8625",
	"ClientRequestURI": "/foo/15248108/",
	"ClientRequestUserAgent": "some bot",
	"ClientSSLCipher": "ECDHE-ECDSA-AES128-GCM-SHA256",
	"ClientSSLProtocol": "TLSv1.2",
	"ClientSrcPort": 39816,
	"ClientXRequestedWith": "",
	"EdgeColoCode": "MAN",
	"EdgeColoID": 341,
	"EdgeEndTimestamp": 1637336610671000000,
	"EdgePathingOp": "wl",
	"EdgePathingSrc": "macro",
	"EdgePathingStatus": "nr",
	"EdgeRateLimitAction": "",
	"EdgeRateLimitID": 0,
	"EdgeRequestHost": "www.foo.com",
	"EdgeResponseBytes": 14878,
	"EdgeResponseCompressionRatio": 1,
	"EdgeResponseContentType": "text/html",
	"EdgeResponseStatus": 200,
	"EdgeServerIP": "8.8.8.8",
	"EdgeStartTimestamp": 1637336610517000000,
	"FirewallMatchesActions": [],
	"FirewallMatchesRuleIDs": [],
	"FirewallMatchesSources": [],
	"OriginIP": "8.8.8.8",
	"OriginResponseBytes": 0,
	"OriginResponseHTTPExpires": "",
	"OriginResponseHTTPLastModified": "",
	"OriginResponseStatus": 200,
	"OriginResponseTime": 123000000,
	"OriginSSLProtocol": "TLSv1.2",
	"ParentRayID": "00",
	"RayID": "6b0a...",
  "RequestHeaders": [],
  "ResponseHeaders": [
    "x-foo": "bar"
  ],
	"SecurityLevel": "med",
	"WAFAction": "unknown",
	"WAFFlags": "0",
	"WAFMatchedVar": "",
	"WAFProfile": "unknown",
	"WAFRuleID": "",
	"WAFRuleMessage": "",
	"WorkerCPUTime": 0,
	"WorkerStatus": "unknown",
	"WorkerSubrequest": false,
	"WorkerSubrequestCount": 0,
	"ZoneID": 1234
}

Exported fields

loki.source.cloudflare does not export any fields.

Component health

loki.source.cloudflare is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.cloudflare exposes the following debug information:

Whether the target is ready and reading logs from the API.
The Cloudflare zone ID.
The last error reported, if any.
The stored positions file entry, as the combination of zone_id, labels and last fetched timestamp.
The last timestamp fetched.
The set of fields being fetched.

Debug metrics

loki_source_cloudflare_target_entries_total (counter): Total number of successful entries sent via the cloudflare target.
loki_source_cloudflare_target_last_requested_end_timestamp (gauge): The last cloudflare request end timestamp fetched, for calculating how far behind the target is.

Example

This example pulls logs from Cloudflare’s API and forwards them to a loki.write component.

loki.source.cloudflare "dev" {
  zone_id   = env("CF_ZONE_ID")
  api_token = local.file.api.content

  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

loki.source.file

Sat, 11 Apr 2026 12:27:38 +0000

loki.source.file

loki.source.file reads log entries from files and forwards them to other loki.* components.

Multiple loki.source.file components can be specified by giving them different labels.

Usage

loki.source.file "LABEL" {
  targets    = TARGET_LIST
  forward_to = RECEIVER_LIST
}

Arguments

The component starts a new reader for each of the given targets and fans out log entries to the list of receivers passed in forward_to.

loki.source.file supports the following arguments:

Name	Type	Description	Default	Required
`targets`	`list(map(string))`	List of files to read from.		yes
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes

Blocks

The loki.source.file component doesn’t support any inner blocks and is configured fully through arguments.

Exported fields

loki.source.file does not export any fields.

Component health

loki.source.file is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.file exposes some target-level debug information per reader:

The tailed path.
Whether the reader is currently running.
What is the last recorded read offset in the positions file.

Debug metrics

loki_source_file_read_bytes_total (gauge): Number of bytes read.
loki_source_file_file_bytes_total (gauge): Number of bytes total.
loki_source_file_read_lines_total (counter): Number of lines read.
loki_source_file_encoding_failures_total (counter): Number of encoding failures.
loki_source_file_files_active_total (gauge): Number of active files.

Component behavior

Each element in the list of targets as a set of key-value pairs called labels. The set of targets can either be static, or dynamically provided periodically by a service discovery component. The special label __path__ must always be present and must point to the absolute path of the file to read from.

The __path__ value is available as the filename label to each log entry the component reads. All other labels starting with a double underscore are considered internal and are removed from the log entries before they’re passed to other loki.* components.

The component uses its data path (a directory named after the domain’s fully qualified name) to store its positions file. The positions file is used to store read offsets, so that in case of a component or Agent restart, loki.source.file can pick up tailing from the same spot.

If a file is removed from the targets list, its positions file entry is also removed. When it’s added back on, loki.source.file starts reading it from the beginning.

Example

This example collects log entries from the files specified in the targets argument and forwards them to a loki.write component so they are can be written to Loki.

loki.source.file "tmpfiles" {
  targets    = [
    {__path__ = "/tmp/foo.txt", "color" = "pink"},
    {__path__ = "/tmp/bar.txt", "color" = "blue"},
    {__path__ = "/tmp/baz.txt", "color" = "grey"},
  ] 
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

loki.source.gcplog

Sat, 11 Apr 2026 12:27:38 +0000

loki.source.gcplog

loki.source.gcplog retrieves logs from cloud resources such as GCS buckets, load balancers, or Kubernetes clusters running on GCP by making use of Pub/Sub subscriptions.

The component uses either the ‘push’ or ‘pull’ strategy to retrieve log entries and forward them to the list of receivers in forward_to.

Multiple loki.source.gcplog components can be specified by giving them different labels.

Usage

loki.source.gcplog "LABEL" {
  pull {
    project_id   = "PROJECT_ID"
    subscription = "SUB_ID"
  }

  forward_to = RECEIVER_LIST
}

Arguments

loki.source.gcplog supports the following arguments:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	“{}”	no

Blocks

The following blocks are supported inside the definition of loki.source.gcplog:

Hierarchy	Name	Description	Required
pull	pull	Configures a target to pull logs from a GCP Pub/Sub subscription.	no
push	push	Configures a server to receive logs as GCP Pub/Sub push requests.	no

The pull and push inner blocks are mutually exclusive; a component must contain exactly one of the two in its definition.

pull block

The pull block defines which GCP project ID and subscription to read log entries from.

The following arguments can be used to configure the pull block. Any omitted fields take their default values.

Name	Type	Description	Default	Required
`project_id`	`string`	The GCP project id the subscription belongs to.		yes
`subscription`	`string`	The subscription to pull logs from.		yes
`labels`	`map(string)`	Additional labels to associate with incoming logs.	`"{}"`	no
`use_incoming_timestamp`	`bool`	Whether to use the incoming log timestamp.	`false`	no

To make use of the pull strategy, the GCP project must have been configured to forward its cloud resource logs onto a Pub/Sub topic for loki.source.gcplog to consume.

Typically, the host system also needs to have its GCP credentials configured. One way to do it is to point the GOOGLE_APPLICATION_CREDENTIALS environment variable to the location of a credential configuration JSON file or a service account key.

push block

The push block defines the configuration of the HTTP server that receives push requests from GCP’s Pub/Sub servers.

The following arguments can be used to configure the push block. Any omitted fields take their default values.

Name	Type	Description	Default	Required
`http_listen_address`	`string`	The address the server listens to.	`"0.0.0.0"`	no
`http_listen_port`	`int`	The port the server listens to.	`8080`	no
`push_timeout`	`duration`	Sets a maximum processing time for each incoming GCP log entry.	`"0s"`	no
`labels`	`map(string)`	Additional labels to associate with incoming entries.	`"{}"`	no
`use_incoming_timestamp`	`bool`	Whether to use the incoming entry timestamp.	`false`	no

The server listens for POST requests from GCP’s Push subscriptions on HOST:PORT/gcp/api/v1/push.

By default, for both strategies the component assigns the log entry timestamp as the time it was processed, except if use_incoming_timestamp is set to true.

The labels map is applied to every entry that passes through the component.

Exported fields

loki.source.gcplog does not export any fields.

Component health

loki.source.gcplog is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.gcplog exposes some debug information per gcplog listener:

The configured strategy.
Their label set.
When using a push strategy, the listen address.

Debug metrics

When using the pull strategy, the component exposes the following debug metrics:

loki_source_gcplog_pull_entries_total (counter): Number of entries received by the gcplog target.
loki_source_gcplog_pull_parsing_errors_total (counter): Total number of parsing errors while receiving gcplog messages.
loki_source_gcplog_pull_last_success_scrape (gauge): Timestamp of target’s last successful poll.

When using the push strategy, the component exposes the following debug metrics:

loki_source_gcplog_push_entries_total (counter): Number of entries received by the gcplog target.
loki_source_gcplog_push_entries_total (counter): Number of parsing errors while receiving gcplog messages.

Example

This example listens for GCP Pub/Sub PushRequests on 0.0.0.0:8080 and forwards them to a loki.write component.

loki.source.gcplog "local" {
  push {}

  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

loki.source.gelf

Sat, 11 Apr 2026 12:27:38 +0000

loki.source.gelf

loki.source.gelf reads Graylog Extended Long Format (GELF) logs from a UDP listener and forwards them to other loki.* components.

Multiple loki.source.gelf components can be specified by giving them different labels and ports.

Usage

loki.source.gelf "LABEL" {
  forward_to    = RECEIVER_LIST
}

Arguments

The component starts a new UDP listener and fans out log entries to the list of receivers passed in forward_to.

loki.source.gelf supports the following arguments:

Name	Type	Description	Default	Required
`listen_address`	`string`	UDP address and port to listen for Graylog messages.	`0.0.0.0:12201`	no
`use_incoming_timestamp`	`bool`	When false, assigns the current timestamp to the log when it was processed	`false`	no
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	“{}”	no

NOTE: GELF logs can be sent uncompressed or compressed with GZIP or ZLIB. A job label is added with the full name of the component loki.source.gelf.LABEL.

Incoming messages have the following labels available:

__gelf_message_level: The GELF level as a string.
__gelf_message_host: The host sending the GELF message.
__gelf_message_host: The GELF level message version sent by the client.
__gelf_message_facility: The GELF facility.

These labels are stripped unless relabeling is used to retain the labels with a loki.relabel component and its Rules export as the relabel_rules argument. An example rule is presented below.

rule {
		action      = "labelmap"
		regex       = "__gelf_(.*)"
		replacement = "gelf_${1}"
	}

Component health

loki.source.gelf is only reported as unhealthy if given an invalid configuration.

Debug Metrics

gelf_target_entries_total (counter): Total number of successful entries sent to the GELF target.
gelf_target_parsing_errors_total (counter): Total number of parsing errors while receiving GELF messages.

Example

loki.source.gelf "listen"  {
    forward_to = [loki.write.endpoint.receiver]
}

loki.write "endpoint" {
    endpoint {
        url ="loki:3100/api/v1/push"
    }  
}

loki.source.heroku

Sat, 11 Apr 2026 12:27:38 +0000

loki.source.heroku

loki.source.heroku listens for Heroku messages over TCP connections and forwards them to other loki.* components.

The component starts a new heroku listener for the given listener block and fans out incoming entries to the list of receivers in forward_to.

Before using loki.source.heroku, Heroku should be configured with the URL where the Agent will be listening. Follow the steps in Heroku HTTPS Drain docs for using the Heroku CLI with a command like the following:

heroku drains:add [http|https]://HOSTNAME:PORT/heroku/api/v1/drain -a HEROKU_APP_NAME

Multiple loki.source.heroku components can be specified by giving them different labels.

Usage

loki.source.heroku "LABEL" {
    listener {
        address = "LISTEN_ADDRESS"
        port    = PORT
    }
    forward_to = RECEIVER_LIST
}

Arguments

loki.source.heroku supports the following arguments:

Name	Type	Description	Default	Required
`use_incoming_timestamp`	`bool`	Whether or not to use the timestamp received from Heroku.	`false`	no
`labels`	`map(string)`	The labels to associate with each received Heroku record.	`{}`	no
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	`{}`	no

The relabel_rules field can make use of the rules export value from a loki.relabel component to apply one or more relabeling rules to log entries before they’re forwarded to the list of receivers in forward_to.

Blocks

The following blocks are supported inside the definition of loki.source.heroku:

Hierarchy	Name	Description	Required
listener	listener	Configures a listener for Heroku messages.	yes

listener block

The listener block defines the listen address and port where the listener expects Heroku messages to be sent to.

Name	Type	Description	Default	Required
`address`	`string`	The `<host>` address to listen to for heroku messages.	`0.0.0.0`	no
`port`	`int`	The `<port>` to listen to for heroku messages.		yes

Labels

The labels map is applied to every message that the component reads.

The following internal labels all prefixed with __ are available but will be discarded if not relabeled:

__heroku_drain_host
__heroku_drain_app
__heroku_drain_proc
__heroku_drain_log_id

All url query params will be translated to __heroku_drain_param_<name>

If the X-Scope-OrgID header is set it will be translated to __tenant_id__

Exported fields

loki.source.heroku does not export any fields.

Component health

loki.source.heroku is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.heroku exposes some debug information per Heroku listener:

Whether the listener is currently running.
The listen address.

Debug metrics

loki_source_heroku_drain_entries_total (counter): Number of successful entries received by the Heroku target.
loki_source_heroku_drain_parsing_errors_total (counter): Number of parsing errors while receiving Heroku messages.

Example

This example listens for Heroku messages over TCP in the specified port and forwards them to a loki.write component using the Heroku timestamp.

loki.source.heroku "local" {
    listener {
        address = "0.0.0.0"
        port    = 8080
    }
    use_incoming_timestamp = true
    labels                 = {component = "loki.source.heroku"}
    forward_to             = [loki.write.local.receiver]
}

loki.write "local" {
    endpoint {
        url = "loki:3100/api/v1/push"
    }
}

loki.source.journal

Sat, 11 Apr 2026 12:27:38 +0000

loki.source.journal

loki.source.journal reads from the systemd journal and forwards them to other loki.* components.

Multiple loki.source.journal components can be specified by giving them different labels.

Usage

loki.source.journal "LABEL" {
  forward_to    = RECEIVER_LIST
}

Arguments

The component starts a new journal reader and fans out log entries to the list of receivers passed in forward_to.

loki.source.journal supports the following arguments:

Name	Type	Description	Default	Required
`format_as_json`	`bool`	When true, log messages from the journal are passed through the pipeline as a JSON message with all of the journal entries’ original fields. When false, the log message is the text content of the MESSAGE field from the journal entry.	`false`	no
`max_age`	`duration`	The oldest relative time from process start that will be read	`"7h"`	no
`path`	`string`	Path to a directory to read entries from. Defaults to system paths (/var/log/journal and /run/log/journal) when empty.	`""`	no
`matches`	`string`	Journal matches to filter. Character (+) is not supported, only logical AND matches will be added.	`""`	no
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes

NOTE: A job label is added with the full name of the component loki.source.journal.LABEL.

Blocks

The following blocks are supported inside the definition of loki.source.journal:

Hierarchy	Name	Description	Required
relabel_rules	relabel_rules	Relabeling rules to apply to received log entries.	no

relabel_rules block

The rule block contains the definition of any relabeling rules that can be applied to an input metric. If more than one rule block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a rule. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`source_labels`	`list(string)`	The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.		no
`separator`	`string`	The separator used to concatenate the values present in `source_labels`.	;	no
`regex`	`string`	A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions.	`(.*)`	no
`modulus`	`uint`	A positive integer used to calculate the modulus of the hashed source label values.		no
`target_label`	`string`	Label to which the resulting value will be written to.		no
`replacement`	`string`	The value against which a regex replace is performed, if the regex matches the extracted value. Supports previously captured groups.	$1	no
`action`	`string`	The relabeling action to perform.	replace	no

Here’s a list of the available actions, along with a brief description of their usage.

replace - Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
keep - Keeps metrics where regex matches the string extracted using the source_labels and separator.
drop - Drops metrics where regex matches the string extracted using the source_labels and separator.
hashmod - Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
labeldrop - Matches regex against all label names. Any labels that match are removed from the metric’s label set.
labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the metric’s label set.

Finally, note that the regex capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

Incoming messages have labels from the journal following the patten __journal_FIELDNAME

These labels are stripped unless a rule is created to retain the labels. An example rule is below.

rule {
		action      = "labelmap"
		regex       = "__journal_(.*)"
		replacement = "journal_${1}"
	}

Component health

loki.source.journal is only reported as unhealthy if given an invalid configuration.

Debug Metrics

agent_loki_source_journal_target_parsing_errors_total (counter): Total number of parsing errors while reading journal messages.
agent_loki_source_journal_target_lines_total (counter): Total number of successful journal lines read.

Example

loki.source.journal "read"  {
    forward_to = [loki.write.endpoint.receiver]
}

loki.write "endpoint" {
    endpoint {
        url ="loki:3100/api/v1/push"
    }  
}

loki.source.kubernetes

Sat, 11 Apr 2026 12:27:38 +0000

loki.source.kubernetes

loki.source.kubernetes tails logs from Kubernetes containers using the Kubernetes API. It has the following benefits over loki.source.file:

It works without a privileged container.
It works without a root user.
It works without needing access to the filesystem of the Kubernetes node.
It doesn’t require a DaemonSet to collect logs, so one agent could collect logs for the whole cluster.

NOTE: Because loki.source.kubernetes uses the Kubernetes API to tail logs, it uses more network traffic and CPU consumption of Kubelets than loki.source.file.

Multiple loki.source.kubernetes components can be specified by giving them different labels.

Usage

loki.source.kubernetes "LABEL" {
  targets    = TARGET_LIST
  forward_to = RECEIVER_LIST
}

Arguments

The component starts a new reader for each of the given targets and fans out log entries to the list of receivers passed in forward_to.

loki.source.kubernetes supports the following arguments:

Name	Type	Description	Default	Required
`targets`	`list(map(string))`	List of files to read from.		yes
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes

Each target in targets must have the following labels:

__meta_kubernetes_namespace or __pod_namespace__ to specify the namespace of the pod to tail.
__meta_kubernetes_pod_name or __pod_name__ to specify the name of the pod to tail.
__meta_kubernetes_pod_container_name or __pod_container_name__ to specify the container within the pod to tail.
__meta_kubernetes_pod_uid or __pod_uid__ to specify the UID of the pod to tail.

By default, all of these labels are present when the output discovery.kubernetes is used.

A log tailer is started for each unique target in targets. Log tailers will reconnect with exponential backoff to Kubernetes if the log stream returns before the container has permanently terminated.

Blocks

The following blocks are supported inside the definition of loki.source.kubernetes:

Hierarchy	Block	Description	Required
client	client	Configures Kubernetes client used to tail logs.	no
client > http_client_config	http_client_config	HTTP client configuration for Kubernetes requests.	no

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

client block

The client block configures the Kubernetes client used to tail logs from containers. If the client block isn’t provided, the default in-cluster configuration with the service account of the running Grafana Agent pod is used.

The following arguments are supported:

Name	Type	Description	Default	Required
`api_server`	`string`	URL of the Kubernetes API server.		no
`kubeconfig_file`	`string`	Path of the `kubeconfig` file to use for connecting to Kubernetes.		no

http_client_config block

The http_client_config block configures settings used to connect to the Kubernetes API server.

Name	Type	Description	Default	Required
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`enable_http_2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

Exported fields

loki.source.kubernetes does not export any fields.

Component health

loki.source.kubernetes is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.kubernetes exposes some target-level debug information per target:

The labels associated with the target.
The full set of labels which were found during service discovery.
The most recent time a log line was read and forwarded to the next components in the pipeline.
The most recent error from tailing, if any.

Debug metrics

loki.source.kubernetes does not expose any component-specific debug metrics.

Example

This example collects logs from all Kubernetes pods and forwards them to a loki.write component so they are can be written to Loki.

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

loki.source.kubernetes "pods" {
  targets    = discovery.kubernetes.pods.targets
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = env("LOKI_URL")
  }
}

loki.source.podlogs

Sat, 11 Apr 2026 12:27:38 +0000

loki.source.podlogs

loki.source.podlogs discovers PodLogs resources on Kubernetes and, using the Kubernetes API, tails logs from Kubernetes containers of Pods specified by the discovered them.

loki.source.podlogs is similar to loki.source.kubernetes, but uses custom resources rather than being fed targets from another Flow component.

NOTE: Unlike loki.source.kubernetes, it is not possible to distribute responsibility of collecting logs across multiple agents. To avoid collecting duplicate logs, only one agent should be running a loki.source.podlogs component.

NOTE: Because loki.source.podlogs uses the Kubernetes API to tail logs, it uses more network traffic and CPU consumption of Kubelets than loki.source.file.

Multiple loki.source.podlogs components can be specified by giving them different labels.

Usage

loki.source.podlogs "LABEL" {
  forward_to = RECEIVER_LIST
}

Arguments

The component starts a new reader for each of the given targets and fans out log entries to the list of receivers passed in forward_to.

loki.source.podlogs supports the following arguments:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes

loki.source.podlogs searches for PodLogs resources on Kubernetes. Each PodLogs resource describes a set of pods to tail logs from.

PodLogs custom resource

The PodLogs resource describes a set of Pods to collect logs from.

NOTE: loki.source.podlogs looks for PodLogs of monitoring.grafana.com/v1alpha2, and is not compatible with PodLogs from the Grafana Agent Operator, which are version v1alpha1.

Field	Type	Description
`apiVersion`	string	`monitoring.grafana.com/v1alpha2`
`kind`	string	`PodLogs`
`metadata`	ObjectMeta	Metadata for the PodLogs.
`spec`	PodLogsSpec	Definition of what Pods to collect logs from.

PodLogsSpec

PodLogsSpec describes a set of Pods to collect logs from.

Field	Type	Description
`selector`	LabelSelector	Label selector of Pods to collect logs from.
`namespaceSelector`	LabelSelector	Label selector of Namespaces that Pods can be discovered in.
`relabelings`	RelabelConfig	Relabel rules to apply to discovered Pods.

If selector is left as the default value, all Pods are discovered. If namespaceSelector is left as the default value, all Namespaces are used for Pod discovery.

The relabelings field can be used to modify labels from discovered Pods. The following meta labels are available for relabeling:

__meta_kubernetes_namespace: The namespace of the Pod.
__meta_kubernetes_pod_name: The name of the Pod.
__meta_kubernetes_pod_ip: The pod IP of the Pod.
__meta_kubernetes_pod_label_<labelname>: Each label from the Pod.
__meta_kubernetes_pod_labelpresent_<labelname>: true for each label from the Pod.
__meta_kubernetes_pod_annotation_<annotationname>: Each annotation from the Pod.
__meta_kubernetes_pod_annotationpresent_<annotationname>: true for each annotation from the Pod.
__meta_kubernetes_pod_container_init: true if the container is an InitContainer.
__meta_kubernetes_pod_container_name: Name of the container.
__meta_kubernetes_pod_container_image: The image the container is using.
__meta_kubernetes_pod_ready: Set to true or false for the Pod’s ready state.
__meta_kubernetes_pod_phase: Set to Pending, Running, Succeeded, Failed or Unknown in the lifecycle.
__meta_kubernetes_pod_node_name: The name of the node the pod is scheduled onto.
__meta_kubernetes_pod_host_ip: The current host IP of the pod object.
__meta_kubernetes_pod_uid: The UID of the Pod.
__meta_kubernetes_pod_controller_kind: Object kind of the Pod’s controller.
__meta_kubernetes_pod_controller_name: Name of the Pod’s controller.

In addition to the meta labels, the following labels are exposed to tell loki.source.podlogs which container to tail:

__pod_namespace__: The namespace of the Pod.
__pod_name__: The name of the Pod.
__pod_container_name__: The container name within the Pod.
__pod_uid__: The UID of the Pod.

Blocks

The following blocks are supported inside the definition of loki.source.podlogs:

Hierarchy	Block	Description	Required
client	client	Configures Kubernetes client used to tail logs.	no
client > http_client_config	http_client_config	HTTP client configuration for Kubernetes requests.	no
selector	selector	Label selector for which `PodLogs` to discover.	no
selector > match_expression	match_expression	Label selector expression for which `PodLogs` to discover.	no
namespace_selector	selector	Label selector for which namespaces to discover `PodLogs` in.	no
namespace_selector > match_expression	match_expression	Label selector expression for which namespaces to discover `PodLogs` in.	no

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

client block

The following arguments are supported:

Name	Type	Description	Default	Required
`api_server`	`string`	URL of the Kubernetes API server.		no
`kubeconfig_file`	`string`	Path of the `kubeconfig` file to use for connecting to Kubernetes.		no

http_client_config block

The http_client_config block configures settings used to connect to the Kubernetes API server.

Name	Type	Description	Default	Required
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`enable_http_2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

selector block

The selector block describes a Kubernetes label selector for PodLogs or Namespace discovery.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_labels`	`map(string)`	Label keys and values used to discover resources.	`{}`	no

When the match_labels argument is empty, all resources will be matched.

match_expression block

The match_expression block describes a Kubernetes label match expression for PodLogs or Namespace discovery.

The following arguments are supported:

Name	Type	Description	Required
`key`	`string`	The label name to match against.	yes
`operator`	`string`	The operator to use when matching.	yes
`values`	`list(string)`	The values used when matching.	no

The operator argument must be one of the following strings:

"In"
"NotIn"
"Exists"
"DoesNotExist"

Both selector and namespace_selector can make use of multiple match_expression inner blocks which are treated as AND clauses.

Exported fields

loki.source.podlogs does not export any fields.

Component health

loki.source.podlogs is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.podlogs exposes some target-level debug information per target:

The labels associated with the target.
The full set of labels which were found during service discovery.
The most recent time a log line was read and forwarded to the next components in the pipeline.
The most recent error from tailing, if any.

Debug metrics

loki.source.podlogs does not expose any component-specific debug metrics.

Example

This example discovers all PodLogs resources and forwards collected logs to a loki.write component so they are can be written to Loki.

loki.source.podlogs "default" {
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = env("LOKI_URL")
  }
}

loki.source.syslog

Sat, 11 Apr 2026 12:27:38 +0000

loki.source.syslog

loki.source.syslog listens for syslog messages over TCP or UDP connections and forwards them to other loki.* components. The messages must be compliant with the RFC5424 format.

The component starts a new syslog listener for each of the given config blocks and fans out incoming entries to the list of receivers in forward_to.

Multiple loki.source.syslog components can be specified by giving them different labels.

Usage

loki.source.syslog "LABEL" {
  listener {
    address = "LISTEN_ADDRESS"
  }
  ...

  forward_to = RECEIVER_LIST
}

Arguments

loki.source.syslog supports the following arguments:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	“{}”	no

Blocks

The following blocks are supported inside the definition of loki.source.syslog:

Hierarchy	Name	Description	Required
listener	listener	Configures a listener for IETF Syslog (RFC5424) messages.	no
listener > tls_config	tls_config	Configures TLS settings for connecting to the endpoint for TCP connections.	no

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

listener block

The listener block defines the listen address and protocol where the listener expects syslog messages to be sent to, as well as its behavior when receiving messages.

The following arguments can be used to configure a listener. Only the address field is required and any omitted fields take their default values.

Name	Type	Description	Default	Required
`address`	`string`	The `<host:port>` address to listen to for syslog messages.		yes
`protocol`	`string`	The protocol to listen to for syslog messages. Must be either `tcp` or `udp`.	`tcp`	no
`idle_timeout`	`duration`	The idle timeout for tcp connections.	`"120s"`	no
`label_structured_data`	`bool`	Whether to translate syslog structured data to loki labels.	`false`	no
`labels`	`map(string)`	The labels to associate with each received syslog record.	`{}`	no
`use_incoming_timestamp`	`bool`	Whether to set the timestamp to the incoming syslog record timestamp.	`false`	no
`use_rfc5424_message`	`bool`	Whether to forward the full RFC5424-formatted syslog message.	`false`	no
`max_message_length`	`int`	The maximum limit to the length of syslog messages.	`8192`	no

By default, the component assigns the log entry timestamp as the time it was processed.

The labels map is applied to every message that the component reads.

All header fields from the parsed RFC5424 messages are brought in as internal labels, prefixed with __syslog_.

If label_structured_data is set, structured data in the syslog header is also translated to internal labels in the form of __syslog_message_sd_<ID>_<KEY>. For example, a structured data entry of [example@99999 test="yes"] becomes the label __syslog_message_sd_example_99999_test with the value "yes".

tls_config block

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

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

Exported fields

loki.source.syslog does not export any fields.

Component health

loki.source.syslog is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.syslog exposes some debug information per syslog listener:

Whether the listener is currently running.
The listen address.
The labels that the listener applies to incoming log entries.

Debug metrics

loki_source_syslog_entries_total (counter): Total number of successful entries sent to the syslog component.
loki_source_syslog_parsing_errors_total (counter): Total number of parsing errors while receiving syslog messages.
loki_source_syslog_empty_messages_total (counter): Total number of empty messages received from the syslog component.

Example

This example listens for Syslog messages in valid RFC5424 format over TCP and UDP in the specified ports and forwards them to a loki.write component.

loki.source.syslog "local" {
  listener {
    address  = "127.0.0.1:51893"
    labels   = { component = "loki.source.syslog", protocol = "tcp" } 
  }

  listener {
    address  = "127.0.0.1:51898"
    protocol = "udp"
    labels   = { component = "loki.source.syslog", protocol = "udp"} 
  }

  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

loki.source.windowsevent

Sat, 11 Apr 2026 12:27:38 +0000

loki.source.windowsevent

loki.source.windowsevent reads events from Windows Event Logs and forwards them to other loki.* components.

Multiple loki.source.windowsevent components can be specified by giving them different labels.

Usage

loki.source.windowsevent "LABEL" {
  eventlog_name = EVENTLOG_NAME
  forward_to    = RECEIVER_LIST
}

Arguments

The component starts a new reader and fans out log entries to the list of receivers passed in forward_to.

loki.source.windowsevent supports the following arguments:

Name	Type	Description	Default	Required
`locale`	`number`	Locale ID for event rendering. 0 default is Windows Locale.	`0`	no
`eventlog_name`	`string`	Event log to read from.		See below.
`xpath_query`	`string`	Event log to read from.	`"*"`	See below.
`bookmark_path`	`string`	Keeps position in event log.	`"DATA_PATH/bookmark.xml"`	no
`poll_interval`	`duration`	How often to poll the event log.	`"3s"`	no
`exclude_event_data`	`bool`	Exclude event data.	`false`	no
`exclude_user_data`	`bool`	Exclude user data.	`false`	no
`user_incoming_timestamp`	`bool`	When false, assigns the current timestamp to the log when it was processed.	`false`	no
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes

NOTE: eventlog_name is required if xpath_query does not specify the event log. You can define xpath_query in short or xml form. When using the XML form you can specify event_log in the xpath_query. If using short form, you must define eventlog_name.

Component health

loki.source.windowsevent is only reported as unhealthy if given an invalid configuration.

Example

This example collects log entries from the Event Log specified in eventlog_name and forwards them to a loki.write component so they are can be written to Loki.

loki.source.windowsevent "application"  {
    eventlog_name = "Application"
    forward_to = [loki.write.endpoint.receiver]
}

loki.write "endpoint" {
    endpoint {
        url ="loki:3100/api/v1/push"
    }  
}

loki.write

Sat, 11 Apr 2026 12:27:38 +0000

loki.write

loki.write receives log entries from other loki components and sends them over the network using Loki’s logproto format.

Multiple loki.write components can be specified by giving them different labels.

Usage

loki.write "LABEL" {
  endpoint {
    url = REMOTE_WRITE_URL
  }
}

Arguments

loki.write supports the following arguments:

Name	Type	Description	Default	Required
`max_streams`	`int`	Time to wait before marking a request as failed.	`"5s"`	no
`external_labels`	`map(string)`	Labels to add to logs sent over the network.		no

Blocks

The following blocks are supported inside the definition of loki.write:

Hierarchy	Block	Description	Required
endpoint	endpoint	Location to send logs to.	no
endpoint > http_client_config	http_client_config	HTTP client settings when connecting to the endpoint.	no
endpoint > http_client_config > basic_auth	basic_auth	Configure basic_auth for authenticating to the endpoint.	no
endpoint > http_client_config > authorization	authorization	Configure generic authorization to the endpoint.	no
endpoint > http_client_config > oauth2	oauth2	Configure OAuth2 for authenticating to the endpoint.	no
endpoint > http_client_config > oauth2 > tls_config	tls_config	Configure TLS settings for connecting to the endpoint.	no
endpoint > http_client_config > tls_config	tls_config	Configure TLS settings for connecting to the endpoint.	no

The > symbol indicates deeper levels of nesting. For example, endpoint > http_client_config refers to an http_client_config block defined inside an endpoint block.

endpoint block

The endpoint block describes a single location to send logs to. Multiple endpoint blocks can be provided to send logs to multiple locations.

The following arguments are supported:

Name	Type	Description	Default	Required
`url`	`string`	Full URL to send logs to.		yes
`name`	`string`	Optional name to identify this endpoint with.		no
`batch_wait`	`bool`	Maximum amount of time to wait before sending a batch.	`"1s"`	no
`batch_size`	`string`	Maximum batch size of logs to accumulate before sending.	`"1MiB"`	no
`remote_timeout`	`duration`	Timeout for requests made to the URL.	`"10s"`	no
`tenant_id`	`string`	The tenant ID used by default to push logs.		no
`min_backoff_period`	`duration`	Initial backoff time between retries.	`"500ms"`	no
`max_backoff_period`	`duration`	Maximum backoff time between retries.	`"5m"`	no
`max_backoff_retries`	`int`	Maximum number of retries.	10	no

If no tenant_id is provided, the component assumes that the Loki instance at endpoint is running in single-tenant mode and no X-Scope-OrgID header is sent.

When multiple endpoint blocks are provided, the loki.write component creates a client for each. Received log entries are fanned-out to these clients in succession. That means that if one client is bottlenecked, it may impact the rest.

Endpoints can be named for easier identification in debug metrics by using the name argument. If the name argument isn’t provided, a name is generated based on a hash of the endpoint settings.

http_client_config block

The http_client_config configures settings used to connect to the Loki API.

Name	Type	Description	Default	Required
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`enable_http_2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

basic_auth block

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

password and password_file are mututally exclusive and only one can be provided inside of a basic_auth block.

authorization block

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

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

oauth2 block

Name	Type	Description	Required
`client_id`	`string`	OAuth2 client ID.	no
`client_secret`	`secret`	OAuth2 client secret.	no
`client_secret_file`	`string`	File containing the OAuth2 client secret.	no
`scopes`	`list(string)`	List of scopes to authenticate with.	no
`token_url`	`string`	URL to fetch the token from.	no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.	no
`proxy_url`	`string`	Optional proxy URL for OAuth2 requests.	no

client_secret and client_secret_file are mututally exclusive and only one can be provided inside of an oauth2 block.

The oauth2 block may also contain its own separate tls_config sub-block.

tls_config block

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

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

Exported fields

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

Name	Type	Description
`receiver`	`LogsReceiver`	A value that other components can use to send log entries to.

Component health

loki.write is only reported as unhealthy if given an invalid configuration.

Debug information

loki.write does not expose any component-specific debug information.

Debug metrics

loki_write_encoded_bytes_total (counter): Number of bytes encoded and ready to send.
loki_write_sent_bytes_total (counter): Number of bytes sent.
loki_write_dropped_bytes_total (counter): Number of bytes dropped because failed to be sent to the ingester after all retries.
loki_write_sent_entries_total (counter): Number of log entries sent to the ingester.
loki_write_dropped_entries_total (counter): Number of log entries dropped because they failed to be sent to the ingester after all retries.
loki_write_request_duration_seconds (histogram): Duration of sent requests.
loki_write_batch_retries_total (counter): Number of times batches have had to be retried.
loki_write_stream_lag_seconds (gauge): Difference between current time and last batch timestamp for successful sends.

Example

This example creates a loki.write component that sends received entries to a local Loki instance:

loki.write "local" {
    endpoint {
        url = "loki:3100"
    }
}

mimir.rules.kubernetes

Sat, 11 Apr 2026 12:27:38 +0000

mimir.rules.kubernetes

mimir.rules.kubernetes discovers PrometheusRule Kubernetes resources and loads them into a Mimir instance.

Multiple mimir.rules.kubernetes components can be specified by giving them different labels.
Kubernetes label selectors can be used to limit the Namespace and PrometheusRule resources considered during reconciliation.
Compatible with the Ruler APIs of Grafana Mimir, Grafana Cloud, and Grafana Enterprise Metrics.
Compatible with the PrometheusRule CRD from the prometheus-operator.

Usage

mimir.rules.kubernetes "LABEL" {
  address = MIMIR_RULER_URL
}

Arguments

mimir.rules.kubernetes supports the following arguments:

Name	Type	Description	Default	Required
`address`	`string`	URL of the Mimir ruler.		yes
`tenant_id`	`string`	Mimir tenant ID.		no
`use_legacy_routes`	`bool`	Whether to use deprecated ruler API endpoints.	false	no
`sync_interval`	`duration`	Amount of time between reconciliations with Mimir.	“30s”	no
`mimir_namespace_prefix`	`string`	Prefix used to differentiate multiple agent deployments.	“agent”	no

If no tenant_id is provided, the component assumes that the Mimir instance at address is running in single-tenant mode and no X-Scope-OrgID header is sent.

The sync_interval argument determines how often Mimir’s ruler API is accessed to reload the current state of rules. Interaction with the Kubernetes API works differently. Updates are processed as events from the Kubernetes API server according to the informer pattern.

The mimir_namespace_prefix argument can be used to separate the rules managed by multiple agent deployments across your infrastructure. It should be set to a unique value for each deployment.

Blocks

The following blocks are supported inside the definition of mimir.rules.kubernetes:

Hierarchy	Block	Description	Required
rule_namespace_selector	label_selector	Label selector for `Namespace` resources.	no
rule_namespace_selector > match_expression	match_expression	Label match expression for `Namespace` resources.	no
rule_selector	label_selector	Label selector for `PrometheusRule` resources.	no
rule_selector > match_expression	match_expression	Label match expression for `PrometheusRule` resources.	no
http_client_config	http_client_config	HTTP client settings when connecting to the endpoint.	no
http_client_config > basic_auth	basic_auth	Configure basic_auth for authenticating to the endpoint.	no
http_client_config > authorization	authorization	Configure generic authorization to the endpoint.	no
http_client_config > oauth2	oauth2	Configure OAuth2 for authenticating to the endpoint.	no
http_client_config > oauth2 > tls_config	tls_config	Configure TLS settings for connecting to the endpoint.	no
http_client_config > tls_config	tls_config	Configure TLS settings for connecting to the endpoint.	no

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

label_selector block

The label_selector block describes a Kubernetes label selector for rule or namespace discovery.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_labels`	`map(string)`	Label keys and values used to discover resources.	`{}`	yes

When the match_labels argument is empty, all resources will be matched.

match_expression block

The match_expression block describes a Kubernetes label match expression for rule or namespace discovery.

The following arguments are supported:

Name	Type	Description	Required
`key`	`string`	The label name to match against.	yes
`operator`	`string`	The operator to use when matching.	yes
`values`	`[]string`	The values used when matching.	no

The operator argument should be one of the following strings:

"in"
"notin"
"exists"

http_client_config block

The http_client_config configures settings used to connect to the Mimir API.

Name	Type	Description	Default	Required
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`enable_http_2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

basic_auth block

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

password and password_file are mututally exclusive and only one can be provided inside of a basic_auth block.

authorization block

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

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

oauth2 block

Name	Type	Description	Required
`client_id`	`string`	OAuth2 client ID.	no
`client_secret`	`secret`	OAuth2 client secret.	no
`client_secret_file`	`string`	File containing the OAuth2 client secret.	no
`scopes`	`list(string)`	List of scopes to authenticate with.	no
`token_url`	`string`	URL to fetch the token from.	no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.	no
`proxy_url`	`string`	Optional proxy URL for OAuth2 requests.	no

client_secret and client_secret_file are mututally exclusive and only one can be provided inside of an oauth2 block.

The oauth2 block may also contain its own separate tls_config sub-block.

tls_config block

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

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

Exported fields

mimir.rules.kubernetes does not export any fields.

Component health

mimir.rules.kubernetes is reported as unhealthy if given an invalid configuration or an error occurs during reconciliation.

Debug information

mimir.rules.kubernetes exposes resource-level debug information.

The following are exposed per discovered PrometheusRule resource:

The Kubernetes namespace.
The resource name.
The resource uid.
The number of rule groups.

The following are exposed per discovered Mimir rule namespace resource:

The namespace name.
The number of rule groups.

Only resources managed by the component are exposed - regardless of how many actually exist.

Debug metrics

Metric Name	Type	Description
`mimir_rules_config_updates_total`	`counter`	Number of times the configuration has been updated.
`mimir_rules_events_total`	`counter`	Number of events processed, partitioned by event type.
`mimir_rules_events_failed_total`	`counter`	Number of events that failed to be processed, partitioned by event type.
`mimir_rules_events_retried_total`	`counter`	Number of events that were retried, partitioned by event type.
`mimir_rules_client_request_duration_seconds`	`histogram`	Duration of requests to the Mimir API.

Example

This example creates a mimir.rules.kubernetes component that loads discovered rules to a local Mimir instance under the team-a tenant. Only namespaces and rules with the agent label set to yes are included.

mimir.rules.kubernetes "local" {
    address = "mimir:8080"
    tenant_id = "team-a"

    rule_namespace_selector {
        match_labels = {
            agent = "yes",
        }
    }

    rule_selector {
        match_labels = {
            agent = "yes",
        }
    }
}

This example creates a mimir.rules.kubernetes component that loads discovered rules to Grafana Cloud.

mimir.rules.kubernetes "default" {
    address = "GRAFANA_CLOUD_METRICS_URL"
    http_client_config {
        basic_auth {
            username = "GRAFANA_CLOUD_USER"
            password = "GRAFANA_CLOUD_API_KEY"
            // Alternatively, load the password from a file:
            // password_file = "GRAFANA_CLOUD_API_KEY_PATH"
        }
    }
}

otelcol.auth.basic

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.auth.basic

otelcol.auth.basic exposes a handler that can be used by other otelcol components to authenticate requests using basic authentication.

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

Multiple otelcol.auth.basic components can be specified by giving them different labels.

Usage

otelcol.auth.basic "LABEL" {
  username = "USERNAME"
  password = "PASSWORD"
}

Arguments

otelcol.auth.basic supports the following arguments:

Name	Type	Description	Default	Required
`username`	`string`	Username to use for basic authentication requests.		yes
`password`	`secret`	Password to use for basic authentication requests.		yes

Exported fields

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

Name	Type	Description
`handler`	`capsule(otelcol.Handler)`	A value that other components can use to authenticate requests.

Component health

otelcol.auth.basic is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.auth.basic does not expose any component-specific debug information.

Example

This example configures otelcol.exporter.otlp to use basic authentication:

otelcol.exporter.otlp "example" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth     = otelcol.auth.basic.creds.handler
  }
}

otelcol.auth.basic "creds" {
  username = "demo"
  password = env("API_KEY")
}

otelcol.auth.bearer

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.auth.bearer

otelcol.auth.bearer exposes a handler that can be used by other otelcol components to authenticate requests using bearer token authentication.

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

Multiple otelcol.auth.bearer components can be specified by giving them different labels.

Usage

otelcol.auth.bearer "LABEL" {
  token = "TOKEN"
}

Arguments

otelcol.auth.bearer supports the following arguments:

Name	Type	Description	Default	Required
`token`	`secret`	Bearer token to use for authenticating requests.		yes

Exported fields

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

Name	Type	Description
`handler`	`capsule(otelcol.Handler)`	A value that other components can use to authenticate requests.

Component health

otelcol.auth.bearer is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.auth.bearer does not expose any component-specific debug information.

Example

This example configures otelcol.exporter.otlp to use bearer token authentication:

otelcol.exporter.otlp "example" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth     = otelcol.auth.bearer.creds.handler
  }
}

otelcol.auth.bearer "creds" {
  token = env("API_KEY")
}

otelcol.auth.headers

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.auth.headers

otelcol.auth.headers exposes a handler that can be used by other otelcol components to authenticate requests using custom headers.

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

Multiple otelcol.auth.headers components can be specified by giving them different labels.

Usage

otelcol.auth.headers "LABEL" {
  header {
    key   = "HEADER_NAME"
    value = "HEADER_VALUE"
  }
}

Arguments

otelcol.auth.headers doesn’t support any arguments and is configured fully through inner blocks.

Blocks

The following blocks are supported inside the definition of otelcol.auth.headers:

Hierarchy	Block	Description	Required
header	header	Custom header to attach to requests.	no

header block

The header block defines a custom header to attach to requests. It is valid to provide multiple header blocks to set more than one header.

Name	Type	Description	Required
`key`	`string`	Name of the header to set.	yes
`value`	`string` or `secret`	Value of the header.	no
`from_context`	`string`	Metadata name to get header value from.	no

Exactly one of value or from_context must be provided for each header block.

The value attribute sets the value of the header directly.

Alternatively, from_context can be used to dynamically retrieve the header value from request metadata.

NOTE: It is not possible to use from_context to get the header value if the otelcol.processor.batch component is used to batch before data is sent to the component referencing otelcol.auth.headers.

Exported fields

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

Name	Type	Description
`handler`	`capsule(otelcol.Handler)`	A value that other components can use to authenticate requests.

Component health

otelcol.auth.headers is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.auth.headers does not expose any component-specific debug information.

Example

This example configures otelcol.exporter.otlp to use custom headers:

otelcol.exporter.otlp "example" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth     = otelcol.auth.headers.creds.handler
  }
}

otelcol.auth.headers "creds" {
  header {
    key          = "X-Scope-OrgID"
    from_context = "tenant_id"
  }

  header {
    key   = "User-ID"
    value = "user_id"
  }
}

otelcol.exporter.jaeger

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.exporter.jaeger

otelcol.exporter.jaeger accepts telemetry data from other otelcol components and writes them over the network using the Jaeger protocol.

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

Multiple otelcol.exporter.jaeger components can be specified by giving them different labels.

Usage

otelcol.exporter.jaeger "LABEL" {
  client {
    endpoint = "HOST:PORT"
  }
}

Arguments

otelcol.exporter.jaeger supports the following arguments:

Name	Type	Description	Default	Required
`timeout`	`duration`	Time to wait before marking a request as failed.	`"5s"`	no

Blocks

The following blocks are supported inside the definition of otelcol.exporter.jaeger:

Hierarchy	Block	Description	Required
client	client	Configures the gRPC server to send telemetry data to.	yes
client > tls	tls	Configures TLS for the gRPC client.	no
client > keepalive	keepalive	Configures keepalive settings for the gRPC client.	no
sending_queue	sending_queue	Configures batching of data before sending.	no
retry_on_failure	retry_on_failure	Configures retry mechanism for failed requests.	no

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

client block

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

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to send telemetry data to.		yes
`compression`	`string`	Compression mechanism to use for requests.	`"gzip"`	no
`read_buffer_size`	`string`	Size of the read buffer the gRPC client to use for reading server responses.		no
`write_buffer_size`	`string`	Size of the write buffer the gRPC client to use for writing requests.	`"512KiB"`	no
`wait_for_ready`	`boolean`	Waits for gRPC connection to be in the `READY` state before sending data.	`false`	no
`headers`	`map(string)`	Additional headers to send with the request.	`{}`	no
`balancer_name`	`string`	Which gRPC client-side load balancer to use for requests.		no
`auth`	`capsule(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 balancer_name argument controls what client-side load balancing mechanism to use. See the gRPC documentation on Load balancing for more information. When unspecified, pick_first is used.

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.exporter.jaeger uses gRPC, the configured proxy server must be able to handle and proxy HTTP/2 traffic.

tls block

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

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`server_name`	`string`	Verifies the hostname of server certificates when set.		no

If the server doesn’t support TLS, the tls block must be provided with the insecure argument set to true. To disable tls for connections to the server, set the insecure argument to true.

keepalive block

The keepalive block configures keepalive settings for gRPC client connections.

The following arguments are supported:

Name	Type	Description	Required
`ping_wait`	`duration`	How often to ping the server after no activity.	no
`ping_response_timeout`	`duration`	Time to wait before closing inactive connections if the server does not respond to a ping.	no
`ping_without_stream`	`boolean`	Send pings even if there is no active stream request.	no

sending_queue block

The sending_queue block configures an in-memory buffer of batches before data is sent to the gRPC server.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables an in-memory buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at once.	`5000`	no

When enabled is true, data is first written to an in-memory buffer before sending it to the configured server. Batches sent to the component’s input exported field are added to the buffer as long as the number of unsent batches does not exceed the configured queue_size.

queue_size is used to determine how long an endpoint outage is tolerated for. Assuming 100 requests/second, the default queue size 5000 provides about 50 seconds of outage tolerance. To calculate the correct value for queue_size, multiply the average number of outgoing requests per second by the amount of time in seconds that outages should be tolerated for.

The num_consumers argument controls how many readers read from the buffer and send data in parallel. Larger values of num_consumers allow data to be sent more quickly at the expense of increased network traffic.

retry_on_failure block

The retry_on_failure block configures how failed requests to the gRPC server are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`max_elapsed_time`	`duration`	Maximum amount of time to wait before discarding a failed batch.	`"5m"`	no

When enabled is true, failed batches are retried after a given interval. The initial_interval argument specifies how long to wait before the first retry attempt. If requests continue to fail, the time to wait before retrying increases exponentially. The max_interval argument specifies the upper bound of how long to wait between retries.

If a batch has not sent successfully, it is discarded after the time specified by max_elapsed_time elapses. If max_elapsed_time is set to "0s", failed requests are retried forever until they succeed.

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.exporter.jaeger is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.jaeger does not expose any component-specific debug information.

Example

This example accepts OTLP traces over gRPC, sends them to a batch processor and forwards to Jaeger without TLS:

otelcol.receiver.otlp "default" {
    grpc {}
    output {
        traces  = [otelcol.processor.batch.default.input]
    }
}

otelcol.processor.batch "default" {
    output {
        traces  = [otelcol.exporter.jaeger.default.input]
    }
}

otelcol.exporter.jaeger "default" {
    client {
        endpoint = "jaeger:14250"
        tls {
            insecure             = true
            insecure_skip_verify = true
        }
    }
}

otelcol.exporter.loki

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.exporter.loki

otelcol.exporter.loki accepts OTLP-formatted logs from other otelcol components, converts them to Loki-formatted log entries, and forwards them to loki components.

NOTE: otelcol.exporter.loki is a custom component unrelated to the lokiexporter from the OpenTelemetry Collector.

Conversion of logs are done according to the OpenTelemetry Logs Data Model specification.

Multiple otelcol.exporter.loki components can be specified by giving them different labels.

Usage

otelcol.exporter.loki "LABEL" {
  forward_to = [...]
}

Arguments

otelcol.exporter.loki supports the following arguments:

Name	Type	Description	Default	Required
`forward_to`	`list(receiver)`	Where to forward converted Loki logs.		yes

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for logs. Other telemetry signals are ignored.

Logs sent to input are converted to Loki-compatible log entries and are forwarded to the forward_to argument in sequence.

Component health

otelcol.exporter.loki is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.loki does not expose any component-specific debug information.

Example

This example accepts OTLP logs over gRPC, transforms them and forwards the converted log entries to loki.write:

otelcol.receiver.otlp "default" {
  grpc {}

  output {
    logs = [otelcol.exporter.loki.default.input]
  }
}

otelcol.exporter.loki "default" {
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
    endpoint {
        url = "loki:3100"
    }
}

otelcol.exporter.otlp

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.exporter.otlp

otelcol.exporter.otlp accepts telemetry data from other otelcol components and writes them over the network using the OTLP gRPC protocol.

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

Multiple otelcol.exporter.otlp components can be specified by giving them different labels.

Usage

otelcol.exporter.otlp "LABEL" {
  client {
    endpoint = "HOST:PORT"
  }
}

Arguments

otelcol.exporter.otlp supports the following arguments:

Name	Type	Description	Default	Required
`timeout`	`duration`	Time to wait before marking a request as failed.	`"5s"`	no

Blocks

The following blocks are supported inside the definition of otelcol.exporter.otlp:

Hierarchy	Block	Description	Required
client	client	Configures the gRPC server to send telemetry data to.	yes
client > tls	tls	Configures TLS for the gRPC client.	no
client > keepalive	keepalive	Configures keepalive settings for the gRPC client.	no
sending_queue	sending_queue	Configures batching of data before sending.	no
retry_on_failure	retry_on_failure	Configures retry mechanism for failed requests.	no

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

client block

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

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to send telemetry data to.		yes
`compression`	`string`	Compression mechanism to use for requests.	`"gzip"`	no
`read_buffer_size`	`string`	Size of the read buffer the gRPC client to use for reading server responses.		no
`write_buffer_size`	`string`	Size of the write buffer the gRPC client to use for writing requests.	`"512KiB"`	no
`wait_for_ready`	`boolean`	Waits for gRPC connection to be in the `READY` state before sending data.	`false`	no
`headers`	`map(string)`	Additional headers to send with the request.	`{}`	no
`balancer_name`	`string`	Which gRPC client-side load balancer to use for requests.		no
`auth`	`capsule(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 balancer_name argument controls what client-side load balancing mechanism to use. See the gRPC documentation on Load balancing for more information. When unspecified, pick_first is used.

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.

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

tls block

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

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`server_name`	`string`	Verifies the hostname of server certificates when set.		no

If the server doesn’t support TLS, the tls block must be provided with the insecure argument set to true. To disable tls for connections to the server, set the insecure argument to true.

keepalive block

The keepalive block configures keepalive settings for gRPC client connections.

The following arguments are supported:

Name	Type	Description	Required
`ping_wait`	`duration`	How often to ping the server after no activity.	no
`ping_response_timeout`	`duration`	Time to wait before closing inactive connections if the server does not respond to a ping.	no
`ping_without_stream`	`boolean`	Send pings even if there is no active stream request.	no

sending_queue block

The sending_queue block configures an in-memory buffer of batches before data is sent to the gRPC server.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables an in-memory buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at once.	`5000`	no

retry_on_failure block

The retry_on_failure block configures how failed requests to the gRPC server are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`max_elapsed_time`	`duration`	Maximum amount of time to wait before discarding a failed batch.	`"5m"`	no

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.exporter.otlp is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.otlp does not expose any component-specific debug information.

Example

This example creates an exporter to send data to a locally running Grafana Tempo without TLS:

otelcol.exporter.otlp "tempo" {
    client {
        endpoint = "tempo:4317"
        tls {
            insecure             = true
            insecure_skip_verify = true
        }
    }
}

otelcol.exporter.otlphttp

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.exporter.otlphttp

otelcol.exporter.otlphttp accepts telemetry data from other otelcol components and writes them over the network using the OTLP HTTP protocol.

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

Multiple otelcol.exporter.otlphttp components can be specified by giving them different labels.

Usage

otelcol.exporter.otlphttp "LABEL" {
  client {
    endpoint = "HOST:PORT"
  }
}

Arguments

otelcol.exporter.otlphttp supports the following arguments:

Name	Type	Description	Default	Required
`metrics_endpoint`	`string`	The endpoint to send metrics to.	`client.endpoint + "/v1/metrics"`	no
`logs_endpoint`	`string`	The endpoint to send logs to.	`client.endpoint + "/v1/logs"`	no
`traces_endpoint`	`string`	The endpoint to send traces to.	`client.endpoint + "/v1/traces"`	no

The default value depends on the endpoint field set in the required client block. If set, these arguments override the client.endpoint field for the corresponding signal.

Blocks

The following blocks are supported inside the definition of otelcol.exporter.otlphttp:

Hierarchy	Block	Description	Required
client	client	Configures the HTTP server to send telemetry data to.	yes
client > tls	tls	Configures TLS for the HTTP client.	no
sending_queue	sending_queue	Configures batching of data before sending.	no
retry_on_failure	retry_on_failure	Configures retry mechanism for failed requests.	no

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

client block

The client block configures the HTTP client used by the component.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to send telemetry data to.		yes
`read_buffer_size`	`string`	Size of the read buffer the HTTP client uses for reading server responses.	`0`	no
`write_buffer_size`	`string`	Size of the write buffer the HTTP client uses for writing requests.	`"512KiB"`	no
`timeout`	`duration`	Time to wait before marking a request as failed.	`"30s"`	no
`headers`	`map(string)`	Additional headers to send with the request.	`{}`	no
`compression`	`string`	Compression mechanism to use for requests.	`"gzip"`	no
`max_idle_conns`	`int`	Limits the number of idle HTTP connections the client can keep open.	`100`	no
`max_idle_conns_per_host`	`int`	Limits the number of idle HTTP connections the host can keep open.	`0`	no
`max_conns_per_host`	`int`	Limits the total (dialing,active, and idle) number of connections per host.	`0`	no
`idle_conn_timeout`	`duration`	Time to wait before an idle connection closes itself.	`"90s"`	no
`auth`	`capsule(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.

tls block

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

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`server_name`	`string`	Verifies the hostname of server certificates when set.		no

If the server doesn’t support TLS, the tls block must be provided with the insecure argument set to true. To disable tls for connections to the server, set the insecure argument to true.

sending_queue block

The sending_queue block configures an in-memory buffer of batches before data is sent to the HTTP server.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables an in-memory buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at once.	`5000`	no

retry_on_failure block

The retry_on_failure block configures how failed requests to the HTTP server are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`max_elapsed_time`	`duration`	Maximum amount of time to wait before discarding a failed batch.	`"5m"`	no

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.exporter.otlphttp is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.otlphttp does not expose any component-specific debug information.

Example

This example creates an exporter to send data to a locally running Grafana Tempo without TLS:

otelcol.exporter.otlphttp "tempo" {
    client {
        endpoint = "tempo:4317"
        tls {
            insecure             = true
            insecure_skip_verify = true
        }
    }
}

otelcol.exporter.prometheus

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.exporter.prometheus

otelcol.exporter.prometheus accepts OTLP-formatted metrics from other otelcol components, converts metrics to Prometheus-formatted metrics, and forwards the resulting metrics to prometheus components.

NOTE: otelcol.exporter.prometheus is a custom component unrelated to the prometheus exporter from OpenTelemetry Collector.

Conversion of metrics are done according to the OpenTelemetry Metrics Data Model specification.

Multiple otelcol.exporter.prometheus components can be specified by giving them different labels.

Usage

otelcol.exporter.prometheus "LABEL" {
  forward_to = [...]
}

Arguments

otelcol.exporter.prometheus supports the following arguments:

Name	Type	Description	Default	Required
`include_target_info`	`boolean`	Whether to include `target_info` metrics.	`true`	no
`include_scope_info`	`boolean`	Whether to include `otel_scope_info` metrics.	`true`	no
`gc_frequency`	`duration`	How often to clean up stale metrics from memory.	`"5m"`	no
`forward_to`	`list(receiver)`	Where to forward converted Prometheus metrics.		yes

By default, OpenTelemetry resources are converted into target_info metrics, and OpenTelemetry instrumentation scopes are converted into otel_scope_info metrics. Set the include_scope_info and include_target_info arguments to false, respectively, to disable the custom metrics.

When include_scope_info is true, the instrumentation scope name and version are added as otel_scope_name and otel_scope_version labels to every converted metric sample.

When include_scope_info is true, OpenTelemetry Collector resources are converted into target_info metrics.

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for metrics. Other telemetry signals are ignored.

Metrics sent to the input are converted to Prometheus-compatible metrics and are forwarded to the forward_to argument.

The following are dropped during the conversion process:

Metrics that use the delta aggregation temporality
Exemplars on OpenTelemetry cumulative sums and OpenTelemetry Histograms
ExponentialHistogram data points

Component health

otelcol.exporter.prometheus is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.prometheus does not expose any component-specific debug information.

Example

This example accepts metrics over OTLP and forwards it using prometheus.remote_write:

otelcol.receiver.otlp "default" {
  grpc {}

  output {
    metrics = [otelcol.exporter.prometheus.default.input]
  }
}

otelcol.exporter.prometheus "default" {
  forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"
  }
}

otelcol.processor.batch

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.processor.batch

otelcol.processor.batch accepts telemetry data from other otelcol components and places them into batches. Batching improves the compression of data and reduces the number of outgoing network requests required to transmit data.

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

Multiple otelcol.processor.batch components can be specified by giving them different labels.

Usage

otelcol.processor.batch "LABEL" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

otelcol.processor.batch supports the following arguments:

Name	Type	Description	Default	Required
`timeout`	`duration`	How long to wait before flushing the batch.	`"200ms"`	no
`send_batch_size`	`number`	Amount of data to buffer before flushing the batch.	`8192`	no
`send_batch_max_size`	`number`	Upper limit of a batch size.	`0`	no

otelcol.processor.batch accumulates data into a batch until one of the following events happens:

The duration specified by timeout elapses since the time the last batch was sent.
The number of spans, log lines, or metric samples processed exceeds the number specified by send_batch_size.

Use send_batch_max_size to limit the amount of data contained in a single batch. When set to 0, batches can be any size.

For example, assume send_batch_size is set to the default 8192 and there are currently 8000 batched spans. If the batch processor receives 8000 more spans at once, the total batch size would be 16,192 which would then be flushed as a single batch. send_batch_max_size constrains how big a batch can get. When set to a non-zero value, send_batch_max_size must be greater or equal to send_batch_size.

Blocks

The following blocks are supported inside the definition of otelcol.processor.batch:

Hierarchy	Block	Description	Required
output	output	Configures where to send received telemetry data.	yes

output block

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

The output block must be specified, but all of its arguments are optional. By default, telemetry data is dropped. To send telemetry data to other components, configure the metrics, logs, and traces arguments accordingly.

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.processor.batch is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.processor.batch does not expose any component-specific debug information.

Example

This example batches telemetry data before sending it to otelcol.exporter.otlp for further processing:

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlp.production.input]
    logs    = [otelcol.exporter.otlp.production.input]
    traces  = [otelcol.exporter.otlp.production.input]
  }
}

otelcol.exporter.otlp "production" {
  client {
    endpoint = env("OTLP_SERVER_ENDPOINT")
  }
}

otelcol.processor.memory_limiter

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.processor.memory_limiter

otelcol.processor.memory_limiter is used to prevent out of memory situations on a telemetry pipeline by performing periodic checks of memory usage. If usage exceeds the defined limits, data is dropped and garbage collections are triggered to reduce it.

The memory_limiter component uses both soft and hard limits, where the hard limit is always equal or larger than the soft limit. When memory usage goes above the soft limit, the processor component drops data and returns errors to the preceding components in the pipeline. When usage exceeds the hard limit, the processor forces a garbage collection in order to try and free memory. When usage is below the soft limit, no data is dropped and no forced garbage collection is performed.

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

Multiple otelcol.processor.memory_limiter components can be specified by giving them different labels.

Usage

otelcol.processor.memory_limiter "LABEL" {
  check_interval = "1s"
  
  limit = "50MiB" // alternatively, set `limit_percentage` and `spike_limit_percentage`

  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

otelcol.processor.memory_limiter supports the following arguments:

Name	Type	Description	Default	Required
`check_interval`	`duration`	How often to check memory usage.		yes
`limit`	`string`	Maximum amount of memory targeted to be allocated by the process heap.	`"0MiB"`	no
`spike_limit`	`string`	Maximum spike expected between the measurements of memory usage.	20% of `limit`	no
`limit_percentage`	`int`	Maximum amount of total available memory targeted to be allocated by the process heap.	`0`	no
`spike_limit_percentage`	`int`	Maximum spike expected between the measurements of memory usage.	`0`	no

The arguments must define either limit or the limit_percentage, spike_limit_percentage pair, but not both.

The configuration options limit and limit_percentage define the hard limits. The soft limits are then calculated as the hard limit minus the spike_limit or spike_limit_percentage values respectively. The recommended value for spike limits is about 20% of the corresponding hard limit.

The recommended check_interval value is 1 second. If the traffic through the component is spiky in nature, it is recommended to either decrease the interval or increase the spike limit to avoid going over the hard limit.

The limit and spike_limit values must be larger than 1 MiB.

Blocks

The following blocks are supported inside the definition of otelcol.processor.memory_limiter:

Hierarchy	Block	Description	Required
output	output	Configures where to send received telemetry data.	yes

output block

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.processor.memory_limiter is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.processor.memory_limiter does not expose any component-specific debug information.

otelcol.receiver.jaeger

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.receiver.jaeger

otelcol.receiver.jaeger accepts Jaeger-formatted data over the network and forwards it to other otelcol.* components.

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

Multiple otelcol.receiver.jaeger components can be specified by giving them different labels.

Usage

otelcol.receiver.jaeger "LABEL" {
  protocols {
    grpc {}
    thrift_http {}
    thrift_binary {}
    thrift_compact {}
  }

  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

otelcol.receiver.jaeger doesn’t support any arguments and is configured fully through inner blocks.

Blocks

The following blocks are supported inside the definition of otelcol.receiver.jaeger:

Hierarchy	Block	Description	Required
protocols	protocols	Configures the protocols the component can accept traffic over.	yes
protocols > grpc	grpc	Configures a Jaeger gRPC server to receive traces.	no
protocols > grpc > tls	tls	Configures TLS for the gRPC server.	no
protocols > grpc > keepalive	keepalive	Configures keepalive settings for the configured server.	no
protocols > grpc > keepalive > server_parameters	server_parameters	Server parameters used to configure keepalive settings.	no
protocols > grpc > keepalive > enforcement_policy	enforcement_policy	Enforcement policy for keepalive settings.	no
protocols > thrift_http	thrift_http	Configures a Thrift HTTP server to receive traces.	no
protocols > thrift_http > tls	tls	Configures TLS for the Thrift HTTP server.	no
protocols > thrift_http > cors	cors	Configures CORS for the Thrift HTTP server.	no
protocols > thrift_binary	thrift_binary	Configures a Thrift binary UDP server to receive traces.	no
protocols > thrift_compact	thrift_compact	Configures a Thrift compact UDP server to receive traces.	no
output	output	Configures where to send received telemetry data.	yes

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

protocols block

The protocols block defines a set of protocols that will be used to accept traces over the network.

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

otelcol.receiver.jeager requires at least one protocol block (grpc, thrift_http, thrift_binary, or thrift_compact) to be provided.

grpc block

The grpc block configures a gRPC server which can accept Jaeger traces. If the grpc block isn’t provided, a gRPC server isn’t started.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to listen for traffic on.	`"0.0.0.0:14250"`	no
`transport`	`string`	Transport to use for the gRPC server.	`"tcp"`	no
`max_recv_msg_size`	`string`	Maximum size of messages the server will accept. 0 disables a limit.		no
`max_concurrent_streams`	`number`	Limit the number of concurrent streaming RPC calls.		no
`read_buffer_size`	`string`	Size of the read buffer the gRPC server will use for reading from clients.	`"512KiB"`	no
`write_buffer_size`	`string`	Size of the write buffer the gRPC server will use for writing to clients.		no
`include_metadata`	`boolean`	Propagate 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:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`reload_interval`	`duration`	Frequency to reload the certificates.		no
`client_ca_file`	`string`	Path to the CA file used to authenticate client certificates.		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:

Name	Type	Description	Default	Required
`max_connection_idle`	`duration`	Maximum age for idle connections.	`"infinity"`	no
`max_connection_age`	`duration`	Maximum age for non-idle connections.	`"infinity"`	no
`max_connection_age_grace`	`duration`	Time to wait before forcibly closing connections.	`"infinity"`	no
`time`	`duration`	How often to ping inactive clients to check for liveness.	`"2h"`	no
`timeout`	`duration`	Time 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:

Name	Type	Description	Default	Required
`min_time`	`duration`	Minimum time clients should wait before sending a keepalive ping.	`"5m"`	no
`permit_without_stream`	`boolean`	Allow clients to send keepalive pings when there are no active streams.	`false`	no

thrift_http block

The thrift_http block configures an HTTP server which can accept Thrift-formatted traces. If the thrift_http block isn’t specified, an HTTP server isn’t started.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to listen for traffic on.	`"0.0.0.0:14268"`	no
`max_request_body_size`	`string`	Maximum request body size the server will allow. No limit when unset.		no
`include_metadata`	`boolean`	Propagate incoming connection metadata to downstream consumers.		no

cors block

The cors block configures CORS settings for an HTTP server.

The following arguments are supported:

Name	Type	Description	Default	Required
`allowed_origins`	`list(string)`	Allowed values for the `Origin` header.		no
`allowed_headers`	`list(string)`	Accepted headers from CORS requests.	`["X-Requested-With"]`	no
`max_age`	`number`	Configures 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.

thrift_binary block

The thrift_binary block configures a UDP server which can accept traces formatted to the Thrift binary protocol. If the thrift_binary block isn’t provided, a UDP server isn’t started.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to listen for traffic on.	`"0.0.0.0:6832"`	no
`queue_size`	`number`	Maximum number of UDP messages that can be queued at once.	`1000`	no
`max_packet_size`	`string`	Maximum UDP message size.	`"65KiB"`	no
`workers`	`number`	Number of workers to concurrently read from the message queue.	`10`	no
`socket_buffer_size`	`string`	Buffer to allocate for the UDP socket.		no

thrift_compact block

The thrift_compact block configures a UDP server which can accept traces formatted to the Thrift compact protocol. If the thrift_compact block isn’t provided, a UDP server isn’t started.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to listen for traffic on.	`"0.0.0.0:6831"`	no
`queue_size`	`number`	Maximum number of UDP messages that can be queued at once.	`1000`	no
`max_packet_size`	`string`	Maximum UDP message size.	`"65KiB"`	no
`workers`	`number`	Number of workers to concurrently read from the message queue.	`10`	no
`socket_buffer_size`	`string`	Buffer to allocate for the UDP socket.		no

output block

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

Exported fields

otelcol.receiver.jaeger does not export any fields.

Component health

otelcol.receiver.jaeger is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.jaeger does not expose any component-specific debug information.

Example

This example creates a pipeline which accepts Jaeger-formatted traces and writes them to an OTLP server:

otelcol.receiver.jaeger "default" {
  protocols {
    grpc {}
    thrift_http {}
    thrift_binary {}
    thrift_compact {}
  }

  output {
    traces = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    traces = [otelcol.exporter.otlp.default.input]
  }
}

otelcol.exporter.otlp "default" {
  client {
    endpoint = "my-otlp-server:4317"
  }
}

otelcol.receiver.kafka

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.receiver.kafka

otelcol.receiver.kafka accepts telemetry data from a Kafka broker and forwards it to other otelcol.* components.

NOTE: otelcol.receiver.kafka is a wrapper over the upstream OpenTelemetry Collector kafka receiver from the otelcol-contrib distribution. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

Multiple otelcol.receiver.kafka components can be specified by giving them different labels.

Usage

otelcol.receiver.kafka "LABEL" {
  brokers          = ["BROKER_ADDR"]
  protocol_version = "PROTOCOL_VERSION"

  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`brokers`	`array(string)`	Kafka brokers to connect to.		yes
`protocol_version`	`string`	Kafka protocol version to use.		yes
`topic`	`string`	Kafka topic to read from.	`"otlp_spans"`	no
`encoding`	`string`	Encoding of payload read from Kafka.	`"otlp_proto"`	no
`group_id`	`string`	Consumer group to consume messages from.	`"otel-collector"`	no
`client_id`	`string`	Consumer client ID to use.	`"otel-collector"`	no

The encoding argument determines how to decode messages read from Kafka. encoding must be one of the following strings:

"otlp_proto": Decode messages as OTLP protobuf.
"jaeger_proto": Decode messages as a single Jaeger protobuf span.
"jaeger_json": Decode messages as a single Jaeger JSON span.
"zipkin_proto": Decode messages as a list of Zipkin protobuf spans.
"zipkin_json": Decode messages as a list of Zipkin JSON spans.
"zipkin_thrift": Decode messages as a list of Zipkin Thrift spans.
"raw": Copy the message bytes into the body of a log record.

"otlp_proto" must be used to read all telemetry types from Kafka; other encodings are signal-specific.

Blocks

The following blocks are supported inside the definition of otelcol.receiver.kafka:

Hierarchy	Block	Description	Required
authentication	authentication	Configures authentication for connecting to Kafka brokers.	no
authentication > plaintext	plaintext	Authenticates against Kafka brokers with plaintext.	no
authentication > sasl	sasl	Authenticates against Kafka brokers with SASL.	no
authentication > sasl > aws_msk	aws_msk	Additional SASL parameters when using AWS_MSK_IAM.	no
authentication > tls	tls	Configures TLS for connecting to the Kafka brokers.	no
authentication > kerberos	kerberos	Authenticates against Kafka brokers with Kerberos.	no
metadata	metadata	Configures how to retrieve metadata from Kafka brokers.	no
metadata > retry	retry	Configures how to retry metadata retrieval.	no
autocommit	autocommit	Configures how to automatically commit updated topic offsets to back to the Kafka brokers.	no
message_marking	message_marking	Configures when Kafka messages are marked as read.	no
output	output	Configures where to send received telemetry data.	yes

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

authentication block

The authentication block holds the definition of different authentication mechanisms to use when connecting to Kafka brokers. It doesn’t support any arguments and is configured fully through inner blocks.

plaintext block

The plaintext block configures PLAIN authentication against Kafka brokers.

The following arguments are supported:

Name	Type	Description	Default	Required
`username`	`string`	Username to use for `PLAIN` authentication.		yes
`password`	`secret`	Password to use for `PLAIN` authentication.		yes

sasl block

The sasl block configures SASL authentication against Kafka brokers.

The following arguments are supported:

Name	Type	Description	Required
`username`	`string`	Username to use for SASL authentication.	yes
`password`	`secret`	Password to use for SASL authentication.	yes
`mechanism`	`string`	SASL mechanism to use when authenticating.	yes

The mechanism argument can be set to one of the following strings:

"PLAIN"
"AWS_MSK_IAM"
"SCRAM-SHA-256"
"SCRAM-SHA-512"

When mechanism is set to "AWS_MSK_IAM", the aws_msk child block must also be provided.

aws_msk block

The aws_msk block configures extra parameters for SASL authentication when using the AWS_MSK_IAM mechanism.

The following arguments are supported:

Name	Type	Description	Default	Required
`region`	`string`	AWS region the MSK cluster is based in.		yes
`broker_addr`	`string`	MSK address to connect to for authentication.		yes

tls block

The tls block configures TLS settings used for connecting to the Kafka brokers. If the tls block isn’t provided, TLS won’t be used for communication.

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`reload_interval`	`duration`	Frequency to reload the certificates.		no
`client_ca_file`	`string`	Path to the CA file used to authenticate client certificates.		no

kerberos block

The kerberos block configures Kerberos authentication against the Kafka broker.

The following arguments are supported:

Name	Type	Description	Required
`service_name`	`string`	Kerberos service name.	no
`realm`	`string`	Kerberos realm.	no
`use_keytab`	`string`	Enables using keytab instead of password.	no
`username`	`string`	Kerberos username to authenticate as.	yes
`password`	`secret`	Kerberos password to authenticate with.	no
`config_file`	`string`	Path to Kerberos location (for example, `/etc/krb5.conf`).	no
`keytab_file`	`string`	Path to keytab file (for eaxmple, `/etc/security/kafka.keytab`).	no

When use_keytab is false, the password argument is required. When use_keytab is true, the file pointed to by the keytab_file argument is used for authentication instead. At most one of password or keytab_file must be provided.

metadata block

The metadata block configures how to retrieve and store metadata from the Kafka broker.

The following arguments are supported:

Name	Type	Description	Default	Required
`include_all_topics`	`bool`	When true, maintains metadata for all topics.	`true`	no

If the include_all_topics argument is true, otelcol.receiver.kafka maintains a full set of metadata for all topics rather than the minimal set that has been necessary so far. Including the full set of metadata is more convenient for users but can consume a substantial amount of memory if you have many topics and partitions.

Retrieving metadata may fail if the Kafka broker is starting up at the same time as the otelcol.receiver.kafka component. The retry child block can be provided to customize retry behavior.

retry block

The retry block configures how to retry retrieving metadata when retrieval fails.

The following arguments are supported:

Name	Type	Description	Default	Required
`max_retries`	`number`	How many times to reattempt retrieving metadata.	`3`	no
`backoff`	`duration`	Time to wait between retries.	`"250ms"`	no

autocommit block

The autocommit block configures how to automatically commit updated topic offsets back to the Kafka brokers.

The following arguments are supported:

Name	Type	Description	Default	Required
`enable`	`bool`	Enable autocommitting updated topic offsets.	`true`	no
`interval`	`duration`	How frequently to autocommit.	`"1s"`	no

message_marking block

The message_marking block configures when Kafka messages are marked as read.

The following arguments are supported:

Name	Type	Description	Default	Required
`after_execution`	`bool`	Mark messages after forwarding telemetry data to other components.	`false`	no
`include_unsuccessful`	`bool`	Whether failed forwards should be marked as read.	`false`	no

By default, a Kafka message is marked as read immediately after it is retrieved from the Kafka broker. If the after_execution argument is true, messages are only read after the telemetry data is forwarded to components specified in the output block.

When after_execution is true, messages are only marked as read when they are decoded successfully and components where the data was forwarded did not return an error. If the include_unsuccessful argument is true, messages are marked as read even if decoding or forwarding failed. Setting include_unsuccessful has no effect if after_execution is false.

WARNING: Setting after_execution to true and include_unsuccessful to false can block the entire Kafka partition if message processing returns a permanent error, such as failing to decode.

output block

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

Exported fields

otelcol.receiver.kafka does not export any fields.

Component health

otelcol.receiver.kafka is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.kafka does not expose any component-specific debug information.

Example

This example forwards read telemetry data through a batch processor before finally sending it to an OTLP-capable endpoint:

otelcol.receiver.kafka "default" {
  brokers          = ["localhost:9092"]
  protocol_version = "2.0.0"

  output {
    metrics = [otelcol.processor.batch.default.input]
    logs    = [otelcol.processor.batch.default.input]
    traces  = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlp.default.input]
    logs    = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

otelcol.exporter.otlp "default" {
  client {
    endpoint = env("OTLP_ENDPOINT")
  }
}

otelcol.receiver.loki

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.receiver.loki

otelcol.receiver.loki receives Loki log entries, converts them to the OpenTelemetry logs format, and forwards them to other otelcol.* components.

Multiple otelcol.receiver.loki components can be specified by giving them different labels.

Usage

otelcol.receiver.loki "LABEL" {
  output {
    logs = [...]
  }
}

Arguments

otelcol.receiver.loki doesn’t support any arguments and is configured fully through inner blocks.

Blocks

The following blocks are supported inside the definition of otelcol.receiver.loki:

Hierarchy	Block	Description	Required
output	output	Configures where to send converted telemetry data.	yes

output block

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

Exported fields

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

Name	Type	Description
`receiver`	`LogsReceiver`	A value that other components can use to send Loki logs to.

Component health

otelcol.receiver.loki is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.loki does not expose any component-specific debug information.

Example

This example uses the otelcol.receiver.loki component as a bridge between the Loki and OpenTelemetry ecosystems. The component exposes a receiver which the loki.source.file component uses to send Loki log entries to. The logs are converted to the OTLP format before they are forwarded to the otelcol.exporter.otlp component to be sent to an OTLP-capable endpoint:

loki.source.file "default" {
  targets = [
    {__path__ = "/tmp/foo.txt", "loki.format" = "logfmt"},
    {__path__ = "/tmp/bar.txt", "loki.format" = "json"},
  ]
  forward_to = [otelcol.receiver.loki.default.receiver]
}

otelcol.receiver.loki "default" {
  output {
    logs = [otelcol.exporter.otlp.default.input] 
  } 
}

otelcol.exporter.otlp "default" {
  client {
    endpoint = env("OTLP_ENDPOINT")
  }
}

otelcol.receiver.opencensus

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.receiver.opencensus

otelcol.receiver.opencensus accepts telemetry data via gRPC or HTTP using the OpenCensus format and forwards it to other otelcol.* components.

NOTE: otelcol.receiver.opencensus is a wrapper over the upstream OpenTelemetry Collector opencensus receiver from the otelcol-contrib distribution. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

Multiple otelcol.receiver.opencensus components can be specified by giving them different labels.

Usage

otelcol.receiver.opencensus "LABEL" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

otelcol.receiver.opencensus supports the following arguments:

Name	Type	Description	Default	Required
`cors_allowed_origins`	`list(string)`	A list of allowed Cross-Origin Resource Sharing (CORS) origins.		no

cors_allowed_origins are the allowed CORS origins for HTTP/JSON requests. An empty list means that CORS is not enabled at all. A wildcard (*) can be used to match any origin or one or more characters of an origin.

Blocks

The following blocks are supported inside the definition of otelcol.receiver.opencensus:

Hierarchy	Block	Description	Required
grpc	grpc	Configures the gRPC/HTTP server to receive telemetry data.	no
grpc > tls	tls	Configures TLS for the gRPC server.	no
grpc > keepalive	keepalive	Configures keepalive settings for the configured server.	no
grpc > keepalive > server_parameters	server_parameters	Server parameters used to configure keepalive settings.	no
grpc > keepalive > enforcement_policy	enforcement_policy	Enforcement policy for keepalive settings.	no
output	output	Configures where to send received telemetry data.	yes

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

grpc block

The grpc block configures the gRPC/HTTP server used by the component. If the grpc block isn’t provided, a server using default parameters is started.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to listen for traffic on.	`"0.0.0.0:4317"`	no
`transport`	`string`	Transport to use for the gRPC server.	`"tcp"`	no
`max_recv_msg_size`	`string`	Maximum size of messages the server will accept. 0 disables a limit.		no
`max_concurrent_streams`	`number`	Limit the number of concurrent streaming RPC calls.		no
`read_buffer_size`	`string`	Size of the read buffer the gRPC server will use for reading from clients.	`"512KiB"`	no
`write_buffer_size`	`string`	Size of the write buffer the gRPC server will use for writing to clients.		no
`include_metadata`	`boolean`	Propagate incoming connection metadata to downstream consumers.		no

In order to use plain HTTP/JSON, specify the endpoint attribute. There is no HTTP-specific block. The HTTP/JSON address is the same as gRPC, as the protocol is recognized and processed accordingly.

To write traces with HTTP/JSON, POST to [address]/v1/trace. The JSON message format parallels the gRPC protobuf format. For details, refer to its OpenApi specification.

Note that max_recv_msg_size, read_buffer_size and write_buffer_size are formatted in a special way, so that the units are included in the string, e.g., “512KiB” or “1024KB”.

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:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`reload_interval`	`duration`	Frequency to reload the certificates.		no
`client_ca_file`	`string`	Path to the CA file used to authenticate client certificates.		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:

Name	Type	Description	Default	Required
`max_connection_idle`	`duration`	Maximum age for idle connections.	`"infinity"`	no
`max_connection_age`	`duration`	Maximum age for non-idle connections.	`"infinity"`	no
`max_connection_age_grace`	`duration`	Time to wait before forcibly closing connections.	`"infinity"`	no
`time`	`duration`	How often to ping inactive clients to check for liveness.	`"2h"`	no
`timeout`	`duration`	Time 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:

Name	Type	Description	Default	Required
`min_time`	`duration`	Minimum time clients should wait before sending a keepalive ping.	`"5m"`	no
`permit_without_stream`	`boolean`	Allow clients to send keepalive pings when there are no active streams.	`false`	no

output block

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

Exported fields

otelcol.receiver.opencensus does not export any fields.

Component health

otelcol.receiver.opencensus is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.opencensus does not expose any component-specific debug information.

Example

This example forwards received telemetry data through a batch processor before finally sending it to an OTLP-capable endpoint:

otelcol.receiver.opencensus "default" {
	cors_allowed_origins = ["https://*.test.com", "https://test.com"]

	grpc {
		endpoint  = "0.0.0.0:9090"
		transport = "tcp"

		max_recv_msg_size      = "32KB"
		max_concurrent_streams = "16"
		read_buffer_size       = "1024KB"
		write_buffer_size      = "1024KB"
		include_metadata       = true

		tls {
			cert_file = "test.crt"
			key_file  = "test.key"
		}

		keepalive {
			server_parameters {
				max_connection_idle      = "11s"
				max_connection_age       = "12s"
				max_connection_age_grace = "13s"
				time                     = "30s"
				timeout                  = "5s"
			}

			enforcement_policy {
				min_time              = "10s"
				permit_without_stream = true
			}
		}
	}

	output {
		metrics = [otelcol.processor.batch.default.input]
		logs    = [otelcol.processor.batch.default.input]
		traces  = [otelcol.processor.batch.default.input]
	}
}

otelcol.processor.batch "default" {
	output {
		metrics = [otelcol.exporter.otlp.default.input]
		logs    = [otelcol.exporter.otlp.default.input]
		traces  = [otelcol.exporter.otlp.default.input]
	}
}

otelcol.exporter.otlp "default" {
	client {
		endpoint = env("OTLP_ENDPOINT")
	}
}

otelcol.receiver.otlp

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.receiver.otlp

otelcol.receiver.otlp accepts OTLP-formatted data over the network and forwards it to other otelcol.* components.

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

Multiple otelcol.receiver.otlp components can be specified by giving them different labels.

Usage

otelcol.receiver.otlp "LABEL" {
  grpc { ... }
  http { ... }

  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

otelcol.receiver.otlp doesn’t support any arguments and is configured fully through inner blocks.

Blocks

The following blocks are supported inside the definition of otelcol.receiver.otlp:

Hierarchy	Block	Description	Required
grpc	grpc	Configures the gRPC server to receive telemetry data.	no
grpc > tls	tls	Configures TLS for the gRPC server.	no
grpc > keepalive	keepalive	Configures keepalive settings for the configured server.	no
grpc > keepalive > server_parameters	server_parameters	Server parameters used to configure keepalive settings.	no
grpc > keepalive > enforcement_policy	enforcement_policy	Enforcement policy for keepalive settings.	no
http	http	Configures the HTTP server to receive telemetry data.	no
http > tls	tls	Configures TLS for the HTTP server.	no
http > cors	cors	Configures CORS for the HTTP server.	no
output	output	Configures where to send received telemetry data.	yes

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

grpc block

The grpc block configures the gRPC server used by the component. If the grpc block isn’t provided, a gRPC server isn’t started.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to listen for traffic on.	`"0.0.0.0:4317"`	no
`transport`	`string`	Transport to use for the gRPC server.	`"tcp"`	no
`max_recv_msg_size`	`string`	Maximum size of messages the server will accept. 0 disables a limit.		no
`max_concurrent_streams`	`number`	Limit the number of concurrent streaming RPC calls.		no
`read_buffer_size`	`string`	Size of the read buffer the gRPC server will use for reading from clients.	`"512KiB"`	no
`write_buffer_size`	`string`	Size of the write buffer the gRPC server will use for writing to clients.		no
`include_metadata`	`boolean`	Propagate 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:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`reload_interval`	`duration`	Frequency to reload the certificates.		no
`client_ca_file`	`string`	Path to the CA file used to authenticate client certificates.		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:

Name	Type	Description	Default	Required
`max_connection_idle`	`duration`	Maximum age for idle connections.	`"infinity"`	no
`max_connection_age`	`duration`	Maximum age for non-idle connections.	`"infinity"`	no
`max_connection_age_grace`	`duration`	Time to wait before forcibly closing connections.	`"infinity"`	no
`time`	`duration`	How often to ping inactive clients to check for liveness.	`"2h"`	no
`timeout`	`duration`	Time 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:

Name	Type	Description	Default	Required
`min_time`	`duration`	Minimum time clients should wait before sending a keepalive ping.	`"5m"`	no
`permit_without_stream`	`boolean`	Allow clients to send keepalive pings when there are no active streams.	`false`	no

http block

The http block configures the HTTP server used by the component. If the http block isn’t specified, an HTTP server isn’t started.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to listen for traffic on.	`"0.0.0.0:4318"`	no
`max_request_body_size`	`string`	Maximum request body size the server will allow. No limit when unset.		no
`include_metadata`	`boolean`	Propagate incoming connection metadata to downstream consumers.		no

cors block

The cors block configures CORS settings for an HTTP server.

The following arguments are supported:

Name	Type	Description	Default	Required
`allowed_origins`	`list(string)`	Allowed values for the `Origin` header.		no
`allowed_headers`	`list(string)`	Accepted headers from CORS requests.	`["X-Requested-With"]`	no
`max_age`	`number`	Configures the `Access-Control-Max-Age` response header.		no

The allowed_headers argument 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 are permitted.

output block

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

Exported fields

otelcol.receiver.otlp does not export any fields.

Component health

otelcol.receiver.otlp is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.otlp does not expose any component-specific debug information.

Example

This example forwards received telemetry data through a batch processor before finally sending it to an OTLP-capable endpoint:

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    metrics = [otelcol.processor.batch.default.input]
    logs    = [otelcol.processor.batch.default.input]
    traces  = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlp.default.input]
    logs    = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

otelcol.exporter.otlp "default" {
  client {
    endpoint = env("OTLP_ENDPOINT")
  }
}

otelcol.receiver.prometheus

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.receiver.prometheus

otelcol.receiver.prometheus receives Prometheus metrics, converts them to the OpenTelemetry metrics format, and forwards them to other otelcol.* components.

Multiple otelcol.receiver.prometheus components can be specified by giving them different labels.

Usage

otelcol.receiver.prometheus "LABEL" {
  output {
    metrics = [...]
  }
}

Arguments

otelcol.receiver.prometheus doesn’t support any arguments and is configured fully through inner blocks.

Blocks

The following blocks are supported inside the definition of otelcol.receiver.prometheus:

Hierarchy	Block	Description	Required
output	output	Configures where to send received telemetry data.	yes

output block

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

Exported fields

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

Name	Type	Description
`receiver`	`receiver`	A value that other components can use to send Prometheus metrics to.

Component health

otelcol.receiver.prometheus is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.prometheus does not expose any component-specific debug information.

Example

This example uses the otelcol.receiver.prometheus component as a bridge between the Prometheus and OpenTelemetry ecosystems. The component exposes a receiver which the prometheus.scrape component uses to send Prometheus metric data to. The metrics are converted to the OTLP format before they are forwarded to the otelcol.exporter.otlp component to be sent to an OTLP-capable endpoint:

prometheus.scrape "default" {
    // Collect metrics from Grafana Agent's default HTTP listen address.
    targets = [{"__address__"   = "127.0.0.1:12345"}]

    forward_to = [otelcol.receiver.prometheus.default.receiver] 
}

otelcol.receiver.prometheus "default" {
  output {
    metrics = [otelcol.exporter.otlp.default.input] 
  } 
}

otelcol.exporter.otlp "default" {
  client {
    endpoint = env("OTLP_ENDPOINT")
  }
}

otelcol.receiver.zipkin

Sat, 11 Apr 2026 12:27:38 +0000

otelcol.receiver.zipkin

otelcol.receiver.zipkin accepts Zipkin-formatted traces over the network and forwards it to other otelcol.* components.

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

Multiple otelcol.receiver.zipkin components can be specified by giving them different labels.

Usage

otelcol.receiver.zipkin "LABEL" {
  output {
    traces = [...]
  }
}

Arguments

otelcol.receiver.zipkin supports the following arguments:

Name	Type	Description	Default	Required
`parse_string_tags`	`bool`	Parse string tags and binary annotations into non-string types.	`false`	no

If parse_string_tags is true, string tags and binary annotations are converted to int, bool, and float if possible. String tags and binary annotations that cannot be converted remain unchanged.

Blocks

The following blocks are supported inside the definition of otelcol.receiver.zipkin:

Hierarchy	Block	Description	Required
http	http	Configures the HTTP server to receive telemetry data.	no
http > tls	tls	Configures TLS for the HTTP server.	no
http > cors	cors	Configures CORS for the HTTP server.	no
output	output	Configures where to send received traces.	yes

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 the HTTP server used by the component.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to listen for traffic on.	`"0.0.0.0:9411"`	no
`max_request_body_size`	`string`	Maximum request body size the server will allow. No limit when unset.		no
`include_metadata`	`boolean`	Propagate 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:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`reload_interval`	`duration`	Frequency to reload the certificates.		no
`client_ca_file`	`string`	Path 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:

Name	Type	Description	Default	Required
`allowed_origins`	`list(string)`	Allowed values for the `Origin` header.		no
`allowed_headers`	`list(string)`	Accepted headers from CORS requests.	`["X-Requested-With"]`	no
`max_age`	`number`	Configures the `Access-Control-Max-Age` response header.		no

The allowed_headers argument 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 are permitted.

output block

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

Exported fields

otelcol.receiver.zipkin does not export any fields.

Component health

otelcol.receiver.zipkin is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.zipkin does not expose any component-specific debug information.

Example

This example forwards received traces through a batch processor before finally sending it to an OTLP-capable endpoint:

otelcol.receiver.zipkin "default" {
  output {
    traces = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlp.default.input]
    logs    = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

otelcol.exporter.otlp "default" {
  client {
    endpoint = env("OTLP_ENDPOINT")
  }
}

phlare.scrape

Sat, 11 Apr 2026 12:27:38 +0000

phlare.scrape

phlare.scrape configures a pprof scraping job for a given set of targets. The scraped performance profiles are forwarded to the list of receivers passed in forward_to.

Multiple phlare.scrape components can be specified by giving them different labels.

Usage

phlare.scrape "LABEL" {
  targets    = TARGET_LIST
  forward_to = RECEIVER_LIST
}

Arguments

The component configures and starts a new scrape job to scrape all of the input targets. Multiple scrape jobs can be spawned for a single input target when scraping multiple profile types.

The list of arguments that can be used to configure the block is presented below.

The scrape job name defaults to the component’s unique identifier.

Any omitted fields take on their default values. If conflicting attributes are being passed (e.g., defining both a BearerToken and BearerTokenFile or configuring both Basic Authorization and OAuth2 at the same time), the component reports an error.

The following arguments are supported:

Name	Type	Description	Default	Required
`targets`	`list(map(string))`	List of targets to scrape.		yes
`forward_to`	`list(ProfilesReceiver)`	List of receivers to send scraped profiles to.		yes
`job_name`	`string`	The job name to override the job label with.	component name	no
`params`	`map(list(string))`	A set of query parameters with which the target is scraped.		no
`scrape_interval`	`duration`	How frequently to scrape the targets of this scrape config.	`"15s"`	no
`scrape_timeout`	`duration`	The timeout for scraping targets of this config.	`"15s"`	no
`scheme`	`string`	The URL scheme with which to fetch metrics from targets.		no

Blocks

The following blocks are supported inside the definition of phlare.scrape:

Hierarchy	Block	Description	Required
http_client_config	http_client_config	HTTP client settings when connecting to targets.	no
http_client_config > basic_auth	basic_auth	Configure basic_auth for authenticating to targets.	no
http_client_config > authorization	authorization	Configure generic authorization to targets.	no
http_client_config > oauth2	oauth2	Configure OAuth2 for authenticating to targets.	no
http_client_config > oauth2 > tls_config	tls_config	Configure TLS settings for connecting to targets via OAuth2.	no
http_client_config > tls_config	tls_config	Configure TLS settings for connecting to targets.	no
profiling_config	profiling_config	Configure profiling settings for the scrape job.	no
profiling_config > profile.memory	profile.memory	Collect memory profiles.	no
profiling_config > profile.block	profile.block	Collect profiles on blocks.	no
profiling_config > profile.goroutine	profile.goroutine	Collect goroutine profiles.	no
profiling_config > profile.mutex	profile.mutex	Collect mutex profiles.	no
profiling_config > profile.process_cpu	profile.process_cpu	Collect CPU profiles.	no
profiling_config > profile.fgprof	profile.fgprof	Collect fgprof profiles.	no
profiling_config > profile.custom	profile.custom	Collect custom profiles.	no

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

http_client_config block

The http_client_config block configures settings used to connect to endpoints.

Name	Type	Description	Default	Required
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`enable_http_2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

basic_auth block

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

password and password_file are mututally exclusive and only one can be provided inside of a basic_auth block.

authorization block

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

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

oauth2 block

Name	Type	Description	Required
`client_id`	`string`	OAuth2 client ID.	no
`client_secret`	`secret`	OAuth2 client secret.	no
`client_secret_file`	`string`	File containing the OAuth2 client secret.	no
`scopes`	`list(string)`	List of scopes to authenticate with.	no
`token_url`	`string`	URL to fetch the token from.	no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.	no
`proxy_url`	`string`	Optional proxy URL for OAuth2 requests.	no

client_secret and client_secret_file are mututally exclusive and only one can be provided inside of an oauth2 block.

The oauth2 block may also contain its own separate tls_config sub-block.

tls_config block

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

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

profiling_config block

The profiling_config block configures the profiling settings when scraping targets.

The block contains the following attributes:

Name	Type	Description	Default	Required
`path_prefix`	`string`	The path prefix to use when scraping targets.		no

profile.memory block

The profile.memory block collects profiles on memory consumption.

It accepts the following arguments:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enable this profile type to be scraped.	`true`	no
`path`	`string`	The path to the profile type on the target.	`"/debug/pprof/memory"`	no
`delta`	`boolean`	Whether to scrape the profile as a delta.	`false`	no

When the delta argument is true, a seconds query parameter is automatically added to requests.

profile.block block

The profile.block block collects profiles on process blocking.

It accepts the following arguments:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enable this profile type to be scraped.	`true`	no
`path`	`string`	The path to the profile type on the target.	`"/debug/pprof/block"`	no
`delta`	`boolean`	Whether to scrape the profile as a delta.	`false`	no

When the delta argument is true, a seconds query parameter is automatically added to requests.

profile.goroutine block

The profile.goroutine block collects profiles on the number of goroutines.

It accepts the following arguments:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enable this profile type to be scraped.	`true`	no
`path`	`string`	The path to the profile type on the target.	`"/debug/pprof/goroutine"`	no
`delta`	`boolean`	Whether to scrape the profile as a delta.	`false`	no

When the delta argument is true, a seconds query parameter is automatically added to requests.

profile.mutex block

The profile.mutex block collects profiles on mutexes.

It accepts the following arguments:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enable this profile type to be scraped.	`true`	no
`path`	`string`	The path to the profile type on the target.	`"/debug/pprof/mutex"`	no
`delta`	`boolean`	Whether to scrape the profile as a delta.	`false`	no

When the delta argument is true, a seconds query parameter is automatically added to requests.

profile.process_cpu block

The profile.process_cpu block collects profiles on CPU consumption for the process.

It accepts the following arguments:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enable this profile type to be scraped.	`true`	no
`path`	`string`	The path to the profile type on the target.	`"/debug/pprof/profile"`	no
`delta`	`boolean`	Whether to scrape the profile as a delta.	`true`	no

When the delta argument is true, a seconds query parameter is automatically added to requests.

profile.fgprof block

The profile.fgprof block collects profiles from an fgprof endpoint.

It accepts the following arguments:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enable this profile type to be scraped.	`false`	no
`path`	`string`	The path to the profile type on the target.	`"/debug/fgprof"`	no
`delta`	`boolean`	Whether to scrape the profile as a delta.	`true`	no

When the delta argument is true, a seconds query parameter is automatically added to requests.

profile.custom block

The profile.custom block allows for collecting profiles from custom endpoints. Blocks must be specified with a label:

profile.custom "PROFILE_TYPE" {
  enabled = true
  path    = "PROFILE_PATH"
}

Multiple profile.custom blocks can be specified. Labels assigned to profile.custom blocks must be unique across the component.

The profile.custom block accepts the following arguments:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enable this profile type to be scraped.		yes
`path`	`string`	The path to the profile type on the target.		yes
`delta`	`boolean`	Whether to scrape the profile as a delta.	`false`	no

When the delta argument is true, a seconds query parameter is automatically added to requests.

Exported fields

phlare.scrape does not export any fields that can be referenced by other components.

Component health

phlare.scrape is only reported as unhealthy if given an invalid configuration.

Debug information

phlare.scrape reports the status of the last scrape for each configured scrape job on the component’s debug endpoint.

Debug metrics

phlare_fanout_latency (histogram): Write latency for sending to direct and indirect components.

Scraping behavior

The phlare.scrape component borrows the scraping behavior of Prometheus. Prometheus, and by extension, this component, uses a pull model for scraping profiles from a given set of targets. Each scrape target is defined as a set of key-value pairs called labels.

The set of targets can either be static, or dynamically provided periodically by a service discovery component such as discovery.kubernetes. The special label __address__ must always be present and corresponds to the <host>:<port> that is used for the scrape request.

By default, the scrape job tries to scrape all available targets’ /debug/pprof endpoints using HTTP, with a scrape interval of 15 seconds and scrape timeout of 15 seconds. The profile paths, protocol scheme, scrape interval and timeout, query parameters, as well as any other settings can be configured using the component’s arguments.

The scrape job expects profiles exposed by the endpoint to follow the pprof protobuf format. All profiles are then propagated to each receiver listed in the component’s forward_to argument.

Labels coming from targets, that start with a double underscore __ are treated as internal, and are removed prior to scraping.

The phlare.scrape component regards a scrape as successful if it responded with an HTTP 200 OK status code and returned a body of valid pprof profile.

If the scrape request fails, the component’s debug UI section contains more detailed information about the failure, the last successful scrape, as well as the labels last used for scraping.

The following labels are automatically injected to the scraped profiles and can help pin down a scrape target.

Label	Description
job	The configured job name that the target belongs to. Defaults to the fully formed component name.
instance	The `__address__` or `<host>:<port>` of the scrape target’s URL.

Example

The following example sets up the scrape job with certain attributes (profiling config, targets) and lets it scrape two local applications (the Agent itself and Phlare). The exposed profiles are sent over to the provided list of receivers, as defined by other components.

phlare.scrape "local" {
  targets    = [
    {"__address__" = "localhost:4100", "app"="phlare"},
    {"__address__" = "localhost:12345", "app"="agent"},
  ]
  forward_to = [phlare.write.local.receiver]
  profiling_config {
    profile.fgprof {
      enabled = true
    }
    profile.block {
      enabled = false
    }
    profile.mutex {
      enabled = false
    }
  }
}

Here are the the endpoints that are being scraped every 15 seconds:

http://localhost:4100/debug/pprof/allocs
http://localhost:4100/debug/pprof/goroutine
http://localhost:4100/debug/pprof/profile?seconds=14
http://localhost:4100/debug/fgprof?seconds=14
http://localhost:12345/debug/pprof/allocs
http://localhost:12345/debug/pprof/goroutine
http://localhost:12345/debug/pprof/profile?seconds=14
http://localhost:12345/debug/fgprof?seconds=14

phlare.write

Sat, 11 Apr 2026 12:27:38 +0000

phlare.write

phlare.write receives performance profiles from other components and forwards them to a series of user-supplied endpoints using Phlare’ Push API.

Multiple phlare.write components can be specified by giving them different labels.

Usage

phlare.write "LABEL" {
  endpoint {
    url = PHLARE_URL

    ...
  }

  ...
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`external_labels`	`map(string)`	Labels to add to profiles sent over the network.		no

Blocks

The following blocks are supported inside the definition of phlare.write:

Hierarchy	Block	Description	Required
endpoint	[endpoint][]	Location to send profiles to.	no
endpoint > http_client_config	[http_client_config][]	HTTP client settings when connecting to the endpoint.	no
endpoint > http_client_config > basic_auth	[basic_auth][]	Configure basic_auth for authenticating to the endpoint.	no
endpoint > http_client_config > authorization	[authorization][]	Configure generic authorization to the endpoint.	no
endpoint > http_client_config > oauth2	[oauth2][]	Configure OAuth2 for authenticating to the endpoint.	no
endpoint > http_client_config > oauth2 > tls_config	[tls_config][]	Configure TLS settings for connecting to the endpoint.	no
endpoint > http_client_config > tls_config	[tls_config][]	Configure TLS settings for connecting to the endpoint.	no

The > symbol indicates deeper levels of nesting. For example, endpoint > http_client_config refers to an http_client_config block defined inside an endpoint block.

endpoint block

The endpoint block describes a single location to send profiles to. Multiple endpoint blocks can be provided to send profiles to multiple locations.

The following arguments are supported:

Name	Type	Description	Default	Required
`url`	`string`	Full URL to send metrics to.		yes
`name`	`string`	Optional name to identify the endpoint in metrics.		no
`remote_timeout`	`duration`	Timeout for requests made to the URL.	`"30s"`	no
`headers`	`map(string)`	Extra headers to deliver with the request.		no

When multiple endpoint blocks are provided, profiles are concurrently forwarded to all configured locations.

http_client_config block

The http_client_config configures settings used to connect to the remote_write server.

Name	Type	Description	Default	Required
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`enable_http_2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

basic_auth block

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

password and password_file are mututally exclusive and only one can be provided inside of a basic_auth block.

authorization block

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

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

oauth2 block

Name	Type	Description	Required
`client_id`	`string`	OAuth2 client ID.	no
`client_secret`	`secret`	OAuth2 client secret.	no
`client_secret_file`	`string`	File containing the OAuth2 client secret.	no
`scopes`	`list(string)`	List of scopes to authenticate with.	no
`token_url`	`string`	URL to fetch the token from.	no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.	no
`proxy_url`	`string`	Optional proxy URL for OAuth2 requests.	no

client_secret and client_secret_file are mututally exclusive and only one can be provided inside of an oauth2 block.

The oauth2 block may also contain its own separate tls_config sub-block.

tls_config block

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

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

Exported fields

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

Name	Type	Description
`receiver`	`receiver`	A value that other components can use to send profiles to.

Component health

phlare.write is only reported as unhealthy if given an invalid configuration. In those cases, exported fields are kept at their last healthy values.

Debug information

phlare.write does not expose any component-specific debug information.

Example

phlare.write "staging" {
  // Send metrics to a locally running Phlare instance.
  endpoint {
    url = "http://phlare:4100"
    headers = {
      "X-Scope-Org-ID" = "squad-1",
    }
  }
  external_labels = {
    "env" = "staging",
  }
}


phlare.scrape "default" {
  targets = [
    {"__address__" = "phlare:4100", "app"="phlare"},
    {"__address__" = "agent:12345", "app"="agent"},
  ]
  forward_to = [phlare.write.staging.receiver]
}

prometheus.integration.node_exporter

Sat, 11 Apr 2026 12:27:38 +0000

prometheus.integration.node_exporter

The prometheus.integration.node_exporter component embeds node_exporter which exposes a wide variety of hardware and OS metrics for *nix-based systems.

The node_exporter itself is comprised of various collectors, which can be enabled and disabled at will. For more information on collectors, refer to the collectors-list section.

The prometheus.integration.node_exporter component can only appear once per configuration file, and a block label must not be passed to it.

Usage

prometheus.integration.node_exporter {
}

Arguments

The following arguments can be used to configure the exporter’s behavior. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`set_collectors`	`list(string)`	Overrides the default set of enabled collectors with the collectors listed.		no
`enable_collectors`	`list(string)`	Collectors to mark as enabled.		no
`disable_collectors`	`list(string)`	Collectors to mark as disabled.		no
`include_exporter_metrics`	`boolean`	Whether metrics about the exporter itself should be reported.	false	no
`procfs_path`	`string`	The procfs mountpoint.	`/proc`	no
`sysfs_path`	`string`	The sysfs mountpoint.	`/sys`	no
`rootfs_path`	`string`	Specify a prefix for accessing the host filesystem.	`/`	no

set_collectors defines a hand-picked list of enabled-by-default collectors. If set, anything not provided in that list is disabled by default. See the Collectors list for the default set of enabled collectors for each supported operating system.

enable_collectors enables more collectors over the default set, or on top of the ones provided in set_collectors.

disable_collectors extends the default set of disabled collectors. In case of conflicts, it takes precedence over enable_collectors.

Blocks

The following blocks are supported inside the definiton of prometheus.integration.node_exporter to configure collector-specific options:

Hierarchy	Name	Description	Required
bcache	bcache	Configures the bcache collector.	no
cpu	cpu	Configures the cpu collector.	no
disk	disk	Configures the diskstats collector.	no
ethtool	ethtool	Configures the ethtool collector.	no
filesystem	filesystem	Configures the filesystem collector.	no
ipvs	ipvs	Configures the ipvs collector.	no
ntp	ntp	Configures the ntp collector.	no
netclass	netclass	Configures the netclass collector.	no
netdev	netdev	Configures the netdev collector.	no
netstat	netstat	Configures the netstat collector.	no
perf	perf	Configures the perf collector.	no
powersupply	powersupply	Configures the powersupply collector.	no
runit	runit	Configures the runit collector.	no
supervisord	supervisord	Configures the supervisord collector.	no
systemd	systemd	Configures the systemd collector.	no
tapestats	tapestats	Configures the tapestats collector.	no
textfile	textfile	Configures the textfile collector.	no
vmstat	vmstat	Configures the vmstat collector.	no

bcache block

Name	Type	Description	Default	Required
`priority_stats`	`boolean`	Enable exposing of expensive bcache priority stats.	false	no

cpu block

Name	Type	Description	Default	Required
`guest`	`boolean`	Enable the `node_cpu_guest_seconds_total` metric.	true	no
`info`	`boolean`	Enable the `cpu_info metric` for the cpu collector.	true	no
`bugs_include`	`string`	Regexp of `bugs` field in cpu info to filter.		no
`flags_include`	`string`	Regexp of `flags` field in cpu info to filter.		no

disk block

Name	Type	Description	Default	Required
`ignored_devices`	`string`	Regexp of devices to ignore for diskstats.	`"^(ram\|loop\|fd\|(h\|s\|v\|xv)d[a-z]\|nvme\\d+n\\d+p)\\d+$"`	no

ethtool block

Name	Type	Description	Default	Required
`device_exclude`	`string`	Regexp of ethtool devices to exclude (mutually exclusive with `device_include`).		no
`device_include`	`string`	Regexp of ethtool devices to include (mutually exclusive with `device_exclude`).		no
`metrics_include`	`string`	Regexp of ethtool stats to include.	`.*`	no

filesystem block

Name	Type	Description	Default	Required
`fs_types_exclude`	`string`	Regexp of filesystem types to ignore for filesystem collector.	(see below )	no
`mount_points_exclude`	`string`	Regexp of mount points to ignore for filesystem collector.	`"^/(dev\|proc\|sys\|var/lib/docker/.+)($\|/)"`	no
`mount_timeout`	`duration`	How long to wait for a mount to respond before marking it as stale.	`"5s"`	no

fs_types_exclude defaults to the following regular expression string:

^(autofs\|binfmt_misc\|bpf\|cgroup2?\|configfs\|debugfs\|devpts\|devtmpfs\|fusectl\|hugetlbfs\|iso9660\|mqueue\|nsfs\|overlay\|proc\|procfs\|pstore\|rpc_pipefs\|securityfs\|selinuxfs\|squashfs\|sysfs\|tracefs)$

ipvs block

Name	Type	Description	Default	Required
`backend_labels`	`list(string)`	Array of IPVS backend stats labels.	`[local_address, local_port, remote_address, remote_port, proto, local_mark]`	no

ntp block

name	type	description	default	required
`server`	`string`	NTP server to use for the collector.	`"127.0.0.1"`	no
`server_is_local`	`boolean`	Certifies that the server address is not a public ntp server.	false	no
`ip_ttl`	`int`	TTL to use while sending NTP query.	1	no
`local_offset_tolerance`	`duration`	Offset between local clock and local ntpd time to tolerate.	`"1ms"`	no
`max_distance`	`duration`	Max accumulated distance to the root.	`"3466080us"`	no
`protocol_version`	`int`	NTP protocol version.	4	no

netclass block

name	type	description	default	required
`ignore_invalid_speed_device`	`boolean`	Ignore net devices with invalid speed values.	false	no
`ignored_devices`	`string`	Regexp of net devices to ignore for netclass collector.	`"^$"`	no

netdev block

name	type	description	default	required
`address_info`	`boolean`	Enable collecting address-info for every device.	false	no
`device_exclude`	`string`	Regexp of net devices to exclude (mutually exclusive with `device_include`).		no
`device_include`	`string`	Regexp of net devices to include (mutually exclusive with `device_exclude`).		no

netstat block

name	type	description	default	required
`fields`	`string`	Regexp of fields to return for netstat collector.	(see below)	no

fields defaults to the following regular expression string:

"^(.*_(InErrors\|InErrs)\|Ip_Forwarding\|Ip(6\|Ext)_(InOctets\|OutOctets)\|Icmp6?_(InMsgs\|OutMsgs)\|TcpExt_(Listen.*\|Syncookies.*\|TCPSynRetrans\|TCPTimeouts)\|Tcp_(ActiveOpens\|InSegs\|OutSegs\|OutRsts\|PassiveOpens\|RetransSegs\|CurrEstab)\|Udp6?_(InDatagrams\|OutDatagrams\|NoPorts\|RcvbufErrors\|SndbufErrors))$"

perf block

name	type	description	default	required
`cpus`	`string`	List of CPUs from which perf metrics should be collected.		no
`tracepoint`	`list(string)`	Array of perf tracepoints that should be collected.		no

powersupply block

name	type	description	default	required
`ignored_supplies`	`string`	Regexp of power supplies to ignore for the powersupplyclass collector.	`"^$"`	no

runit block

name	type	description	default	required
`service_dir`	`string`	Path to runit service directory.	`"/etc/service"`	no

supervisord block

name	type	description	default	required
`url`	`string`	XML RPC endpoint for the supervisord collector.	`"http://localhost:9001/RPC2"`	no

Setting SUPERVISORD_URL in the environment overrides the default value. An explicit value in the block takes precedence over the environment variable.

systemd block

name	type	description	default	required
`enable_restarts`	`boolean`	Enables service unit metric `service_restart_total`	false	no
`start_time`	`boolean`	Enables service unit metric `unit_start_time_seconds`	false	no
`task_metrics`	`boolean`	Enables service unit task metrics `unit_tasks_current` and `unit_tasks_max.`	false	no
`unit_exclude`	`string`	Regexp of systemd units to exclude. Units must both match include and not match exclude to be collected.	`".+\\.(automount\|device\|mount\|scope\|slice)"`	no
`unit_include`	`string`	Regexp of systemd units to include. Units must both match include and not match exclude to be collected.	`".+"`	no

tapestats block

name	type	description	default	required
`ignored_devices`	`string`	Regexp of tapestats devices to ignore.	`"^$"`	no

textfile block

name	type	description	default	required
`textfile_directory`	`string`	Directory to read `*.prom` files from for the textfile collector.		no

vmstat block

name	type	description	default	required
`fields`	`string`	Regexp of fields to return for the vmstat collector.	`"^(oom_kill\|pgpg\|pswp\|pg.fault)."`	no

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect `node_exporter` metrics.

For example, the targets could either be passed to a prometheus.relabel component to rewrite the metrics’ label set, or to a prometheus.scrape component that collects the exposed metrics.

Component health

prometheus.integration.node_exporter is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.integration.node_exporter does not expose any component-specific debug information.

Debug metrics

prometheus.integration.node_exporter does not expose any component-specific debug metrics.

Collectors list

The following table lists the available collectors that node_exporter brings bundled in. Some collectors only work on specific operating systems; enabling a collector that is not supported by the host OS where Flow is running is a no-op.

Users can choose to enable a subset of collectors to limit the amount of metrics exposed by the prometheus.integration.node_exporter component, or disable collectors that are expensive to run.

Name	Description	OS	Enabled by default
`arp`	Exposes ARP statistics from `/proc/net/arp`.	Linux	yes
`bcache`	Exposes bcache statistics from `/sys/fs/bcache`.	Linux	yes
`bonding`	Exposes the number of configured and active slaves of Linux bonding interfaces.	Linux	yes
`boottime`	Exposes system boot time derived from the `kern.boottime sysctl`.	Darwin, Dragonfly, FreeBSD, NetBSD, OpenBSD, Solaris	yes
`btrfs`	Exposes statistics on btrfs.	Linux	yes
`buddyinfo`	Exposes statistics of memory fragments as reported by `/proc/buddyinfo`.	Linux	no
`conntrack`	Shows conntrack statistics (does nothing if no `/proc/sys/net/netfilter/` present).	Linux	yes
`cpu`	Exposes CPU statistics.	Darwin, Dragonfly, FreeBSD, Linux, Solaris	yes
`cpufreq`	Exposes CPU frequency statistics.	Linux, Solaris	yes
`devstat`	Exposes device statistics.	Dragonfly, FreeBSD	no
`diskstats`	Exposes disk I/O statistics.	Darwin, Linux, OpenBSD	yes
`dmi`	Exposes DMI information.	Linux	yes
`drbd`	Exposes Distributed Replicated Block Device statistics (to version 8.4).	Linux	no
`drm`	Exposes GPU card info from `/sys/class/drm/card?/device`.	Linux	no
`edac`	Exposes error detection and correction statistics.	Linux	yes
`entropy`	Exposes available entropy.	Linux	yes
`ethtool`	Exposes ethtool stats.	Linux	no
`exec`	Exposes execution statistics.	Dragonfly, FreeBSD	yes
`fibrechannel`	Exposes FibreChannel statistics.	Linux	yes
`filefd`	Exposes file descriptor statistics from `/proc/sys/fs/file-nr`.	Linux	yes
`filesystem`	Exposes filesystem statistics, such as disk space used.	Darwin, Dragonfly, FreeBSD, Linux, OpenBSD	yes
`hwmon`	Exposes hardware monitoring and sensor data from `/sys/class/hwmon`.	Linux	yes
`infiniband`	Exposes network statistics specific to InfiniBand and Intel OmniPath configurations.	Linux	yes
`interrupts`	Exposes detailed interrupts statistics.	Linux, OpenBSD	no
`ipvs`	Exposes IPVS status from `/proc/net/ip_vs` and stats from `/proc/net/ip_vs_stats`.	Linux	yes
`ksmd`	Exposes kernel and system statistics from `/sys/kernel/mm/ksm`.	Linux	no
`lnstat`	Exposes Linux network cache stats.	Linux	no
`loadavg`	Exposes load average.	Darwin, Dragonfly, FreeBSD, Linux, NetBSD, OpenBSD, Solaris	yes
`logind`	Exposes session counts from logind.	Linux	no
`mdadm`	Exposes statistics about devices in `/proc/mdstat` (does nothing if no `/proc/mdstat` present).	Linux	yes
`meminfo`	Exposes memory statistics.	Darwin, Dragonfly, FreeBSD, Linux, OpenBSD	yes
`meminfo_numa`	Exposes memory statistics from `/proc/meminfo_numa`.	Linux	no
`mountstats`	Exposes filesystem statistics from `/proc/self/mountstats`. Exposes detailed NFS client statistics.	Linux	no
`netclass`	Exposes network interface info from `/sys/class/net`.	Linux	yes
`netdev`	Exposes network interface statistics such as bytes transferred.	Darwin, Dragonfly, FreeBSD, Linux, OpenBSD	yes
`netstat`	Exposes network statistics from `/proc/net/netstat`. This is the same information as `netstat -s`.	Linux	yes
`network_route`	Exposes network route statistics.	Linux	no
`nfs`	Exposes NFS client statistics from `/proc/net/rpc/nfs`. This is the same information as `nfsstat -c`.	Linux	yes
`nfsd`	Exposes NFS kernel server statistics from `/proc/net/rpc/nfsd`. This is the same information as `nfsstat -s`.	Linux	yes
`ntp`	Exposes local NTP daemon health to check time.	any	no
`nvme`	Exposes NVMe statistics.	Linux	yes
`os`	Exposes os-release information.	Linux	yes
`perf`	Exposes perf based metrics (Warning: Metrics are dependent on kernel configuration and settings).	Linux	no
`powersupplyclass`	Collects information on power supplies.	any	yes
`pressure`	Exposes pressure stall statistics from `/proc/pressure/`.	Linux (kernel 4.20+ and/or CONFIG_PSI)	yes
`processes`	Exposes aggregate process statistics from /proc.	Linux	no
`qdisc`	Exposes queuing discipline statistics.	Linux	no
`rapl`	Exposes various statistics from `/sys/class/powercap`.	Linux	yes
`runit`	Exposes service status from runit.	any	no
`schedstat`	Exposes task scheduler statistics from `/proc/schedstat`.	Linux	yes
`sockstat`	Exposes various statistics from `/proc/net/sockstat`.	Linux	yes
`softnet`	Exposes statistics from `/proc/net/softnet_stat`.	Linux	yes
`stat`	Exposes various statistics from `/proc/stat`. This includes boot time, forks and interrupts.	Linux	yes
`supervisord`	Exposes service status from supervisord.	any	no
`systemd`	Exposes service and system status from systemd.	Linux	no
`tapestats`	Exposes tape device stats.	Linux	yes
`tcpstat`	Exposes TCP connection status information from `/proc/net/tcp` and `/proc/net/tcp6`. (Warning: The current version has potential performance issues in high load situations.)	Linux	no
`textfile`	Collects metrics from files in a directory matching the filename pattern `*.prom`. The files must be using the text format defined here: https://prometheus.io/docs/instrumenting/exposition_formats/.	any	yes
`thermal`	Exposes thermal statistics.	Darwin	yes
`thermal_zone`	Exposes thermal zone & cooling device statistics from `/sys/class/thermal`.	Linux	yes
`time`	Exposes the current system time.	any	yes
`timex`	Exposes selected `adjtimex(2)` system call stats.	Linux	yes
`udp_queues`	Exposes UDP total lengths of the `rx_queue` and `tx_queue` from `/proc/net/udp` and `/proc/net/udp6`.	Linux	yes
`uname`	Exposes system information as provided by the uname system call.	Darwin, FreeBSD, Linux, OpenBSD	yes
`vmstat`	Exposes statistics from `/proc/vmstat`.	Linux	yes
`wifi`	Exposes WiFi device and station statistics.	Linux	no
`xfs`	Exposes XFS runtime statistics.	Linux (kernel 4.4+)	yes
`zfs`	Exposes ZFS performance statistics.	Linux, Solaris	yes
`zoneinfo`	Exposes zone stats.	Linux	no

Running on Docker/Kubernetes

When running Flow in a Docker container, you need to bind mount the filesystem, procfs, and sysfs from the host machine, as well as set the corresponding arguments for the component to work.

You may also need to add capabilities such as SYS_TIME and make sure that the Agent is running with elevated privileges for some of the collectors to work properly.

Example

This example uses a prometheus.scrape component to collect metrics from prometheus.integration.node_exporter:

prometheus.integration.node_exporter {
}

// Configure a prometheus.scrape component to collect node_exporter metrics.
prometheus.scrape "demo" {
  targets    = prometheus.integration.node_exporter.targets
  forward_to = [ /* ... */ ]
}

prometheus.relabel

Sat, 11 Apr 2026 12:27:38 +0000

prometheus.relabel

Prometheus metrics follow the OpenMetrics format. Each time series is uniquely identified by its metric name, plus optional key-value pairs called labels. Each sample represents a datapoint in the time series and contains a value and an optional timestamp.

<metric name>{<label_1>=<label_val_1>, <label_2>=<label_val_2> ...} <value> [timestamp]

The prometheus.relabel component rewrites the label set of each metric passed along to the exported receiver by applying one or more relabeling rules. If no rules are defined or applicable to some metrics, then those metrics are forwarded as-is to each receiver passed in the component’s arguments. If no labels remain after the relabeling rules are applied, then the metric is dropped.

The most common use of prometheus.relabel is to filter Prometheus metrics or standardize the label set that is passed to one or more downstream receivers. The rule blocks are applied to the label set of each metric in order of their appearance in the configuration file. The configured rules can be retrieved by calling the function in the rules export field.

Multiple prometheus.relabel components can be specified by giving them different labels.

Usage

prometheus.relabel "LABEL" {
  forward_to = RECEIVER_LIST

  rule {
    ...
  }

  ...
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`forward_to`	`list(receiver)`	Where the metrics should be forwarded to, after relabeling takes place.		yes

Blocks

The following blocks are supported inside the definition of prometheus.relabel:

Hierarchy	Name	Description	Required
rule	rule	Relabeling rules to apply to received metrics.	no

rule block

The rule block contains the definition of any relabeling rules that can be applied to an input metric. If more than one rule block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a rule. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`source_labels`	`list(string)`	The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.		no
`separator`	`string`	The separator used to concatenate the values present in `source_labels`.	;	no
`regex`	`string`	A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions.	`(.*)`	no
`modulus`	`uint`	A positive integer used to calculate the modulus of the hashed source label values.		no
`target_label`	`string`	Label to which the resulting value will be written to.		no
`replacement`	`string`	The value against which a regex replace is performed, if the regex matches the extracted value. Supports previously captured groups.	$1	no
`action`	`string`	The relabeling action to perform.	replace	no

Here’s a list of the available actions, along with a brief description of their usage.

replace - Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
keep - Keeps metrics where regex matches the string extracted using the source_labels and separator.
drop - Drops metrics where regex matches the string extracted using the source_labels and separator.
hashmod - Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
labeldrop - Matches regex against all label names. Any labels that match are removed from the metric’s label set.
labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the metric’s label set.

Finally, note that the regex capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

Exported fields

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

Name	Type	Description
`receiver`	`receiver`	The input receiver where samples are sent to be relabeled.
`rules`	`RelabelRules`	The currently configured relabeling rules.

Component health

prometheus.relabel is only reported as unhealthy if given an invalid configuration. In those cases, exported fields are kept at their last healthy values.

Debug information

prometheus.relabel does not expose any component-specific debug information.

Debug metrics

agent_prometheus_relabel_metrics_processed (counter): Total number of metrics processed.
agent_prometheus_relabel_metrics_written (counter): Total number of metrics written.
agent_prometheus_relabel_cache_misses (counter): Total number of cache misses.
agent_prometheus_relabel_cache_hits (counter): Total number of cache hits.
agent_prometheus_relabel_cache_size (gauge): Total size of relabel cache.
agent_prometheus_fanout_latency (histogram): Write latency for sending to direct and indirect components.

Example

Let’s create an instance of a see prometheus.relabel component and see how it acts on the following metrics.

prometheus.relabel "keep_backend_only" {
  forward_to = [prometheus.remote_write.onprem.receiver]

  rule {
    action        = "replace"
    source_labels = ["__address__", "instance"]
    separator     = "/"
    target_label  = "host"
  }
  rule {
    action        = "keep"
    source_labels = ["app"]
    regex         = "backend"
  }
  rule {
    action = "labeldrop"
    regex  = "instance"
  }
}

metric_a{__address__ = "localhost", instance = "development", app = "frontend"} 10
metric_a{__address__ = "localhost", instance = "development", app = "backend"}  2
metric_a{__address__ = "cluster_a", instance = "production",  app = "frontend"} 7
metric_a{__address__ = "cluster_a", instance = "production",  app = "backend"}  9
metric_a{__address__ = "cluster_b", instance = "production",  app = "database"} 4

After applying the first rule, the replace action populates a new label named host by concatenating the contents of the __address__ and instance labels, separated by a slash /.

metric_a{host = "localhost/development", __address__ = "localhost", instance = "development", app = "frontend"} 10
metric_a{host = "localhost/development", __address__ = "localhost", instance = "development", app = "backend"}  2
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", instance = "production",  app = "frontend"} 7
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", instance = "production",  app = "backend"}  9
metric_a{host = "cluster_b/production",  __address__ = "cluster_a", instance = "production",  app = "database"} 4

On the second relabeling rule, the keep action only keeps the metrics whose app label matches regex, dropping everything else, so the list of metrics is be trimmed down to:

metric_a{host = "localhost/development", __address__ = "localhost", instance = "development", app = "backend"}  2
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", instance = "production",  app = "backend"}  9

The third and final relabeling rule which uses the labeldrop action removes the instance label from the set of labels.

So in this case, the initial set of metrics passed to the exported receiver is:

metric_a{host = "localhost/development", __address__ = "localhost", app = "backend"}  2
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", app = "backend"}  9

The two resulting metrics are then propagated to each receiver defined in the forward_to argument.

prometheus.remote_write

Sat, 11 Apr 2026 12:27:38 +0000

prometheus.remote_write

prometheus.remote_write collects metrics sent from other components into a Write-Ahead Log (WAL) and forwards them over the network to a series of user-supplied endpoints. Metrics are sent over the network using the Prometheus Remote Write protocol.

Multiple prometheus.remote_write components can be specified by giving them different labels.

Usage

prometheus.remote_write "LABEL" {
  endpoint {
    url = REMOTE_WRITE_URL

    ...
  }

  ...
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`external_labels`	`map(string)`	Labels to add to metrics sent over the network.		no

Blocks

The following blocks are supported inside the definition of prometheus.remote_write:

Hierarchy	Block	Description	Required
endpoint	endpoint	Location to send metrics to.	no
endpoint > http_client_config	http_client_config	HTTP client settings when connecting to the endpoint.	no
endpoint > http_client_config > basic_auth	basic_auth	Configure basic_auth for authenticating to the endpoint.	no
endpoint > http_client_config > authorization	authorization	Configure generic authorization to the endpoint.	no
endpoint > http_client_config > oauth2	oauth2	Configure OAuth2 for authenticating to the endpoint.	no
endpoint > http_client_config > oauth2 > tls_config	tls_config	Configure TLS settings for connecting to the endpoint.	no
endpoint > http_client_config > tls_config	tls_config	Configure TLS settings for connecting to the endpoint.	no
endpoint > queue_config	queue_config	Configuration for how metrics are batched before sending.	no
endpoint > metadata_config	metadata_config	Configuration for how metric metadata is sent.	no
wal	wal	Configuration for the component’s WAL.	no

The > symbol indicates deeper levels of nesting. For example, endpoint > http_client_config refers to an http_client_config block defined inside an endpoint block.

endpoint block

The endpoint block describes a single location to send metrics to. Multiple endpoint blocks can be provided to send metrics to multiple locations.

The following arguments are supported:

Name	Type	Description	Default	Required
`url`	`string`	Full URL to send metrics to.		yes
`name`	`string`	Optional name to identify the endpoint in metrics.		no
`remote_timeout`	`duration`	Timeout for requests made to the URL.	`"30s"`	no
`headers`	`map(string)`	Extra headers to deliver with the request.		no
`send_exemplars`	`bool`	Whether exemplars should be sent.	`true`	no
`send_native_histograms`	`bool`	Whether native histograms should be sent.	`false`	no

When multiple endpoint blocks are provided, metrics are concurrently sent to all configured locations. Each endpoint has a queue which is used to read metrics from the WAL and queue them for sending. The queue_config block can be used to customize the behavior of the queue.

Endpoints can be named for easier identification in debug metrics using the name argument. If the name argument isn’t provided, a name is generated based on a hash of the endpoint settings.

When send_native_histograms is true, native Prometheus histogram samples sent to prometheus.remote_write are forwarded to the configured endpoint. If the endpoint doesn’t support receiving native histogram samples, pushing metrics fails.

http_client_config block

The http_client_config configures settings used to connect to the remote_write server.

Name	Type	Description	Default	Required
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`enable_http_2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

basic_auth block

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

password and password_file are mututally exclusive and only one can be provided inside of a basic_auth block.

authorization block

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

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

oauth2 block

Name	Type	Description	Required
`client_id`	`string`	OAuth2 client ID.	no
`client_secret`	`secret`	OAuth2 client secret.	no
`client_secret_file`	`string`	File containing the OAuth2 client secret.	no
`scopes`	`list(string)`	List of scopes to authenticate with.	no
`token_url`	`string`	URL to fetch the token from.	no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.	no
`proxy_url`	`string`	Optional proxy URL for OAuth2 requests.	no

client_secret and client_secret_file are mututally exclusive and only one can be provided inside of an oauth2 block.

The oauth2 block may also contain its own separate tls_config sub-block.

tls_config block

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

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

queue_config block

Name	Type	Description	Default	Required
`capacity`	`number`	Number of samples to buffer per shard.	`2500`	no
`min_shards`	`number`	Minimum amount of concurrent shards sending samples to the endpoint.	`1`	no
`max_shards`	`number`	Maximum number of concurrent shards sending samples to the endpoint.	`200`	no
`max_samples_per_send`	`number`	Maximum number of samples per send.	`500`	no
`batch_send_deadline`	`duration`	Maximum time samples will wait in the buffer before sending.	`"5s"`	no
`min_backoff`	`duration`	Initial retry delay. The backoff time gets doubled for each retry.	`"30ms"`	no
`max_backoff`	`duration`	Maximum retry delay.	`"5s"`	no
`retry_on_http_429`	`bool`	Retry when an HTTP 429 status code is received.	`false`	no

Each queue then manages a number of concurrent shards which is responsible for sending a fraction of data to their respective endpoints. The number of shards is automatically raised if samples are not being sent to the endpoint quickly enough. The range of permitted shards can be configured with the min_shards and max_shards arguments.

Each shard has a buffer of samples it will keep in memory, controlled with the capacity argument. New metrics aren’t read from the WAL unless there is at least one shard that is not at maximum capcity.

The buffer of a shard is flushed and sent to the endpoint either after the shard reaches the number of samples specified by max_samples_per_send or the duration specified by batch_send_deadline has elapsed since the last flush for that shard.

Shards retry requests which fail due to a recoverable error. An error is recoverable if the server responds with an HTTP 5xx status code. The delay between retries can be customized with the min_backoff and max_backoff arguments.

The retry_on_http_429 argument specifies whether HTTP 429 status code responses should be treated as recoverable errors; other HTTP 4xx status code responses are never considered recoverable errors. When retry_on_http_429 is enabled, Retry-After response headers from the servers are honored.

metadata_config block

Name	Type	Description	Default	Required
`send`	`bool`	Controls whether metric metadata is sent to the endpoint.	`true`	no
`send_interval`	`duration`	How frequently metric metadata is sent to the endpoint.	`"1m"`	no
`max_samples_per_send`	`number`	Maximum number of metadata samples to send to the endpoint at once.	`500`	no

wal block

The wal block customizes the Write-Ahead Log (WAL) used to temporarily store metrics before they are sent to the configured set of endpoints.

Name	Type	Description	Default	Required
`truncate_frequency`	`duration`	How frequently to clean up the WAL.	`"2h"`	no
`min_keepalive_time`	`duration`	Minimum time to keep data in the WAL before it can be removed.	`"5m"`	no
`max_keepalive_time`	`duration`	Maximum time to keep data in the WAL before removing it.	`"8h"`	no

The WAL serves two primary purposes:

Buffer unsent metrics in case of intermittent network issues.
Populate in-memory cache after a process restart.

The WAL is located inside a component-specific directory relative to the storage path Grafana Agent is configured to use. See the agent run documentation for how to change the storage path.

The truncate_frequency argument configures how often to clean up the WAL. Every time the truncate_frequency period elapses, the lower two-thirds of data is removed from the WAL and is no available for sending.

When a WAL clean-up starts, the lowest successfully sent timestamp is used to determine how much data is safe to remove from the WAL. The min_keepalive_time and max_keepalive_time control the permitted age range of data in the WAL; samples aren’t removed until they are at least as old as min_keepalive_time, and samples are forcibly removed if they are older than max_keepalive_time.

Exported fields

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

Name	Type	Description
`receiver`	`receiver`	A value which other components can use to send metrics to.

Component health

prometheus.remote_write is only reported as unhealthy if given an invalid configuration. In those cases, exported fields are kept at their last healthy values.

Debug information

prometheus.remote_write does not expose any component-specific debug information.

Debug metrics

agent_wal_storage_active_series (gauge): Current number of active series being tracked by the WAL.
agent_wal_storage_deleted_series (gauge): Current number of series marked for deletion from memory.
agent_wal_storage_created_series_total (counter): Total number of created series appended to the WAL.
agent_wal_storage_removed_series_total (counter): Total number of series removed from the WAL.
agent_wal_samples_appended_total (counter): Total number of samples appended to the WAL.
agent_wal_exemplars_appended_total (counter): Total number of exemplars appended to the WAL.
prometheus_remote_storage_samples_total (counter): Total number of samples sent to remote storage.
prometheus_remote_storage_exemplars_total (counter): Total number of exemplars sent to remote storage.
prometheus_remote_storage_metadata_total (counter): Total number of metadata entries sent to remote storage.
prometheus_remote_storage_samples_failed_total (counter): Total number of samples that failed to send to remote storage due to non-recoverable errors.
prometheus_remote_storage_exemplars_failed_total (counter): Total number of exemplars that failed to send to remote storage due to non-recoverable errors.
prometheus_remote_storage_metadata_failed_total (counter): Total number of metadata entries that failed to send to remote storage due to non-recoverable errors.
prometheus_remote_storage_samples_retries_total (counter): Total number of samples that failed to send to remote storage but were retried due to recoverable errors.
prometheus_remote_storage_exemplars_retried_total (counter): Total number of exemplars that failed to send to remote storage but were retried due to recoverable errors.
prometheus_remote_storage_metadata_retried_total (counter): Total number of metadata entries that failed to send to remote storage but were retried due to recoverable errors.
prometheus_remote_storage_samples_dropped_total (counter): Total number of samples which were dropped after being read from the WAL before being sent to remote_write because of an unknown reference ID.
prometheus_remote_storage_exemplars_dropped_total (counter): Total number of exemplars which were dropped after being read from the WAL before being sent to remote_write because of an unknown reference ID.
prometheus_remote_storage_enqueue_retries_total (counter): Total number of times enqueue has failed because a shard’s queue was full.
prometheus_remote_storage_sent_batch_duration_seconds (histogram): Duration of send calls to remote storage.
prometheus_remote_storage_queue_highest_sent_timestamp_seconds (gauge): Unix timestamp of the latest WAL sample successfully sent by a queue.
prometheus_remote_storage_samples_pending (gauge): The number of samples pending in shards to be sent to remote storage.
prometheus_remote_storage_exemplars_pending (gauge): The number of exemplars pending in shards to be sent to remote storage.
prometheus_remote_storage_shard_capacity (gauge): The capacity of shards within a given queue.
prometheus_remote_storage_shards (gauge): The number of shards used for concurrent delivery of metrics to an endpoint.
prometheus_remote_storage_shards_min (gauge): The minimum number of shards a queue is allowed to run.
prometheus_remote_storage_shards_max (gauge): The maximum number of a shards a queue is allowed to run.
prometheus_remote_storage_shards_desired (gauge): The number of shards a queue wants to run to be able to keep up with the amount of incoming metrics.
prometheus_remote_storage_bytes_total (counter): Total number of bytes of data sent by queues after compression.
prometheus_remote_storage_metadata_bytes_total (counter): Total number of bytes of metadata sent by queues after compression.
prometheus_remote_storage_max_samples_per_send (gauge): The maximum number of samples each shard is allowed to send in a single request.
prometheus_remote_storage_samples_in_total (counter): Samples read into remote storage.
prometheus_remote_storage_exemplars_in_total (counter): Exemplars read into remote storage.

Example

prometheus.remote_write "staging" {
  // Send metrics to a locally running Mimir.
  endpoint {
    url = "http://mimir:9009/api/v1/push"

    http_client_config {
      basic_auth {
        username = "example-user"
        password = "example-password"
      }
    }
  }
}

// Configure a prometheus.scrape component to send metrics to
// prometheus.remote_write component.
prometheus.scrape "demo" {
  targets = [
    // Collect metrics from Grafana Agent's default HTTP listen address.
    {"__address__" = "127.0.0.1:12345"},
  ]
  forward_to = [prometheus.remote_write.staging.receiver]
}

prometheus.scrape

Sat, 11 Apr 2026 12:27:38 +0000

prometheus.scrape

prometheus.scrape configures a Prometheus scraping job for a given set of targets. The scraped metrics are forwarded to the list of receivers passed in forward_to.

Multiple prometheus.scrape components can be specified by giving them different labels.

Usage

prometheus.scrape "LABEL" {
  targets    = TARGET_LIST
  forward_to = RECEIVER_LIST
}

Arguments

The component configures and starts a new scrape job to scrape all of the input targets. The list of arguments that can be used to configure the block is presented below.

The scrape job name defaults to the component’s unique identifier.

Any omitted fields take on their default values. In case that conflicting attributes are being passed (eg. defining both a BearerToken and BearerTokenFile or configuring both Basic Authorization and OAuth2 at the same time), the component reports an error.

The following arguments are supported:

Name	Type	Description	Default	Required
`targets`	`list(map(string))`	List of targets to scrape.		yes
`forward_to`	`list(MetricsReceiver)`	List of receivers to send scraped metrics to.		yes
`job_name`	`string`	The job name to override the job label with.	component name	no
`extra_metrics`	`bool`	Whether extra metrics should be generated for scrape targets.	`false`	no
`honor_labels`	`bool`	Indicator whether the scraped metrics should remain unmodified.	`false`	no
`honor_timestamps`	`bool`	Indicator whether the scraped timestamps should be respected.	`true`	no
`params`	`map(list(string))`	A set of query parameters with which the target is scraped.		no
`scrape_interval`	`duration`	How frequently to scrape the targets of this scrape config.	`"60s"`	no
`scrape_timeout`	`duration`	The timeout for scraping targets of this config.	`"10s"`	no
`metrics_path`	`string`	The HTTP resource path on which to fetch metrics from targets.	`/metrics`	no
`scheme`	`string`	The URL scheme with which to fetch metrics from targets.		no
`body_size_limit`	`int`	An uncompressed response body larger than this many bytes causes the scrape to fail. 0 means no limit.		no
`sample_limit`	`uint`	More than this many samples post metric-relabeling causes the scrape to fail		no
`target_limit`	`uint`	More than this many targets after the target relabeling causes the scrapes to fail.		no
`label_limit`	`uint`	More than this many labels post metric-relabeling causes the scrape to fail.		no
`label_name_length_limit`	`uint`	More than this label name length post metric-relabeling causes the scrape to fail.		no
`label_value_length_limit`	`uint`	More than this label value length post metric-relabeling causes the scrape to fail.		no

Blocks

The following blocks are supported inside the definition of prometheus.scrape:

Hierarchy	Block	Description	Required
http_client_config	http_client_config	HTTP client settings when connecting to targets.	no
http_client_config > basic_auth	basic_auth	Configure basic_auth for authenticating to targets.	no
http_client_config > authorization	authorization	Configure generic authorization to targets.	no
http_client_config > oauth2	oauth2	Configure OAuth2 for authenticating to targets.	no
http_client_config > oauth2 > tls_config	tls_config	Configure TLS settings for connecting to targets via OAuth2.	no
http_client_config > tls_config	tls_config	Configure TLS settings for connecting to targets.	no

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

http_client_config block

The http_client_config block configures settings used to connect to endpoints.

Name	Type	Description	Default	Required
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`enable_http_2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

basic_auth block

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

password and password_file are mututally exclusive and only one can be provided inside of a basic_auth block.

authorization block

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

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

oauth2 block

Name	Type	Description	Required
`client_id`	`string`	OAuth2 client ID.	no
`client_secret`	`secret`	OAuth2 client secret.	no
`client_secret_file`	`string`	File containing the OAuth2 client secret.	no
`scopes`	`list(string)`	List of scopes to authenticate with.	no
`token_url`	`string`	URL to fetch the token from.	no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.	no
`proxy_url`	`string`	Optional proxy URL for OAuth2 requests.	no

client_secret and client_secret_file are mututally exclusive and only one can be provided inside of an oauth2 block.

The oauth2 block may also contain its own separate tls_config sub-block.

tls_config block

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

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

Exported fields

prometheus.scrape does not export any fields that can be referenced by other components.

Component health

prometheus.scrape is only reported as unhealthy if given an invalid configuration.

Debug information

prometheus.scrape reports the status of the last scrape for each configured scrape job on the component’s debug endpoint.

Debug metrics

agent_prometheus_fanout_latency (histogram): Write latency for sending to direct and indirect components.

Scraping behavior

The prometheus.scrape component borrows the scraping behavior of Prometheus. Prometheus, and by extent this component, uses a pull model for scraping metrics from a given set of targets. Each scrape target is defined as a set of key-value pairs called labels. The set of targets can either be static, or dynamically provided periodically by a service discovery component such as discovery.kubernetes. The special label __address__ must always be present and corresponds to the <host>:<port> that is used for the scrape request.

By default, the scrape job tries to scrape all available targets’ /metrics endpoints using HTTP, with a scrape interval of 1 minute and scrape timeout of 10 seconds. The metrics path, protocol scheme, scrape interval and timeout, query parameters, as well as any other settings can be configured using the component’s arguments.

The scrape job expects the metrics exposed by the endpoint to follow the OpenMetrics format. All metrics are then propagated to each receiver listed in the component’s forward_to argument.

Labels coming from targets, that start with a double underscore __ are treated as internal, and are removed prior to scraping.

The prometheus.scrape component regards a scrape as successful if it responded with an HTTP 200 OK status code and returned a body of valid metrics.

If the scrape request fails, the component’s debug UI section contains more detailed information about the failure, the last successful scrape, as well as the labels last used for scraping.

The following labels are automatically injected to the scraped time series and can help pin down a scrape target.

Label	Description
job	The configured job name that the target belongs to. Defaults to the fully formed component name.
instance	The `__address__` or `<host>:<port>` of the scrape target’s URL.

Similarly, these metrics that record the behavior of the scrape targets are also automatically available.

Metric Name	Description
`up`	1 if the instance is healthy and reachable, or 0 if the scrape failed.
`scrape_duration_seconds`	Duration of the scrape in seconds.
`scrape_samples_scraped`	The number of samples the target exposed.
`scrape_samples_post_metric_relabeling`	The number of samples remaining after metric relabeling was applied.
`scrape_series_added`	The approximate number of new series in this scrape.
`scrape_timeout_seconds`	The configured scrape timeout for a target. Useful for measuring how close a target was to timing out using `scrape_duration_seconds / scrape_timeout_seconds`
`scrape_sample_limit`	The configured sample limit for a target. Useful for measuring how close a target was to reaching the sample limit using `scrape_samples_post_metric_relabeling / (scrape_sample_limit > 0)`
`scrape_body_size_bytes`	The uncompressed size of the most recent scrape response, if successful. Scrapes failing because the `body_size_limit` is exceeded report -1, other scrape failures report 0.

The up metric is particularly useful for monitoring and alerting on the health of a scrape job. It is set to 0 in case anything goes wrong with the scrape target, either because it is not reachable, because the connection times out while scraping, or because the samples from the target could not be processed. When the target is behaving normally, the up metric is set to 1.

Example

The following example sets up the scrape job with certain attributes (scrape endpoint, scrape interval, query parameters) and lets it scrape two instances of the blackbox exporter. The exposed metrics are sent over to the provided list of receivers, as defined by other components.

prometheus.scrape "blackbox_scraper" {
  targets = [
    {"__address__" = "blackbox-exporter:9115", "instance" = "one"},
    {"__address__" = "blackbox-exporter:9116", "instance" = "two"},
  ]

  forward_to = [prometheus.remote_write.grafanacloud.receiver, prometheus.remote_write.onprem.receiver]

  scrape_interval = "10s"
  params          = { "target" = ["grafana.com"], "module" = ["http_2xx"] }
  metrics_path    = "/probe"
}

Here’s the the endpoints that are being scraped every 10 seconds:

http://blackbox-exporter:9115/probe?target=grafana.com&module=http_2xx
http://blackbox-exporter:9116/probe?target=grafana.com&module=http_2xx

remote.http

Sat, 11 Apr 2026 12:27:38 +0000

remote.http

remote.http exposes the response body of a URL to other components. The URL is polled for changes so that the most recent content is always available.

The most common use of remote.http is to load discovery targets from an HTTP server.

Multiple remote.http components can be specified by giving them different labels.

Usage

remote.http "LABEL" {
  url = "URL_TO_POLL"
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`url`	`string`	URL to poll.		yes
`poll_frequency`	`duration`	Frequency to poll the URL.	`"1m"`	no
`poll_timeout`	`duration`	Timeout when polling the URL.	`"10s"`	no
`is_secret`	`bool`	Whether the response body should be treated as a secret.	false	no

When remote.http performs a poll operation, an HTTP GET request is made against the URL specified by the url argument. A poll is triggered by the following:

When the component first loads.
Every time the component’s arguments get re-evaluated.
At the frequency specified by the poll_frequency argument.

The poll is successful if the URL returns a 200 OK response code. All other response codes are treated as errors and mark the component as unhealthy. After a successful poll, the response body from the URL is exported.

Blocks

The following blocks are supported inside the definition of remote.http:

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

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

client block

The client block configures settings used to connect to the HTTP server.

Name	Type	Description	Default	Required
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`enable_http_2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive and only one can be provided inside of a http_client_config block.

basic_auth block

The basic_auth block configures basic authentication to use when polling the configured URL.

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

password and password_file are mututally exclusive and only one can be provided inside of a basic_auth block.

authorization block

The authorization block configures custom authorization to use when polling the configured URL.

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

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

oauth2 block

The oauth2 block configures OAuth2 authorization to use when polling the configured URL.

Name	Type	Description	Required
`client_id`	`string`	OAuth2 client ID.	no
`client_secret`	`secret`	OAuth2 client secret.	no
`client_secret_file`	`string`	File containing the OAuth2 client secret.	no
`scopes`	`list(string)`	List of scopes to authenticate with.	no
`token_url`	`string`	URL to fetch the token from.	no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.	no
`proxy_url`	`string`	Optional proxy URL for OAuth2 requests.	no

client_secret and client_secret_file are mututally exclusive and only one can be provided inside of an oauth2 block.

The oauth2 block may also contain its own separate tls_config sub-block.

tls_config block

The tls_config block configures TLS settings for connecting to HTTPS servers.

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

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

Exported fields

The following field is exported and can be referenced by other components:

Name	Type	Description	Default	Required
`content`	`string` or `secret`	The contents of the file.		no

If the is_secret argument was true, content is a secret type.

Component health

Instances of remote.http report as healthy if the most recent HTTP GET request of the specified URL succeeds.

Debug information

remote.http does not expose any component-specific debug information.

Debug metrics

remote.http does not expose any component-specific debug metrics.

Example

This example reads a JSON array of objects from an endpoint and uses them as a set of scrape targets:

remote.http "targets" {
  url = env("MY_TARGETS_URL")
}

prometheus.scrape "default" {
  targets    = json_decode(remote.http.targets.content)
  forward_to = [prometheus.remote_write.default.receiver]
}

prometheus.remote_write "default" {
  client {
    url = env("PROMETHEUS_URL")
  }
}

remote.s3

Sat, 11 Apr 2026 12:27:38 +0000

remote.s3

remote.s3 exposes the string contents of a file located in AWS S3 to other components. The file will be polled for changes so that the most recent content is always available.

The most common use of remote.s3 is to load secrets from files.

Multiple remote.s3 components can be specified using different name labels. By default, AWS environment variables are used to authenticate against S3. The key and secret arguments inside client_options blocks can be used to provide custom authentication.

NOTE: Other S3-compatible systems can be read with remote.s3 but may require specific authentication environment variables. There is no guarantee that remote.s3 will work with non-AWS S3 systems.

Usage

remote.s3 "LABEL" {
  path = S3_FILE_PATH
}

Arguments

The following arguments are supported:

Name	Type	Description	Default	Required
`path`	`string`	Path in the format of `"s3://bucket/file"`.		yes
`poll_frequency`	`duration`	How often to poll the file for changes. Must be greater than 30 seconds.	`"10m"`	no
`is_secret`	`bool`	Marks the file as containing a secret.	`false`	no

NOTE: path must include a full path to a file. This does not support reading of directories.

Blocks

Hierarchy	Name	Description	Required
client_options	client_options	Additional options for configuring the S3 client.	no

client_options block

The client_options block customizes options to connect to the S3 server.

Name	Type	Description	Default	Required
`key`	`string`	Used to override default access key.		no
`secret`	`secret`	Used to override default secret value.		no
`endpoint`	`string`	Specifies a custom url to access, used generally for S3-compatible systems.		no
`disable_ssl`	`bool`	Used to disable SSL, generally used for testing.		no
`use_path_style`	`string`	Path style is a deprecated setting that is generally enabled for S3 compatible systems.	`false`	no
`region`	`string`	Used to override default region.		no

Exported fields

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

Name	Type	Description	Default	Required
`content`	`string` or `secret`	The contents of the file.		no

The content field will be secret if is_secret was set to true.

Component health

Instances of remote.s3 report as healthy if the most recent read of the watched file was successful.

Debug information

remote.s3 does not expose any component-specific debug information.

Debug metrics

remote.s3 does not expose any component-specific debug metrics.

Example

remote.s3 "data" {
  path = "s3://test-bucket/file.txt"
}

Components on Grafana Labs

discovery.docker

discovery.docker

Usage

Arguments

Blocks

filter block

http_client_config block

basic_auth block

authorization block

oauth2 block

tls_config block

Exported fields

Component health

Debug information

Debug metrics

Examples

Linux or macOS hosts

Windows hosts

discovery.file

discovery.file

Usage

Arguments

Exported fields

Component health

Debug information

Debug metrics

Examples

Kubernetes

discovery.kubernetes

discovery.kubernetes

Usage

Arguments

node role

service role

pod role

endpoints role

endpointslice role

ingress role

Blocks

namespaces block

selectors block

http_client_config block

basic_auth block

authorization block

oauth2 block

tls_config block

Exported fields

Component health

Debug information

Debug metrics

Examples

In-cluster discovery

Kubeconfig authentication

Limit searched namespaces

discovery.relabel

discovery.relabel

Usage

Arguments

Blocks

rule block

Exported fields

Component health

Debug information

Debug metrics

Example

local.file

local.file

Usage

Arguments

File change detectors

fsnotify

poll

Exported fields

Component health

Debug information

Debug metrics

Example

loki.process

loki.process