Introdução ao OpenTelemetry Java

OpenTelemetry Java é o conjunto de ferramentas de observabilidade do OpenTelemetry para o ecossistema Java. Em alto nível, consiste na API, no SDK e na instrumentação.

Esta página apresenta o ecossistema, com uma visão geral conceitual, um guia para navegar pela documentação, uma lista de repositórios com detalhes importantes sobre lançamentos e artefatos.

Visão geral

A API é um conjunto de classes e interfaces para registrar telemetria em sinais-chave de observabilidade. Ela suporta múltiplas implementações, incluindo uma implementação minimalista Noop de baixo overhead (pronunciada “no-op”, de “no operation”, significando “sem operação”) e uma implementação de referência de SDK fornecida de forma nativa. Ela foi projetada para ser utilizada como dependência direta por bibliotecas, frameworks e responsáveis por aplicações que desejam adicionar instrumentação. Possui fortes garantias de compatibilidade retroativa, nenhuma dependência transitiva e suporte ao Java 8+.

O SDK é a implementação de referência integrada da API, responsável por processar e exportar a telemetria produzida pelas chamadas da API de instrumentação. Configurar o SDK para processar e exportar adequadamente é um passo essencial para integrar o OpenTelemetry a uma aplicação. O SDK possui opções de configuração automática e programática.

A instrumentação registra telemetria através da API. Existem várias categorias de instrumentação, incluindo: agente Java sem código, inicializador do Spring Boot sem código, biblioteca, nativa, manual e shims.

Para uma visão geral independente de linguagem, consulte conceitos do OpenTelemetry.

Navegando pela documentação

A documentação do OpenTelemetry Java está organizada da seguinte forma:

• Primeiros Passos com Exemplos: Um exemplo rápido para começar a utilizar o OpenTelemetry Java, demonstrando a integração do agente Java OpenTelemetry em uma aplicação web simples.
• Ecossistema de instrumentação: Um guia para o ecossistema de instrumentação do OpenTelemetry Java. Este é um recurso chave para autores de aplicações que desejam integrar o OpenTelemetry Java em suas aplicações. Aprenda sobre as diferentes categorias de instrumentação e decida qual é a certa para você.
• Registrar Telemetria com a API: Uma referência técnica para a API do OpenTelemetry, explorando todos os aspectos chave da API com exemplos de código funcionais. A maioria dos usuários usará esta página como uma enciclopédia, consultando o índice de seções conforme necessário, em vez de ler do início ao fim.
• Gerenciar Telemetria com o SDK Uma referência técnica para o SDK do OpenTelemetry, explorando todos os pontos de extensão de plugins do SDK e a API de configuração programática, com exemplos de código funcionais. Assim como a anterior, esta página costuma ser utilizada como uma enciclopédia.
• Configurar o SDK: Uma referência técnica para configurar o SDK, com foco na configuração automática sem código. Inclui uma referência de todas as variáveis de ambiente e propriedades do sistema suportadas para configurar o SDK. Também explora todos os pontos de personalização programática com exemplos de código. A maioria dos usuários usará esta página como uma enciclopédia.
• Saiba Mais: Recursos complementares, incluindo exemplos completos, Javadoc, registro de componentes e uma referência de desempenho.

Repositórios

O código-fonte do OpenTelemetry Java está organizado em vários repositórios:

| Repositório | Descrição | ID do Grupo | Versão atual | Cadência de lançamento |\n|

|

| ———————————- | ———————————— |

| | opentelemetry-java | Componentes principais da API e do SDK | io.opentelemetry | 1.50.0 | Sexta-feira após a primeira segunda-feira do mês | | opentelemetry-java-instrumentation | Instrumentação mantida pelo OpenTelemetry, incluindo o agente Java OpenTelemetry | io.opentelemetry.instrumentation | 2.16.0 | Quarta-feira após a segunda segunda-feira do mês | | opentelemetry-java-contrib | Componentes mantidos pela comunidade que não se encaixam no escopo expresso de outros repositórios | io.opentelemetry.contrib | 1.46.0 | Sexta-feira após a segunda segunda-feira do mês | | semantic-conventions-java | Código gerado para convenções semânticas | io.opentelemetry.semconv | 1.32.0 | Segue os lançamentos de semantic-conventions | | opentelemetry-proto-java | Bindings gerados para OTLP | io.opentelemetry.proto | 1.3.2-alpha | Segue os lançamentos de opentelemetry-proto | | opentelemetry-java-examples | Exemplos de código completos demonstrando uma variedade de padrões usando a API, SDK e instrumentação | n/a | n/a | n/a |

opentelemetry-java, opentelemetry-java-instrumentation e opentelemetry-java-contrib publicam grandes catálogos de artefatos. Consulte os repositórios para mais detalhes ou veja a coluna “Dependências gerenciadas” na tabela de Declaração de Materiais para conferir a lista completa de dependências gerenciadas.

Como regra geral, artefatos publicados a partir do mesmo repositório possuem a mesma versão. A exceção é o opentelemetry-java-contrib, que pode ser entendido como um conjunto de projetos independentes que compartilham o mesmo repositório para aproveitar ferramentas compartilhadas. Por enquanto, os artefatos do opentelemetry-java-contrib estão alinhados, mas isso é uma coincidência e vai mudar no futuro.

Os repositórios têm uma cadência de lançamento que reflete sua estrutura de dependência em alto nível:

• opentelemetry-java é o núcleo e lança primeiro a cada mês.
• opentelemetry-java-instrumentation depende de opentelemetry-java e é publicado logo em seguida.
• opentelemetry-java-contrib depende de opentelemetry-java-instrumentation e opentelemetry-java e é publicado por último.
• Embora semantic-conventions-java seja uma dependência de opentelemetry-java-instrumentation, é um artefato independente e possui seu próprio cronograma de lançamento.

Dependências e declaração de materiais (BOMs)

Uma declaração de materiais, ou BOM (bill of materials) de forma abreviada, é um artefato que ajuda a manter alinhadas as versões de dependências relacionadas. O OpenTelemetry Java publica várias BOMs para diferentes casos de uso, listados abaixo em ordem crescente de escopo. Recomendamos fortemente o uso de uma BOM.

Clique no link na coluna “Dependências gerenciadas” para ver uma lista dos artefatos gerenciados pela BOM.

O trecho de código a seguir demonstra como adicionar uma dependência de BOM, com {{bomGroupId}}, {{bomArtifactId}} e {{bomVersion}} referindo-se, respectivamente, às colunas “ID do grupo”, “ID do artefato” e “Versão atual” da tabela.

• Gradle
• Maven

dependencies {
  implementation(platform("{{bomGroupId}}:{{bomArtifactId}}:{{bomVersion}}"))
  // Adiciona uma dependência em um artefato cuja versão é gerenciada pela BOM
  implementation("io.opentelemetry:opentelemetry-api")
}

<project>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>{{bomGroupId}}</groupId>
        <artifactId>{{bomArtifactId}}</artifactId>
        <version>{{bomVersion}}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <!-- Adiciona uma dependência em um artefato cuja versão é gerenciada pela BOM -->
  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
    </dependency>
  </dependencies>
</project>