Fluent Bit on Grafana Labs

Sending logs to Loki using Fluent Bit tutorial

Thu, 09 Apr 2026 02:28:18 +0000

Sending logs to Loki using Fluent Bit tutorial

In this tutorial, you will learn how to send logs to Loki using Fluent Bit. Fluent Bit is a lightweight and fast log processor and forwarder that can collect, process, and deliver logs to various destinations. We will use the official Fluent Bit Loki output plugin to send logs to Loki.

Dependencies

Before you begin, ensure you have the following to run the demo:

Docker
Docker Compose

Tip
Alternatively, you can try out this example in our interactive learning environment: Sending logs to Loki using Fluent Bit tutorial.

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

Provide feedback, report bugs, and raise issues in the Grafana Killercoda repository.

Scenario

In this scenario, we have a microservices application called the Carnivorous Greenhouse. This application consists of the following services:

User Service: Manages user data and authentication for the application. Such as creating users and logging in.
Plant Service: Manages the creation of new plants and updates other services when a new plant is created.
Simulation Service: Generates sensor data for each plant.
Websocket Service: Manages the websocket connections for the application.
Bug Service: A service that when enabled, randomly causes services to fail and generate additional logs.
Main App: The main application that ties all the services together.
Database: A database that stores user and plant data.

Each service has been instrumented with the Fluent Bit logging framework to generate logs. If you would like to learn more about how the Carnivorous Greenhouse application was instrumented with Fluent Bit, refer to the Carnivorous Greenhouse repository.

Step 1: Environment setup

In this step, we will set up our environment by cloning the repository that contains our demo application and spinning up our observability stack using Docker Compose.

To get started, clone the repository that contains our demo application:

git clone -b fluentbit-official  https://github.com/grafana/loki-fundamentals.git

Next we will spin up our observability stack using Docker Compose:

docker compose -f loki-fundamentals/docker-compose.yml up -d

This will spin up the following services:

✔ Container loki-fundamentals-grafana-1       Started                                                        
✔ Container loki-fundamentals-loki-1          Started                        
✔ Container loki-fundamentals-fluent-bit-1    Started

Once we have finished configuring the Fluent Bit agent and sending logs to Loki, we will be able to view the logs in Grafana. To check if Grafana is up and running, navigate to the following URL: http://localhost:3000

Step 2: Configure Fluent Bit to send logs to Loki

To configure Fluent Bit to receive logs from our application, we need to provide a configuration file. This configuration file will define the components and their relationships. We will build the entire observability pipeline within this configuration file.

Open your code editor and locate the `fluent-bit.conf` file

Fluent Bit requires a configuration file to define the components and their relationships. The configuration file is written using Fluent Bit configuration syntax. We will build the entire observability pipeline within this configuration file. To start, we will open the fluent-bit.conf file in the code editor:

Open the loki-fundamentals directory in a code editor of your choice.
Locate the fluent-bit.conf file in the loki-fundamentals directory (Top level directory).
Click on the fluent-bit.conf file to open it in the code editor.

You will copy all of the configuration snippets into the fluent-bit.conf file.

Receiving Fluent Bit protocol logs

The first step is to configure Fluent Bit to receive logs from the Carnivorous Greenhouse application. Since the application is instrumented with Fluent Bit logging framework, it will send logs using the forward protocol (unique to Fluent Bit). We will use the forward input plugin to receive logs from the application.

Now add the following configuration to the fluent-bit.conf file:

[INPUT]
    Name              forward
    Listen            0.0.0.0
    Port              24224

In this configuration:

Name: The name of the input plugin. In this case, we are using the forward input plugin.
Listen: The IP address to listen on. In this case, we are listening on all IP addresses.
Port: The port to listen on. In this case, we are listening on port 24224.

For more information on the forward input plugin, see the Fluent Bit Forward documentation.

Export logs to Loki using the official Loki output plugin

Lastly, we will configure Fluent Bit to export logs to Loki using the official Loki output plugin. The Loki output plugin allows you to send logs or events to a Loki service. It supports data enrichment with Kubernetes labels, custom label keys, and structured metadata.

Add the following configuration to the fluent-bit.conf file:

