Grafana Alloy tutorials on Grafana Labs

Use Grafana Alloy to send logs to Loki

Mon, 30 Mar 2026 15:47:22 +0000

Use Grafana Alloy to send logs to Loki

This tutorial shows you how to configure Alloy to collect logs from your local machine, filter non-essential log lines, send them to Loki, and use Grafana to explore the results.

Before you begin

To complete this tutorial:

You must have a basic understanding of Alloy and telemetry collection in general.
You should be familiar with Prometheus, PromQL, Loki, LogQL, and basic Grafana navigation.

Tip
Alternatively, you can try out this example in the interactive learning environment: Sending Logs to Loki.

It’s a fully configured environment with all the dependencies already installed.

Install Alloy and start the service

This tutorial requires a Linux or macOS environment with Docker installed.

Linux

Install and run Alloy on Linux.

Install Alloy.
Run Alloy.

macOS

Install and run Alloy on macOS.

Install Alloy.
Run Alloy.

You can access the Alloy UI at http://localhost:12345.

Set up a local Grafana instance

In this tutorial, you configure Alloy to collect logs from your local machine and send them to Loki. You can use the following Docker Compose file to set up a local Grafana instance. This Docker Compose file includes Loki and Prometheus configured as data sources.

Create a directory and save the Docker Compose file as docker-compose.yml.
Bash
```
mkdir alloy-tutorial
cd alloy-tutorial
touch docker-compose.yml
```

Copy the following Docker Compose file into docker-compose.yml.

version: '3'
services:
  loki:
    image: grafana/loki:3.0.0
    ports:
      - "3100:3100"
    command: -config.file=/etc/loki/local-config.yaml
  prometheus:
    image: prom/prometheus:v2.47.0
    command:
      - --web.enable-remote-write-receiver
      - --config.file=/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"
  grafana:
    environment:
      - GF_PATHS_PROVISIONING=/etc/grafana/provisioning
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
    entrypoint:
      - sh
      - -euc
      - |
        mkdir -p /etc/grafana/provisioning/datasources
        cat <<EOF > /etc/grafana/provisioning/datasources/ds.yaml
        apiVersion: 1
        datasources:
        - name: Loki
          type: loki
          access: proxy
          orgId: 1
          url: http://loki:3100
          basicAuth: false
          isDefault: false
          version: 1
          editable: false
        - name: Prometheus
          type: prometheus
          orgId: 1
          url: http://prometheus:9090
          basicAuth: false
          isDefault: true
          version: 1
          editable: false
        EOF
        /run.sh
    image: grafana/grafana:11.0.0
    ports:
      - "3000:3000"

To start the local Grafana instance, run the following command.
Bash
```
docker compose up -d
```
Note
If you encounter the following error when you start your Docker container, docker: 'compose' is not a docker command, use the command docker-compose up to start your Docker container.
Open http://localhost:3000 in your browser to access the Grafana UI.

Configure Alloy

After the local Grafana instance is set up, the next step is to configure Alloy. You use components in the config.alloy file to tell Alloy which logs you want to scrape, how you want to process that data, and where you want the data sent.

The examples run on a single host so that you can run them on your laptop or in a Virtual Machine. You can try the examples using a config.alloy file and experiment with the examples.

Create a `config.alloy` file

Create a config.alloy file within your current working directory.

touch config.alloy

First component: Log files

Copy and paste the following component configuration at the top of the file.

local.file_match "local_files" {
  path_targets = [{"__path__" = "/var/log/*.log"}]
  sync_period = "5s"
}

This configuration creates a local.file_match component named local_files which does the following:

It tells Alloy which files to source.
It checks for new files every 5 seconds.

Second component: Scraping

Copy and paste the following component configuration below the previous component in your config.alloy file:

loki.source.file "log_scrape" {
  targets    = local.file_match.local_files.targets
  forward_to = [loki.process.filter_logs.receiver]
  tail_from_end = true
}

This configuration creates a loki.source.file component named log_scrape which does the following:

It connects to the local_files component as its source or target.
It forwards the logs it scrapes to the receiver of another component called filter_logs.
It provides extra attributes and options to tail the log files from the end so you don’t ingest the entire log file history.

Third component: Filter non-essential logs

Filtering non-essential logs before sending them to a data source can help you manage log volumes to reduce costs.

The following example demonstrates how you can filter out or drop logs before sending them to Loki.

Copy and paste the following component configuration below the previous component in your config.alloy file:

loki.process "filter_logs" {
  stage.drop {
    source = ""
    expression  = ".*Connection closed by authenticating user root"
    drop_counter_reason = "noisy"
  }
  forward_to = [loki.write.grafana_loki.receiver]
}

The loki.process component allows you to transform, filter, parse, and enrich log data. Within this component, you can define one or more processing stages to specify how you would like to process log entries before they’re stored or forwarded.

