faro.receiver

Wed, 14 Oct 2026 20:19:24 +0000

`faro.receiver`

faro.receiver accepts web application telemetry data from the Grafana Faro Web SDK and forwards it to other components for processing.

Note
This component does not work with Grafana Cloud Frontend Observability. For more information, refer to the Choose a component guide.

Usage

faro.receiver "<LABEL>" {
    output {
        logs   = [<LOKI_RECEIVERS>]
        traces = [<OTELCOL_COMPONENTS>]
    }
}

Arguments

You can use the following arguments with faro.receiver:

Name	Type	Description	Default	Required
`extra_log_labels`	`map(string)`	Extra labels to attach to emitted log lines.	`{}`	no
`log_format`	`string`	Export format for the logs.	`"logfmt"`	no

Log format

The following strings are valid log line formats:

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

Blocks

You can use the following blocks with faro.receiver:

Block	Description	Required
`output`	Configures where to send collected telemetry data.	yes
`server`	Configures the HTTP server.	no
`server` > `rate_limiting`	Configures rate limiting for the HTTP server.	no
`sourcemaps`	Configures sourcemap retrieval.	no
`sourcemaps` > `cache`	Configures sourcemap caching behavior.	no
`sourcemaps` > `location`	Configures the location for sourcemap retrieval.	no

`output`

The output block specifies where to forward collected logs and traces.

Name	Type	Description	Default	Required
`logs`	`list(LogsReceiver)`	A list of `loki` components to forward logs to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	A list of `otelcol` components to forward traces to.	`[]`	no

`server`

The server block configures the HTTP server managed by the faro.receiver component. Clients using the Grafana Faro Web SDK forward telemetry data to this HTTP server for processing.

Name	Type	Description	Default	Required
`listen_address`	`string`	Address to listen for HTTP traffic on.	`"127.0.0.1"`	no
`listen_port`	`number`	Port to listen for HTTP traffic on.	`12347`	no
`cors_allowed_origins`	`list(string)`	Origins for which cross-origin requests are permitted.	`[]`	no
`api_key`	`secret`	Optional API key to validate client requests with.	`""`	no
`max_allowed_payload_size`	`string`	Maximum size (in bytes) for client requests.	`"5MiB"`	no
`include_metadata`	`bool`	Propagate incoming connection metadata to downstream consumers.	`false`	no

By default, telemetry data is only accepted from applications on the same local network as the browser. To accept telemetry data from a wider set of clients, modify the listen_address attribute to the IP address of the appropriate network interface to use.

The cors_allowed_origins argument determines what origins browser requests may come from. The default value, [], disables CORS support. To support requests from all origins, set cors_allowed_origins to ["*"]. The * character indicates a wildcard.

You can use the following headers for cross-domain requests: Content-Type, Content-Encoding, Idempotency-Key, Traceparent, X-API-Key, X-Faro-Session-Id, or X-Scope-OrgID.

Browser clients can read the Retry-After response header when it’s present. faro.receiver doesn’t generate this header or deduplicate requests based on Idempotency-Key.

The server supports gzip-compressed request bodies. When a client sends a request with a Content-Encoding: gzip header, the server automatically decompresses the body before processing.

When the api_key argument is non-empty, client requests must have an HTTP header called X-API-Key matching the value of the api_key argument. Requests that are missing the header or have the wrong value are rejected with an HTTP 401 Unauthorized status code. If the api_key argument is empty, no authentication checks are performed, and the X-API-Key HTTP header is ignored.

`rate_limiting`

The rate_limiting block configures rate limiting for client requests.

Name	Type	Description	Default	Required
`enabled`	`bool`	Whether to enable rate limiting.	`true`	no
`strategy`	`string`	The strategy to use for rate limiting.	`global`	no
`rate`	`number`	Rate of allowed requests per second.	`50`	no
`burst_size`	`number`	Allowed burst size of requests.	`100`	no

The following strategy strings are valid:

"global": Global rate limiting.
"per_app": Application/Environment based rate limiting.

Rate limiting functions as a token bucket algorithm, where a bucket has a maximum capacity for up to burst_size requests and refills at a rate of rate per second.

Each HTTP request drains the capacity of the bucket by one.

After the bucket is empty, HTTP requests are rejected with an HTTP 429 Too Many Requests status code until the bucket has more available capacity.

When strategy is per_app, rate limiting is applied per application and environment combination instead of globally.

This prevents one application from affecting the rate limits of other applications sending their data on the same gateway.

The application and environment are extracted from the Faro payload metadata using the app.name and app.environment fields. If these fields are missing, the request shares a rate limiter with other requests that also lack this metadata.

