설치

공식 OpenTelemetry Java 에이전트를 JVM에 붙이고 환경 변수로 설정하여 트레이스, 메트릭, 로그를 Sophonz로 전송하세요.

이 문서는 Sophonz 패키지가 아니라 업스트림 OpenTelemetry Java 에이전트를 설치합니다. 에이전트는 시작 시점에 JVM을 자동으로 계측하며, 환경 변수는 텔레메트리를 어디로 보낼지와 자신을 어떻게 식별할지를 알려줍니다.

빠른 시작

아래에서 수집기 URL, 프로젝트, 앱, 버전, 앱 키를 입력하고 탭(Env vars · System properties)을 선택하면 그 값으로 스니펫이 생성됩니다. 고급 옵션은 "고급 옵션" 토글 뒤에 있습니다.

# shell — JVM을 시작하기 전에 설정합니다 (.env 파일, Docker ENV, systemd Environment=)
OTEL_SERVICE_NAME=next-sample
OTEL_EXPORTER_OTLP_ENDPOINT=https://in.sophonz.ai
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=authorization=sk_tYtJUa4WweXXedj6lxjSqoPW5O0DnbXz
OTEL_RESOURCE_ATTRIBUTES=service.key=sk_tYtJUa4WweXXedj6lxjSqoPW5O0DnbXz,service.namespace=sophonz,service.version=1.0.0,deployment.environment.name=production
OTEL_LOGS_EXPORTER=otlp

export JAVA_TOOL_OPTIONS="-javaagent:/path/to/opentelemetry-javaagent.jar"
java -jar your-app.jar

사전 요구 사항

  • Java 8 이상.
  • Sophonz 콘솔에 등록한 서비스와 그 서비스에 발급된 sk_... API 키.

에이전트 다운로드

curl -L -o opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

이 jar 파일을 이미지나 빌드 산출물에 포함하세요 — 빌드에 설치할 것은 없고, JVM 시작 시 붙이는 독립 실행 파일입니다.

TIP — API 키 발급

Sophonz 콘솔에 로그인해 서비스를 등록하고 발급된 sk_... 키를 복사하세요. 이 키는 테넌트 신원을 나타냅니다 — 아래 service.key 참고.

에이전트 붙이기

-javaagent로 jar를 추가하거나, 기존 실행 명령을 건드리지 않도록 JAVA_TOOL_OPTIONS를 설정하세요.

export JAVA_TOOL_OPTIONS="-javaagent:/path/to/opentelemetry-javaagent.jar"
java -jar your-app.jar

Dockerfile에서는 다음과 같이 작성합니다.

COPY opentelemetry-javaagent.jar /app/opentelemetry-javaagent.jar
ENV JAVA_TOOL_OPTIONS="-javaagent:/app/opentelemetry-javaagent.jar"

환경 변수 구성

OTEL_SERVICE_NAME=my-java-service
OTEL_EXPORTER_OTLP_ENDPOINT=https://in.sophonz.ai
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=authorization=sk_your_api_key
OTEL_RESOURCE_ATTRIBUTES=service.key=sk_your_api_key,service.namespace=my-project,deployment.environment.name=production
OTEL_LOGS_EXPORTER=otlp
변수값설명
OTEL_SERVICE_NAME서비스 이름콘솔에 등록한 서비스 이름과 반드시 일치해야 합니다 — 포털은 (project, service.name) 조합으로 텔레메트리를 등록된 서비스에 연결합니다. 이름이 다르면 데이터는 수신되지만 서비스 페이지는 비어 있습니다.
OTEL_EXPORTER_OTLP_ENDPOINThttps://in.sophonz.ai기본 OTLP 엔드포인트. 에이전트가 여기서 /v1/traces, /v1/logs, /v1/metrics 경로를 파생시킵니다.
OTEL_EXPORTER_OTLP_PROTOCOLhttp/protobufHTTP를 통한 OTLP 전송. (Java 에이전트 2.x는 이미 http/protobuf를 기본값으로 사용하지만, 에이전트 버전에 의존하지 않도록 명시적으로 설정하세요.)
OTEL_EXPORTER_OTLP_HEADERSauthorization=sk_your_api_key모든 전송 요청에 HTTP 헤더로 포함됩니다.
OTEL_RESOURCE_ATTRIBUTESservice.key=sk_your_api_key,service.namespace=...,deployment.environment.name=...service.key는 컬렉터가 검사하는 테넌트 신원으로 필수입니다. service.namespace는 서비스들을 프로젝트로 묶고, deployment.environment.name은 환경(production, staging 등)을 표시합니다.
OTEL_LOGS_EXPORTERotlp트레이스, 메트릭과 함께 OTLP 로그 전송을 활성화합니다.

