Documentation Grafana Cloud Instrument and send data Grafana Alloy Reference Components faro faro.receiver

faro.receiver

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

Usage

alloy Copy

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

Arguments

You can use the following arguments with faro.receiver:

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:

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

output

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

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.

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, Traceparent, X-API-Key, X-Faro-Session-Id, or X-Scope-OrgID.

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.

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.

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.

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.

The download_from_origins argument determines which origins a sourcemap may be downloaded from. The origin is attached to the URL that a browser is sending telemetry data from. The default value, ["*"], enables downloading sourcemaps from all origins. The * character indicates a wildcard.

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 instead of the network, specify one or more location blocks. When location blocks are provided, they’re checked first for sourcemaps before falling back to downloading.

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.

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:

alloy Copy

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:

1. Removes the minified path prefix to extract the path to the file example.js.
2. 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.

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 (counter): 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.

Example

alloy Copy

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.otlp.traces.input]
    }
}

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

otelcol.exporter.otlp "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.otlp if you want to use authentication to send logs to the Loki server.

Compatible components

faro.receiver can accept arguments from the following components:

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