#Java Auto-instrumentation

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

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

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

• 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-библиотек и frameworks

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

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

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

Оператор автоматически внедряет 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:

• OTEL_JAVAAGENT_EXTENSIONS - Путь к дополнительным расширениям agent
• 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 с несколькими контейнерами укажите, какие контейнеры должны быть instrumented:

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 экспортера указан правильно и доступен из pod приложения.

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

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

Полный пример instrumenting для 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

#Связывание логов приложения с traces

После внедрения Java agent он также может добавлять активные trace_id и span_id в логи вашего приложения, позволяя переходить от строки лога к соответствующему trace. Примеры для Spring Boot, Logback и Log4j 2 см. в разделе Связывание логов приложения с traces.

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

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

Документация по Java Auto-instrumentation