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

При использовании инструментирования OpenTelemetry вы можете столкнуться с двумя основными типами проблем: проблемы с внедрением инструментирования в рабочие нагрузки и проблемы с генерацией телеметрических данных библиотеками инструментирования. В этом документе приведены методы устранения неполадок для обоих типов проблем.

#Overview

Устранение неполадок с инструментированием в первую очередь сосредоточено на следующих аспектах:

• Проблемы внедрения: успешно ли инструментирование внедряется в поды приложений
• Проблемы генерации данных: корректно ли библиотеки инструментирования генерируют и отправляют телеметрию

#Устранение неполадок с внедрением инструментирования в вашу рабочую нагрузку

Если инструментирование не внедряется корректно в рабочие нагрузки, выполните следующие проверки для диагностики проблемы.

#Проверка объекта Instrumentation

Сначала убедитесь, что объект Instrumentation был успешно создан:

kubectl get instrumentation -n <workload_namespace>

Если вы не видите ожидаемый объект Instrumentation, проверьте:

1. Был ли ресурс Instrumentation создан корректно
2. Правильность указанного namespace
3. Наличие сообщений об ошибках в логах Operator

#Проверка init-контейнера

Убедитесь, что init-контейнер opentelemetry-auto-instrumentation успешно запустился:

kubectl get events -n <workload_namespace>

Просмотрите подробную информацию о поде:

kubectl describe pod <pod_name> -n <workload_namespace>

В выводе найдите раздел init-контейнера и подтвердите:

• Существует ли init-контейнер
• Завершился ли init-контейнер успешно
• Есть ли ошибки или предупреждения

#Проверка порядка развертывания ресурсов

Убедитесь, что ресурсы развернуты в правильном порядке:

1. Сначала разверните объект Instrumentation
2. Затем разверните или перезапустите поды приложения

Если поды приложения были созданы до объекта Instrumentation, инструментирование не будет внедрено. Необходимо перезапустить поды:

kubectl rollout restart deployment <deployment_name> -n <workload_namespace>

#Поиск ошибок в логах Operator

Проверьте логи Operator на наличие ошибок, связанных с инструментированием:

kubectl logs -l app.kubernetes.io/name=opentelemetry-operator -n opentelemetry-operator2 --tail=100

Распространённые ошибки включают:

• Ошибки валидации конфигурации
• Недостаточные права доступа
• Конфликты ресурсов

#Проверка аннотаций подов

Убедитесь, что у подов приложения есть правильные аннотации для инструментирования:

kubectl get pod <pod_name> -n <workload_namespace> -o jsonpath='{.metadata.annotations}' | jq

Вы должны увидеть аннотации, похожие на следующие:

{
  ...
  "instrumentation.opentelemetry.io/inject-java": "true"
  ...
}

Если аннотации отсутствуют или некорректны:

1. Проверьте конфигурацию аннотаций в Deployment или шаблоне Pod
2. Убедитесь, что namespace аннотаций и тип языка указаны правильно
3. Проверьте конфигурацию объекта Instrumentation

#Проверка внедрённых переменных окружения

Убедитесь, что инструментирование корректно внедрило переменные окружения:

kubectl exec <pod_name> -n <workload_namespace> -- env | grep OTEL

Вы должны увидеть переменные окружения, связанные с OpenTelemetry, например:

OTEL_SERVICE_NAME=my-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_RESOURCE_ATTRIBUTES=service.name=my-service

#Проверка библиотек инструментирования

Проверьте, были ли библиотеки инструментирования корректно установлены в контейнере:

kubectl exec <pod_name> -n <workload_namespace> -- sh -c 'ls -lh /otel-auto-instrumentation-*'

В этой директории должны находиться библиотеки инструментирования и связанные файлы.

#Устранение неполадок с генерацией телеметрических данных библиотеками инструментирования

Если инструментирование было успешно внедрено, но не генерирует телеметрию, воспользуйтесь следующими методами для диагностики.

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

Убедитесь, что инструментирование отправляет данные на правильный endpoint:

kubectl get instrumentation <instrumentation_name> -n <workload_namespace> -o jsonpath='{.spec.exporter.endpoint}'

Пример вывода

http://otel-collector:4317

kubectl get instrumentation <instrumentation_name> -n <workload_namespace> -o yaml | grep -A 1 'OTEL_'

По умолчанию endpoint — http://localhost:4317. Если вы используете кастомный endpoint Collector, убедитесь, что:

1. Адрес endpoint указан правильно
2. Сервис Collector доступен
3. Конфигурация портов корректна (gRPC использует 4317, HTTP — 4318)

#Проверка логов приложения на наличие ошибок

Проверьте логи приложения на наличие ошибок, связанных с инструментированием:

kubectl logs <application_pod> -n <workload_namespace>

Ищите ошибки, связанные с OpenTelemetry, такие как:

• Ошибки подключения
• Ошибки аутентификации
• Ошибки конфигурации
• Ошибки загрузки библиотек

#Проверка получения данных Collector-ом

Убедитесь, что Collector получает телеметрические данные:

Проверка логов Collector-а

kubectl logs <collector_pod> -n opentelemetry-collector

Если Debug Exporter включён, вы должны видеть получаемые данные.

Проверка метрик Collector-а

kubectl port-forward -n opentelemetry-collector <collector_pod> 8888:8888

Затем откройте http://localhost:8888/metrics и проверьте:

• otelcol_receiver_accepted_spans: должно быть больше 0
• otelcol_receiver_refused_spans: должно быть 0 или очень мало