En este documento, se muestra cómo instrumentar automáticamente aplicaciones Java que se ejecutan en Google Kubernetes Engine (GKE) con la instrumentación de código cero de OpenTelemetry. La instrumentación sin código te brinda una observabilidad integral de tus cargas de trabajo de Java con un mínimo esfuerzo manual.
En esta guía, se proporcionan pasos detallados para implementar una aplicación de ejemplo en Java en GKE, instrumentar automáticamente la aplicación con OpenTelemetry y visualizar los indicadores de telemetría generados con Google Cloud Observability.
En la guía, se describe la instrumentación automática de cargas de trabajo de Java que se ejecutan en GKE, pero puedes extender estas instrucciones a otros lenguajes compatibles.
¿Por qué usar la instrumentación sin código?
La instrumentación sin código (también llamada instrumentación automática) en OpenTelemetry es una herramienta potente que permite a los desarrolladores de aplicaciones agregar observabilidad configurable a su código sin necesidad de escribir código adicional ni modificar el código existente. La instrumentación sin código funciona agregando automáticamente instrumentación a las bibliotecas de aplicaciones implementadas de forma activa, lo que proporciona estadísticas confiables sobre el rendimiento de las aplicaciones a través de la emisión de indicadores clave de rendimiento. Esto hace que la instrumentación sin código sea un excelente punto de partida para el recorrido de observabilidad de una aplicación.
La instrumentación sin código en Java emite métricas y tramos de seguimiento a través de la instrumentación de bibliotecas populares que se usan ampliamente en el ecosistema del lenguaje. En el caso de Java, las métricas incluyen lo siguiente:
- Métricas de tiempo de ejecución de JVM emitidas por la plataforma Java
- Métricas de HttpClient y intervalos de HttpClient emitidos desde bibliotecas como la biblioteca cliente de Http de Java y la biblioteca cliente de Http de Google
- Métricas del cliente de la base de datos y intervalos del cliente de la base de datos emitidos desde bibliotecas como JDBC y Lettuce.
El conjunto de métricas emitidas depende de la aplicación que se instrumenta y de las bibliotecas que usa la aplicación. Para obtener una lista completa de las bibliotecas y los frameworks que se pueden instrumentar con el agente de instrumentación sin código de Java, consulta Supported Libraries and Frameworks.
Con la instrumentación automática, puedes hacer lo siguiente:
- Obtén la supervisión de los indicadores clave de rendimiento sin tener que realizar cambios en el código.
- Correlaciona la latencia alta del percentil 99.9 con los registros de usuarios individuales, que abarcan cada llamada a RPC.
- Obtén telemetría coherente en métricas, registros y registros de seguimiento de una amplia variedad de bibliotecas y frameworks populares.
Para obtener más información sobre la instrumentación sin código, consulta Sin código de OpenTelemetry.
Descripción general
Para agregar observabilidad a una carga de trabajo de Java que se ejecuta en GKE, debes implementar los siguientes componentes:
- Instrumentación de OpenTelemetry sin código, que genera la telemetría de tu aplicación.
- El recopilador de OpenTelemetry, que recopila la telemetría generada por tu aplicación, la enriquece con metadatos y contexto críticos, y la enruta a Google Cloud para su consumo.
En este recorrido, implementarás una aplicación de Java instrumentada en GKE que emite métricas y registros a Google Cloud. Luego, puedes ver estos indicadores de telemetría con las ofertas de observabilidad de Google Cloud, como el Explorador de métricas, el Explorador de registros y el Explorador de registros de seguimiento. Para obtener información sobre cómo ver y usar la telemetría generada, consulta Cómo ver tu telemetría.
En esta explicación, se usan los siguientes servicios por los que se cobra para escribir indicadores:
- Servicio administrado para Prometheus de Cloud Monitoring
- Cloud Logging
- Cloud Trace
- Google Kubernetes Engine
- Cloud Build
- Artifact Registry
Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.
Antes de comenzar
En esta sección, se describe cómo configurar tu entorno para implementar y registrar la app, y, luego, ejecutarla.
Selecciona o crea un proyecto de Google Cloud
Elige un Google Cloud proyecto para este recorrido. Si aún no tienes un proyecto Google Cloud , crea uno:
- Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Instala herramientas de línea de comandos
En este documento, se usan las siguientes herramientas de línea de comandos:
gcloudkubectl
Las herramientas gcloud y kubectl forman parte de la CLI de Google Cloud. Para obtener información sobre cómo instalarlos, consulta Administra los componentes de Google Cloud CLI. Para ver los componentes de gcloud CLI que instalaste, ejecuta el siguiente comando:
gcloud components list
Configura las variables de entorno
Para reducir la escritura de valores frecuentes, evitar errores de escritura y hacer que los comandos de este documento se puedan ejecutar, configura las siguientes variables de entorno:
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export CLUSTER_NAME=CLUSTER_NAME
export CLUSTER_REGION=us-east1
export ARTIFACT_REGISTRY=opentelemetry-autoinstrument-registry
export REGISTRY_LOCATION=us-east4
Antes de ejecutar los comandos, reemplaza las siguientes variables o usa los valores predeterminados:
- PROJECT_ID: Es el identificador del proyecto.
- CLUSTER_NAME: Es el nombre de tu clúster. Puede referirse a un clúster nuevo o existente.
- us-east1: Es la región del clúster. Si usas un clúster existente, usa la región de ese clúster.
- opentelemetry-autoinstrument-registry: Es el nombre de tu repositorio de Artifact Registry. Puede referirse a un repositorio nuevo o existente.
- us-east4: Es la región de tu repositorio de Artifact Registry. Si usas un repositorio existente, usa la región de ese repositorio.
Si encuentras errores cuando ejecutas los comandos de este documento, verifica que estas variables estén configuradas correctamente en tu entorno de terminal.
Habilita las APIs
Para usar los servicios que se describen en este documento, debes tener habilitadas las siguientes APIs en tu proyecto de Google Cloud :
- API de Artifact Registry:
artifactregistry.googleapis.com - API de Cloud Build:
cloudbuild.googleapis.com - Google Kubernetes Engine:
container.googleapis.com - API de Identity and Access Management:
iam.googleapis.com - API de Cloud Logging:
logging.googleapis.com - API de Cloud Monitoring:
monitoring.googleapis.com - API de Telemetry:
telemetry.googleapis.com
Es posible que estas APIs, con la excepción probable de la API de Telemetry, ya estén habilitadas en tu proyecto de Google Cloud . Ejecuta el siguiente comando para enumerar las APIs habilitadas:
gcloud services list
Habilita cualquiera de las APIs que aún no estén habilitadas.
Presta especial atención a la API de Telemetry, telemetry.googleapis.com, ya que es posible que esta sea la primera vez que te encuentras con ella.
Para habilitar las APIs que aún no están habilitadas, ejecuta los comandos de las APIs correspondientes:
gcloud services enable artifactregistry.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable iam.googleapis.com
gcloud services enable logging.googleapis.com
gcloud services enable monitoring.googleapis.com
gcloud services enable telemetry.googleapis.com
Configura tu clúster
Configura un clúster de GKE para la aplicación de ejemplo y el recopilador:
Para acceder a Google Cloud , ejecuta los siguientes comandos:
gcloud auth login gcloud config set project PROJECT_IDSi aún no tienes un clúster de GKE, crea uno de Autopilot ejecutando el siguiente comando:
gcloud container clusters create-auto --region us-east1 CLUSTER_NAME --project PROJECT_IDPara interactuar con tu clúster, conecta tu utilidad local de
kubectlejecutando el siguiente comando:gcloud container clusters get-credentials CLUSTER_NAME --region us-east1 --project PROJECT_ID
Implementa la aplicación de Java
En los pasos de esta sección, se implementa una aplicación de ejemplo de Java sin instrumentar, el ejemplo de instrumentación de OpenTelemetry Spring Boot, en tu clúster. En esta sección, se usan Cloud Build y Artifact Registry para crear y almacenar la imagen de la aplicación.
Si aún no tienes un repositorio de Artifact Registry, crea uno ejecutando el siguiente comando:
gcloud artifacts repositories create opentelemetry-autoinstrument-registry --repository-format=docker --location=us-east4 --description="GKE Autoinstrumentation sample app"Clona la aplicación de ejemplo ejecutando el siguiente comando:
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java.gitConfigura las siguientes variables de entorno:
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export ARTIFACT_REGISTRY=opentelemetry-autoinstrument-registry export REGISTRY_LOCATION=us-east4Compila la imagen de la aplicación y envíala a tu repositorio de Artifact Registry ejecutando los siguientes comandos:
pushd opentelemetry-operations-java/examples/instrumentation-quickstart && \ gcloud builds submit --config <(envsubst < cloudbuild-uninstrumented-app.yaml) . && \ popdCrea un archivo de configuración de implementación de Kubernetes para la aplicación. Copia la siguiente configuración y guárdala en un archivo llamado
deployment.yaml:apiVersion: v1 kind: Service metadata: name: quickstart-app labels: app: quickstart-app app.kubernetes.io/part-of: gke-autoinstrument-guide spec: ports: - port: 8080 targetPort: 8080 name: quickstart-app selector: app: quickstart-app --- apiVersion: apps/v1 kind: Deployment metadata: name: quickstart-app labels: app: quickstart-app app.kubernetes.io/part-of: gke-autoinstrument-guide spec: replicas: 2 selector: matchLabels: app: quickstart-app template: metadata: labels: app: quickstart-app spec: containers: - name: quickstart-app image: us-east4-docker.pkg.dev/PROJECT_ID/opentelemetry-autoinstrument-registry/java-quickstart:latest ports: - containerPort: 8080 name: quickstart-appEjecuta el siguiente comando para crear un espacio de nombres para tu aplicación:
kubectl create namespace APPLICATION_NAMESPACEEjecuta el siguiente comando para aplicar la configuración de implementación a tu clúster:
kubectl apply -f deployment.yaml -n APPLICATION_NAMESPACEDespués de crear la implementación, es posible que los pods tarden un tiempo en crearse y comenzar a ejecutarse. Para verificar el estado de los pods, ejecuta el siguiente comando:
kubectl get po -n APPLICATION_NAMESPACE -wPara dejar de observar el estado del pod, presiona Ctrl+C para detener el comando.
Configura una instancia del recopilador de OpenTelemetry
En esta sección, crearás otra implementación que ejecute una instancia del recopilador de OpenTelemetry compilado por Google en tu clúster de GKE. El recopilador está configurado para exportar datos con los siguientes exportadores:
- Métricas con el exportador HTTP de OTLP
- Registros de seguimiento con el exportador de OTLP HTTP
- Registros con el exportador de Google Cloud
En lugar de seguir los pasos manuales que se indican en este documento para implementar el recopilador de OpenTelemetry, puedes seguir OpenTelemetry administrado para GKE, que usa el recopilador de OpenTelemetry integrado en Google en un entorno administrado.
Para autorizar la cuenta de servicio de Kubernetes para la implementación del recopilador de OpenTelemetry, ejecuta los siguientes comandos:
export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)") gcloud projects add-iam-policy-binding projects/PROJECT_ID \ --role=roles/logging.logWriter \ --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \ --condition=None gcloud projects add-iam-policy-binding projects/PROJECT_ID \ --role=roles/monitoring.metricWriter \ --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \ --condition=None gcloud projects add-iam-policy-binding projects/PROJECT_ID \ --role=roles/telemetry.tracesWriter \ --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \ --condition=None
Ejecuta el siguiente comando para implementar la instancia del recopilador de OpenTelemetry compilado por Google en tu clúster de GKE con la configuración predeterminada recomendada:
kubectl kustomize https://github.com/GoogleCloudPlatform/otlp-k8s-ingest//k8s/base?ref=otlpmetric | envsubst | kubectl apply -f -Esta configuración implementa el recopilador en el espacio de nombres
opentelemetry.Después de crear la implementación, es posible que los pods tarden un tiempo en crearse y comenzar a ejecutarse. Para verificar el estado de los pods, ejecuta el siguiente comando:
kubectl get po -n opentelemetry -wPara dejar de observar el estado del pod, presiona Ctrl+C para detener el comando.
Configura la instrumentación sin código de OpenTelemetry
Para configurar la instrumentación sin código de OpenTelemetry para una aplicación implementada en GKE, instala el operador de OpenTelemetry en tu clúster de GKE. El operador de OpenTelemetry proporciona acceso a una definición de recurso personalizado (CRD) de Kubernetes, el recurso de Instrumentation, que se usa para insertar la instrumentación automática en los recursos de Kubernetes que se ejecutan dentro de un clúster.
El recurso de Instrumentation se "inserta" o "aplica" a cargas de trabajo específicas con anotaciones especiales. El operador de OpenTelemetry observa estas anotaciones en los recursos que se ejecutan dentro del clúster y, luego, inserta la instrumentación adecuada en las aplicaciones administradas por esos recursos.
Si aún no tienes instalada la CLI de Helm, ejecuta los siguientes comandos para instalarla:
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 chmod 700 get_helm.sh ./get_helm.shSi aún no tienes instalado
cert-manageren el clúster, ejecuta los siguientes comandos para instalarlo:helm repo add jetstack https://charts.jetstack.io helm repo update helm install \ --create-namespace \ --namespace cert-manager \ --set installCRDs=true \ --set global.leaderElection.namespace=cert-manager \ --set extraArgs={--issuer-ambient-credentials=true} \ cert-manager jetstack/cert-managerInstala el operador de OpenTelemetry ejecutando el siguiente comando y usando la versión 0.140.0 o posterior:
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/download/v0.140.0/opentelemetry-operator.yamlCrea un archivo de configuración para el recurso personalizado de Instrumentation creando un archivo llamado
instrumentation.yamlcon el siguiente contenido:apiVersion: opentelemetry.io/v1alpha1 kind: Instrumentation metadata: name: sample-java-auto-instrumentation spec: exporter: endpoint: http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317 sampler: type: parentbased_traceidratio # Adjust the sampling rate to control cost argument: "0.01" java: env: - name: OTEL_EXPORTER_OTLP_PROTOCOL value: grpc - name: OTEL_LOGS_EXPORTER value: noneCrea un espacio de nombres para el operador. Puedes usar el mismo valor que usaste para el espacio de nombres de la aplicación, APPLICATION_NAMESPACE.
kubectl create namespace INSTRUMENTATION_NAMESPACECrea el recurso personalizado de Instrumentation en tu clúster y aplica tu archivo
instrumentation.yamlejecutando el siguiente comando:kubectl apply -f instrumentation.yaml -n INSTRUMENTATION_NAMESPACEAplica la anotación de instrumentación automática a la aplicación de ejemplo en Java implementada anteriormente. Aplica un parche al Deployment original con la anotación ejecutando el siguiente comando:
kubectl patch deployment.apps/quickstart-app -n APPLICATION_NAMESPACE -p '{"spec":{"template":{"metadata":{"annotations":{"instrumentation.opentelemetry.io/inject-java": "'"INSTRUMENTATION_NAMESPACE"'/sample-java-auto-instrumentation"}}}}}'Después de aplicar el parche a la implementación, lo que provoca que se reinicie la implementación de la aplicación, puedes verificar el estado de los pods en la aplicación ejecutando el siguiente comando:
kubectl get po -n APPLICATION_NAMESPACE -wPara dejar de observar el estado del pod, presiona Ctrl+C para detener el comando.
La aplicación de Java implementada en tu clúster de GKE ahora está instrumentada automáticamente.
Genera datos de telemetría a partir de la aplicación implementada
Para generar telemetría a partir de la aplicación instrumentada automáticamente, debes enviar solicitudes a la aplicación para simular la actividad del usuario. Puedes generar un flujo constante de tráfico ejecutando un simulador de tráfico. En esta sección, se describe cómo descargar el simulador, compilarlo con Cloud Build, almacenarlo en una imagen en Artifact Registry y, luego, implementarlo:
Descarga la aplicación del simulador de tráfico ejecutando los siguientes comandos:
mkdir traffic-simulator && pushd traffic-simulator && \ curl -O https://raw.githubusercontent.com/GoogleCloudPlatform/opentelemetry-operator-sample/refs/heads/main/recipes/self-managed-otlp-ingest/traffic/hey.Dockerfile && \ curl -O https://raw.githubusercontent.com/GoogleCloudPlatform/opentelemetry-operator-sample/refs/heads/main/recipes/self-managed-otlp-ingest/traffic/cloudbuild-hey.yaml && \ popdLos comandos anteriores realizan las siguientes acciones:
- Crea un directorio independiente para compilar una aplicación de simulador de tráfico.
- Descarga el Dockerfile de la aplicación.
- Descarga la configuración de Cloud Build para compilar la imagen de la aplicación.
Crea la imagen de la aplicación con Cloud Build y envíala a Artifact Registry ejecutando los siguientes comandos:
pushd traffic-simulator && \ gcloud builds submit --config <(envsubst < cloudbuild-hey.yaml) . && \ popdCopia el siguiente contenido en un archivo del directorio
traffic-simulatorllamadoquickstart-traffic.yamlpara crear un archivo de configuración de implementación para el simulador:apiVersion: apps/v1 kind: Deployment metadata: name: traffic-simulator labels: app.kubernetes.io/part-of: gke-autoinstrument-guide spec: replicas: 1 selector: matchLabels: app: traffic-simulator template: metadata: labels: app: traffic-simulator spec: containers: - name: traffic-simulator image: us-east4-docker.pkg.dev/PROJECT_ID/opentelemetry-autoinstrument-registry/hey:latest args: - -c=2 - -q=1 - -z=1h - http://quickstart-app:8080/multiPara implementar el simulador de tráfico, ejecuta los siguientes comandos:
pushd traffic-simulator && \ kubectl apply -f quickstart-traffic.yaml -n APPLICATION_NAMESPACE && \ popdDespués de crear la implementación, es posible que los pods tarden un tiempo en crearse y comenzar a ejecutarse. Para verificar el estado de los pods, ejecuta el siguiente comando:
kubectl get po -n APPLICATION_NAMESPACE -wPara dejar de observar el estado del pod, presiona Ctrl+C para detener el comando.
Cómo ver tus datos de telemetría
Después de que el simulador de tráfico comience a enviar solicitudes a la aplicación, la aplicación Java implementada generará telemetría. Es posible que las métricas y los registros tarden unos minutos en aparecer en Google Cloud.
La instrumentación que inyecta el operador de OpenTelemetry se basa en el agente de Java de OpenTelemetry. El agente de Java de OpenTelemetry contiene instrumentación integrada para muchas bibliotecas y frameworks de Java populares que emiten métricas.
La instrumentación insertada también captura automáticamente los registros de cualquier llamada realizada a cualquier extremo expuesto por la aplicación de ejemplo. El simulador de tráfico envía solicitudes constantemente al extremo
/multique expone la aplicación de Java a una frecuencia fija. A su vez, el extremo/multienvía solicitudes al extremo/singlepara generar la respuesta final. Estas interacciones terminan como registros que se pueden ver con el Explorador de registros.
Ver métricas
Puedes ver tus métricas instrumentadas automáticamente en el Explorador de métricas de Cloud Monitoring. En esta sección, se incluyen consultas de ejemplo escritas en PromQL.
En la consola de Google Cloud , accede a la página leaderboard Explorador de métricas:
Acceder al Explorador de métricas
Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.
Estas son algunas de las métricas que puedes consultar para la aplicación de ejemplo:
Métricas del entorno de ejecución de JVM: El agente de Java de OpenTelemetry emite métricas sobre la JVM subyacente. Estas métricas exponen información sobre la memoria de la JVM, la recolección de elementos no utilizados, las clases, los subprocesos y otros conceptos relacionados. Para obtener una lista completa de las métricas de JVM admitidas, consulta la página JVM Runtime Metrics Semantic Conventions.
Uso de memoria de JVM: Pega la siguiente consulta de PromQL en el Explorador de métricas:
sum(avg_over_time({"process.runtime.jvm.memory.usage"}[${__interval}]))Utilización de CPU de JVM: Pega la siguiente consulta de PromQL en el Explorador de métricas:
sum(avg_over_time({"process.runtime.jvm.cpu.utilization"}[${__interval}]))En el siguiente gráfico, se muestra la métrica de uso de CPU de la JVM:
Métricas de Spring Boot: La aplicación de ejemplo usa el framework de Spring Boot, que también es compatible con la instrumentación sin código de OpenTelemetry para Java.
Duración media del cliente HTTP: Pega la siguiente consulta de PromQL en el Explorador de métricas:
sum(rate({"http.client.duration_sum"}[${__interval}])) by (cluster, job) / sum(rate({"http.client.duration_count"}[${__interval}])) by (cluster, job)Duración media del servidor HTTP: Pega la siguiente consulta de PromQL en el Explorador de métricas:
sum(rate({"http.server.duration_sum"}[${__interval}])) by (cluster, job) / sum(rate({"http.server.duration_count"}[${__interval}])) by (cluster, job)En el siguiente gráfico, se muestra la métrica de duración promedio del servidor HTTP de Spring Boot:
Para obtener más información sobre el uso del Explorador de métricas, consulta Selecciona métricas cuando uses el Explorador de métricas.
Ver seguimientos
Puedes ver tus seguimientos instrumentados automáticamente en el Explorador de seguimiento de Cloud Trace. Puedes filtrar estos registros en el Explorador de registros filtrando por "Nombre del servicio" y configurando el nombre del servicio como quickstart-app.
En la consola de Google Cloud , ve a la página
Explorador de seguimiento:
Ve al Explorador de seguimiento
También puedes usar la barra de búsqueda para encontrar esta página.
En la siguiente captura de pantalla, se muestran los registros generados por la implementación de quickstart-app de OpenTelemetry:
Para obtener más información sobre el uso del Explorador de Trace, consulta Busca y explora seguimientos.
Realiza una limpieza
Si creaste un proyecto Google Cloud nuevo y ya no lo necesitas, puedes borrarlo con el siguiente comando:
gcloud projects delete PROJECT_ID
Si usaste un proyecto existente, puedes borrar los recursos que creaste como parte de este instructivo para ahorrar costos:
Borra el clúster de GKE ejecutando el siguiente comando:
gcloud container clusters delete CLUSTER_NAME --location=us-east1Borra el repositorio de Artifact Registry ejecutando el siguiente comando:
gcloud artifacts repositories delete opentelemetry-autoinstrument-registry --location=us-east4