CAUTION — service.key는 필수입니다

컬렉터는 강제 모드로 동작합니다. 해석 가능한 service.key 리소스 속성이 없는 텔레메트리는 조용히 폐기됩니다. 애플리케이션은 계속 실행되고 예외도 발생하지 않지만, Sophonz에는 아무것도 나타나지 않습니다. 항상 OTEL_RESOURCE_ATTRIBUTES로 service.key를 설정하고, OTEL_EXPORTER_OTLP_HEADERS를 통해 같은 키를 authorization 헤더로도 전송하세요.

프레임워크 참고 사항

에이전트는 클래스 로드 시점에 지원 프레임워크를 자동으로 계측합니다 — 위의 환경 변수 외에 프레임워크별로 추가할 설정은 없습니다.

  • Spring Boot — HTTP 엔드포인트, RestTemplate/WebClient, JDBC, 예약 작업이 기본적으로 트레이싱됩니다. OTEL_SERVICE_NAME이 보고되는 서비스 이름에서 spring.application.name을 대체합니다.
  • 서블릿 컨테이너 (Tomcat, Jetty, Undertow) — web.xml이나 필터 체인을 건드리지 않고도 들어오는 요청이 트레이싱됩니다.
  • JDBC 드라이버 — DataSource를 감싸지 않아도 쿼리 스팬이 자동으로 생성됩니다.

NOTE — 대안: 시스템 프로퍼티

모든 OTEL_* 환경 변수는 대응하는 -Dotel.* JVM 시스템 프로퍼티를 가지고 있습니다(예: -Dotel.service.name=my-java-service). 컨테이너와 CI 환경에서는 환경 변수 쪽이 관리하기 쉬워 이 문서는 환경 변수를 사용하지만, 둘 다 동일하게 동작합니다.

확인

환경 변수를 설정한 뒤 앱을 실행하고 표준 출력을 확인하세요 — 에이전트가 시작 시 로그 한 줄을 남깁니다.

OTEL_SERVICE_NAME=my-java-service \
OTEL_EXPORTER_OTLP_ENDPOINT=https://in.sophonz.ai \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_HEADERS=authorization=sk_your_api_key \
OTEL_RESOURCE_ATTRIBUTES=service.key=sk_your_api_key,service.namespace=my-project,deployment.environment.name=production \
java -javaagent:opentelemetry-javaagent.jar -jar your-app.jar
[otel.javaagent ...] INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 2.x.x

이 로그는 에이전트가 정상적으로 붙었다는 것만 확인해 줄 뿐, 텔레메트리가 실제로 Sophonz까지 도달했는지는 알려주지 않습니다. service.key가 잘못되었거나 없으면 위 캐우션처럼 조용히 실패하기 때문입니다. 트래픽을 조금 발생시킨 뒤 Sophonz 콘솔에서 등록한 서비스를 확인하세요.

NOTE — 디버그 로깅

OTEL_JAVAAGENT_DEBUG=true를 설정하면 컬렉터로부터의 HTTP 응답 코드를 포함해 모든 전송 시도를 로깅합니다 — 트래픽이 보이지 않을 때 요청이 실제로 JVM을 벗어나고 있는지 확인하는 데 유용합니다.

TIP — 이제 시작입니다

이제 앱을 배포하세요. Sophonz가 실사용자가 겪는 문제를 포착하고, 당신의 앱은 스스로 진화합니다.