Pular para conteúdo

Monitoramento com Loki e Grafana

Este documento descreve como utilizar Loki e Grafana para visualizar e analisar logs do AT Learning Gap Engine.

Acesso ao Grafana

O Grafana está disponível na seguinte URL:

https://grafana.arcotech.cloud/

Introdução

O que é Loki?

Loki é um sistema de agregação de logs inspirado no Prometheus, projetado para ser muito eficiente em termos de custo e operação. Ao contrário de outros sistemas de logs, o Loki não indexa o conteúdo dos logs, mas apenas um conjunto de rótulos para cada fluxo de log, o que o torna mais leve e econômico.

O que é Grafana?

Grafana é uma plataforma de análise e visualização de métricas que permite consultar, visualizar, alertar e explorar suas métricas, logs e traces independentemente de onde estão armazenados. É a interface ideal para visualizar os dados coletados pelo Loki.

Por que usar Loki + Grafana?

  • Eficiência: Loki é projetado para ser eficiente em termos de recursos
  • Integração: Funciona perfeitamente com Grafana
  • Consultas poderosas: Suporta LogQL, uma linguagem de consulta inspirada no PromQL
  • Escalabilidade: Pode escalar horizontalmente para lidar com grandes volumes de logs
  • Formato JSON: Ideal para logs estruturados como os gerados pelo AT Learning Gap Engine

Integração com o AT Learning Gap Engine

O AT Learning Gap Engine está configurado para gerar logs em formato JSON estruturado usando o StructuredLogFormatter. Este formatador garante que todos os logs incluam informações importantes como:

  • Timestamp
  • Nível de log
  • Nome do logger
  • ID de correlação
  • Mensagem
  • Módulo e função
  • Linha do código
  • Contexto adicional
  • Informações de exceção (quando aplicável)

Fluxo de Processamento de Logs

  1. Os serviços geram logs usando o logger estruturado
  2. O StructuredLogFormatter converte os logs para JSON
  3. O Loki coleta e armazena os logs
  4. O Grafana permite visualizar e consultar os logs

Consultas LogQL para Análise de Logs

LogQL é a linguagem de consulta do Loki, inspirada no PromQL do Prometheus. Aqui estão algumas consultas úteis para analisar os logs do AT Learning Gap Engine.

IMPORTANTE: Todas as consultas devem começar com o filtro {io_arcotech_app="at-learning-gap-engine"} para selecionar os logs da aplicação.

Consultas Básicas

  1. Filtrar por serviço: 

    {io_arcotech_app="at-learning-gap-engine", service="PedagogicalItemHierarchyService"}

  2. Filtrar por tipo de log: 

    {io_arcotech_app="at-learning-gap-engine", log_type="request"}

  3. Filtrar por nível de log: 

    {io_arcotech_app="at-learning-gap-engine", log_level="ERROR"}

  4. Filtrar por ID de contexto: 

    {io_arcotech_app="at-learning-gap-engine", context_id="contexto-teste-123"}

  5. Filtrar por ID de correlação: 

    {io_arcotech_app="at-learning-gap-engine", correlation_id="550e8400-e29b-41d4-a716-446655440000"}

Consultas Avançadas

  1. Encontrar erros em um serviço específico: 

    {io_arcotech_app="at-learning-gap-engine", service="PedagogicalItemHierarchyService", log_level="ERROR"}

  2. Rastrear uma requisição completa usando ID de correlação: 

    {io_arcotech_app="at-learning-gap-engine", correlation_id="550e8400-e29b-41d4-a716-446655440000"} | json

Exemplos Práticos

Exemplo 1: Rastreamento de uma Requisição Completa

Para rastrear uma requisição completa, siga estes passos:

  1. Encontre o ID de correlação nos logs: 

    {io_arcotech_app="at-learning-gap-engine"} | json | line_format "{{.correlation_id}} - {{.context_id}}" | grep "contexto-teste-123"

  2. Use o ID de correlação para visualizar todo o fluxo: 

    {io_arcotech_app="at-learning-gap-engine", correlation_id="550e8400-e29b-41d4-a716-446655440000"} | json | line_format "{{.timestamp}} - {{.service}} - {{.operation}} - {{.log_type}}"

  3. Analise o tempo de execução: 

    {io_arcotech_app="at-learning-gap-engine", correlation_id="550e8400-e29b-41d4-a716-446655440000", log_type="performance_metrics"} | json | unwrap execution_time_ms

