OpenTelemetry Java Instrumentation

개요

OpenTelemetry Java Instrumentation(이하 opentelemetry-javaagent)는 WAS(Wildfly, Tomcat) 리소스의 모니터링을 위해 사용됩니다. WAS 리소스를 모니터링하려면 Java Agent 설정을 추가하여, WAS 리소스 실행 시 자동으로 작동하도록 설정해야 합니다.

Java Agent 설정 추가 방법에 대한 자세한 설명은 웹 애플리케이션 서버의 Java Agent 설정(Wildfly, Tomcat)을 참고합니다.

실행

opentelemetry-javaagent를 실행하기 위해서는 JVM 옵션 설정이 필요합니다.

다음은 설정 가능한 옵션들에 대한 예시입니다.

-javaagent:/agent-home/opentelemetry-javaagent.jar
-Dotel.resource.attributes=service.name=myBusiness,service.instance.id=myInstance,provider.type=was -Dotel.javaagent.debug=false -Dotel.exporter.otlp.endpoint=http://localhost:4317 -Dotel.exporter.otlp.metrics.temporality.preference=DELTA -Dotel.metric.export.interval=10000 -Dotel.instrumentation.methods.tmax.include=/agent-home/extend-bci.json -Dio.opentelemetry.javaagent.slf4j.simpleLogger.logFile=/agent-home/agent.log
옵션 설명

javaagent (필수)

로드할 에이전트 파일(opentelemetry-javaagent.jar)의 경로입니다.

otel.resource.attributes (필수)

데이터를 수집하는 opentelemetry-javaagent의 리소스 관련 변수입니다.

  • service.name: 업무 이름

  • service.instance.id: 인스턴스(또는 호스트) 이름

  • provider.type: 모니터링 대상 엔진의 종류 (예: tomcat, nginx, apache, vm 등)

otel.javaagent.debug

디버깅 허용 여부입니다.

  • true

  • false

io.opentelemetry.javaagent.slf4j.simpleLogger.logFile (필수)

opentelemetry-javaagent 로그 파일의 경로입니다.

otel.exporter.otlp.endpoint (필수)

opentelemetry-javaagent로 수집한 데이터들을 모니터링 마스터로 보내기 위해 사용할 otelcol의 주소입니다.

otel.exporter.otlp.metrics.temporality.preference

기본 출력 집계 시간 옵션입니다. (현재 'DELTA’로 고정)

otel.metric.export.interval (필수)

메트릭 전송 주기입니다. (단위: ms, 기본값: 60000, 권장값: 10000)

otel.bsp.schedule.delay

트레이스 전송 주기입니다. (단위: ms, 기본값: 5000)

otel.instrumentation.methods.tmax.include

Extend BCI에 필요한 설정 파일의 경로입니다.

모니터링에서 기본적으로 수집하고 있는 데이터 외에 추가로 BCI를 이용하여 수집하는 데이터가 있을 경우에 설정합니다.

[참고] Extend BCI 설정 파일의 작성 방법에 대한 자세한 설명은 Extend BCI 설정 파일을 참고합니다.

Extend BCI 설정 파일

Extend BCI 설정 파일은 다음과 같은 규칙에 따라 작성합니다.

  • 설정 파일은 항상 JSON 형식으로 작성

  • 'clazz’는 클래스의 패키지명을 포함한 클래스명을 작성

  • 'methodName’은 수집하고자 하는 메소드명을 작성

  • 'methodSignature’는 'methodName’에 작성한 메소드의 시그니처를 작성

  • 반환값의 키는 무조건 rtn으로 고정 (변경 불가능)

  • 현재 call은 항상 toString으로 고정

Extend BCI 설정 파일 작성 시 다음 사항에 유의합니다.

  1. 소괄호를 반드시 포함

  2. 띄어쓰기 미포함

  3. 클래스 전체를 작성

  4. 메소드의 시그니처와 동일하게 순서로 작성

  5. 2개 이상일 경우에는 반드시 ,를 사용

다음은 Java 코드와 Extend BCI 설정 파일의 예시입니다.

  • Java 코드

    package com.tmax.monitoring.example;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Servicepublic
class SampleService {
	@Autowired
	private SampleRepository repository;

	public String sampleGet(String hello, int i) {
		String s =  "helloService" + hello + String.valueOf(i);
		repository.findAll();
		return s;
	}

	public String sampleInsert() {
	        return "insert";
	}
}

  • Extend BCI 설정 파일

    {
  "required": true,
  "target": [
    {
      "clazz": "com.tmax.monitoring.example.SampleService",
      "methods": [
        {
          "methodName": "sampleGet",
          "methodSignature": "(java.lang.String,int)",
          "params": [
            {
              "key": "string.hello",
              "call": "toString",
              "required": true
            },
            {
              "key": "int.hello",
              "call": "toString",
              "required": true
            }
          ],
          "rtn": {
            "key": "rtn"
          }
        }
      ]
    }
  ]
}