Configuração de logs do Amazon ECS para obtenção de alto throughput

Para cenários com alto throughput de logs, recomendamos o uso do driver de log awsfirelens com o FireLens e o Fluent Bit. O Fluent Bit é um processador de log leve que é eficiente com recursos e capaz de lidar com milhões de registros de log. Porém, atingir o desempenho ideal em grande escala requer ajustar sua configuração.

Esta seção aborda técnicas avançadas de otimização de Fluent Bit para lidar com a alto throughput de logs e, ao mesmo tempo, manter a estabilidade do sistema e garantir que não haja perda de dados.

Para obter informações sobre como usar arquivos de configuração personalizados com o FireLens, consulte Uso de um arquivo de configuração personalizado. Para receber exemplos adicionais, consulte Exemplos do FireLens do Amazon ECS no GitHub.

Noções básicas sobre blocos

O Fluent Bit processa dados em unidades chamadas blocos. Quando um plug-in INPUT recebe dados, o mecanismo cria um bloco que é armazenado na memória ou no sistema de arquivos antes de ser enviado aos destinos OUTPUT.

O comportamento do buffer depende da configuração storage.type nas seções INPUT. Por padrão, o Fluent Bit usa buffer de memória. Em cenários de throughput alto ou de produção, o buffer do sistema de arquivos oferece maior resiliência.

Para obter mais informações, consulte Blocos na documentação do Fluent Bit e O que é um bloco? no AWS para um repositório de exemplos do Fluent Bit.

Buffer de memória (padrão)

Por padrão, o Fluent Bit usa buffer de memória (storage.type memory). Você pode limitar o uso de memória por plug-in INPUT usando o parâmetro Mem_Buf_Limit.

O exemplo a seguir mostra uma configuração de entrada com buffer de memória:

[INPUT]
    Name          tcp
    Tag           ApplicationLogs
    Port          5170
    storage.type  memory
    Mem_Buf_Limit 5MB

[input] tcp.1 paused (mem buf overlimit)

O armazenamento em buffer de memória é adequado para casos de uso simples com throughput de logs baixo a moderado. Em cenários de throughput alto ou de produção, nos quais a perda de dados é uma preocupação, use o buffer do sistema de arquivos.

Para obter mais informações, consulte Buffer e memória na documentação do Fluent Bit e Apenas buffer de memória no AWS para o repositório de exemplos do Fluent Bit.

Buffer do sistema de arquivos

Para cenários de alto throughput, recomendamos o uso do processo de buffer do sistema de arquivos. Para obter mais informações sobre como o Fluent Bit gerencia o processo de buffer e o armazenamento, consulte Processo de buffer e armazenamento na documentação do Fluent Bit.

O processo de buffer do sistema de arquivos oferece as seguintes vantagens:

Para habilitar o buffer do sistema de arquivos, forneça um arquivo de configuração personalizado do Fluent Bit. O exemplo a seguir mostra a configuração recomendada:

[SERVICE]
    # Flush logs every 1 second
    Flush 1
    # Wait 120 seconds during shutdown to flush remaining logs
    Grace 120
    # Directory for filesystem buffering
    storage.path             /var/log/flb-storage/
    # Limit chunks stored 'up' in memory (reduce for memory-constrained environments)
    storage.max_chunks_up    32
    # Flush backlog chunks to destinations during shutdown (prevents log loss)
    storage.backlog.flush_on_shutdown On

[INPUT]
    Name forward
    unix_path /var/run/fluent.sock
    # Run input in separate thread to prevent blocking
    threaded true
    # Enable filesystem buffering for persistence
    storage.type filesystem

[OUTPUT]
    Name cloudwatch_logs
    Match *
    region us-west-2
    log_group_name /aws/ecs/my-app
    log_stream_name $(ecs_task_id)
    # Use multiple workers for parallel processing
    workers 2
    # Retry failed flushes up to 15 times
    retry_limit 15
    # Maximum disk space for buffered data for this output
    storage.total_limit_size 10G

Principais parâmetros de configuração:

Para mais informações, consulte Buffer do sistema de arquivos na documentação do Fluent Bit e Sistema de arquivos e buffer de memória no AWS para o repositório de exemplos do Fluent Bit.

Noções básicas sobre o storage.total_limit_size

O parâmetro storage.total_limit_size em cada plug-in OUTPUT controla o espaço máximo em disco para dados armazenados em buffer para essa saída. Quando esse limite é atingido, os registros mais antigos dessa saída são descartados para liberar espaço para novos dados. Quando o espaço em disco se esgota completamente, o Fluent Bit não consegue ser colocado na fila e acaba se perdendo.

Use a seguinte fórmula para calcular o storage.total_limit_size adequado com base na sua taxa de log e no intervalo de recuperação desejado:

If log rate is in KB/s, convert to MB/s first:
log_rate (MB/s) = log_rate (KB/s) / 1000

storage.total_limit_size (GB) = log_rate (MB/s) × duration (hours) × 3600 (seconds/hour) / 1000 (MB to GB)

A tabela a seguir apresenta exemplos de cálculos para taxas logarítmicas comuns e janelas de recuperação:

