Ecossistema de Instrumentação

A instrumentação registra a telemetria usando a API. O SDK é a implementação de referência embutida na API, e é configurada para processar e exportar a telemetria produzida pelas chamadas de instrumentação da API. Esta página discute o ecossistema de instrumentação no OpenTelemetry Java, incluindo recursos para usuários finais e tópicos relacionados à instrumentação:

• Categorias de instrumentação: Existem diversas categorias de instrumentação para diferentes casos de uso e padrões de instalação.
• Propagação de Contexto: Propagação de Contexto provê uma correlação entre rastros, métricas, e logs, permitindo que os sinais se complementem.
• Convenções semânticas: As convenções semânticas definem como produzir telemetria para operações padrão.
• Log instrumentation

Categorias de instrumentação

Existem diversas categorias de instrumentação:

• Sem código: Agente Java é uma forma de instrumentação sem código [1] que manipula dinamicamente o bytecode da aplicação.
• Sem código: Spring Boot starter é uma forma de instrumentação sem código [1] que utiliza a autoconfiguração do spring para instalar biblioteca de instrumentação.
• Biblioteca de instrumentação envolve ou utiliza pontos de extensão para instrumentar uma biblioteca, exigindo que os usuários instalem e/ou adaptem o uso da biblioteca.
• Instrumentação nativa é incorporada diretamente em bibliotecas e frameworks.
• Instrumentação manual é escrito pelos autores das aplicações, e normalmente específico para o domínio da aplicação.
• Shims conectam dados de uma biblioteca de observabilidade a outra, normalmente de alguma biblioteca para o OpenTelemetry.

[1]: A instrumentação sem código é instalada automaticamente baseado nas bibliotecas e frameworks detectados.

O projeto opentelemetry-java-instrumentation contém o código fonte do Agente Java, inicializador Spring Boot, e Biblioteca de instrumentação.

Sem código: Agente Java

O agente do Java é uma forma de instrumentação automática zero código que manipula dinamicamente o bytecode da aplicação.

Para uma lista de bibliotecas instrumentadas pelo agente do Java, confira a coluna “Auto-instrumented versions” (versões auto-instrumentadas) em bibliotecas suportadas.

Veja Agente Java para mais detalhes.

Sem código: inicializador Spring Boot

O inicializador Spring Boot é uma forma de instrumentação automática zero código que aproveita a autoconfiguração do spring para instalar a biblioteca de instrumentação.

Veja inicializador Spring Boot para detalhes.

Biblioteca de instrumentação

Biblioteca de instrumentação envolve ou usa os pontos de extensão para instrumentar a biblioteca, obrigando os usuários a instalar e/ou adaptar o uso da biblioteca.

Para uma lista de bibliotecas de instrumentação, veja a coluna “Standalone Library Instrumentation [1]” (Biblioteca autônoma de instrumentação) em bibliotecas suportadas.

Instrumentação nativa

Instrumentação nativa é definido diretamente nas bibliotecas ou frameworks. O OpenTelemetry encoraja os autores de bibliotecas a adicionarem instrumentação nativa usando a API. No longo prazo, nós esperamos que a instrumentação nativa seja o padrão, e que a instrumentação mantida pelo OpenTelemetry em opentelemetry-java-instrumentação seja um meio temporário de preencher a lacuna.

• Elasticsearch Java API Client
• Micrometer Tracing
• Quarkus

Instrumentação manual

Instrumentação manual é escrita pelos autores das aplicações, e normalmente específica para o domínio da aplicação.

Shims

Um shim é uma instrumentação que conecta dados de uma biblioteca de observabilidade até outra, normalmente de alguma biblioteca para o OpenTelemetry.

Shims mantidos no ecossistema OpenTelemetry Java:

Propagação de Contexto

As APIs do OpenTelemetry foram desenhadas para serem complementares, onde o todo é maior que a soma das partes. Cada sinal tem seus pontos fortes e juntos formam uma narrativa convincente de observabilidade.

É importante ressaltar que os dados de vários sinais são interligados através do contexto de rastreamento:

• Trecho são relacionados com outros trechos através do trecho pai e links, que registram os contextos de rastreamento dos trechos relacionados.
• Métricas são relacionadas a trechos através de exemplares, que registram o contexto de rastreamento de uma medição específica.
• Logs são relacionados a trechos ao registrar o contexto de rastreamento nos registros de logs.

Para essa correlação funcionar, o contexto de rastreamento precisa ser propagado através da aplicação (entre chamada de funções e processos), e entre limites da aplicação. A API de contexto facilita isso.

A instrumentação deve ser escrita de uma maneira que seja ciente do contexto:

• Bibliotecas que representam um ponto de entrada da aplicação (i.e. servidores HTTP, consumidores de mensagens, etc.) devem extrair o contexto de mensagens recebidas.
• Bibliotecas que representam um ponto de saída de uma aplicação (ex. clientes HTTP, produtores de mensagens, etc.) devem injetar o contexto em mensagens de saída.
• Bibliotecas devem passar implicitamente ou explicitamente o contexto através da pilha de chamadas e entre qualquer processo.

Convenção semântica

As convenções semânticas definem como produzir telemetria para operações padrão. Entre outras coisas, as convenções semânticas especificam nomes e tipos de trechos, instrumentos de métrica, unidades de métricas, tipos de métricas, e atributos chave, valor, e níveis de requisitos.

Ao escrever instrumentação, consulte a convenção semântica e confirme que quaisquer convenções aplicáveis ao domínio estejam sendo seguidas.

O OpenTelemetry Java publica artefatos para auxiliar a conformidade com a convenção semântica, incluindo constantes geradas para chaves e valores de atributos.

Instrumentação de Log

Enquanto as APIs do LoggerProvider / Logger são estruturalmente similares ou equivalentes às APIs de rastros e métricas, elas possuem diferentes casos de uso. A partir de agora, LoggerProvider / Logger e as classes associadas representam a Log Bridge API, que existe para escrever anexadores de logs para conectar logs registrados através de outras APIs de log / frameworks no OpenTelemetry. Eles não são destinados para usuários finais como um substituto para Log4j / SLF4J / Logback / etc.

Eles são dois workflows típicos para consumir instrumentação de logs no OpenTelemetry atendendo a diferentes requisitos de aplicação:

Direto para o Collector

No workflow direto para o Collector, logs são emitidos diretamente da aplicação para o Collector usando um protocolo de rede (ex. OTLP). Este workflow é simples para configurar já que não requer nenhum componente adicional de encaminhamento de log, e permite que uma aplicação facilmente emita logs estruturados em conformidade com o modelo de dados de log. No entanto, a sobrecarga necessária para as aplicações enfileirarem e exportarem os logs para um local de rede pode não ser adequada para todas as aplicações.

Para usar este workflow:

• Instale o conector apropriado de log. [1]
• Configure o OpenTelemetry Log SDK para exportar registros de logs para o destino desejado (o Collector ou outro).

[1]: Anexadores de Logs são um tipo de shim que conecta logs de um framework no SDK de Logs do OpenTelemetry. Veja os items “Bridge Log4j em OpenTelemetry”, “Bridge Logback em OpenTelemetry”. Veja Exemplo de Anexadores de Logs para demonstração de uma variedade de cenários.

Via arquivo ou stdout

No workflow para arquivos ou stdout, os logs são gravados em arquivos ou na saída standout. Outro componente (ex. FluentBit) é responsável por ler / acompanhar os logs, convertê-los para um formato mais estruturado, e encaminhá-los para um destino, como um Collector. Este workflow pode ser preferível em situações onde os requisitos da aplicação não permitem sobrecarga adicional da abordagem direto para o Collector. No entanto, isso requer que todos os campos de logs necessários para processamento posterior sejam codificados nos logs, e este componente lendo os logs os interprete no modelo de dados de log. A instalação e configuração dos componentes de encaminhamento de log está fora do escopo deste documento.

Correlação de Logs com rastros está disponível instalando um shim para conectar o contexto do OpenTelemetry no log framework. Veja os items “Bridge OpenTelemetry contexto em Log4j”, “Bridge OpenTelemetry contexto em Logback”.