Java

공식 OpenTelemetry Java 에이전트를 사용해 별도의 Sophonz 패키지 없이 모든 Java 서버에서 트레이스, 메트릭, 로그를 Sophonz로 전송하세요.

@sophonz/java-sdk는 존재하지 않으며, 필요하지도 않습니다. Sophonz 컬렉터는 표준 OTLP를 사용하므로, 모든 Java 서비스는 공식 OpenTelemetry Java 에이전트 — 플래그 하나로 붙이는 JVM 에이전트 — 를 통해 트레이스, 메트릭, 로그를 전송할 수 있습니다. 설정은 전부 환경 변수로 이뤄집니다.

제공되는 것

  • 100개 이상의 라이브러리와 프레임워크에 대한 코드 변경 없는 계측 — Spring, 서블릿 컨테이너, JDBC, Kafka, gRPC, 주요 HTTP 클라이언트, Reactor 등 — OpenTelemetry Java 에이전트에 내장된 계측 모듈을 통해 제공됩니다.
  • 트레이스, 메트릭, 로그가 OTLP로 전송되며, 모두 동일한 OTEL_* 환경 변수로 제어됩니다 — 애플리케이션 코드 변경이 필요 없습니다.
  • 공식 OpenTelemetry API — 커스텀 스팬을 추가하고 싶다면 io.opentelemetry:opentelemetry-api를 가져와 사용하면, 에이전트가 수동으로 만든 스팬을 동일한 트레이스에 이어 붙여줍니다.

동작 방식

  1. OpenTelemetry 프로젝트가 배포하는 단일 JVM 에이전트인 opentelemetry-javaagent.jar를 다운로드합니다.
  2. -javaagent: 플래그(또는 JAVA_TOOL_OPTIONS)로 JVM에 붙입니다.
  3. 환경 변수로 Sophonz를 가리킵니다 — 컬렉터 엔드포인트, 프로토콜, API 키.

에이전트는 클래스 로드 시점에 바이트코드를 계측하므로, 지원되는 프레임워크는 자동으로 트레이싱됩니다 — 수동 스팬 생성이나 SDK 초기화 코드가 필요 없습니다.

CAUTION — 유효한 service.key가 없으면 텔레메트리는 조용히 버려집니다

Sophonz 컬렉터는 강제 모드(enforce mode)로 동작합니다. 즉, OTLP 페이로드는 네트워크상으로 정상 수신되더라도 해석 가능한 service.key 리소스 속성이 없으면 조용히 폐기됩니다. 애플리케이션에 오류가 발생하지도, 요청이 거부되지도 않습니다 — 그저 콘솔이 비어 있을 뿐입니다. 다른 문제라고 넘겨짚기 전에 OTEL_RESOURCE_ATTRIBUTES(그리고 OTEL_EXPORTER_OTLP_HEADERS)부터 다시 확인하세요.

TIP — 다음 단계

정확한 다운로드 명령, 환경 변수 표, 프레임워크별 참고 사항은 설치 문서를 확인하세요.