Introducción a OpenTelemetry Java

OpenTelemetry Java es el conjunto de herramientas de observabilidad de OpenTelemetry para el ecosistema Java. A grandes rasgos, se compone de la API, el SDK y la instrumentación.

Esta página presenta el ecosistema con una descripción general conceptual, una guía para navegar por la documentación y una lista de repositorios con detalles clave sobre versiones y artefactos.

Descripción general

La API es un conjunto de clases e interfaces para registrar telemetría en las señales de observabilidad clave. Admite múltiples implementaciones e incluye de forma predeterminada una implementación minimalista sin operaciones (no-op) de bajo consumo y una implementación de referencia del SDK. Está diseñada para que bibliotecas, frameworks y responsables de aplicaciones que deseen añadir instrumentación la utilicen como dependencia directa. Ofrece sólidas garantías de compatibilidad hacia atrás, no tiene dependencias transitivas y es compatible con Java 8+.

El SDK es la implementación de referencia integrada de la API, que procesa y exporta la telemetría generada por las llamadas a la API de instrumentación. Configurar el SDK para que procese y exporte correctamente es un paso esencial para integrar OpenTelemetry en una aplicación. El SDK ofrece opciones de autoconfiguración y de configuración programática.

La instrumentación registra telemetría mediante la API. Existen diversas categorías de instrumentación, entre ellas: agente Java sin código (zero-code), iniciador de Spring Boot sin código (zero-code), de biblioteca, nativa, manual y shims.

Para obtener una descripción general independiente del lenguaje, consulta los conceptos de OpenTelemetry.

Navegar por la documentación

La documentación de OpenTelemetry Java está organizada de la siguiente manera:

• Primeros pasos con un ejemplo: Un ejemplo rápido para empezar a trabajar con OpenTelemetry Java, que muestra la integración del agente Java de OpenTelemetry en una aplicación web sencilla.
• Ecosistema de instrumentación: Una guía sobre el ecosistema de instrumentación de OpenTelemetry Java. Es un recurso clave para los desarrolladores de aplicaciones que buscan integrar OpenTelemetry Java en sus aplicaciones. Conoce las diferentes categorías de instrumentación y decide cuál es la más adecuada para ti.
• Registrar telemetría con la API: Una referencia técnica de la API de OpenTelemetry, que explora todos los aspectos clave de la API con ejemplos de código funcionales. La mayoría de los usuarios utilizarán esta página como una enciclopedia, consultando el índice de secciones según sea necesario, en lugar de leerla de principio a fin.
• Gestionar la telemetría con el SDK Una referencia técnica del SDK de OpenTelemetry, que explora todos los puntos de extensión de complementos del SDK y la API de configuración programática con ejemplos de código funcionales. La mayoría de los usuarios utilizarán esta página como una enciclopedia, consultando el índice de secciones según sea necesario, en lugar de leerla de principio a fin.
• Configurar el SDK: Una referencia técnica para configurar el SDK, centrada en la autoconfiguración sin código (zero-code). Incluye una referencia de todas las variables de entorno y propiedades del sistema compatibles para configurar el SDK. Explora todos los puntos de personalización programática con ejemplos de código funcionales. La mayoría de los usuarios utilizarán esta página como una enciclopedia, consultando el índice de secciones según sea necesario, en lugar de leerla de principio a fin.
• Más información: Recursos complementarios, que incluyen ejemplos de extremo a extremo, Javadoc, el registro de componentes y una referencia de rendimiento.

Repositorios

El código fuente de OpenTelemetry Java está organizado en varios repositorios:

opentelemetry-java, opentelemetry-java-instrumentation y opentelemetry-java-contrib publican, cada uno, amplios catálogos de artefactos. Consulta los repositorios para obtener más detalles o revisa la columna «Dependencias gestionadas» de la tabla Bill of Materials para ver la lista completa de dependencias gestionadas.

Como regla general, los artefactos publicados desde el mismo repositorio tienen la misma versión. La excepción es opentelemetry-java-contrib, que puede considerarse como un grupo de proyectos independientes ubicados en el mismo repositorio para aprovechar herramientas compartidas. Por ahora, los artefactos de opentelemetry-java-contrib están alineados, pero esto es una coincidencia y cambiará en el futuro.

Los repositorios tienen una cadencia de lanzamiento que refleja su estructura de dependencias de alto nivel:

• opentelemetry-java es el núcleo y es el primero en publicar cada mes.
• opentelemetry-java-instrumentation depende de opentelemetry-java y es el siguiente en publicar.
• opentelemetry-java-contrib depende de opentelemetry-java-instrumentation y de opentelemetry-java, y es el último en publicar.
• Aunque semantic-conventions-java es una dependencia de opentelemetry-java-instrumentation, es un artefacto independiente con su propio calendario de lanzamientos.

Dependencias y BOMs

Un bill of materials, o BOM para abreviar, es un artefacto que ayuda a mantener alineadas las versiones de dependencias relacionadas. OpenTelemetry Java publica varios BOMs orientados a diferentes casos de uso, enumerados a continuación en orden de alcance creciente. Recomendamos encarecidamente utilizar un BOM.

Haz clic en el enlace de la columna «Dependencias gestionadas» para ver una lista de los artefactos gestionados por el BOM.

El siguiente fragmento de código muestra cómo añadir una dependencia de BOM, donde {{bomGroupId}}, {{bomArtifactId}} y {{bomVersion}} hacen referencia a las columnas «Grupo ID», «Artefacto ID» y «Versión actual» de la tabla, respectivamente.

• Gradle
• Maven

dependencies {
  implementation(platform("{{bomGroupId}}:{{bomArtifactId}}:{{bomVersion}}"))
  // Añade una dependencia sobre un artefacto cuya versión gestiona el 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>
  <!-- Añade una dependencia sobre un artefacto cuya versión gestiona el BOM -->
  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
    </dependency>
  </dependencies>
</project>