Logs | OpenTelemetry

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.
O OpenTelemetry fornece uma API e SDK de Logs para produzir registros de log, e SDKs de linguagem e pontes de log (logging bridges) para integrar com frameworks de logging existentes. Logs são qualquer coisa que você envie através de um Logging Provider, e eventos são um tipo especial de logs. Nem todos os logs são eventos, mas todos os eventos são logs. A API de Logs é pública e pode ser usada diretamente pelo código da aplicação ou indiretamente por meio de bibliotecas de logging e pontes existentes.
O OpenTelemetry é projetado para funcionar com os logs que você já produz, oferecendo ferramentas para correlacionar logs com outros sinais, adicionar atributos de contexto, e normalizar diferentes fontes em uma representação comum para processamento e exportação.
O OpenTelemetry Collector fornece várias ferramentas para trabalhar com logs:
O primeiro passo na adoção do OpenTelemetry frequentemente envolve implantar um Collector como um agente de logging genérico.
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.
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:
O OpenTelemetry aceita qualquer formato de log, mas nem todos os formatos são igualmente úteis para análise. A seção a seguir explica as diferenças entre logs estruturados, semiestruturados e não estruturados. Importante: um log codificado como JSON não é automaticamente “estruturado” no sentido de possuir um esquema estável — podendo ser semiestruturado. Logs estruturados implicam um esquema consistente ou campos com tipos bem definidos nos quais o processamento downstream pode confiavelmente depender.
Um log estruturado é um log com um esquema definido e consistente ou campos tipados que sistemas downstream podem analisar e interpretar de forma confiável. A codificação textual pode ser JSON, protobuf ou outro formato, mas o que torna um log estruturado é a presença de um esquema estável (nomes de campos, tipos e semântica), e não apenas o fato de ser um JSON válido. Por exemplo, um log JSON estruturado pode se parecer com:
e, para componentes de infraestrutura, o Common Log Format (CLF) é frequentemente usado:
Também é comum encontrar formatos híbridos ou estendidos (por exemplo, campos CLF combinados com um blob JSON ao final).
Nesses casos, analise ou extraia as partes necessárias para um registro normalizado, de modo que as ferramentas downstream possam analisá-las de forma consistente. O filelogreceiver no OpenTelemetry Collector fornece auxiliares para analisar formatos mistos.
Logs estruturados são preferidos em produção porque seu esquema estável facilita a validação, a análise, a correlação com rastros e métricas e a análise em escala.
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:
É 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 incluem pares chave/valor legíveis por máquina ou campos delimitados, mas não garantem um esquema estável entre emissores. Exemplos incluem logging no formato chave=valor (mostrado abaixo) ou blobs JSON em que nomes e tipos de campos variam entre mensagens. Logs semiestruturados geralmente são mais fáceis de analisar do que logs não estruturados, mas ainda podem exigir processamento e normalização antes da análise.
Exemplo de um log semiestruturado:
Logs semiestruturados podem exigir mapeamento e coerção de tipos durante a ingestão para serem totalmente úteis na análise downstream.
Uma dúvida comum é se o código da aplicação deve verificar se o logging está habilitado antes de fazer uma chamada de log, por exemplo:
Na maioria dos casos, essa verificação é desnecessária e não é recomendada. Os SDKs do OpenTelemetry são projetados para serem eficientes – a invocação da API de logs tem uma sobrecarga mínima quando o logger não está habilitado. Fazer uma chamada extra a logger.Enabled reduz o desempenho e torna o código mais complexo.
A API Enabled é útil apenas quando avaliar os argumentos passados para a chamada de log é, por si só, custoso, e se deseja evitar esse custo quando o logger não está habilitado. Por exemplo, se o corpo ou um atributo precisar ser obtido de um banco de dados ou calculado por meio de uma operação custosa:
Proteja apenas expressões livres de efeitos colaterais, já que o código protegido é executado some