[OUTPUT]
    name   loki
    match  service.**
    host   loki
    port   3100
    labels agent=fluent-bit
    label_map_path /fluent-bit/etc/conf/logmap.json

In this configuration:

name: The name of the output plugin. In this case, we are using the loki output plugin.
match: The tag to match. In this case, we are matching all logs with the tag service.**.
host: The hostname of the Loki service. In this case, we are using the hostname loki.
port: The port of the Loki service. In this case, we are using port 3100.
labels: Additional labels to add to the logs. In this case, we are adding the label agent=fluent-bit.
label_map_path: The path to the label map file. In this case, we are using the file logmap.json.

For more information on the loki output plugin, see the Fluent Bit Loki documentation.

`logmap.json` file

The logmap.json file is used to map the log fields to the Loki labels. In this tutorial we have pre-filled the logmap.json file with the following configuration:

{
"service": "service_name",
"instance_id": "instance_id"
 }

This configuration maps the service field to the Loki label service_name and the instance_id field to the Loki label instance_id.

Reload the Fluent Bit configuration

After adding the configuration to the fluent-bit.conf file, you will need to reload the Fluent Bit configuration. To reload the configuration, run the following command:

docker restart loki-fundamentals-fluent-bit-1

To verify that the configuration has been loaded successfully, you can check the Fluent Bit logs by running the following command:

docker logs loki-fundamentals-fluent-bit-1

Stuck? Need help?

If you get stuck or need help creating the configuration, you can copy and replace the entire config.alloy using the completed configuration file:

cp loki-fundamentals/completed/fluent-bit.conf loki-fundamentals/fluent-bit.conf
docker restart loki-fundamentals-fluent-bit-1

Step 3: Start the Carnivorous Greenhouse

In this step, we will start the Carnivorous Greenhouse application. To start the application, run the following command:

Note
This docker-compose file relies on the loki-fundamentals_loki Docker network. If you have not started the observability stack, you will need to start it first.

docker compose -f loki-fundamentals/greenhouse/docker-compose-micro.yml up -d --build

This will start the following services:

 ✔ Container greenhouse-db-1                 Started                                                         
 ✔ Container greenhouse-websocket_service-1  Started 
 ✔ Container greenhouse-bug_service-1        Started
 ✔ Container greenhouse-user_service-1       Started
 ✔ Container greenhouse-plant_service-1      Started
 ✔ Container greenhouse-simulation_service-1 Started
 ✔ Container greenhouse-main_app-1           Started

Once started, you can access the Carnivorous Greenhouse application at http://localhost:5005. Generate some logs by interacting with the application in the following ways:

Create a user.
Log in.
Create a few plants to monitor.
Enable bug mode to activate the bug service. This will cause services to fail and generate additional logs.

Finally to view the logs in Loki, navigate to the Loki Logs Explore view in Grafana at http://localhost:3000/a/grafana-lokiexplore-app/explore.

Summary

In this tutorial, you learned how to send logs to Loki using Fluent Bit. You configured Fluent Bit to receive logs from the Carnivorous Greenhouse application and export logs to Loki using the official Loki output plugin. Where to next?

Complete metrics, logs, traces, and profiling example

If you would like to use a demo that includes Mimir, Loki, Tempo, and Grafana, you can use Introduction to Metrics, Logs, Traces, and Profiling in Grafana. Intro-to-mltp provides a self-contained environment for learning about Mimir, Loki, Tempo, and Grafana.

The project includes detailed explanations of each component and annotated configurations for a single-instance deployment. Data from intro-to-mltp can also be pushed to Grafana Cloud.

Fluent Bit community plugin

Thu, 09 Apr 2026 02:28:18 +0000

Fluent Bit community plugin

Warning
We recommend using the official Fluent Bit Loki plugin. The official plugin is more feature-rich and has better support for features such as structured metadata. The community plugin is still available for use, but it’s no longer actively maintained.

The Fluent Bit community plugin by Grafana Labs (grafana-loki) provided an alternative way to send logs to Loki. Although very similar to the official plugin there are some differences in the configuration options. This page provides instructions for how to install, configure, and use the Fluent Bit community plugin to send logs to Loki. Although the plugin is no longer actively maintained, this documentation is still available for reference.