This configuration creates a loki.process component named filter_logs which does the following:

It receives scraped log entries from the default log_scrape component.
It uses the stage.drop block to define what to drop from the scraped logs.
It uses the expression parameter to identify the specific log entries to drop.
It uses an optional string label drop_counter_reason to show the reason for dropping the log entries.
It forwards the processed logs to the receiver of another component called grafana_loki.

The loki.process documentation provides more comprehensive information on processing logs.

Fourth component: Write logs to Loki

Copy and paste this component configuration below the previous component in your config.alloy file.

loki.write "grafana_loki" {
  endpoint {
    url = "http://localhost:3100/loki/api/v1/push"

    // basic_auth {
    //  username = "admin"
    //  password = "admin"
    // }
  }
}

This final component creates a loki.write component named grafana_loki that points to http://localhost:3100/loki/api/v1/push.

This completes the simple configuration pipeline.

Tip
The basic_auth block is commented out because the local docker compose stack doesn’t require it. It’s included in this example to show how you can configure authorization for other environments. For further authorization options, refer to the loki.write component reference.

With this configuration, Alloy connects directly to the Loki instance running in the Docker container.

Reload the configuration

Copy your local config.alloy file into the default Alloy configuration file location.
macos
sudo cp config.alloy $(brew --prefix)/etc/alloy/config.alloy
linux
sudo cp config.alloy /etc/alloy/config.alloy
Call the /-/reload endpoint to tell Alloy to reload the configuration file without a system service restart.
Bash
```
curl -X POST http://localhost:12345/-/reload
```
Tip
This step uses the Alloy UI on localhost port 12345. If you chose to run Alloy in a Docker container, make sure you use the --server.http.listen-addr=0.0.0.0:12345 argument. If you don’t use this argument, the debugging UI won’t be available outside of the Docker container.
Optional: You can do a system service restart Alloy and load the configuration file.

brew services restart grafana/grafana/alloy

sudo systemctl reload alloy

Inspect your configuration in the Alloy UI

Open http://localhost:12345 and click the Graph tab at the top. The graph should look similar to the following:

The Alloy UI shows you a visual representation of the pipeline you built with your Alloy component configuration.

You can see that the components are healthy, and you are ready to explore the logs in Grafana.

Log in to Grafana and explore Loki logs

Open http://localhost:3000/explore to access Explore feature in Grafana.

Select Loki as the data source and click the Label Browser button to select a file that Alloy has sent to Loki.

Here you can see that logs are flowing through to Loki as expected, and the end-to-end configuration was successful.

Summary

You have installed and configured Alloy, and sent logs from your local host to your local Grafana stack.

In the next tutorial, you learn more about configuration concepts and metrics.

Use Grafana Alloy to send metrics to Prometheus

Mon, 30 Mar 2026 15:47:22 +0000

Use Grafana Alloy to send metrics to Prometheus

In the previous tutorial, you learned how to configure Alloy to collect and process logs from your local machine and send them to Loki.

This tutorial shows you how to configure Alloy to collect and process metrics from your local machine, send them to Prometheus, and use Grafana to explore the results.

Before you begin

To complete this tutorial:

You must have a basic understanding of Alloy and telemetry collection in general.
You should be familiar with Prometheus, PromQL, Loki, LogQL, and basic Grafana navigation.
You must complete the previous tutorial to prepare the following prerequisites:
- Install Alloy and start the service in your environment.
- Set up a local Grafana instance.
- Create a config.alloy file.

Tip
Alternatively, you can try out this example in the interactive learning environment: Sending metrics to Prometheus.

It’s a fully configured environment with all the dependencies already installed.

Configure Alloy

In this tutorial, you configure Alloy to collect metrics and send them to Prometheus.

You add components to your config.alloy file to tell Alloy which metrics you want to scrape, how you want to process that data, and where you want the data sent.

The following steps build on the config.alloy file you created in the previous tutorial.

First component: Scraping

Paste the following component configuration at the top of your config.alloy file:

prometheus.exporter.unix "local_system" { }

prometheus.scrape "scrape_metrics" {
  targets         = prometheus.exporter.unix.local_system.targets
  forward_to      = [prometheus.relabel.filter_metrics.receiver]
  scrape_interval = "10s"
}

This configuration creates a prometheus.scrape component named scrape_metrics which does the following:

It connects to the local_system component as its source or target.
It forwards the metrics it scrapes to the receiver of another component called filter_metrics.
It tells Alloy to scrape metrics every 10 seconds.

Second component: Filter metrics

Filtering non-essential metrics before sending them to a data source can help you reduce costs and allow you to focus on the data that matters most.

The following example demonstrates how you can filter out or drop metrics before sending them to Prometheus.

Paste the following component configuration below the previous component in your config.alloy file:

