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.

Documentation Beyla Configure Export modes

Beyla export modes

Beyla can export data in two modes:

• Agent mode (recommended mode): the auto-instrumentation tool will send the metrics and the traces to the Grafana Agent, which will process and send them to Mimir and Tempo. In this scenario, the Agent takes care of the authentication required by the Grafana Mimir/Tempo endpoints. This mode also integrates better with some Grafana exclusive features, such as the span-to-metrics and span-to-service graph converters.
• Direct mode: the auto-instrumentation tool can push metrics and/or traces directly to a remote endpoint (using the OpenTelemetry/OTEL protocols) or expose a Prometheus HTTP endpoint ready to be scraped (i.e. pull mode). In the direct OTEL push mode, the auto-instrumentation tool needs to be configured with the authentication credentials.

Running in Direct mode

You can follow our getting started tutorial for a quick introduction to auto-instrumentation in Direct mode, by using OpenTelemetry. The OTLP endpoint authentication credentials are provided by using the following environment variables:

• OTEL_EXPORTER_OTLP_ENDPOINT
• OTEL_EXPORTER_OTLP_HEADERS

To run in Direct mode by using the Prometheus scrape endpoint, please refer to the configuration documentation.

Running in Agent mode

ℹ️ This tutorial assumes that both the Agent and the auto-instrumentation tool are installed as local Linux OS executables. For further examples on downloading and running the auto-instrumentation tool as an OCI container, you can check the documentation sections on running the Beyla as a Docker container or running Beyla in Kubernetes.

First, you will need to locally install and configure the Grafana Agent in Flow mode, according to the latest documentation. Running the Agent in Flow mode will facilitate the ingestion of OpenTelemetry metrics and traces from the auto-instrumentation tool, as well as process and forward to the different Grafana product endpoints (Mimir and/or Tempo).

Configuring the Agent pipeline

Next, you’ll need to specify the following nodes by using the River configuration language:

You can download the example of the whole River configuration file, which will be explained in the rest of this section.

The Agent needs to expose an OpenTelemetry receiver endpoint, such that the auto-instrumentation tool can forward both metrics and traces. The Agent configuration file will need to include the following entry:

hcl Copy

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

  output {
    metrics = [otelcol.processor.batch.default.input]
    traces = [otelcol.processor.batch.default.input]
  }
}

This enables reception of OpenTelemetry events via GRPC and HTTP, which will be forwarded to the next stage in the pipeline, the Batch processor, which will then accumulate the messages and forward them to the exporters:

hcl Copy

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.prometheus.default.input]
    traces  = [otelcol.exporter.otlp.tempo.input]
  }
}

You can export either metrics, traces, or both. If you only want to export a single type of data, you can just avoid the metrics or traces lines in the previous node definitions, and ignore some of the following exporters.

The metrics are exported in Prometheus format to Grafana Mimir. The configuration entry will need to specify an endpoint with basic authentication. In the provided example, the endpoint and the credentials are provided via environment variables:

hcl Copy

otelcol.exporter.prometheus "default" {
    forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "https://" + env("MIMIR_ENDPOINT") + "/api/prom/push"
    basic_auth {
      username = env("MIMIR_USER")
      password = env("GRAFANA_API_KEY")
    }
  }
}

Assuming you have a configuration file as above, you will need to run the Agent with the environment variables set. For example:

sh Copy

export MIMIR_USER=734432
export MIMIR_ENDPOINT=prometheus-prod-01-eu-west-0.grafana.net
export GRAFANA_API_KEY=VHJhbGFyw60gcXVlIHRlIHbD....=

Finally, to export the traces, you will need to set up a Grafana Tempo exporter and an endpoint, also configured via environment variables:

hcl Copy

otelcol.exporter.otlp "tempo" {
    client {
        endpoint = env("TEMPO_ENDPOINT")
        auth     = otelcol.auth.basic.creds.handler
    }
}

otelcol.auth.basic "creds" {
    username = env("TEMPO_USER")
    password = env("GRAFANA_API_KEY")
}

Please note that the TEMPO_ENDPOINT and TEMPO_USER values are different from MIMIR_ENDPOINT and MIMIR_USER.

To run the agent with the previous configuration (for example, written in a file named agent-config.river), you need to run the following command:

Copy

agent run agent-config.river

Configuring and running the auto-instrumentation tool

Now we can configure the auto-instrumentation tool to forward data to the running Grafana Agent. In this tutorial we are assuming that both the auto-instrumentation tool and the Agent are running on the same host, so there is no need to secure the traffic nor provide authentication in the Agent OTLP receiver.

You can configure the auto-instrumentation tool both via environment variables or via a configuration YAML file, which is what we will use in this example. Please refer to the complete Configuration documentation for more detailed description of each configuration option.

You can download the whole example configuration file, which we will explain in the rest of this section.

First, you will need to specify the executable to instrument. If, for example, the service executable is a process that opens the port 443, you can use the open_port property of the YAML document:

yaml Copy

open_port: 443

The auto-instrumentation tool will automatically search and instrument the process listening on port 443.

Next, you will need to specify where the traces and the metrics will be submitted. If the Agent is running on the local host, it will use the port 4318:

yaml Copy

otel_metrics_export:
  endpoint: http://localhost:4318
otel_traces_export:
  endpoint: http://localhost:4318

You can specify both otel_metrics_export and otel_traces_export properties to allow exporting both metrics and traces, or only one of them to export either metrics or traces.

To run the auto-instrumentation tool (previously downloaded from the Beyla releases page), you will need to specify the path to the configuration YAML file, either with the -config command-line argument or the BEYLA_CONFIG_PATH environment variable. For example instrument-config.yml:

Copy

beyla -config instrument-config.yml

or

Copy

BEYLA_CONFIG_PATH=instrument-config.yml beyla