Usage

Docker

You can run a Fluent Bit container with Loki output plugin pre-installed using our Docker Hub image:

docker run -v /var/log:/var/log \
    -e LOG_PATH="/var/log/*.log" -e LOKI_URL="http://localhost:3100/loki/api/v1/push" \
    grafana/fluent-bit-plugin-loki:latest

Or, an alternative is to run the fluent-bit container using Docker Hub image:

Docker container logs

To ship logs from Docker containers to Grafana Cloud using Fluent Bit, you can use the Fluent Bit Docker image and configure it to forward logs directly to Grafana Loki. Below is a step-by-step guide on setting up Fluent Bit for this purpose.

Prerequisites

Docker is installed on your machine.
Running instance of Loki OSS.

Configuration

Create a Fluent Bit configuration file named fluent-bit.conf with the following content, which defines the input from Docker container logs and sets up the output to send logs to your Grafana Cloud Loki instance:

[SERVICE]
    Flush        1
    Log_Level    info

[INPUT]
    Name     tail
    Path     /var/lib/docker/containers/*/*.log
    Parser   docker
    Tag      docker.*

[OUTPUT]
    Name         grafana-loki
    Match        *
    Url          http://localhost:3100/loki/api/v1/push
    Labels       {job="fluentbit"}

Kubernetes

You can run Fluent Bit as a daemonset to collect all your Kubernetes workload logs.

To do so you can use the Fluent Bit Helm chart with the following values.yaml changing the value of FLUENT_LOKI_URL:

image:
  # Here we use the Docker image which has the plugin installed
  repository: grafana/fluent-bit-plugin-loki
  tag: main-e2ed1c0

args:
  - "-e"
  - "/fluent-bit/bin/out_grafana_loki.so"
  - --workdir=/fluent-bit/etc
  - --config=/fluent-bit/etc/conf/fluent-bit.conf

env:
  # Note that for security reasons you should fetch the credentials through a Kubernetes Secret https://kubernetes.io/docs/concepts/configuration/secret/ . You may use the envFrom for this.
  - name: FLUENT_LOKI_URL
    value: https://user:pass@your-loki.endpoint/loki/api/v1/push

config:
  inputs: |
    [INPUT]
        Name tail
        Tag kube.*
        Path /var/log/containers/*.log
        # Be aware that local clusters like docker-desktop or kind use the docker log format and not the cri (https://docs.fluentbit.io/manual/installation/kubernetes#container-runtime-interface-cri-parser)
        multiline.parser docker, cri
        Mem_Buf_Limit 5MB
        Skip_Long_Lines On

  outputs: |
    [Output]
        Name grafana-loki
        Match kube.*
        Url ${FLUENT_LOKI_URL}
        Labels {job="fluent-bit"}
        LabelKeys level,app # this sets the values for actual Loki streams and the other labels are converted to structured_metadata https://grafana.com/docs/loki/<LOKI_VERSION>/get-started/labels/structured-metadata/
        BatchWait 1
        BatchSize 1001024
        LineFormat json
        LogLevel info
        AutoKubernetesLabels true

helm repo add fluent https://fluent.github.io/helm-charts
helm repo update
helm install fluent-bit fluent/fluent-bit -f values.yaml

By default it will collect all containers logs and extract labels from Kubernetes API (container_name, namespace, etc.).

If you also want to host your Loki instance inside the cluster install the official Loki Helm chart.

AWS Elastic Container Service (ECS)

You can use the fluent-bit Loki Docker image as a Firelens log router in AWS ECS. For more information about this see the AWS ECS documentation.

Local

First, you need to follow the instructions in order to build the plugin dynamic library.

Assuming you have Fluent Bit installed in your $PATH you can run the plugin using:

fluent-bit -e /path/to/built/out_grafana_loki.so -c fluent-bit.conf

You can also adapt your plugins.conf, removing the need to change the command line options:

[PLUGINS]
    Path /path/to/built/out_grafana_loki.so

Configuration options

Key	Description	Default
Url	Url of Loki server API endpoint.	http://localhost:3100/loki/api/v1/push
TenantID	The tenant ID used by default to push logs to Loki. If omitted or empty it assumes Loki is running in single-tenant mode and no `X-Scope-OrgID` header is sent.	""
BatchWait	Time to wait before send a log batch to Loki, full or not.	1s
BatchSize	Log batch size to send a log batch to Loki (unit: Bytes).	10 KiB (10 * 1024 Bytes)
Timeout	Maximum time to wait for Loki server to respond to a request.	10s
MinBackoff	Initial backoff time between retries.	500ms
MaxBackoff	Maximum backoff time between retries.	5m
MaxRetries	Maximum number of retries when sending batches. Setting it to `0` will retry indefinitely.	10
Labels	Labels for API requests.	{job=“fluent-bit”}
LogLevel	LogLevel for plugin logger.	`info`
RemoveKeys	Specify removing keys.	none
AutoKubernetesLabels	If set to `true`, it will add all Kubernetes labels to Loki labels.	false
LabelKeys	Comma separated list of keys to use as stream labels. All other keys will be placed into the log line. LabelKeys is deactivated when using `LabelMapPath` label mapping configuration.	none
LineFormat	Format to use when flattening the record to a log line. Valid values are `json` or `key_value`. If set to `json` the log line sent to Loki will be the fluentd record (excluding any keys extracted out as labels) dumped as json. If set to `key_value`, the log line will be each item in the record concatenated together (separated by a single space) in the format <key>=<value>.	json
DropSingleKey	If set to true and after extracting label_keys a record only has a single key remaining, the log line sent to Loki will just be the value of the record key.	true
LabelMapPath	Path to a json file defining how to transform nested records.	none
Buffer	Enable buffering mechanism.	false
BufferType	Specify the buffering mechanism to use (currently only `dque` is implemented).	dque
DqueDir	Path to the directory for queued logs.	/tmp/flb-storage/loki
DqueSegmentSize	Segment size in terms of number of records per segment.	500
DqueSync	Whether to fsync each queue change. Specify no fsync with `normal`, and fsync with `full`.	`normal`
DqueName	Queue name, must be unique per output.	dque

Labels

Labels, for example {container_name="nginx", cluster="us-west1"}, are used to query logs. Labels are usually metadata about the workload producing the log stream (instance, container_name, region, cluster, level). In Loki labels are indexed, so you should be cautious when choosing them. High cardinality label values can have drastic impact on query performance.

You can use the config parameters Labels, RemoveKeys , LabelKeys and LabelMapPath to instruct the output plugin how to perform labels extraction from your log entries or to add static labels to all log entries.

AutoKubernetesLabels

If set to true, AutoKubernetesLabels will add all Kubernetes labels to Loki labels automatically and ignore parameters LabelKeys, LabelMapPath.

LabelMapPath

When using the Parser and Filter plugins Fluent Bit can extract and add data to the current record/log data. While Loki labels are key value pairs, record data can be nested structures. You can pass a JSON file that defines how to extract labels from each record. Each JSON key from the file will be matched with the log record to find label values. Values from the configuration are used as label names.

Considering the record below :

{
  "kubernetes": {
    "container_name": "myapp",
    "pod_name": "myapp-xxx",
    "namespace_name": "prod",
    "labels" : {
        "team": "x-men"
    }
  },
  "HOSTNAME": "docker-desktop",
  "log" : "a log line",
  "time": "20190926T152206Z"
}

and a LabelMap file as follows :

{
  "kubernetes": {
    "container_name": "container",
    "pod_name": "pod",
    "namespace_name": "namespace",
    "labels" : {
        "team": "team"
    }
  }
}

The labels extracted will be {team="x-men", container="myapp", pod="myapp-xxx", namespace="prod"}.

If you don’t want the kubernetes and HOSTNAME fields to appear in the log line you can use the RemoveKeys configuration field. For example, RemoveKeys kubernetes,HOSTNAME.

Buffering

Buffering refers to the ability to store the records somewhere, and while they are processed and delivered, still be able to continue storing more records. The Loki output plugin can be blocked by the Loki client because of its design:

If the BatchSize is over the limit, the output plugin pauses receiving new records until the pending batch is successfully sent to the server
If the Loki server is unreachable (retry 429s, 500s and connection-level errors), the output plugin blocks new records until the Loki server is available again, and the pending batch is successfully sent to the server or as long as the maximum number of attempts has been reached within configured back-off mechanism

The blocking state with some of the input plugins is not acceptable, because it can have an undesirable side effect on the part that generates the logs. Fluent Bit implements a buffering mechanism that is based on parallel processing. Therefore, it cannot send logs in order. There are two ways of handling the out-of-order logs:

Configure Loki to accept out-of-order writes.

Configure the Loki output plugin to use the buffering mechanism based on dque, which is compatible with the Loki server strict time ordering:

[Output]
    Name grafana-loki
    Match *
    Url http://localhost:3100/loki/api/v1/push
    Buffer true
    DqueSegmentSize 8096
    DqueDir /tmp/flb-storage/buffer
    DqueName loki.0

Configuration examples

To configure the Loki output plugin add this section to your luent-bit.conf file.

[Output]
    Name grafana-loki
    Match *
    Url http://localhost:3100/loki/api/v1/push
    BatchWait 1s
    BatchSize 30720
    # (30KiB)
    Labels {test="fluent-bit-go", lang="Golang"}
    RemoveKeys key1,key2
    LabelKeys key3,key4
    LineFormat key_value

[Output]
    Name grafana-loki
    Match *
    Url http://localhost:3100/loki/api/v1/push
    BatchWait 1s
    BatchSize 30720 # (30KiB)
    AutoKubernetesLabels true
    RemoveKeys key1,key2

A full example configuration file is also available in the Loki repository.

Running multiple plugin instances

You can run multiple plugin instances in the same fluent-bit process, for example if you want to push to different Loki servers or route logs into different Loki tenant IDs. To do so, add additional [Output] sections.

Fluent Bit Loki output plugin

Thu, 09 Apr 2026 02:28:18 +0000

Fluent Bit Loki output plugin

Fluent Bit is a fast and lightweight logs and metrics processor and forwarder that can be configured with the Fluent-bit Loki output plugin to ship logs to Loki.

You can define which log files you want to collect using the Tail or Stdin data pipeline input. Additionally, Fluent Bit supports multiple Filter and Parser plugins (Kubernetes, JSON, etc.) to structure and alter log lines.

Note
There are two Fluent Bit plugins for Loki: the officially maintained plugin loki and the grafana-loki plugin. We recommend using the loki plugin described within this page as it’s officially maintained by the Fluent Bit project.

For more information, see the Fluent Bit Loki output plugin documentation. Note that the grafana-loki plugin is no longer actively maintained.

Configuration

All configuration options for the Fluent Bit Loki output plugin are documented in the Fluent Bit Loki output plugin documentation.

Here is a generic example for connecting Fluent Bit to Loki hosted on Grafana Cloud:

    [OUTPUT]
        Name        loki
        Match       *
        Host        YourHostname.company.com
        port        443
        tls         on
        tls.verify  on
        http_user   XXX
        http_passwd XXX

Replace Host, http_user, and http_passwd with your Grafana Cloud Loki endpoint and credentials.

Usage examples

Here are some examples of how to use Fluent Bit to send logs to Loki.

Tail Docker logs

Here is an example to run Fluent Bit in a Docker container, collect Docker logs, and send them to a local Loki instance.

docker run -v /var/lib/docker/containers:/var/lib/docker/containers fluent/fluent-bit:latest /fluent-bit/bin/fluent-bit -i tail -p Path="/var/lib/docker/containers/*/*.log" -p Parser=docker -p Tag="docker.*"  -o loki -p host=loki -p port=3100 -p labels="agent=fluend-bit,env=docker"