prometheus.relabel "filter_metrics" {
  rule {
    action        = "drop"
    source_labels = ["env"]
    regex         = "dev"
  }

  forward_to = [prometheus.remote_write.metrics_service.receiver]
}

The prometheus.relabel component is commonly used to filter Prometheus metrics or standardize the label set passed to one or more downstream receivers. You can use this component to rewrite the label set of each metric sent to the receiver. Within this component, you can define rule blocks to specify how you would like to process metrics before they’re stored or forwarded.

This configuration creates a prometheus.relabel component named filter_metrics which does the following:

It receives scraped metrics from the scrape_metrics component.
It tells Alloy to drop metrics that have an "env" label equal to "dev".
It forwards the processed metrics to the receiver of another component called metrics_service.

Third component: Write metrics to Prometheus

Note
Prometheus typically scrapes metrics from targets using a pull mechanism. This component pushes metrics to Prometheus using the remote write protocol. To accept these remote write requests, start Prometheus with the --web.enable-remote-write-receiver flag. For more information, refer to the Remote storage integrations topic in the Prometheus documentation.

Paste the following component configuration below the previous component in your config.alloy file:

prometheus.remote_write "metrics_service" {
    endpoint {
        url = "http://localhost:9090/api/v1/write"

        // basic_auth {
        //   username = "admin"
        //   password = "admin"
        // }
    }
}

This final component creates a prometheus.remote_write component named metrics_service that points to http://localhost:9090/api/v1/write.

This completes the simple configuration pipeline.

Tip
The basic_auth is commented out because the local docker compose stack doesn’t require it. It’s included in this example to show how you can configure authorization for other environments.

For further authorization options, refer to the prometheus.remote_write component documentation.

This connects directly to the Prometheus instance running in the Docker container.

Reload the configuration

Copy your local config.alloy file into the default Alloy configuration file location.

sudo cp config.alloy $(brew --prefix)/etc/alloy/config.alloy

sudo cp config.alloy /etc/alloy/config.alloy

Call the /-/reload endpoint to tell Alloy to reload the configuration file without a system service restart.

curl -X POST http://localhost:12345/-/reload

Tip
This step uses the Alloy UI, on localhost port 12345. If you choose to run Alloy in a Docker container, make sure you use the --server.http.listen-addr=0.0.0.0:12345 argument.

If you don’t use this argument, the debugging UI won’t be available outside of the Docker container.

Optional: You can do a system service restart Alloy and load the configuration file:

brew services restart grafana/grafana/alloy

sudo systemctl reload alloy

Inspect your configuration in the Alloy UI

Open http://localhost:12345 and click the Graph tab at the top. The graph should look similar to the following:

The Alloy UI shows you a visual representation of the pipeline you built with your Alloy component configuration.

You can see that the components are healthy, and you are ready to explore the metrics in Grafana.

Log into Grafana and explore metrics in Prometheus

Open http://localhost:3000/explore/metrics/ to access the Metrics Drilldown feature in Grafana.

From here you can visually explore the metrics sent to Prometheus by Alloy.

You can also build PromQL queries manually to explore the data further.

Open http://localhost:3000/explore to access the Explore feature in Grafana.

Select Prometheus as the data source and click the Metrics Browser button to select the metric, labels, and values for your labels.

Here you can see that metrics are flowing through to Prometheus as expected, and the end-to-end configuration was successful.

Summary

You have configured Alloy to collect and process metrics from your local host and send them to your local Grafana stack.

First components and the standard library in Grafana Alloy

Mon, 30 Mar 2026 15:47:22 +0000

First components and the standard library in Grafana Alloy

This tutorial covers the basics of the Alloy configuration syntax and the standard library. It introduces a basic pipeline that collects metrics from the host and sends them to Prometheus.

Before you begin

To complete this tutorial:

You must set up a local Grafana instance.

Alloy configuration syntax basics

An Alloy configuration file contains three elements:

Attributes

key = value pairs used to configure individual settings.
Alloy
```
url = "http://localhost:9090"
```
Expressions

Expressions are used to compute values. They can be constant values, for example "localhost:9090". They can be more complex, for example, referencing a component’s export: prometheus.exporter.unix.targets. They can also be a mathematical expression: (1 + 2) * 3, or a standard library function call: sys.env("HOME"). If you are curious, you can find a list of available standard library functions in the Standard library documentation.
Blocks

Blocks are used to configure components with groups of attributes or nested blocks. The following example block can be used to configure the logging output of Alloy:
Alloy
```
logging {
    level  = "debug"
    format = "json"
}
```
Note
The default log level is info and the default log format is logfmt.

Try pasting this into config.alloy and running <BINARY_FILE_PATH> run config.alloy to see what happens. Replace <BINARY_FILE_PATH> with the path to the Alloy binary.

Congratulations, you’ve just written your first Alloy configuration file. This configuration won’t do anything. In the next step, you add some functionality to this configuration.