Para observar o pico de throughput e escolher tamanhos de buffer adequados, use a amostra measure-throughput FireLens.

Use a fórmula, os exemplos de cálculos e a análise comparativa para escolher um storage.total_limit_size adequado que ofereça margem suficiente para uma recuperação com o máximo esforço possível durante uma interrupção.

Requisitos de armazenamento de tarefas do Amazon ECS

Some todos os valores de storage.total_limit_size das seções OUTPUT e acrescente uma margem para cobrir as despesas gerais. Esse total determina o espaço de armazenamento necessário na definição da tarefa do Amazon ECS. Por exemplo, 3 saídas × 10 GB cada = 30 GB + buffer (5–10 GB) = 35–40 GB são necessários. Se o total exceder o espaço de armazenamento disponível, o Fluent Bit pode não conseguir colocar os registros na fila, e eles serão perdidos.

Estão disponíveis as seguintes opções de armazenamento:

Para obter mais informações sobre volumes de dados, consulte Opções de armazenamento para tarefas do Amazon ECS.

Otimizar a configuração de saída

Problemas de rede, interrupções no serviço e controle de utilização de destino podem impedir a entrega dos logs. A configuração adequada da saída garante resiliência sem perda de dados.

Quando uma descarga de saída falha, o Fluent Bit pode repetir a operação. Os seguintes parâmetros controlam o comportamento de novas tentativas:

O tempo de espera entre tentativas utiliza um recuo exponencial com variação:

wait_time = random(base, min(base × 2^retry_number, cap))

Por exemplo, com scheduler.base 10 e scheduler.cap 60:

Para obter mais informações, consulte Configurar o tempo de espera para nova tentativa e Redes na documentação do Fluent Bit.

O parâmetro Grace na seção [SERVICE] define o tempo de espera do Fluent Bit durante o desligamento para limpar os dados em buffer. O período de Grace deve ser coordenado com o stopTimeout do contêiner. Certifique-se de que stopTimeout exceda o período de Grace para permitir que o Fluent Bit faça a descarga completa antes de receber SIGKILL. Por exemplo, se Grace for 120 segundos, defina stopTimeout como 150 segundos.

O exemplo a seguir mostra uma configuração completa de Fluent Bit com todas as definições recomendadas para cenários de alto throughput:

[SERVICE]
    # Flush logs every 1 second
    Flush 1
    # Wait 120 seconds during shutdown to flush remaining logs
    Grace 120
    # Directory for filesystem buffering
    storage.path             /var/log/flb-storage/
    # Limit chunks stored 'up' in memory (reduce for memory-constrained environments)
    storage.max_chunks_up    32
    # Flush backlog chunks to destinations during shutdown (prevents log loss)
    storage.backlog.flush_on_shutdown On
    # Minimum seconds between retries
    scheduler.base           10
    # Maximum seconds between retries (exponential backoff cap)
    scheduler.cap            60

[INPUT]
    Name forward
    unix_path /var/run/fluent.sock
    # Run input in separate thread to prevent blocking
    threaded true
    # Enable filesystem buffering for persistence
    storage.type filesystem

[OUTPUT]
    Name cloudwatch_logs
    Match *
    region us-west-2
    log_group_name /aws/ecs/my-app
    log_stream_name $(ecs_task_id)
    # Use multiple workers for parallel processing
    workers 2
    # Retry failed flushes up to 15 times
    retry_limit 15
    # Maximum disk space for buffered data for this output
    storage.total_limit_size 10G

Compreender os cenários de perda de dados

Os registros podem ser perdidos durante interrupções prolongadas ou problemas com os destinos de saída. As recomendações de configuração contidas neste guia são medidas que visam minimizar a perda de dados, mas não podem garantir que não haverá nenhuma perda durante falhas prolongadas. Compreender esses cenários ajuda a configurar o Fluent Bit para maximizar a resiliência.

Os registros podem ser perdidos de duas maneiras: os registros mais antigos são excluídos quando o espaço de armazenamento fica cheio, ou os registros mais recentes são rejeitados quando o sistema não consegue aceitar mais dados.

Os registros mais antigos foram excluídos

Os registros mais antigos armazenados no buffer são descartados quando as tentativas de repetição se esgotam ou quando o storage.total_limit_size fica cheio e precisa liberar espaço para novos dados.

Registros mais recentes rejeitados

Os registros mais recentes são descartados quando o espaço em disco se esgota ou quando a entrada é pausada devido a Mem_Buf_Limit.

Práticas recomendadas para minimizar a perda de dados

Considere as seguintes práticas recomendadas para minimizar a perda de dados:

Usar o registro em log em vários destinos para confiabilidade

O envio de logs para vários destinos elimina pontos únicos de falha. Por exemplo, se o Amazon CloudWatch Logs sofrer uma interrupção, os logs ainda chegarão ao Amazon S3.

O registro em log em vários destinos oferece os seguintes benefícios. O plug-in de saída do Amazon S3 também oferece suporte a opções de compactação, como gzip e formato Parquet, que podem reduzir os custos de armazenamento. Para mais informações, consulte Compactação do S3 na documentação do Fluent Bit.

