Java

Cocktail APM은 OpenTelemetry Java Instrumentation 1.33.5 버전의 에이전트를 기준으로 동작합니다.

에이전트 준비

OpenTelemetry Java Agent는 코드를 변경하지 않고도 추적 및 메트릭과 같은 원격 측정 데이터를 수집하기 위해 Java 애플리케이션을 자동으로 계측하는 도구입니다.

칵테일에서는 에이전트 이미지가 Harbor 에 제공됩니다. 로컬 Harbor 주소가 local.harbor.io의 경우 다음과 같은 이미지가 제공됩니다.

local.harbor.io/ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:1.33.5

Cocktail APM은 1.33.5 버전을 기준으로 동작합니다. 다른 버전의 에이전트를 직접 사용하는 경우 특정 메트릭이 수집되지 않을 수 있습니다.

이미지 빌드

다음과 같은 스크립트를 추가하여 애플리케이션 이미지에 에이전트를 삽입할 수 있습니다.

Java Agent는 최소 Java 8 이상에서 동작합니다.

• Executable Java

# 에이전트 이미지를 복사할 이미지
FROM local.harbor.io/ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:1.33.5 AS agent

# 빌드 작업을 위한 이미지 (예시)
FROM maven:3.8.6-openjdk-8 AS build
# TODO Build script RUN
# Build to app.jar

# 애플리케이션 기본 이미지 (예시)
FROM openjdk:8-jre-slim
COPY --from=build /build/target/*.jar /app.jar
# -- 에이전트 이미지에서 에이전트 파일을 복사합니다. 
COPY --from=agent /javaagent.jar /opentelemetry-javaagent.jar

# 기본 환경 변수 설정 (고정값)
ENV OTEL_EXPORTER_OTLP_ENDPOINT=http://cocktail-telemetry-collector.cocktail-addon:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_METRICS_EXPORTER=otlp \
OTEL_TRACES_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=none \
JAVA_TOOL_OPTIONS=-javaagent:/opentelemetry-javaagent.jar

# 일반 Java 실행 파일의 경우 예시
ENTRYPOINT ["java", "-jar", "/app.jar"]

• War + Tomcat

# 에이전트 이미지를 복사할 이미지
FROM local.harbor.io/ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:1.33.5 AS agent

# Tomcat 이미지 (예시에서는 9.0 버전 사용)
FROM tomcat:9.0.20-jre8-alpine

RUN rm -rf $CATALINA_BASE/webapps/ROOT
COPY --from=download /home/curl_user/sample.war $CATALINA_BASE/webapps/ROOT.war
COPY --from=agent /javaagent.jar /opentelemetry-javaagent.jar
RUN ls -al $CATALINA_BASE/webapps/

# 기본 환경 변수 설정 (고정값)
ENV OTEL_EXPORTER_OTLP_ENDPOINT=http://cocktail-telemetry-collector.cocktail-addon:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_METRICS_EXPORTER=otlp \
OTEL_TRACES_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=none \
JAVA_TOOL_OPTIONS=-javaagent:/opentelemetry-javaagent.jar

EXPOSE 8080
CMD ["catalina.sh", "run"]

기본 설정 가능한 환경 변수는 다음과 같은 의미를 가집니다.

• OTEL_LOGS_EXPORTER : 로그를 수집하는 collector에 전달하는 프로토콜을 정의합니다.

  • otlp : OpenTelemetry Protocol을 사용하여 Collector에 정보를 전달합니다.

  • none: 사용하지 않습니다.

• OTEL_METRICS_EXPORTER : 메트릭을 수집하는 collector에 전달하는 프로토콜을 정의합니다.

  • otlp : OpenTelemetry Protocol을 사용하여 Collector에 정보를 전달합니다.

  • none: 사용하지 않습니다.

• OTEL_TRACES_EXPORTER : 트레이스(추적)를 수집하는 collector에 전달하는 프로토콜을 정의합니다.

  • otlp : OpenTelemetry Protocol을 사용하여 Collector에 정보를 전달합니다.

  • none: 사용하지 않습니다.

• OTEL_EXPORTER_OTLP_ENDPOINT : 수집 Collector 접속 주소를 입력 합니다. 칵테일에서는 고정값입니다.

• OTEL_EXPORTER_OTLP_PROTOCOL : OpenTelemetry Collector에서 전달 받을 프토토콜 종류 선택

  • http/protobuf : 기본값으로 칵테일에서는 이 값을 사용합니다.

• JAVA_TOOL_OPTIONS : 에이전트를 동작 시키기 위한 설정입니다.

워크로드 환경 변수 설정

이미지를 쿠버네티스에서 동작 시킬때 환경 변수를 추가하여, 수집 정보에 필요한 정보를 추가해 주어야 합니다. 필수로 애플리케이션 이름이 필요합니다.

환경 변수 이름	설명	기본값
OTEL_SERVICE_NAME	어플리케이션 고유 이름	필수값 (고유 ID)
OTEL_METRICS_EXPORTER	메트릭 전송 프로토콜 선택	수집 하지 않을 경우 none 입력
OTEL_TRACES_EXPORTER	추적 전송 프로토콜 선택	수집 하지 않을 경우 none 입력

워크로드 시작시 에이전트 동작 확인

로그에 다음과 같은 시작 로그가 기록 되는지 확인합니다.

[otel.javaagent 2024-10-21 02:10:15:820 +0000] [main] INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 1.33.5