Note
Comments in Alloy syntax are prefixed with // and are single-line only. For example: // This is a comment.

Components

Components are the building blocks of an Alloy configuration. They’re configured and linked to create pipelines that collect, process, and output your telemetry data. Components are configured with Arguments and have Exports that may be referenced by other components.

An example pipeline

Look at the following simple pipeline:

local.file "example" {
    filename = sys.env("HOME") + "/file.txt"
}

prometheus.remote_write "local_prom" {
    endpoint {
        url = "http://localhost:9090/api/v1/write"

        basic_auth {
            username = "admin"
            password = local.file.example.content
        }
    }
}

Note
A list of all available components can be found in the Component reference. Each component has a link to its documentation, which contains a description of what the component does, its arguments, its exports, and examples.

This pipeline has two components: local.file and prometheus.remote_write. The local.file component is configured with a single argument, filename, which is set by calling the sys.env standard library function to retrieve the value of the HOME environment variable and concatenating it with the string "file.txt". The local.file component has a single export, content, which contains the contents of the file.

The prometheus.remote_write component is configured with an endpoint block, containing the url attribute and a basic_auth block. The url attribute is set to the URL of the Prometheus remote write endpoint. The basic_auth block contains the username and password attributes, which are set to the string "admin" and the content export of the local.file component, respectively. The content export is referenced by using the syntax local.file.example.content, where local.file.example is the fully qualified name of the component (the component’s type + its label) and content is the name of the export.

Note
The local.file component’s label is set to "example", so the fully qualified name of the component is local.file.example. The prometheus.remote_write component’s label is set to "local_prom", so the fully qualified name of the component is prometheus.remote_write.local_prom.

This example pipeline still doesn’t do anything, so its time to add some more components to it.

Send your first metrics

Now that you have a simple pipeline, you can send your first metrics.

Modify your pipeline and scrape the metrics

Make a simple pipeline with a prometheus.exporter.unix component, a prometheus.scrape component to scrape it, and a prometheus.remote_write component to send the scraped metrics to Prometheus.

prometheus.exporter.unix "localhost" {
    // This component exposes a lot of metrics by default, so we will keep all of the default arguments.
}

prometheus.scrape "default" {
    // Setting the scrape interval lower to make it faster to be able to see the metrics
    scrape_interval = "10s"

    targets    = prometheus.exporter.unix.localhost.targets
    forward_to = [
        prometheus.remote_write.local_prom.receiver,
    ]
}

prometheus.remote_write "local_prom" {
    endpoint {
        url = "http://localhost:9090/api/v1/write"
    }
}

Run Alloy with the following command:

<BINARY_FILE_PATH> run config.alloy

Replace the following:

<BINARY_FILE_PATH>: The path to the Alloy binary.

Navigate to http://localhost:3000/explore in your browser. After ~15-20 seconds, you should be able to see the metrics from the prometheus.exporter.unix component. Try querying for node_memory_Active_bytes to see the active memory of your host.

Visualize the relationship between components

The following diagram is an example pipeline:

Your pipeline configuration defines three components:

prometheus.scrape - A component that scrapes metrics from components that export targets.
prometheus.exporter.unix - A component that exports metrics from the host, built around node_exporter.
prometheus.remote_write - A component that sends metrics to a Prometheus remote-write compatible endpoint.

The prometheus.scrape component references the prometheus.exporter.unix component’s targets export, which is a list of scrape targets. The prometheus.scrape component forwards the scraped metrics to the prometheus.remote_write component.

One rule is that components can’t form a cycle. This means that a component can’t reference itself directly or indirectly. This is to prevent infinite loops from forming in the pipeline.

Exercise

The following exercise guides you through modifying your pipeline to scrape metrics from Redis.

Finish up and next steps

You might have noticed that running Alloy with the configurations created a directory called data-alloy in the directory you ran Alloy from. This directory is where components can store data, such as the prometheus.exporter.unix component storing its Write Ahead Log (WAL). If you look in the directory, do you notice anything interesting? The directory for each component is the fully qualified name.

If you’d like to store the data elsewhere, you can specify a different directory by supplying the --storage.path flag to Alloy’s run command, for example, <BINARY_FILE_PATH> run config.alloy --storage.path /etc/alloy. Replace <BINARY_FILE_PATH> with the path to the Alloy binary. Generally, you can use a persistent directory for this, as some components may use the data stored in this directory to perform their function.

In the next tutorial, you learn how to configure Alloy to collect logs from a file and send them to Loki. You also learn how to use different components to process metrics and logs.

Logs and relabeling basics in Grafana Alloy

Mon, 30 Mar 2026 15:47:22 +0000

Logs and relabeling basics in Grafana Alloy

This tutorial covers some basic metric relabeling, and shows you how to send logs to Loki.