Configuring the rate argument determines how fast the bucket refills, and configuring the burst_size argument determines how many requests can be received in a burst before the bucket is empty and starts rejecting requests.

`sourcemaps`

The sourcemaps block configures how to retrieve sourcemaps. Sourcemaps are then used to transform file and line information from minified code into the file and line information from the original source code.

Name	Type	Description	Default	Required
`download`	`bool`	Whether to download sourcemaps.	`true`	no
`download_from_origins`	`list(string)`	Which origins to download sourcemaps from.	`["*"]`	no
`download_timeout`	`duration`	Timeout when downloading sourcemaps.	`"1s"`	no

When exceptions are sent to the faro.receiver component, it can download sourcemaps from the web application. You can disable this behavior by setting the download argument to false.

Warning
By default, faro.receiver downloads sourcemaps by requesting any URL that a client includes in its telemetry. Those requests come from the host that runs Alloy, so any client that reaches the receiver can make Alloy send HTTP or HTTPS requests to any address the host can reach, including internal services.

If the receiver accepts telemetry from the internet or from other networks that you don’t trust, take one or more of the following steps:

Set download to false, and provide sourcemaps with location blocks.

Set download_from_origins so Alloy downloads sourcemaps only for scripts served from your own origins, and end each origin with a /.

Restrict outbound network access from the host that runs Alloy, for example with a network policy or firewall rules, so that it can only reach the destinations it needs.

download_from_origins only restricts the script URLs that Alloy fetches. It doesn’t restrict the sourcemap URL that a script refers to, so restrict outbound network access as well.

The download_from_origins argument restricts sourcemap downloads to scripts served from the listed origins. The receiver compares the URL of the script file in each stack frame of the telemetry it receives with these origins. The client that sends the telemetry sets that URL. The default value, ["*"], enables downloading sourcemaps from all origins. The * character indicates a wildcard.

The receiver matches each origin as a prefix of the full URL, where * matches any characters, including /, and ? matches a single character. End each origin with a / so that it can’t match a longer host name. For example, the origin https://app.example.com/ doesn’t match a script at https://app.example.com.example.net/app.js, but the origin https://app.example.com does. Avoid using * in the host part of an origin. For example, https://*.example.com/ also matches https://example.net/x.example.com/app.js.

The following example downloads sourcemaps only for scripts served from https://app.example.com/:

faro.receiver "default" {
    sourcemaps {
        download_from_origins = ["https://app.example.com/"]
    }

    output {
        logs   = [loki.write.default.receiver]
        traces = [otelcol.exporter.otlphttp.traces.input]
    }
}

By default, sourcemap downloads are subject to a timeout of "1s", specified by the download_timeout argument. Setting download_timeout to "0s" disables timeouts.

To retrieve sourcemaps from disk or another network location, specify one or more location blocks. When location blocks are provided, they’re checked first for sourcemaps before falling back to downloading.

`cache`

The cache block configures sourcemap caching behavior.

Name	Type	Description	Default	Required
`cleanup_check_interval`	`duration`	How often Alloy checks cached sourcemaps for cleanup.	`"30s"`	no
`error_cleanup_interval`	`duration`	How long Alloy waits before retrying a failed source map download.	`"1h"`	no
`ttl`	`duration`	How long Alloy keeps an unused source map in the cache.	`inf`	no

By default, Alloy keeps sourcemaps in memory indefinitely. Set ttl to remove sourcemaps that are not accessed within the specified duration.

Alloy caches errors that occur while downloading or parsing a sourcemap. Use error_cleanup_interval to control how long these errors remain cached.

Cached sourcemaps are checked for cleanup every 30 seconds by default. Set cleanup_check_interval to adjust this frequency.

`location`

The location block declares a location where sourcemaps are stored on the filesystem. You can specify the location block multiple times to declare multiple locations where sourcemaps are stored.

Name	Type	Description	Default	Required
`minified_path_prefix`	`string`	The prefix of the minified path sent from browsers.		yes
`path`	`string`	The path on disk or base URL where sourcemaps are stored.		yes

The minified_path_prefix argument determines the prefix of paths to JavaScript files, such as http://example.com/. The path argument then determines where to find the sourcemap for the file.

For example, given the following location block:

location {
    path                 = "/var/my-app/build"
    minified_path_prefix = "http://example.com/"
}

To look up the sourcemaps for a file hosted at http://example.com/example.js, the faro.receiver component:

Removes the minified path prefix to extract the path to the file example.js.
Searches the path for the file with a .map extension, for example example.js.map in the path /var/my-app/build/example.js.map.

