Documentation Grafana Alloy Monitor metrics and logs Monitor structured logs

Monitor structured logs with Grafana Alloy

Structured logs use a consistent format, such as JSON, to organize data into key-value pairs. This format makes it easier to search, filter, and analyze log data. With Alloy, you can collect your logs, forward them to a Grafana stack, and create dashboards to monitor your system behavior.

The alloy-scenarios repository contains complete examples of Alloy deployments. Clone the repository and use the examples to understand how Alloy collects, processes, and exports telemetry signals.

In this example scenario, Alloy collects log entries over HTTP, parses them into labels and structured metadata, and forwards the results to a Loki destination.

Before you begin

Ensure you have the following:

• Docker
• Git

Clone and deploy the example

Follow these steps to clone the scenarios repository and deploy the monitoring example:

1. Clone the Alloy scenarios repository:

   shell Copy

   git clone https://github.com/grafana/alloy-scenarios.git

2. Start Docker to deploy the Grafana stack:

   shell Copy

   cd alloy-scenarios/mail-house
   docker compose up -d

   Verify the status of the Docker containers:

   shell Copy

   docker ps

3. (Optional) Stop Docker to shut down the Grafana stack when you finish exploring this example:

   shell Copy

   docker compose down

Monitor and visualize your data

Use Grafana to monitor your deployment’s health and visualize your data.

Monitor Alloy

To monitor the health of your Alloy deployment, open your browser and go to http://localhost:12345.

For more information about the Alloy UI, refer to Debug Grafana Alloy.

Visualize your data

To use the Grafana Logs Drilldown, open your browser and go to http://localhost:3000/a/grafana-lokiexplore-app.

To create a dashboard to visualize your metrics and logs, open your browser and go to http://localhost:3000/dashboards.

Understand the Alloy configuration

This example uses a config.alloy file to configure the Alloy components for logging. You can find the config.alloy file in the cloned repository at alloy-scenarios/mail-house/.

The configuration includes livedebugging to stream real-time data to the Alloy UI.

Configure livedebugging

livedebugging streams real-time data from your components directly to the Alloy UI. Refer to the Troubleshooting documentation for more details about this feature.

livedebugging

livedebugging is disabled by default. Enable it explicitly through the livedebugging configuration block to make debugging data visible in the Alloy UI.

alloy Copy

livedebugging {
  enabled = true
}

Configure logging

The logging configuration in this example requires three components:

• loki.source.api
• loki.process
• loki.write

loki.source.api

The loki.source.api component receives log entries over HTTP and forwards them to other Loki components. In this example, the component requires the following arguments:

• listen_address: The network address the server listens to for new connections. Setting this argument to 0.0.0.0 tells the server to listen on all IP addresses.
• listen_port: The port the server listens to for new connections.
• forward_to: The list of receivers to send log entries to.

alloy Copy

loki.source.api "loki_push_api" {
    http {
        listen_address = "0.0.0.0"
        listen_port = 9999
    }
    forward_to = [
        loki.process.labels.receiver,
    ]
}

loki.process

The loki.process component receives log entries from other Loki components, applies processing stages, and forwards the results to the list of receivers. In this example, the component requires the following arguments:

• expressions: Key-value pairs defining the name of the data extracted and the value it’s populated with.
• source: Name from extracted values map to use for the timestamp.
• format: Determines how to parse the source string.
• values: Key-value pairs defining the label to set and how to look them up.
• forward_to: The list of receivers to send log entries to.

alloy Copy

Expand code

loki.process "labels" {
    stage.json {
      expressions = { 
                      "timestamp" = "",
                      "state" = "", 
                      "package_size" = "", 
                      "package_status" = "", 
                      "package_id" = "",
                    }
    }

  stage.timestamp {
    source = "timestamp"
    format = "RFC3339"
  }

  stage.labels {
    values = {
      "state" = "",
      "package_size" = "",
    }
  }

  stage.structured_metadata {
    values = {
      "package_status" = "",
      "package_id" = "",
    }
  }

  stage.static_labels {
    values = {
      "service_name" = "Delivery World",
    }
  }

  stage.output {
    source = "message"
  }

  forward_to = [loki.write.local.receiver]
}

loki.write

The loki.write component writes logs to a Loki destination. In this example, the component requires the following argument:

• url: Defines the full URL endpoint in Loki to send logs to.

alloy Copy

loki.write "local" {
  endpoint {
    url = "http://loki:3100/loki/api/v1/push"
  }
}