Before you begin

To complete this tutorial:

You must complete the First components and the standard library tutorial.

Relabel metrics

Now that you have built a basic pipeline and scraped some metrics, you can use the prometheus.relabel component to relabel metrics.

Add a `prometheus.relabel` component to your pipeline

The prometheus.relabel component allows you to perform Prometheus relabeling on metrics and is similar to the relabel_configs section of a Prometheus scrape configuration.

Add a prometheus.relabel component to a basic pipeline and add labels.

prometheus.exporter.unix "localhost" { }

prometheus.scrape "default" {
    scrape_interval = "10s"

    targets    = prometheus.exporter.unix.localhost.targets
    forward_to = [
        prometheus.relabel.example.receiver,
    ]
}

prometheus.relabel "example" {
    forward_to = [
        prometheus.remote_write.local_prom.receiver,
    ]

    rule {
        action       = "replace"
        target_label = "os"
        replacement  = constants.os
    }
}

prometheus.remote_write "local_prom" {
    endpoint {
        url = "http://localhost:9090/api/v1/write"
    }
}

You have created the following pipeline:

This pipeline has a prometheus.relabel component that has a single rule. This rule has the replace action, which replaces the value of the os label with a special value: constants.os. This value is a special constant that’s replaced with the OS of the host Alloy is running on. You can see the other available constants in the constants documentation. This example has one rule block, but you can have as many as you want. Each rule block is applied in order.

Note
Multiple keep rules are applied sequentially. If a target fails the first keep, it’s dropped immediately, so two separate keep rules act like a logical AND. To implement OR logic across multiple criteria, you can combine them in one rule using multiple source_labels and a compound regular expression.

The following example demonstrates how you can implement OR in one rule:
Alloy
rule {
 source_labels = ["__meta_kubernetes_pod_annotation_A", "__meta_kubernetes_pod_label_B"]
 regex         = "(true;.*|.*;true)"
 action        = "keep"
}

If you run Alloy and navigate to http://localhost:3000/explore, you can see the os label on the metrics. Try querying for node_context_switches_total and look at the labels.

Relabeling uses the same rules as Prometheus. You can always refer to the prometheus.relabel rule-block documentation for a full list of available options.

Note
You can forward multiple components to one prometheus.relabel component. This allows you to apply the same relabeling rules to multiple pipelines.

Warning
There is an issue commonly faced when relabeling and using labels that start with __ (double underscore). These labels are considered internal and are dropped before relabeling rules from a prometheus.relabel component are applied. If you would like to keep or act on these kinds of labels, use a discovery.relabel component.

Send logs to Loki

Now that you’ve created components and chained them together, you can collect some logs and send them to Loki.

Find and collect the logs

You can use the local.file_match component to perform file discovery, the loki.source.file to collect the logs, and the loki.write component to send the logs to Loki.

Before doing this, make sure you have a log file to scrape. You can use the echo command to create a file with some log content.

mkdir -p /tmp/alloy-logs
echo "This is a log line" > /tmp/alloy-logs/log.log

Now that you have a log file, you can create a pipeline to scrape it.

local.file_match "tmplogs" {
    path_targets = [{"__path__" = "/tmp/alloy-logs/*.log"}]
}

loki.source.file "local_files" {
    targets    = local.file_match.tmplogs.targets
    forward_to = [loki.write.local_loki.receiver]
}

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

The rough flow of this pipeline is:

If you navigate to http://localhost:3000/explore and switch the data source to Loki, you can query for {filename="/tmp/alloy-logs/log.log"} and see the log line you created earlier. Try running the following command to add more logs to the file.

echo "This is another log line!" >> /tmp/alloy-logs/log.log

If you re-execute the query, you can see the new log lines.

If you are curious how Alloy keeps track of where it’s in a log file, you can look at data-alloy/loki.source.file.local_files/positions.yml. If you delete this file, Alloy starts reading from the beginning of the file again, which is why keeping the Alloy’s data directory in a persistent location is desirable.

Exercise

The following exercise guides you through adding a label to the logs, and filtering the results.

Add a Label to Logs

This exercise has two parts, and builds on the previous example. Start by adding an os label (just like the Prometheus example) to all of the logs you collect.

Modify the following snippet to add the label os with the value of the os constant.

local.file_match "tmplogs" {
    path_targets = [{"__path__" = "/tmp/alloy-logs/*.log"}]
}

loki.source.file "local_files" {
    targets    = local.file_match.tmplogs.targets
    forward_to = [loki.write.local_loki.receiver]
}

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

Tip
You can use the loki.relabel component to relabel and add labels, just like you can with the prometheus.relabel component.

Run Alloy and execute the following:

echo 'level=info msg="INFO: This is an info level log!"' >> /tmp/alloy-logs/log.log
echo 'level=warn msg="WARN: This is a warn level log!"' >> /tmp/alloy-logs/log.log
echo 'level=debug msg="DEBUG: This is a debug level log!"' >> /tmp/alloy-logs/log.log

Navigate to http://localhost:3000/explore and switch the data source to Loki. Try querying for {filename="/tmp/alloy-logs/log.log"} and see if you can find the new label.

Now that you have added new labels, you can also filter on them. Try querying for {os!=""}. You should only see the lines you added in the previous step.

// Let's learn about relabeling and send logs to Loki!

local.file_match "tmplogs" {
    path_targets = [{"__path__" = "/tmp/alloy-logs/*.log"}]
}

loki.source.file "local_files" {
    targets    = local.file_match.tmplogs.targets
    forward_to = [loki.relabel.add_static_label.receiver]
}

loki.relabel "add_static_label" {
    forward_to = [loki.write.local_loki.receiver]

    rule {
        target_label = "os"
        replacement  = constants.os
    }
}

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

Extract and add a Label from Logs

Note
This exercise is more challenging than the previous one. If you are having trouble, skip it and move to the next section, which covers some of the concepts used here. You can always come back to this exercise later.

This exercise builds on the previous one, though it’s more involved.

Assume you want to extract the level from the logs and add it as a label. As a starting point, look at loki.process. This component allows you to perform processing on logs, including extracting values from log contents.

Try modifying your configuration from the previous section to extract the level from the logs and add it as a label. If needed, you can find a solution to the previous exercise at the end of the previous section.

Tip
The stage.logfmt and stage.labels blocks for loki.process may be helpful.

Run Alloy and execute the following:

echo 'level=info msg="INFO: This is an info level log!"' >> /tmp/alloy-logs/log.log
echo 'level=warn msg="WARN: This is a warn level log!"' >> /tmp/alloy-logs/log.log
echo 'level=debug msg="DEBUG: This is a debug level log!"' >> /tmp/alloy-logs/log.log

Navigate to http://localhost:3000/explore and switch the data source to Loki. Try querying for {level!=""} to see the new labels in action.

// Let's learn about relabeling and send logs to Loki!

local.file_match "tmplogs" {
    path_targets = [{"__path__" = "/tmp/alloy-logs/*.log"}]
}

loki.source.file "local_files" {
    targets    = local.file_match.tmplogs.targets
    forward_to = [loki.process.add_new_label.receiver]
}

loki.process "add_new_label" {
    // Extract the value of "level" from the log line and add it to the extracted map as "extracted_level"
    // You could also use "level" = "", which would extract the value of "level" and add it to the extracted map as "level"
    // but to make it explicit for this example, we will use a different name.
    //
    // The extracted map will be covered in more detail in the next section.
    stage.logfmt {
        mapping = {
            "extracted_level" = "level",
        }
    }

    // Add the value of "extracted_level" from the extracted map as a "level" label
    stage.labels {
        values = {
            "level" = "extracted_level",
        }
    }

    forward_to = [loki.relabel.add_static_label.receiver]
}

loki.relabel "add_static_label" {
    forward_to = [loki.write.local_loki.receiver]

    rule {
        target_label = "os"
        replacement  = constants.os
    }
}

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

Finish up and next steps

You have learned the concepts of components, attributes, and expressions. You have also seen how to use some standard library components to collect metrics and logs. In the next tutorial, you learn more about how to use the loki.process component to extract values from logs and use them.

Process logs with Grafana Alloy

Mon, 30 Mar 2026 15:47:22 +0000

Process logs with Grafana Alloy

This tutorial assumes you are familiar with setting up and connecting components. It covers using loki.source.api to receive logs over HTTP, processing and filtering them, and sending them to Loki.

Before you begin

To complete this tutorial:

You must complete the Logs and relabeling basics tutorial.

Receive logs over HTTP and Process

The loki.source.api component can receive logs over HTTP. It can be useful for receiving logs from other Alloys or collectors, or directly from applications that can send logs over HTTP, and then processing them centrally.

Set up the `loki.source.api` component

Your pipeline is going to look like this:

Start by setting up the loki.source.api component:

loki.source.api "listener" {
    http {
        listen_address = "127.0.0.1"
        listen_port    = 9999
    }

    labels = { source = "api" }

    forward_to = [loki.process.process_logs.receiver]
}

This is a simple configuration. You are configuring the loki.source.api component to listen on 127.0.0.1:9999 and attach a source="api" label to the received log entries, which are then forwarded to the loki.process.process_logs component’s exported receiver.

Process and Write Logs

Configure the `loki.process` and `loki.write` components

Now that you have set up the loki.source.api component, you can configure the loki.process and loki.write components.

// Let's send and process more logs!

loki.source.api "listener" {
    http {
        listen_address = "127.0.0.1"
        listen_port    = 9999
    }

    labels = { "source" = "api" }

    forward_to = [loki.process.process_logs.receiver]
}