Optionally, the value for the path argument may contain {{ .Release }} as a template value, such as /var/my-app/{{ .Release }}/build. The template value is replaced with the release value provided by the Faro Web App SDK.

When you specify a remote location, the procedure for retrieving the sourcemaps is the same as for a location block with a local path, except that the component retrieves the sourcemap from a remote HTTP server.

In the following example, the faro.receiver sends a GET request to http://storage.example.com/blob/sourcemaps/example.js.map and retrieves the sourcemap for a file hosted at http://example.com/example.js.

You can specify multiple location blocks. For example:

location {
    path                 = "http://storage.example.com/blob/sourcemaps/"
    minified_path_prefix = "http://example.com/"
}

```alloy
location {
    path                 = "/var/my-app/build"
    minified_path_prefix = "http://example.com/"
}
location {
    path                 = "http://storage.example.com/blob/sourcemaps/"
    minified_path_prefix = "http://example.com/"
}

The faro.receiver component searches through all locations for the sourcemap files. Local on-disk paths take precedence over remote paths. For a file hosted at http://example.com/example.js, the faro.receiver first checks the path /var/my-app/build/example.js.map, and then tries to retrieve http://storage.example.com/blob/sourcemaps/example.js.map.

Exported fields

faro.receiver doesn’t export any fields.

Component health

faro.receiver is reported as unhealthy when the integrated server fails to start.

Debug information

faro.receiver doesn’t expose any component-specific debug information.

Debug metrics

faro.receiver exposes the following metrics for monitoring the component:

faro_receiver_logs_total (counter): Total number of ingested logs.
faro_receiver_measurements_total (counter): Total number of ingested measurements.
faro_receiver_exceptions_total (counter): Total number of ingested exceptions.
faro_receiver_events_total (counter): Total number of ingested events.
faro_receiver_exporter_errors_total (counter): Total number of errors produced by an internal exporter.
faro_receiver_request_duration_seconds (histogram): Time (in seconds) spent serving HTTP requests.
faro_receiver_request_message_bytes (histogram): Size (in bytes) of HTTP requests received from clients.
faro_receiver_response_message_bytes (histogram): Size (in bytes) of HTTP responses sent to clients.
faro_receiver_inflight_requests (gauge): Current number of inflight requests.
faro_receiver_sourcemap_cache_size (gauge): Number of items in sourcemap cache per origin.
faro_receiver_sourcemap_downloads_total (counter): Total number of sourcemap downloads performed per origin and status.
faro_receiver_sourcemap_file_reads_total (counter): Total number of sourcemap retrievals using the filesystem per origin and status.
faro_receiver_rate_limiter_active_app (gauge): Number of active applications with rate limiters. Inactive limiters are cleaned up every 10 minutes.
faro_receiver_rate_limiter_requests_total (counter): Total number of requests processed by the rate limiter per app/environment.

Example

faro.receiver "default" {
    server {
        listen_address = "<NETWORK_ADDRESS>"
    }

    sourcemaps {
        location {
            path                 = "<PATH_TO_SOURCEMAPS>"
            minified_path_prefix = "<WEB_APP_PREFIX>"
        }
    }

    output {
        logs   = [loki.write.default.receiver]
        traces = [otelcol.exporter.otlphttp.traces.input]
    }
}

loki.write "default" {
    endpoint {
        url = "https://LOKI_ADDRESS/loki/api/v1/push"
    }
}

otelcol.exporter.otlphttp "traces" {
    client {
        endpoint = "<OTLP_ADDRESS>"
    }
}

Replace the following:

<NETWORK_ADDRESS>: The IP address of the network interface to listen to traffic on. This IP address must be reachable by browsers using the web application to instrument.
<PATH_TO_SOURCEMAPS>: The path on disk where sourcemaps are located.
<WEB_APP_PREFIX>: Prefix of the web application being instrumented.
LOKI_ADDRESS: Address of the Loki server to send logs to. Refer to loki.write if you want to use authentication to send logs to the Loki server.
<OTLP_ADDRESS>: The address of the OTLP-compatible server to send traces to. Refer tootelcol.exporter.otlphttp if you want to use authentication to send logs to an OTLP server.

Compatible components

faro.receiver can accept arguments from the following components:

Components that export Loki LogsReceiver
Components that export OpenTelemetry otelcol.Consumer

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

faro on Grafana Labs

faro.receiver

faro.receiver

Usage

Arguments

Log format

Blocks

output

server

rate_limiting

sourcemaps

cache

location

Exported fields

Component health

Debug information

Debug metrics

Example

Compatible components

`faro.receiver`

`output`

`server`

`rate_limiting`

`sourcemaps`

`cache`

`location`