OTel 트랜잭션

애플리케이션이 이미 OpenTelemetry 또는 Micrometer 트레이싱 어노테이션을 사용하고 있다면 jvmguard는 추가 구성 없이 이를 트랜잭션으로 전환할 수 있습니다. “OTel” 트랜잭션 타입은 다음을 매핑합니다:

• 메서드의 io.opentelemetry.instrumentation.annotations.WithSpan
• 메서드 및 클래스의 io.micrometer.observation.annotation.Observed

두 어노테이션 모두 OpenTelemetry 또는 Micrometer를 사용하는 애플리케이션에 트레이싱 백엔드가 연결되어 있지 않더라도 이미 존재하는 경우가 많습니다. @WithSpan은 OpenTelemetry 에이전트나 Spring 스타터가 있어야만 동작하고 @Observed는 클래스패스에 Micrometer AOP가 있어야만 동작하기 때문입니다. jvmguard는 어노테이션을 이름으로만 일치시키므로 어노테이션이 기능하지 않아도 되며, 사용되지 않을 때 오버헤드도 없습니다.

트랜잭션 기록 설정의 “OTel” 탭에는 미리 구성된 OTel 트랜잭션 정의가 있습니다. 다른 트랜잭션 정의와 마찬가지로 편집, 순서 변경, 버리기 또는 삭제가 가능합니다. 삭제하면 다시 생성되지 않습니다.

명명

기본적으로 트랜잭션은 어노테이션의 스팬 이름 속성(@WithSpan은 value, @Observed는 contextualName)으로 이름이 지정됩니다. 속성이 비어 있으면 트랜잭션 이름은 ClassName.methodName이 되며, 이는 OpenTelemetry 자체의 기본 스팬 이름이기도 합니다. “명명” 탭에서 다른 트랜잭션 정의와 마찬가지로 명명을 변경할 수 있습니다.

스팬 이름으로 필터링

OTel 트랜잭션 정의의 “필터” 탭에는 클래스 필터 외에 “스팬 이름” 필드가 있습니다. 스팬 이름이 구성된 와일드카드 또는 정규식과 일치하는 어노테이션만 트랜잭션을 생성합니다. 스팬 이름 속성이 없는 어노테이션은 스팬 이름 필터와 절대 일치하지 않습니다.

다른 트랜잭션 타입과의 중복

메서드는 지원되는 어노테이션을 여러 개 가질 수 있습니다. 중복 트랜잭션을 방지하기 위해 다음 규칙이 적용됩니다:

• 메서드에 @MethodTransaction 어노테이션이 있으면 선언적 트랜잭션만 생성됩니다.
• 메서드에 @WithSpan과 @Observed가 모두 있으면(메서드 자체 또는 외부 클래스의 클래스 수준 @Observed를 통해) @WithSpan 트랜잭션만 생성됩니다.
• 메서드에 직접 붙은 어노테이션은 외부 클래스의 클래스 수준 @Observed보다 우선합니다.

OTel 로그 레코드로 전송되는 캡처 이벤트

캡처(힙 덤프, 스레드 덤프, JFR 스냅샷, JProfiler 기록)가 수행되면 에이전트는 모니터링되는 애플리케이션의 OpenTelemetry SDK 로그 브리지를 통해 OTel 로그 레코드를 내므로, 캡처가 기존 OTel 파이프라인에서 트레이스와 함께 표시됩니다. 이는 트리거 액션으로 실행된 캡처와 UI 또는 REST API에서 수동으로 수행한 캡처 모두에 적용됩니다.

에이전트는 OpenTelemetry API를 리플렉션으로 호출하므로 별도의 설정이 필요하지 않습니다. 애플리케이션의 클래스 패스에 OpenTelemetry API가 없으면 아무것도 보내지 않고 에이전트 로그에 한 줄만 기록됩니다.

로그 레코드의 심각도는 트리거를 실행한 정책 이벤트에서 결정됩니다: 오류 이벤트는 ERROR, 매우 느림 및 기한 초과 이벤트는 WARN, 그 외(수동 캡처 포함)는 INFO입니다. 로그 레코드에는 다음 속성이 포함됩니다:

• jvmguard.capture.type: heap_dump, thread_dump, jfr_snapshot 또는 jprofiler_recording
• jvmguard.capture.origin: trigger 또는 manual
• jvmguard.vm.name: 모니터링되는 VM의 이름
• jvmguard.trigger: 캡처를 실행한 트리거의 설명
• jvmguard.transaction.name: 트리거 실행에 가장 최근에 기여한 정책 이벤트의 트랜잭션
• jvmguard.policy.event: 해당 트랜잭션의 정책 이벤트 타입(예: SLOW 또는 VERY_SLOW)

마지막 두 속성은 정책 트리거로 실행된 캡처에만 존재합니다. 트리거는 실행되기까지 여러 트랜잭션의 이벤트를 누적할 수 있으므로, 이 속성들은 가장 많이 기여한 트랜잭션이 아니라 가장 최근에 이벤트를 추가한 트랜잭션을 나타냅니다.

전송을 끄려면 트리거 기록 설정에서 “캡처 이벤트를 OTel 로그 레코드로 전송” 확인란의 선택을 해제합니다. 이 확인란은 루트 그룹에만 표시되며 전체 플릿에 적용됩니다. 트리거는 그룹 계층에서 추가적으로 적용되므로 그룹별 스위치로는 전송 범위를 확실히 지정할 수 없습니다.