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 OpenTelemetry Collector. The agent is compatible with OpenTelemetry and Prometheus, the most widely used observability standard formats.

Grafana Alloy uses the otel-collector/awscloudwatchreceiver component, which receives logs from the FilterLogEvents method of the Amazon CloudWatch API. A list of all Grafana Alloy components can be seen in 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 permission in the Projects area and the role:

• member or logs.admin for read and write log access;
• logs.write for write log access;
• reader or logs.viewer for read-only log access.

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

2. Issue an S3 key to the user

Users with access to the control panel can issue S3 keys for 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 get an S3 key independently because they do not have access to the control panel — the Account Owner or iam.admin.

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

1. In the control panel, click IAM.

2. Go to the section for the required user type:

   • Users — for users with access to the control panel;
   • Service users — for service users.

3. Open the user page → in the Access tab.

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

5. Enter a key name.

6. Select a 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 — you will not be able to view it after closing the window.

3. Install the agent

Use 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 the configuration to receive events using the otelcol.receiver.awscloudwatch component. Example configuration:

   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> — a 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.

2. 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 to access the Logs service API. You can see the list of URLs in the URL List instruction;
   • <access_key> — the value of the Access key field from the S3 key you issued to the user;
   • <secret_key> — the value of the Secret key field from the S3 key you issued to the user.

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

   • via environment variables, see more in the Using environment variables to globally configure AWS SDKs and tools Amazon documentation;
   • or via config and credentials files, see more in the Using shared config and credentials files to globally configure AWS SDKs and tools Amazon documentation.

   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={}
   ...