Caution
Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.
Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
pyroscope.write
BETA: This is a beta component. Beta components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case.
pyroscope.write
receives performance profiles from other components and forwards them
to a series of user-supplied endpoints using Pyroscope’ Push API.
Multiple pyroscope.write
components can be specified by giving them
different labels.
Usage for Grafana Agent flow mode
pyroscope.write "LABEL" {
endpoint {
url = PYROSCOPE_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
pyroscope.write
:
Hierarchy | Block | Description | Required |
---|---|---|---|
endpoint | endpoint | Location to send profiles to. | no |
endpoint > basic_auth | basic_auth | Configure basic_auth for authenticating to the endpoint. | no |
endpoint > authorization | authorization | Configure generic authorization to the endpoint. | no |
endpoint > oauth2 | oauth2 | Configure OAuth2 for authenticating to the endpoint. | no |
endpoint > oauth2 > tls_config | tls_config | Configure TLS settings for connecting to the endpoint. | no |
endpoint > tls_config | tls_config | Configure TLS settings for connecting to the endpoint. | no |
The >
symbol indicates deeper levels of nesting. For example, endpoint > basic_auth
refers to a basic_auth
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. | "10s" | no |
headers | map(string) | Extra headers to deliver with the request. | 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. 0 to retry infinitely. | 10 | no |
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_http2 | bool | Whether HTTP2 is supported for requests. | true | no |
At most one of the following can be provided:
When multiple endpoint
blocks are provided, profiles are concurrently forwarded to all
configured locations.
basic_auth block
Name | Type | Description | Default | Required |
---|---|---|---|---|
password_file | string | File containing the basic auth password. | no | |
password | secret | Basic auth password. | no | |
username | string | Basic auth username. | no |
password
and password_file
are mutually exclusive, and only one can be provided inside a basic_auth
block.
authorization block
Name | Type | Description | Default | Required |
---|---|---|---|---|
credentials_file | string | File containing the secret value. | no | |
credentials | secret | Secret value. | no | |
type | string | Authorization type, for example, “Bearer”. | no |
credential
and credentials_file
are mutually exclusive, and only one can be provided inside an authorization
block.
oauth2 block
Name | Type | Description | Default | Required |
---|---|---|---|---|
client_id | string | OAuth2 client ID. | no | |
client_secret_file | string | File containing the OAuth2 client secret. | no | |
client_secret | secret | OAuth2 client secret. | no | |
endpoint_params | map(string) | Optional parameters to append to the token URL. | no | |
proxy_url | string | Optional proxy URL for OAuth2 requests. | no | |
scopes | list(string) | List of scopes to authenticate with. | no | |
token_url | string | URL to fetch the token from. | no |
client_secret
and client_secret_file
are mutually exclusive, and only one can be provided inside an oauth2
block.
The oauth2
block may also contain a separate tls_config
sub-block.
tls_config block
Name | Type | Description | Default | Required |
---|---|---|---|---|
ca_pem | string | CA PEM-encoded text to validate the server with. | no | |
ca_file | string | CA certificate to validate the server with. | no | |
cert_pem | string | Certificate PEM-encoded text for client authentication. | no | |
cert_file | string | Certificate file for client authentication. | no | |
insecure_skip_verify | bool | Disables validation of the server certificate. | no | |
key_file | string | Key file for client authentication. | no | |
key_pem | secret | Key PEM-encoded text for client authentication. | no | |
min_version | string | Minimum acceptable TLS version. | no | |
server_name | string | ServerName extension to indicate the name of the server. | no |
The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:
ca_pem
andca_file
cert_pem
andcert_file
key_pem
andkey_file
When configuring client authentication, both the client certificate (using
cert_pem
or cert_file
) and the client key (using key_pem
or key_file
)
must be provided.
When min_version
is not provided, the minimum acceptable TLS version is
inherited from Go’s default minimum version, TLS 1.2. If min_version
is
provided, it must be set to one of the following strings:
"TLS10"
(TLS 1.0)"TLS11"
(TLS 1.1)"TLS12"
(TLS 1.2)"TLS13"
(TLS 1.3)
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
pyroscope.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
pyroscope.write
does not expose any component-specific debug
information.
Example
pyroscope.write "staging" {
// Send metrics to a locally running Pyroscope instance.
endpoint {
url = "http://pyroscope:4100"
headers = {
"X-Scope-OrgID" = "squad-1",
}
}
external_labels = {
"env" = "staging",
}
}
pyroscope.scrape "default" {
targets = [
{"__address__" = "pyroscope:4100", "service_name"="pyroscope"},
{"__address__" = "agent:12345", "service_name"="agent"},
]
forward_to = [pyroscope.write.staging.receiver]
}