Skip to main content

Grafana Alloy

Grafana Alloy is an agent for collecting and forwarding metrics, logs, and traces. Grafana Alloy is a flexible and high-performance distribution of the OpenTelemetry Collector. The agent is compatible with OpenTelemetry and Prometheus, the most widely used observability standard formats.

Grafana Alloy uses the otel-colector/awscloudwatchreceiver component, which receives logs from the Amazon CloudWatch API FilterLogEvents method. For a list of all Grafana Alloy components, see the Choose a Grafana Alloy component guide in the official Grafana documentation.

  1. Add a service user.
  2. Issue an S3 key to the user.
  3. Install the agent.
  4. Configure the agent to receive events.

1. Add a service user

Add a service user with permissions in the Projects scope and a role:

Users can be added by the Account Owner or users with the role iam.admin.

2. Issue an S3 key to the user

Control panel users can issue S3 keys to themselves, but we recommend creating service users and issuing S3 keys to them.

Only the Account Owner or a user with the iam.admin role can issue S3 keys to other users. A service user cannot obtain an S3 key independently because they do not have access to the control panel — the Account Owner or iam.admin must issue a key to them.

You must create a separate key for each project. You can issue multiple keys for a single project.

  1. In the control panel, in the top menu, click IAM.

  2. Go to the section with the desired user type:

    • Control panel users — for users with access to the control panel;
    • Service users — for users with programmatic access without access to the control panel.

  3. Open the user page → Access tab.

  4. In the S3 keys block, click Add key.

  5. Enter a key name.

  6. Select the project for which the key will work.

  7. Click Generate. Two values will be generated:

    • Access key — Access Key ID, a key identifier;
    • Secret key — Secret Access Key, a secret key.

  8. Click Copy and save the key — it cannot be viewed after closing the window.

3. Install the agent

Follow the Install Grafana Alloy instructions in the official Grafana Alloy documentation.

4. Configure the agent to receive events

  1. Open the CLI.

  2. Create a config.alloy configuration file:

    nano /etc/alloy/config.alloy

  3. In the config.alloy file, add a configuration for receiving events using the otelcol.receiver.awscloudwatch component. Configuration example:

    logging {
      level  = "info"
      format = "logfmt"
    }

    otelcol.receiver.awscloudwatch "logs" {
      region = "<pool>"

      logs {
        groups {
          named {
            group_name = "<log_group_name>"
            names = "<log_stream_names>"
          }
        }
      }

      output {
        logs = [otelcol.exporter.loki.default.input]
      }
    }

    otelcol.exporter.loki "default" {
      forward_to = [loki.process.parse_json.receiver]
    }

    loki.process "parse_json" {

      stage.json {
        expressions = {
          source = "<key>",
        }
      }

      stage.output {
          source = "<key>"
      }

      forward_to = [loki.echo.default.receiver]

    }

    loki.echo "default" {}

Specify:

  • arguments for the otelcol.receiver.awscloudwatch component:

    • <pool> — pool, for example, kz-1 ;
    • <log_group_name> — log group name, for example, s/lbaas/Loabalancer-1;
    • optional: <log_stream_names> — list of streams to receive events from, for example, [http-c48d78e2-6f49-43b5-80b7-2f2b8e5f669d].

  • arguments for the loki.process component:

    • <key> — event field, for example, body. The value for processing will be extracted from the field specified in the stage.json parameter. The value of the field specified in the stage.output parameter will be sent to the output after processing.

  1. Run Alloy:

    docker run \
        -v /etc/alloy/config.alloy:/etc/alloy/config.alloy \
        -p 12345:12345 \
        -e AWS_ENDPOINT_URL=<log_endpoint> \
        -e AWS_ACCESS_KEY=<access_key> \
        -e AWS_SECRET_KEY=<secret_key> \
             grafana/alloy:latest \
          run --server.http.listen-addr=0.0.0.0:12345 \
          --storage.path=/var/lib/alloy/data \
          --stability.level experimental \
          /etc/alloy/config.alloy

    Specify:

    • <log_endpoint> — URL for calling the Logs service API. For a list of URLs, see the Logs subsection of the List of URLs;
    • <access_key> — value of the Access key field from the S3 key that you issued to the user;
    • <secret_key> — value of the Secret key field from the S3 key that you issued to the user.

    You can add <log_endpoint>, <access_key>, and <secret_key> to the container in any way:

    Example of output to stdout:

    ...
    ts=2025-10-14T06:07:03.637492043Z level=info component_path=/ component_id=loki.echo.default receiver=loki.echo.default entry="{\"client\":\"204.76.203.219:41942\" ... }" entry_timestamp=2025-10-14T05:50:35.549Z labels="{exporter=\"OTLP\"}" structured_metadata={}
    ts=2025-10-14T06:07:03.637503251Z level=info component_path=/ component_id=loki.echo.default receiver=loki.echo.default entry="{\"client\":\"204.76.203.18:45864\" ... }" entry_timestamp=2025-10-14T05:54:58.753Z labels="{exporter=\"OTLP\"}" structured_metadata={}
    ...