#Java Auto-instrumentation

Java auto-instrumentation обеспечивает комплексный сбор telemetry для Java-приложений с использованием OpenTelemetry Java agent. Эта instrumentation автоматически собирает traces, metrics и logs из Java-приложений и популярных frameworks без необходимости изменения кода.

#Как работает Java Auto-instrumentation

Operator внедряет OpenTelemetry Java agent в контейнеры Java-приложений в виде JAR-файла Java agent. Agent использует bytecode instrumentation для автоматической instrumentation Java-классов во время выполнения, собирая telemetry-данные из:

• HTTP servers и clients (Servlet, Spring MVC, JAX-RS и т. д.)
• Database clients (JDBC, Hibernate и т. д.)
• Messaging systems (JMS, Kafka, RabbitMQ и т. д.)
• RPC frameworks (gRPC и т. д.)
• Caching libraries (Redis, Memcached и т. д.)
• И многих других популярных Java libraries и frameworks

#Включение Java Instrumentation

Чтобы включить auto-instrumentation для Java-приложений, добавьте annotation в pod или namespace:

apiVersion: v1
kind: Pod
metadata:
  name: java-app
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
spec:
  containers:
  - name: app
    image: myjavaapp:latest

Operator автоматически внедряет Java agent и настраивает JVM на его загрузку при запуске, устанавливая переменную среды JAVA_TOOL_OPTIONS с флагом -javaagent.

#Переменные среды Java Agent

Следующие переменные среды управляют поведением Java agent:

#Управление instrumentation

• OTEL_JAVAAGENT_ENABLED - Включает или отключает Java agent (по умолчанию: true)
• OTEL_JAVAAGENT_DEBUG - Включает отладочное logging для agent (по умолчанию: false)
• OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED - По умолчанию включает все instrumentations (по умолчанию: true)

#Управление конкретными instrumentation

Вы можете включать или отключать отдельные instrumentations:

• OTEL_INSTRUMENTATION_JDBC_ENABLED - JDBC instrumentation
• OTEL_INSTRUMENTATION_SPRING_WEB_ENABLED - Spring Web instrumentation
• OTEL_INSTRUMENTATION_KAFKA_ENABLED - Kafka instrumentation
• OTEL_INSTRUMENTATION_REDIS_ENABLED - Redis instrumentation

Пример конфигурации:

spec:
  java:
    env:
      - name: OTEL_INSTRUMENTATION_JDBC_ENABLED
        value: "true"
      - name: OTEL_INSTRUMENTATION_KAFKA_ENABLED
        value: "true"
      - name: OTEL_INSTRUMENTATION_REDIS_ENABLED
        value: "false"

#Конфигурация расширений

Настройте дополнительные agent extensions:

• OTEL_JAVAAGENT_EXTENSIONS - Путь к дополнительным agent extensions
• OTEL_JAVAAGENT_CONFIGURATION_FILE - Путь к файлу конфигурации agent

#Расширенная конфигурация

#Пользовательский образ Agent

Вы можете указать пользовательский образ Java agent:

spec:
  java:
    image: my-registry.com/custom-java-agent:my-tag

#Монтирование томов

Agent монтируется в контейнер приложения по пути /otel-auto-instrumentation-java-<container-name>/.

#Внедрение для отдельных контейнеров

Для pod с несколькими контейнерами укажите, какие контейнеры следует instrumentировать:

metadata:
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
    instrumentation.opentelemetry.io/container-names: "app,worker"

#Поддерживаемые версии Java

OpenTelemetry Java agent поддерживает:

• Java 8 и новее

#Устранение неполадок

#Проверка внедрения Agent

Проверьте, что agent был успешно внедрен:

kubectl describe pod <pod-name>

Обратите внимание на аргумент -javaagent в команде контейнера.

#Включение отладочного logging

Включите отладочное logging для диагностики проблем:

spec:
  java:
    env:
      - name: OTEL_JAVAAGENT_DEBUG
        value: "true"
      - name: OTEL_LOG_LEVEL
        value: "debug"

#Частые проблемы

Agent не загружается: Убедитесь, что init container завершился успешно и JAR-файл agent присутствует в общем томе.

Отсутствуют traces: Проверьте, что endpoint exporter указан верно и доступен из pod приложения.

Высокое потребление памяти: Уменьшите количество включенных instrumentations или настройте параметры heap JVM.

#Пример конфигурации

Полный пример instrumentation Java-приложения:

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: java-instrumentation
  namespace: java-development
spec:
  java:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.26.1
    env:
      - name: OTEL_JAVAAGENT_DEBUG
        value: "false"
  exporter:
    endpoint: http://otel-collector.observability.svc:4318
  env:
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: deployment.environment.name=development
  sampler:
    type: parentbased_traceidratio
    argument: "1"
  propagators:
    - tracecontext
    - baggage
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: java-app
  namespace: java-development
spec:
  replicas: 1
  selector:
    matchLabels:
      app: java-app
  template:
    metadata:
      labels:
        app: java-app
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"
    spec:
      containers:
      - name: app
        image: myjavaapp:latest
        ports:
        - containerPort: 8080

#Справочник по конфигурации

Подробные параметры конфигурации, поддерживаемые libraries и сценарии расширенного использования см. в официальной документации OpenTelemetry Operator:

Java Auto-instrumentation Documentation