In this example, we are using the tail input plugin to collect Docker logs and the loki output plugin to send logs to Loki. Note it is recommended to use a configuration file to define the input and output plugins. The -p flag is used to pass configuration parameters to the plugins.

Configuration file (Alternative to command line arguments)

Create a configuration file fluent-bit.conf with the following content:

[INPUT]
    Name   tail
    Path   /var/lib/docker/containers/*/*.log
    Parser docker
    Tag    docker.*

[OUTPUT]
    Name   loki
    Match  *
    Host   loki
    Port   3100
    Labels agent=fluend-bit,env=docker

Run Fluent Bit with the configuration file:

docker run -v /var/lib/docker/containers:/var/lib/docker/containers -v $(pwd)/fluent-bit.conf:/fluent-bit/etc/fluent-bit.conf fluent/fluent-bit:latest /fluent-bit/bin/fluent-bit -c /fluent-bit/etc/fluent-bit.conf

Collect Docker events

Here is an example to run Fluent Bit in a Docker container, collect docker events, and send them to a local Loki instance.

docker run -v /var/run/docker.sock:/var/run/docker.sock fluent/fluent-bit:latest /fluent-bit/bin/fluent-bit -i docker_events -o loki -p host=loki -p port=3100 -p labels="agent=fluend-bit,env=docker"

In this example, we are using the docker_events input plugin to collect Docker events and the loki output plugin to send logs to Loki. Note it is recommended to use a configuration file to define the input and output plugins. The -p flag is used to pass configuration parameters to the plugins.

Configuration file (Alternative to command line arguments)

Create a configuration file fluent-bit.conf with the following content:

[INPUT]
    Name   docker_events

[OUTPUT]
    Name   loki
    Match  *
    Host   loki
    Port   3100
    Labels agent=fluent-bit,env=docker

Run Fluent Bit with the configuration file:

docker run -v /var/run/docker.sock:/var/run/docker.sock -v $(pwd)/fluent-bit.conf:/fluent-bit/etc/fluent-bit.conf fluent/fluent-bit:latest /fluent-bit/bin/fluent-bit -c /fluent-bit/etc/fluent-bit.conf

Collect Kubernetes logs

The recommended way to collect logs from Kubernetes with Fluent Bit is to use the Helm chart provided by the Fluent Bit project. The Helm chart is available at https://github.com/fluent/helm-charts.

Here is an example of how to deploy the Fluent Bit Helm chart to collect logs from Kubernetes and send them to Loki:

Add the Fluent Bit Helm repository:

helm repo add fluent https://fluent.github.io/helm-charts

Create a values.yaml file with the following content:

config:
    outputs: |
        [OUTPUT]
            Name        loki
            Match       *
            Host        YourHost.Company.net
            port        443
            tls         on
            tls.verify  on
            http_user   XXX
            http_passwd XXX
            Labels agent=fluend-bit

Note we are only updating the `outputs` section of the Fluent Bit configuration. This is to replace the default output plugin with the Loki output plugin. If you need to update other parts of the Fluent Bit configuration refer to the [Fluent Bit values file reference](https://github.com/fluent/helm-charts/blob/main/charts/fluent-bit/values.yaml).

Deploy the Fluent Bit Helm chart:

helm install fluent-bit fluent/fluent-bit -f values.yaml

Next steps

Sending logs to Loki using Fluent Bit tutorial

Fluent Bit on Grafana Labs

Sending logs to Loki using Fluent Bit tutorial

Sending logs to Loki using Fluent Bit tutorial

Dependencies

Scenario

Step 1: Environment setup

Step 2: Configure Fluent Bit to send logs to Loki

Open your code editor and locate the fluent-bit.conf file

Receiving Fluent Bit protocol logs

Export logs to Loki using the official Loki output plugin

logmap.json file

Reload the Fluent Bit configuration

Stuck? Need help?

Step 3: Start the Carnivorous Greenhouse

Summary

Further reading

Complete metrics, logs, traces, and profiling example

Fluent Bit community plugin

Fluent Bit community plugin

Usage

Docker

Docker container logs

Prerequisites

Configuration

Kubernetes

AWS Elastic Container Service (ECS)

Local

Configuration options

Labels

AutoKubernetesLabels

LabelMapPath

Buffering

Configuration examples

Running multiple plugin instances

Fluent Bit Loki output plugin

Fluent Bit Loki output plugin

Configuration

Usage examples

Tail Docker logs

Configuration file (Alternative to command line arguments)

Collect Docker events

Configuration file (Alternative to command line arguments)

Collect Kubernetes logs

Next steps

Open your code editor and locate the `fluent-bit.conf` file

`logmap.json` file