Menu

This is documentation for the next version of Agent. For the latest stable release, go to the latest version.

Open source

faro.receiver

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

Usage

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

Arguments

The following arguments are supported:

NameTypeDescriptionDefaultRequired
extra_log_labelsmap(string)Extra labels to attach to emitted log lines.{}no

Blocks

The following blocks are supported inside the definition of faro.receiver:

HierarchyBlockDescriptionRequired
serverserverConfigures the HTTP server.no
server > rate_limitingrate_limitingConfigures rate limiting for the HTTP server.no
sourcemapssourcemapsConfigures sourcemap retrieval.no
sourcemaps > locationlocationConfigures on-disk location for sourcemap retrieval.no
outputoutputConfigures where to send collected telemetry data.yes

server block

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.

NameTypeDescriptionDefaultRequired
listen_addressstringAddress to listen for HTTP traffic on.127.0.0.1no
listen_portnumberPort to listen for HTTP traffic on.12347no
cors_allowed_originslist(string)Origins for which cross-origin requests are permitted.[]no
api_keysecretOptional API key to validate client requests with.""no
max_allowed_payload_sizestringMaximum size (in bytes) for client requests."5MiB"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.

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 block

The rate_limiting block configures rate limiting for client requests.

NameTypeDescriptionDefaultRequired
enabledboolWhether to enable rate limiting.trueno
ratenumberRate of allowed requests per second.50no
burst_sizenumberAllowed burst size of requests.100no

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. Once 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 block

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.

NameTypeDescriptionDefaultRequired
downloadboolWhether to download sourcemaps.trueno
download_from_originslist(string)Which origins to download sourcemaps from.["*"]no
download_timeoutdurationTimeout 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.

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 are checked first for sourcemaps before falling back to downloading.

location block

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

NameTypeDescriptionDefaultRequired
pathstringThe path on disk where sourcemaps are stored.yes
minified_path_prefixstringThe prefix of the minified path sent from browsers.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/foo.js, the faro.receiver component will:

  1. Remove the minified path prefix to extract the path to the file (foo.js).
  2. Search for that file path with a .map extension (foo.js.map) in path (/var/my-app/build/foo.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 will be replaced with the release value provided by the Faro Web App SDK.

output block

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

NameTypeDescriptionDefaultRequired
logslist(LogsReceiver)A list of loki components to forward logs to.[]no
traceslist(otelcol.Consumer)A list of otelcol components to forward traces to.[]no

Exported fields

faro.receiver does not export any fields.

Component health

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

Debug information

faro.receiver does not 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

river
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/api/v1/push"
    }
}

otelcol.exporter.otlp "traces" {
    client {
        endpoint = "OTLP_ADDRESS"
    }
}

Replace the following:

  • NETWORK_ADDRESS: 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: 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.

    • If authentication is required to send logs to the Loki server, refer to the documentation of loki.write for more information.
  • OTLP_ADDRESS: The address of the OTLP-compatible server to send traces to.

    • If authentication is required to send logs to the Loki server, refer to the documentation of otelcol.exporter.otlp for more information.

Compatible components

faro.receiver can accept arguments from the following components:

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.