Docker: Instalar e Executar o Grafana Loki

Introdução

Grafana Loki é um sistema de agregação de logs multi-tenant, altamente escalável horizontalmente e altamente disponível, inspirado no Prometheus. Ele foi projetado para ser muito econômico e fácil de operar. Diferentemente de outros sistemas de logging, o Loki não indexa o conteúdo dos logs, mas sim um conjunto de labels (rótulos) para cada fluxo de log (log stream).

Neste laboratório, você realizará uma instalação básica do Grafana Loki usando sua imagem Docker oficial. Você aprenderá a criar um arquivo de configuração mínimo e a iniciar o serviço Loki como um contêiner. Este é o primeiro passo fundamental na construção de uma pilha de logging completa com o Loki.

Puxar a Imagem Docker do Loki

Nesta etapa, você baixará a imagem Docker oficial do Grafana Loki do Docker Hub. O comando docker pull busca uma imagem ou um repositório de um registro (registry). Seu ambiente de laboratório já possui o Docker instalado e configurado.

Execute o seguinte comando no terminal para puxar a imagem Loki mais recente:

docker pull grafana/loki

Você verá uma saída indicando o progresso do download. O Docker puxará a imagem com a tag latest por padrão.

Saída esperada (os números de versão podem variar):

latest: Pulling from grafana/loki
a48641c1b8a9: Pull complete
...
Digest: sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Status: Downloaded newer image for grafana/loki
docker.io/grafana/loki

Criar o Arquivo Básico loki-config.yaml

Nesta etapa, você criará um arquivo de configuração mínimo para o Loki. Este arquivo, loki-config.yaml, instrui o Loki sobre como executar, onde armazenar dados e qual esquema (schema) usar. Para este laboratório, configuraremos o Loki para usar o sistema de arquivos local (local filesystem) para armazenamento.

Usaremos o editor de texto nano para criar o arquivo. Execute o seguinte comando para abrir um novo arquivo chamado loki-config.yaml:

nano loki-config.yaml

Agora, copie e cole o seguinte conteúdo YAML no editor nano:

auth_enabled: false

server:
  http_listen_port: 3100

common:
  path_prefix: /tmp/loki
  storage:
    filesystem:
      chunks_directory: /tmp/loki/chunks
      rules_directory: /tmp/loki/rules
  ring:
    kvstore:
      store: inmemory

schema_config:
  configs:
    - from: 2020-10-24
      store: boltdb-shipper
      object_store: filesystem
      schema: v11
      index:
        prefix: index_
        period: 24h

storage_config:
  boltdb_shipper:
    active_index_directory: /tmp/loki/index
    cache_location: /tmp/loki/cache
  filesystem:
    directory: /tmp/loki/chunks

ruler:
  alertmanager_url: http://localhost:9093

limits_config:
  allow_structured_metadata: false

Esta configuração mantém tudo o que o Loki precisa sob /tmp/loki dentro do contêiner, o que evita problemas de permissão e mantém a configuração fácil de entender. Ela desativa a autenticação, habilita um ring em memória (in-memory ring) para uso em nó único (single-node) e armazena blocos (blocks) e índices no sistema de arquivos local.

Veja o que cada seção do arquivo faz:

auth_enabled: false: Desliga a autenticação para que você possa interagir com o Loki sem credenciais extras. Isso simplifica os testes locais; em produção, você habilitaria a autenticação.
server.http_listen_port: 3100: Diz ao Loki para escutar requisições HTTP na porta 3100. Quando você usa curl localhost:3100, você está acessando esta porta.
common.path_prefix: Define a pasta base onde o Loki armazena dados temporários dentro do contêiner. Todos os outros caminhos neste arquivo são construídos a partir de /tmp/loki, mantendo tudo em um só lugar.
common.storage.filesystem: Aponta o Loki para duas pastas para armazenar chunks de dados de log e arquivos de regras. Como não montamos nada especial no contêiner, usar /tmp/loki evita dores de cabeça com permissões.
common.ring.kvstore.store: inmemory: Mantém as informações de pertencimento (membership) na memória. Para um laboratório de nó único, isso é perfeito; um cluster real usaria um armazenamento compartilhado como Consul ou etcd.
schema_config: Define como o Loki deve organizar o índice para os dados de log. Definimos uma data de início, escolhemos o armazenamento boltdb-shipper e mantemos o índice no sistema de arquivos. O prefix e o period controlam como os arquivos são nomeados e com que frequência um novo arquivo de índice é criado (a cada 24 horas).
storage_config: Fornece as pastas exatas para o índice do boltdb-shipper (active_index_directory e cache_location) e para o armazenamento de chunks brutos. Todos os caminhos novamente residem sob /tmp/loki para manter a organização.
ruler.alertmanager_url: Prepara o componente ruler do Loki para enviar alertas para um Alertmanager em http://localhost:9093. Nada falhará se o Alertmanager não estiver rodando; o Loki simplesmente registrará um aviso ao tentar enviar um alerta.
limits_config.allow_structured_metadata: false: Desabilita um recurso avançado para que o Loki se atenha aos metadados de log de texto simples mais simples que os iniciantes esperam.