O registro em log em vários destinos pode oferecer os seguintes benefícios:

A configuração do Fluent Bit a seguir envia logs ao Amazon CloudWatch Logs e ao Amazon S3:

[OUTPUT]
    Name cloudwatch_logs
    Match *
    region us-west-2
    log_group_name /aws/ecs/my-app
    log_stream_name $(ecs_task_id)
    workers 2
    retry_limit 15

[OUTPUT]
    Name s3
    Match *
    bucket my-logs-bucket
    region us-west-2
    total_file_size 100M
    s3_key_format /fluent-bit-logs/$(ecs_task_id)/%Y%m%d/%H/%M/$UUID
    upload_timeout 10m
    # Maximum disk space for buffered data for this output
    storage.total_limit_size 5G

Como ambas as saídas usam o mesmo padrão Match *, todos os registros são enviados aos dois destinos de maneira independente. Durante uma interrupção em um destino, os logs continuam fluindo para o outro, enquanto as descargas com falha se acumulam no buffer do sistema de arquivos para uma nova tentativa posterior.

Usar o log com base em arquivo com o plug-in de entrada tail

Para cenários de alto throughput em que a perda de logs é uma preocupação crítica, é possível usar uma abordagem alternativa: fazer com que sua aplicação grave os logs em arquivos no disco e configurar o Fluent Bit para lê-los usando o plug-in de entrada tail. Essa abordagem ignora completamente a camada do driver de log do Docker.

O registro em log baseado em arquivo com o plug-in tail oferece os seguintes benefícios:

Para usar essa abordagem, sua aplicação deve gravar logs em arquivos em vez de stdout. Tanto o contêiner da aplicação quanto o contêiner do Fluent Bit montam um volume compartilhado onde os arquivos de log são armazenados.

O exemplo a seguir mostra uma configuração de entrada de cauda com práticas recomendadas:

[INPUT]
    Name tail
    # File path or glob pattern to tail
    Path /var/log/app.log
    # Database file for storing file offsets (enables resuming after restart)
    DB /var/log/flb_tail.db
    # when true, controls that only fluent-bit will access the database (improves performance)
    DB.locking true
    # Skip long lines instead of skipping the entire file
    Skip_Long_Lines On
    # How often (in seconds) to check for new files matching the glob pattern
    Refresh_Interval 10
    # Extra seconds to monitor a file after rotation to account for pending flush
    Rotate_Wait 30
    # Maximum size of the buffer for a single line
    Buffer_Max_Size 10MB
    # Initial allocation size for reading file data
    Buffer_Chunk_Size 1MB
    # Maximum memory buffer size (tail pauses when full)
    Mem_Buf_Limit 75MB

Ao usar o plug-in de entrada tail, considere o seguinte:

Para mais informações, consulte Tail na documentação do Fluent Bit. Para conhecer as práticas recomendadas, consulte Configuração do Tail com práticas recomendadas, no guia de solução de problemas da AWS para Fluent Bit.

Registrar em log diretamente no FireLens

Quando o driver de log awsfirelens for especificado em uma definição de tarefa, o agente do Amazon ECS injetará as seguintes variáveis de ambiente no contêiner:

Você pode usar essas variáveis de ambiente para registrar diretamente no roteador de log do Fluent Bit a partir do código da sua aplicação usando o protocolo Fluent Forward, em vez de gravar no stdout. Essa abordagem ignora a camada do driver de log do Docker, o que oferece os seguintes benefícios:

As seguintes bibliotecas de agente de log Fluent são compatíveis com o protocolo Fluent Forward e podem ser usadas para enviar logs diretamente para o Fluent Bit:

Configurar o limite de buffer do Docker

Ao criar uma definição de tarefa, você pode especificar o número de linhas de log que são armazenadas em buffer na memória especificando o valor em log-driver-buffer-limit. Isso controla o buffer entre o Docker e o Fluent Bit. Para obter mais informações, consulte Driver de registro do Fluentd na documentação do Docker.

Use essa opção quando houver throughput alto, porque o Docker pode ficar sem memória buffer e descartar mensagens de buffer para que ele possa adicionar novas mensagens.

Considere o seguinte ao usar essa opção:

A seguinte definição de tarefa mostra como configurar log-driver-buffer-limit:

{
    "containerDefinitions": [
        {
            "name": "my_service_log_router",
            "image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:3",
            "cpu": 0,
            "memoryReservation": 51,
            "essential": true,
            "firelensConfiguration": {
                "type": "fluentbit"
            }
        },
        {
            "essential": true,
            "image": "public.ecr.aws/docker/library/httpd:latest",
            "name": "app",
            "logConfiguration": {
                "logDriver": "awsfirelens",
                "options": {
                    "Name": "firehose",
                    "region": "us-west-2",
                    "delivery_stream": "my-stream",
                    "log-driver-buffer-limit": "52428800"
                }
            },
            "dependsOn": [
                {
                    "containerName": "my_service_log_router",
                    "condition": "START"
                }
            ],
            "memoryReservation": 100
        }
    ]
}