Exemplo 2: Análise de Erros

Para analisar erros no sistema:

  1. Visualize todos os erros recentes: 

    {io_arcotech_app="at-learning-gap-engine", log_level="ERROR"} | json

  2. Agrupe erros por serviço: 

    {io_arcotech_app="at-learning-gap-engine", log_level="ERROR"} | json | line_format "{{.service}} - {{.operation}} - {{.error.message}}"

  3. Identifique os erros mais frequentes: 

    {io_arcotech_app="at-learning-gap-engine", log_level="ERROR"} | json | line_format "{{.error.type}}" | count_over_time[1h] | sort

Exemplo 3: Consultas com Formato JSON

Com o novo formato JSON, você pode usar o operador | json para extrair campos específicos:

  1. Extrair todos os campos: 

    {io_arcotech_app="at-learning-gap-engine"} | json

  2. Filtrar por campos específicos: 

    {io_arcotech_app="at-learning-gap-engine"} | json | service="PedagogicalItemHierarchyService" | operation="generate_hierarchy"

  3. Visualizar campos específicos: 

    {io_arcotech_app="at-learning-gap-engine"} | json | line_format "{{.timestamp}} - {{.service}} - {{.operation}} - {{.log_level}}"

Exemplo 4: Análise de Performance

Para analisar a performance do sistema:

  1. Visualize os tempos de execução médios por operação: 

    {io_arcotech_app="at-learning-gap-engine", log_type="performance_metrics"} | json | unwrap execution_time_ms | avg by(operation)

  2. Identifique operações com picos de tempo de execução: 

    {io_arcotech_app="at-learning-gap-engine", log_type="performance_metrics"} | json | unwrap execution_time_ms | max by(operation)

  3. Compare a performance entre diferentes serviços: 

    {io_arcotech_app="at-learning-gap-engine", log_type="performance_metrics"} | json | unwrap execution_time_ms | avg by(service)

Melhores Práticas

Otimização de Consultas

  1. Use rótulos para filtrar: Sempre filtre primeiro por rótulos antes de aplicar filtros de conteúdo
  2. Limite o intervalo de tempo: Use intervalos de tempo menores para consultas mais rápidas
  3. Evite expressões regulares complexas: Elas podem ser lentas em grandes volumes de dados
  4. Sempre inclua o filtro da aplicação: Todas as consultas devem começar com {io_arcotech_app="at-learning-gap-engine"}

Visualização Eficiente de Logs no Grafana

Para visualizar logs no formato JSON de forma eficiente no Grafana, siga estas recomendações:

Uso do Operador | json

O operador | json do LogQL é essencial para trabalhar com logs no formato JSON. Ele permite extrair e visualizar campos específicos:

{io_arcotech_app="at-learning-gap-engine"} | json

Este operador analisa automaticamente os pares chave-valor e permite filtrar por campos específicos:

{io_arcotech_app="at-learning-gap-engine"} | json | service="PedagogicalItemHierarchyService" | operation="generate_hierarchy"

Visualização de Campos Específicos

Para visualizar apenas campos específicos dos logs:

{io_arcotech_app="at-learning-gap-engine"} | json | line_format "{{.timestamp}} - {{.service}} - {{.operation}} - {{.log_level}}"

Formatação de Tabelas

Para visualizar logs em formato de tabela, use a visualização "Table" no Grafana e configure as colunas para exibir os campos desejados:

  1. Selecione a visualização "Table"
  2. Em "Transform", escolha "Labels to fields"
  3. Configure as colunas para mostrar os campos relevantes

Dicas para Trabalhar com Formato JSON

  1. Use o operador | json para extrair campos
  2. Para campos aninhados, use a notação de ponto: target.id, prioritization.criteria
  3. Para filtrar por valores numéricos, use operadores de comparação: execution_time_ms > 1000
  4. Para buscar texto em campos específicos, use o operador |~: context_id |~ "123"

Conclusão

A combinação de Loki e Grafana oferece uma solução poderosa e eficiente para visualizar e analisar logs do AT Learning Gap Engine. Com as consultas LogQL adequadas e as técnicas de visualização descritas acima, é possível obter insights valiosos sobre o comportamento do sistema, identificar problemas rapidamente e monitorar a performance em tempo real.

Para acessar o Grafana, visite https://grafana.arcotech.cloud/ e utilize as consultas fornecidas neste documento, sempre começando com o filtro {io_arcotech_app="at-learning-gap-engine"}.