오픈텔레메트리 JavaAgent 설정 및 Zipkin Exporter 하기 (OpenTelemetry - JavaAgent - Collector - Zipkin)

스프링 부트 MVC 프로젝트 만들기

개발 환경은 Intellij이다. 일단 IntelliJ로 프로젝트를 빠르게 구성해보자. 최근에는 거의 코틀린을 사용하기 때문에 코틀린으로 진행해보겠다. 프로젝트 생성은 Spring Boot로 하자.

 
Spring Web과 Spring Data JPA 디펜던시만 추가한다.

 
Data JPA를 설정했으면 JdbcDriver 설정 등이  필요하다. H2 데이터베이스를 디펜던시를 추가해준다.

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    implementation("com.h2database:h2:2.3.232") // H2 데이터베이스 추가
    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit5")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

 

샘플 코드 작성하기

적절한 패키지에 리파지토리 코드를 작성한다.

import jakarta.persistence.*

@Entity
@Table(name ="message")
data class MessageEntity(
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long? = null,
    val message: String
)

@Repository
interface MessageRepository: CrudRepository<MessageEntity, Long>

 
서비스 코드도 작성한다.

data class MessageRequest(val message: String)

data class MessageResponse(val greetingMessage: String)

@Service
class MessageService(
    val messageRepository: MessageRepository
) {
    @Transactional
    fun greeting(
        messageRequest: MessageRequest
    ): MessageResponse {
        val greeting = "Hello World! ${messageRequest.message}"

        messageRepository.save(MessageEntity(message = messageRequest.message))

        return MessageResponse(greeting)
    }
}

 
컨트롤러 코드는 간단히 어플리케이션 코드쪽에 작성해보았다.

@RestController
@SpringBootApplication
class TracingDemoApplication(
    val messageService: MessageService
) {
    @PostMapping("/message")
    fun message(@RequestBody messageRequest: MessageRequest): MessageResponse =
        messageService.greeting(messageRequest)
}

 
코드를 실행한 후 CURL을 호출해보면 다음과 같은 결과를 얻을 수 있다. POST 전송으로 메시지를 보내면 인사말을 붙여서 리턴하는 간단한 코드이다.

curl --location 'http://localhost:8080/message' \
--header 'Content-Type: application/json' \
--data '{ "message" : "James" }'
{"greetingMessage":"Hello World! James"}

 

Zipkin 설정하기

기존과 같이 docker를 활용해 최신 이미지의 도커를 로컬에서 실행해본다.

docker pull openzipkin/zipkin
docker run -p 9411:9411 openzipkin/zipkin

 

 

OpenTelemetry Collector 설정 하기

Opentelemetry collector를 설치해보자. 이번에도 docker를 활용한다.

docker pull otel/opentelemetry-collector-contrib

 
다음으로 opentelemetry 설정 파일을 작성한다. 파일명은 otel-config.yml로 작성해보자. yml 파일 작성시 유의사항은 exporters.zipkin.endpoint의 URL을 본인 노트북이나 PC의 로컬IP로 설정해야된다. localhost나 127.0.0.1은 안된다. 그 이유는 별도의 이미지들을 띄웠기 때문에 collector에서 로컬호스트를 찾으면 해당 로컬에는 9411포트가 없어서 집킨이 구동되지 않은 것 처럼 인식한다. 

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  zipkin:
    endpoint: "http://xxx.xxx.xxx.xxx:9411/api/v2/spans"

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [zipkin]

 
그리고 collector를 구동해보자. docker명령에 익숙하지 않는 분들에게 간단히 설명하자면, collector 이미지가 구동될 때 config.yaml을 우리가 작성한 otel-config.yml로 오버라이드해서 구동시키는 커맨드이다. otel-config.yml의 패스를 정확히 넣어야 한다. 

docker run -p 4318:4318 -v /Users/projects/demo/otel-config.yml:/etc/otelcol-contrib/config.yaml otel/opentelemetry-collector-contrib

 

OpenTelemetry Agent 설정 하기

JavaAgent를 먼저 다운로드를 받아보자. 일단 최신으로 받도록 하자.
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases

Releases · open-telemetry/opentelemetry-java-instrumentation

파일명은 opentelemetry-javaagent.jar이다.
 
스프링 부트 프로젝트 Run Configuration 설정에 2가지 환경 변수를 추가하자. JAVA_TOOL_OPTIONS는 -javagent:{opentelemetry-javaagent.jar의 패스}로 설정하고 OTEL_SERVICE_NAME은 식별될 서비스명을 작성하자.

 
스프링 부트 시작시에 에이전트 설정이 됨을 확인할 수 있다.

Picked up JAVA_TOOL_OPTIONS: -javaagent:/Users/sonjeong-ug/kakao/projects/tracing-demo/opentelemetry-javaagent.jar
[otel.javaagent 2025-03-21 11:28:55:808 +0900] [main] INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 2.13.3

 

최종 확인

다시 CURL을 요청하면 zipkin에 트레이싱이 수행됨을 확인할 수 있다.

curl --location 'http://localhost:8080/message' \
--header 'Content-Type: application/json' \
--data '{ "message" : "James" }'
{"greetingMessage":"Hello World! James"}