ECS Firelens Integration with Grafana Loki

This document outlines a sample AWS Elastic Container Service (ECS) task definition that utilizes Firelens to route Nginx logs to a Grafana Loki instance. Firelens acts as a log router, enabling flexible log collection and forwarding from your containers.

Nginx Container Configuration

The primary Nginx container is configured to serve web traffic and essential for demonstrating log forwarding. Its logs are captured by the Firelens log driver.

Log Router Setup with Fluent Bit

The log_router container uses the grafana/fluent-bit-plugin-loki:latest image. This container is essential for processing and forwarding logs. The firelensConfiguration specifies its type as fluentbit and enables ECS log metadata, which enriches log entries with valuable context like container name and task definition.

Firelens Log Driver Options for Loki

The logConfiguration for the Nginx container is set to awsfirelens. Key options are configured to direct logs to Loki:

• RemoveKeys: Specifies keys to remove from log metadata for cleaner logs.
• LineFormat: Sets the log line format to key_value for structured logging.
• Labels: Defines static labels to be added to all logs, such as job, service, and environment.
• LabelKeys: Specifies dynamic labels to be extracted from ECS task metadata, including container_name, ecs_task_definition, source, and ecs_cluster.
• Url: The endpoint for pushing logs to your Loki instance. Replace x:x with your Loki authentication credentials and loki.mydomain.com with your Loki domain.
• Name: Identifies the log driver as grafana-loki.

ECS Task Definition Requirements

This task definition is configured for EC2 launch type, indicated by requiresCompatibilities: ["EC2"]. Ensure your ECS service is set up to use the EC2 launch type.

External Resources

• AWS FireLens Documentation
• Grafana Loki FireLens Client
• Grafana Loki Configuration Guide
• Fluent Bit for Loki

{
  "family": "nginx-loki-logs",
  "executionRoleArn": "arn:aws:iam::xxxxxxxxxxxx:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::xxxxxxxxxxxx:role/ecs-task-role",
  "containerDefinitions": [
    {
      "name": "nginx",
      "image": "nginx:latest",
      "portMappings": [
        {
          "hostPort": 0,
          "protocol": "tcp",
          "containerPort": 80
        }
      ],
      "memoryReservation": 256,
      "stopTimeout": 30,
      "startTimeout": 60,
      "essential": true,
      "logConfiguration": {
        "logDriver": "awsfirelens",
        "options": {
          "RemoveKeys": "container_id,ecs_task_arn",
          "LineFormat": "key_value",
          "Labels": "{job=\"prod/dockerlogs\", service=\"nginx-web\", environment=\"prod\"}",
          "LabelKeys": "container_name,ecs_task_definition,source,ecs_cluster",
          "Url": "https://x:x@loki.mydomain.com/loki/api/v1/push",
          "Name": "grafana-loki"
        }
      }
    },
    {
      "name": "log_router",
      "memoryReservation": 50,
      "image": "grafana/fluent-bit-plugin-loki:latest",
      "firelensConfiguration": {
        "type": "fluentbit",
        "options": {
          "enable-ecs-log-metadata": "true"
        }
      },
      "essential": true
    }
  ],
  "requiresCompatibilities": [
    "EC2"
  ]
}