loki.process "process_logs" {

    // Stage 1
    stage.json {
        expressions = {
            log = "",
            ts  = "timestamp",
        }
    }

    // Stage 2
    stage.timestamp {
        source = "ts"
        format = "RFC3339"
    }

    // Stage 3
    stage.json {
        source = "log"

        expressions = {
            is_secret = "",
            level     = "",
            log_line  = "message",
        }
    }

    // Stage 4
    stage.drop {
        source = "is_secret"
        value  = "true"
    }

    // Stage 5
    stage.labels {
        values = {
            level = "",
        }
    }

    // Stage 6
    stage.output {
        source = "log_line"
    }

    // This stage adds static values to the labels on the log line
    stage.static_labels {
        values = {
            source = "demo-api",
        }
    }

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

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

Many of the stage.* blocks in loki.process act on reading or writing a shared map of values extracted from the logs. You can think of this extracted map as a hashmap or table that each stage has access to, and it’s referred to as the “extracted map” from here on. In subsequent stages, you can use the extracted map to filter logs, add, or remove labels, or even modify the log line.

Note
stage.* blocks are executed in the order they appear in the component, top down.

You can use an example log line to illustrate this, then go stage by stage, showing the contents of the extracted map. Here is the example log line:

{
    "log": {
        "is_secret": "true",
        "level": "info",
        "message": "This is a secret message!",
    },
    "timestamp": "2023-11-16T06:01:50Z",
}

Stage 1

stage.json {
    expressions = {
        log = "",
        ts  = "timestamp",
    }
}

This stage parses the log line as JSON, extracts two values from it, log and timestamp, and puts them into the extracted map with keys log and ts, respectively.

Note
Supplying an empty string is shorthand for using the same key as in the input log line, so log = "" is the same as log = "log". The keys of the expressions object end up as the keys in the extracted map, and the values are used as keys to look up in the parsed log line.

If this were Python, it would be roughly equivalent to:

extracted_map = {}
log_line      = {"log": {"is_secret": "true", "level": "info", "message": "This is a secret message!"}, "timestamp": "2023-11-16T06:01:50Z"}

extracted_map["log"] = log_line["log"]
extracted_map["ts"]  = log_line["timestamp"]

Extracted map before performing this stage:

{}

Extracted map after performing this stage:

{
    "log": {
        "is_secret": "true",
        "level": "info",
        "message": "This is a secret message!",
    },
    "ts": "2023-11-16T06:01:50Z",
}

Stage 2

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

This stage acts on the ts value in the map you extracted in the previous stage. The value of ts is parsed in the format of RFC3339 and added as the timestamp to be ingested by Loki. This is useful if you want to use the timestamp present in the log itself, rather than the time the log is ingested. This stage doesn’t modify the extracted map.

Stage 3

stage.json {
    source = "log"

    expressions = {
        is_secret = "",
        level     = "",
        log_line  = "message",
    }
}

This stage acts on the log value in the extracted map, which is a value that you extracted in the previous stage. This value is also a JSON object, so you can extract values from it as well. This stage extracts three values from the log value, is_secret, level, and log_line, and puts them into the extracted map with keys is_secret, level, and log_line.

If this were Python, it would be roughly equivalent to:

extracted_map = {
    "log": {
        "is_secret": "true",
        "level": "info",
        "message": "This is a secret message!",
    },
    "ts": "2023-11-16T06:01:50Z",
}

source = extracted_map["log"]

extracted_map["is_secret"] = source["is_secret"]
extracted_map["level"]     = source["level"]
extracted_map["log_line"]  = source["message"]

Extracted map before performing this stage:

{
    "log": {
        "is_secret": "true",
        "level": "info",
        "message": "This is a secret message!",
    },
    "ts": "2023-11-16T06:01:50Z",
}

Extracted map after performing this stage:

{
    "log": {
        "is_secret": "true",
        "level": "info",
        "message": "This is a secret message!",
    },
    "ts": "2023-11-16T06:01:50Z",
    "is_secret": "true",
    "level": "info",
    "log_line": "This is a secret message!",
}

Stage 4

stage.drop {
    source = "is_secret"
    value  = "true"
}

This stage acts on the is_secret value in the extracted map, which is a value that you extracted in the previous stage. This stage drops the log line if the value of is_secret is "true" and doesn’t modify the extracted map. There are many other ways to filter logs, but this is a simple example. Refer to the [loki.process][loki.process#stage.drop] stage.drop documentation for more information.

Stage 5

stage.labels {
    values = {
        level = "",
    }
}

This stage adds a label to the log using the same shorthand as before, so this is equivalent to using values = { level = "level" }. This stage adds a label with key level and the value of level in the extracted map to the log ("info" from the example log line). This stage doesn’t modify the extracted map.

Stage 6

stage.output {
    source = "log_line"
}

This stage uses the log_line value in the extracted map to set the actual log line that’s forwarded to Loki. Rather than sending the entire JSON blob to Loki, you are only sending original_log_line["log"]["message"], along with some labels that you attached.

This stage doesn’t modify the extracted map.

Put it all together

Now that you have all of the pieces, you can run Alloy and send some logs to it. Modify config.alloy with the configuration from the previous example and start Alloy with:

<BINARY_FILE_PATH> run config.alloy

Replace the following:

<BINARY_FILE_PATH>: The path to the Alloy binary.

Try executing the following which inserts the current timestamp:

curl localhost:9999/loki/api/v1/raw -XPOST -H "Content-Type: application/json" -d '{"log": {"is_secret": "false", "level": "debug", "message": "This is a debug message!"}, "timestamp":  "'"$(date -u +"%Y-%m-%dT%H:%M:%SZ")"'"}'

Now that you have sent some logs, its time to see how they look in Grafana. Navigate to http://localhost:3000/explore and switch the data source to Loki. Try querying for {source="demo-api"} and see if you can find the logs you sent.

Try playing around with the values of "level", "message", "timestamp", and "is_secret" and see how the logs change. You can also try adding more stages to the loki.process component to extract more values from the logs, or add more labels.

Exercise

Since you are already using Docker and Docker exports logs, you can send those logs to Loki. Refer to the discovery.docker and loki.source.docker documentation for more information.

To ensure proper timestamps and other labels, make sure you use a loki.process component to process the logs before sending them to Loki.

Although you haven’t used it before, you can use a discovery.relabel component to attach the container name as a label to the logs. You can refer to the discovery.relabel documentation for more information. The discovery.relabel component is very similar to the prometheus.relabel component, but it relabels discovered targets rather than metrics.

// Discover docker containers to collect logs from
discovery.docker "docker_containers" {
    // Note that if you are using Docker Desktop Engine this may need to be changed to
    // something like "unix:///${HOME}/.docker/desktop/docker.sock"
    host = "unix:///var/run/docker.sock"
}

// Extract container name from __meta_docker_container_name label and add as label
discovery.relabel "docker_containers" {
    targets = discovery.docker.docker_containers.targets

    rule {
        source_labels = ["__meta_docker_container_name"]
        target_label  = "container"
    }
}

// Scrape logs from docker containers and send to be processed
loki.source.docker "docker_logs" {
    host    = "unix:///var/run/docker.sock"
    targets = discovery.relabel.docker_containers.output
    forward_to = [loki.process.process_logs.receiver]
}

// Process logs and send to Loki
loki.process "process_logs" {
    stage.docker { }

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

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

Grafana Alloy tutorials on Grafana Labs

Use Grafana Alloy to send logs to Loki

Use Grafana Alloy to send logs to Loki

Before you begin

Install Alloy and start the service

Linux

macOS

Set up a local Grafana instance

Configure Alloy

Create a config.alloy file

First component: Log files

Second component: Scraping

Third component: Filter non-essential logs

Fourth component: Write logs to Loki

Reload the configuration

Inspect your configuration in the Alloy UI

Log in to Grafana and explore Loki logs

Summary

Use Grafana Alloy to send metrics to Prometheus

Use Grafana Alloy to send metrics to Prometheus

Before you begin

Configure Alloy

First component: Scraping

Second component: Filter metrics

Third component: Write metrics to Prometheus

Reload the configuration

Inspect your configuration in the Alloy UI

Log into Grafana and explore metrics in Prometheus

Summary

First components and the standard library in Grafana Alloy

First components and the standard library in Grafana Alloy

Before you begin

Recommended reading

Alloy configuration syntax basics

Components

Recommended reading

An example pipeline

Send your first metrics

Recommended reading

Modify your pipeline and scrape the metrics

Visualize the relationship between components

Exercise

Recommended Reading

Finish up and next steps

Logs and relabeling basics in Grafana Alloy

Logs and relabeling basics in Grafana Alloy

Before you begin

Relabel metrics

Recommended reading

Add a prometheus.relabel component to your pipeline

Send logs to Loki

Recommended reading

Find and collect the logs

Exercise

Recommended reading

Add a Label to Logs

Extract and add a Label from Logs

Finish up and next steps

Process logs with Grafana Alloy

Process logs with Grafana Alloy

Before you begin

Receive logs over HTTP and Process

Recommended reading

Set up the loki.source.api component

Process and Write Logs

Recommended reading

Configure the loki.process and loki.write components

Stage 1

Stage 2

Stage 3

Stage 4

Stage 5

Stage 6

Put it all together

Exercise

Create a `config.alloy` file

Add a `prometheus.relabel` component to your pipeline

Set up the `loki.source.api` component

Configure the `loki.process` and `loki.write` components