Pressione Ctrl+X para sair, depois Y para confirmar o salvamento e, finalmente, Enter para salvar o arquivo com o nome loki-config.yaml.

Executar o Container Loki na Porta 3100 com Configuração

Agora que você tem a imagem do Loki e um arquivo de configuração, você executará o Loki como um contêiner Docker. Você usará o comando docker run para iniciar o contêiner, montar seu arquivo de configuração e expor a porta necessária.

Execute o seguinte comando:

docker run -d --name loki -v $(pwd)/loki-config.yaml:/etc/loki/config.yml -p 3100:3100 grafana/loki -config.file=/etc/loki/config.yml

Vamos analisar este comando:

-d: Executa o contêiner em modo detached (em segundo plano).
--name loki: Atribui o nome loki ao contêiner para fácil referência.
-v $(pwd)/loki-config.yaml:/etc/loki/config.yml: Monta seu arquivo local loki-config.yaml dentro do contêiner em /etc/loki/config.yml. O Loki lerá sua configuração a partir deste arquivo.
-p 3100:3100: Mapeia a porta 3100 da máquina hospedeira (host machine) para a porta 3100 dentro do contêiner, permitindo que você acesse a API do Loki.
grafana/loki: A imagem a ser usada para o contêiner.
-config.file=/etc/loki/config.yml: Um argumento de linha de comando passado para o processo Loki, informando onde encontrar o arquivo de configuração.

Após executar o comando, o Docker imprimirá o ID exclusivo do contêiner recém-criado.

e8a9f2b1c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0

Verificar o Endpoint de Prontidão do Loki em localhost:3100/ready

Nesta etapa, você realizará uma verificação de saúde (health check) para confirmar que o servidor Loki está ativo e funcionando corretamente. O Loki expõe um endpoint HTTP /ready que pode ser usado para este propósito. Uma resposta bem-sucedida indica que o servidor está pronto para receber requisições.

Use o comando curl para enviar uma requisição a este endpoint. Como mapeamos a porta 3100 na etapa anterior, você pode acessá-lo via localhost:3100.

curl http://localhost:3100/ready

Se o Loki tiver iniciado com sucesso, ele responderá com o texto ready e um código de status HTTP 200 OK.

Saída esperada:

ready

Verificar os Logs do Loki para Confirmação de Inicialização

Outra maneira de verificar se o Loki iniciou com sucesso é inspecionando os logs do seu contêiner. Isso é útil para depurar problemas de configuração ou outros problemas de inicialização. O comando docker logs recupera os logs de um contêiner.

Use o seguinte comando para visualizar os logs do seu contêiner loki:

docker logs loki

Você deverá ver uma saída detalhando o processo de inicialização. Procure por uma linha confirmando que o servidor está escutando por conexões. Isso confirma que o serviço foi inicializado sem erros críticos.

Trecho de saída esperado (detalhes do log podem variar):

level=info ts=... caller=server.go:299 http=[::]:3100 grpc=[::]:9096 msg="server listening on addresses"
level=info ts=... caller=loki.go:372 msg="Loki started"

Resumo

Parabéns! Você concluiu com sucesso este laboratório (lab).

Neste laboratório, você aprendeu os passos fundamentais para colocar uma instância do Grafana Loki em funcionamento. Você:

Puxou (pulled) a imagem oficial do Loki do Docker Hub.
Criou um arquivo básico loki-config.yaml para definir as configurações do servidor e de armazenamento (storage).
Iniciou o Loki em um contêiner Docker, montando a configuração e expondo a porta da API.
Verificou se a instância do Loki está rodando e saudável usando seu endpoint /ready e checando os logs do contêiner.

Esta configuração básica é a fundação para construir uma arquitetura de logs mais complexa e robusta. A partir daqui, você pode prosseguir para configurar um agente de envio de logs como o Promtail para enviar logs ao Loki e usar o Grafana para consultá-los e visualizá-los.

Instalação do Loki