Logs

Um log é um registro de texto com marcação de data e hora, que pode ser tanto estruturado (recomendado) quanto não estruturado, e com metadados opcionais. Dentre os sinais de telemetria, os logs têm uma história mais consolidada. A maioria das linguagens de programação possuem recursos nativos ou bibliotecas bem conhecidas e amplamente utilizadas para gerar logs.

Logs do OpenTelemetry

O OpenTelemetry não possui uma especificação de API ou SDK própria para gerar logs. Em vez disso, os logs no OpenTelemetry são os logs que você já possui, que foram gerados por um framework de logging ou componente de infraestrutura. Os SDKs e a autoinstrumentação do OpenTelemetry utilizam vários componentes para correlacionar automaticamente logs com rastros.

O suporte do OpenTelemetry para logs é projetado para ser totalmente compatível com o que você já possui, oferecendo a capacidade de adicionar contextos a esses logs e uma série de ferramentas para analisar e manipular logs em um formato comum, abrangendo diversas fontes.

Logs do OpenTelemetry no OpenTelemetry Collector

O OpenTelemetry Collector fornece várias ferramentas para trabalhar com logs:

• Vários receivers que analisam logs de fontes específicas e conhecidas de dados de logs.
• O filelogreceiver, que lê logs de qualquer arquivo e fornece recursos para analisá-los a partir de diferentes formatos ou usar uma expressão regular.
• Processors como o transformprocessor, permite analisar dados aninhados, simplificar estruturas complexas, adicionar/remover/atualizar valores e mais.
• Exporters permitem emitir dados de log em um formato não OpenTelemetry.

O primeiro passo na adoção do OpenTelemetry frequentemente envolve implantar um Collector como um agente de logging genérico.

Logs do OpenTelemetry para aplicações

Em aplicações, logs do OpenTelemetry são criados com qualquer biblioteca ou recursos nativos para geração de logs. Quando você adiciona autoinstrumentação ou ativa um SDK, o OpenTelemetry automaticamente correlaciona seus logs com os rastros e trechos, incluindo os seus IDs no corpo do log. Em outras palavras, o OpenTelemetry automaticamente correlaciona seus logs com os seus rastros.

Linguagens suportadas

Log é um sinal estável na especificação do OpenTelemetry. Para as implementações específicas da API e SDK de Logs em cada linguagem, temos o seguinte estado:

Logs estruturados, não estruturados e semiestruturados

Tecnicamente o OpenTelemetry não distingue entre logs estruturados e não estruturados. Você pode usar qualquer log que tiver com o OpenTelemetry. No entanto, nem todos os formatos de log são igualmente úteis! Logs estruturados, em particular, são recomendados para observabilidade em produção porque são fáceis de analisar e interpretar em escala. A seção a seguir explica as diferenças entre logs estruturados, não estruturados e semiestruturados.

Logs estruturados

Um log estruturado é aquele que segue um formato consistente e legível por máquina. Para aplicações, um dos formatos mais comuns é o JSON:

{
  "timestamp": "2024-08-04T12:34:56.789Z",
  "level": "INFO",
  "service": "user-authentication",
  "environment": "production",
  "message": "User login successful",
  "context": {
    "userId": "12345",
    "username": "johndoe",
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36"
  },
  "transactionId": "abcd-efgh-ijkl-mnop",
  "duration": 200,
  "request": {
    "method": "POST",
    "url": "/api/v1/login",
    "headers": {
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
    "body": {
      "username": "johndoe",
      "password": "******"
    }
  },
  "response": {
    "statusCode": 200,
    "body": {
      "success": true,
      "token": "jwt-token-here"
    }
  }
}

e para componentes de infraestrutura, o Common Log Format (CLF) é frequentemente usado:

127.0.0.1 - johndoe [04/Aug/2024:12:34:56 -0400] "POST /api/v1/login HTTP/1.1" 200 1234

Também é comum ter logs estruturados com uma mistura de formatos. Por exemplo, um log no formato Extended Log Format (ELF) pode combinar JSON com os dados separados por espaços em um log CLF.

192.168.1.1 - johndoe [04/Aug/2024:12:34:56 -0400] "POST /api/v1/login HTTP/1.1" 200 1234 "http://example.com" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36" {"transactionId": "abcd-efgh-ijkl-mnop", "responseTime": 150, "requestBody": {"username": "johndoe"}, "responseHeaders": {"Content-Type": "application/json"}}

Para aproveitar ao máximo este log, transforme tantos os dados formatados em JSON quanto os formatados em ELF em um mesmo formato comum para facilitar a análise em um backend de observabilidade. O filelogreceiver do OpenTelemetry Collector contém maneiras padronizadas de analisar logs como estes.

Logs estruturados são a melhor forma de usar logs. Por serem emitidos em um formato consistente, eles são simples de extrair informações, o que facilita o pré-processamento no OpenTelemetry Collector, a correlação com outros dados e, por fim, a análise em um backend de Observabilidade.

Logs não estruturados

Logs não estruturados são logs que não seguem uma estrutura consistente. Eles podem ser mais legíveis para humanos e são frequentemente usados em desenvolvimento. No entanto, não é aconselhável usar logs não estruturados para fins de observabilidade em produção, pois são muito mais difíceis de analisar e interpretar em escala.

Exemplos de logs não estruturados:

[ERROR] 2024-08-04 12:45:23 - Failed to connect to database. Exception: java.sql.SQLException: Timeout expired. Attempted reconnect 3 times. Server: db.example.com, Port: 5432

System reboot initiated at 2024-08-04 03:00:00 by user: admin. Reason: Scheduled maintenance. Services stopped: web-server, database, cache. Estimated downtime: 15 minutes.

DEBUG - 2024-08-04 09:30:15 - User johndoe performed action: file_upload. Filename: report_Q3_2024.pdf, Size: 2.3 MB, Duration: 5.2 seconds. Result: Success

É possível armazenar e analisar logs não estruturados em produção, embora seja necessário realizar um trabalho significativo para analisá-los ou processa-los antes de serem legíveis por máquinas. Por exemplo, os três logs acima exigirão uma expressão regular para analisar a marcação de data e hora e personalizar analisadores para extrair os campos da mensagem de log de forma consistente. Isso geralmente é necessário para que um backend de log saiba como classificar e organizar os logs por data e hora. Embora seja possível processar logs não estruturados para análise, fazer isso pode dar mais trabalho do que mudar para logs estruturados, através de um framework de log padrão em suas aplicações.

Logs Semiestruturados

Um log semiestruturado é um log que utiliza um padrão interno consistente para distinguir dados de forma que sejam legíveis por máquinas, mas que pode não usar o mesmo formato e delimitadores entre os dados em diferentes sistemas.

Exemplo de um log semiestruturado:

2024-08-04T12:45:23Z level=ERROR service=user-authentication userId=12345 action=login message="Failed login attempt" error="Invalid password" ipAddress=192.168.1.1 userAgent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36"

Embora sejam legíveis por máquinas, logs semiestruturados podem precisar de diferentes tipos de analisadores para interpretação em grande escala.

Componentes de logs do OpenTelemetry

A seguir estão listados os conceitos e componentes que sustentam o suporte de log do OpenTelemetry.

Conector / Ponte de Log

Como desenvolvedor de aplicações, você não deve chamar diretamente a API de Logs Bridge, pois ela é destinada a pessoas desenvolvendo bibliotecas de geração de logs que querem construir conectores ou pontes de log. Em vez disso, você deve usar sua biblioteca de log preferida e configurá-la para utilizar um conector de log (ou ponte de log) capaz de emitir logs para um OpenTelemetry LogRecordExporter.

Os SDKs do OpenTelemetry oferecem essa funcionalidade.

Logger Provider

Parte da API de Logs Bridge e deve ser usada apenas se você estiver desenvolvendo uma biblioteca de log.

Um Logger Provider (às vezes chamado de LoggerProvider) é uma fábrica de Loggers. Na maioria dos casos, o Logger Provider é inicializado uma vez, e seu ciclo de vida coincide com o ciclo de vida da aplicação. A inicialização do Logger Provider também inclui a inicialização do Resource e Exporter.

Logger

Parte da API de Logs Bridge e deve ser usada apenas se você estiver desenvolvendo uma biblioteca de log.

Um Logger cria registros de log. Loggers são criados a partir do Log Providers.

Log Record Exporter

Os Log Record Exporters enviam registros de log para um consumidor. Esse consumidor pode ser a saída padrão de um terminal para depuração durante o desenvolvimento, o OpenTelemetry Collector, ou qualquer backend de código aberto ou de fornecedor de sua escolha.

Log Record

Um log record representa a gravação de um evento. No OpenTelemetry, um log record contém dois tipos de campos:

• Campos nomeados de nível superior com tipo e significado específicos
• Campos de recurso e atributos com valor e tipo variáveis

Os campos de nível superior são:

Para mais detalhes sobre registros de log e campos de log, consulte Modelo de Dados de Logs.

Especificação

Para saber mais sobre logs no OpenTelemetry, consulte a especificação de logs.