Monithub Blog
Posts Tags Categories
Monithub Blog

목차

OpenTelemetry Java Agent 설정 파일 설명서

 분류: SRE
   2176 단어   읽는데 약 5분 

OpenTelemetry Java Agent 설정 파일 설명서

1. 개요

본 문서는 Java 애플리케이션(API Gateway 추정)에 부착되는 OpenTelemetry Java Agent(-javaagent)의 런타임 구성 설명서입니다.

이 설정은 표준(기본) 메트릭 이상의 깊이 있는 메트릭 데이터 확보에 초점이 맞춰져 있습니다. 대부분의 계측(Instrumentation) 옵션에서 실험적(Experimental) 기능과 확장 속성 캡처를 활성화하고 있으며, 특히 로그(Log)와 트레이스(Trace) 간의 컨텍스트 전파(MDC, Baggage) 및 HTTP 헤더/SQL 원문 캡처에 상세한 설정을 적용했습니다. 또한, SaaS 환경의 멀티테넌트 아키텍처를 지원하기 위한 식별자 주입이 포함되어 있습니다.

2. 구조

otel.logs.exporter=otlp
otel.traces.exporter=otlp
otel.metrics.exporter=otlp
otel.exporter.otlp.protocol=http/protobuf
otel.exporter.otlp.endpoint=http://otel.monitoring.mesimsaas.com
otel.exporter.otlp.headers=x-tenant-id=k6-52565
otel.service.name=API_GATEWAY_AGENT
otel.resource.attributes=tenant.id=k6-52565

# JMX
otel.semconv-stability.opt-in=http
otel.instrumentation.micrometer.base-time-unit=s
otel.instrumentation.common.mdc.resource-attributes = *
otel.instrumentation.log4j-appender.experimental-log-attributes=true
otel.instrumentation.log4j-appender.experimental.capture-map-message-attributes = true
otel.instrumentation.log4j-appender.experimental.capture-marker-attribute = true
otel.instrumentation.log4j-appender.experimental.capture-mdc-attributes = *
otel.instrumentation.log4j-context-data.add-baggage=true
otel.instrumentation.logback-mdc.add-baggage=true
otel.instrumentation.logback-appender.experimental-log-attributes=true
otel.instrumentation.logback-appender.experimental.capture-code-attributes=true
otel.instrumentation.logback-appender.experimental.capture-marker-attribute=true
otel.instrumentation.logback-appender.experimental.capture-key-value-pair-attributes=true
otel.instrumentation.logback-appender.experimental.capture-logger-context-attributes=true
otel.instrumentation.logback-appender.experimental.capture-arguments=true
otel.instrumentation.logback-appender.experimental.capture-mdc-attributes = *
otel.instrumentation.logback-mdc.add-baggage=true
otel.instrumentation.common.enduser.enabled=true
otel.instrumentation.common.enduser.role.enabled=true
otel.instrumentation.common.enduser.scope.enabled=true
otel.instrumentation.common.enduser.id.enabled=true
otel.instrumentation.http.client.emit-experimental-metrics=true
otel.instrumentation.http.server.emit-experimental-metrics=true
otel.instrumentation.camel.enabled=true
otel.instrumentation.common.db-statement-sanitizer.enabled=false
otel.instrumentation.camel.experimental-span-attributes=true
otel.instrumentation.netty.always-create-connect-span=true
otel.instrumentation.netty.ssl-telemetry.enabled=true
otel.instrumentation.http.client.emit-experimental-telemetry=true
otel.instrumentation.http.server.emit-experimental-telemetry=true
otel.instrumentation.spring-integration.producer.enabled=true
otel.instrumentation.spring-batch.item.enabled=true
otel.instrumentation.spring-batch.experimental.chunk.new-trace=true
otel.instrumentation.spring-batch.experimental-span-attributes=true
otel.instrumentation.spring-integration.producer.enabled=true
otel.instrumentation.spring-scheduling.experimental-span-attributes=true
otel.instrumentation.spring-webmvc.experimental-span-attributes=true
otel.instrumentation.http.server.capture-request-headers=content-length,content-encoding,transfer-encoding
otel.instrumentation.http.server.capture-response-headers=content-length,content-encoding,transfer-encoding
otel.instrumentation.http.client.capture-request-headers=content-length,content-encoding,transfer-encoding
otel.instrumentation.http.client.capture-response-headers=content-length,content-encoding,transfer-encoding
otel.instrumentation.http.client.capture-request-headers=true
otel.instrumentation.http.client.capture-response-headers=true
otel.instrumentation.http.server.capture-request-headers=true
otel.instrumentation.http.server.capture-response-headers=true
otel.instrumentation.servlet.enabled=true
otel.instrumentation.spring-web.enabled=true
otel.instrumentation.tomcat.enabled=true
otel.instrumentation.jdbc-datasource.enabled=true
otel.instrumentation.micrometer.enabled=true
otel.instrumentation.messaging.experimental.receive-telemetry.enabled=true
otel.instrumentation.jsp.experimental-span-attributes=true
otel.instrumentation.quartz.experimental-span-attributes=true
otel.instrumentation.reactor.experimental-span-attributes=true
otel.instrumentation.reactor-netty.connection-telemetry.enabled=true

설정은 크게 다음 네 가지 영역으로 분류됩니다.

  1. 전송 및 식별(Transport & Identity): OTLP/HTTP 프로토콜 설정 및 테넌트 식별자 헤더 주입.
  2. 로깅 및 컨텍스트(Logging & Context): Log4j/Logback 연동, MDC 전파, 코드 레벨 디버깅 정보 수집.
  3. HTTP 및 네트워크(HTTP & Network): 요청/응답 헤더 캡처 및 클라이언트/서버 상세 텔레메트리.
  4. 프레임워크 및 DB(Framework & DB): Spring Batch, Netty, DB 쿼리 원문 수집 등 라이브러리별 심층 계측.

3. 상세 설명

3.1. 전송 및 식별 (Transport & Identity)

  • otel.exporter.otlp.protocol: http/protobuf
    • gRPC가 아닌 HTTP 위의 Protobuf 바이너리 포맷을 사용합니다. 로드밸런서 친화적이며 80/443 포트 통신 환경에서 유리합니다. 로드밸런싱이 필요 없는 경우, gRPC 프로토콜로 변경하시면 됩니다.
  • otel.exporter.otlp.endpoint: http://otel.monitoring.mesimsaas.com
    • 수집 서버의 베이스 URL입니다. Java Agent는 이 경로 뒤에 자동으로 /v1/traces, /v1/metrics, /v1/logs를 붙여서 전송합니다.
  • otel.exporter.otlp.headers: x-tenant-id=k6-52565
    • 모든 OTLP 패킷 헤더에 테넌트 ID를 포함시켜 전송합니다. 수집 서버(Collector)나 백엔드에서 테넌트별 데이터 격리 및 라우팅을 수행하는 기준이 됩니다.
  • otel.service.name: API_GATEWAY_AGENT
    • 이 에이전트가 부착된 서비스의 논리적 식별자입니다.

3.2. 로깅 및 컨텍스트 전파 (Logging & Context Propagation)

이 섹션은 로그 데이터 품질 향상을 위해 매우 상세하게 구성되어 있습니다.

  • MDC 및 Baggage 연동 (*.add-baggage=true, *.capture-mdc-attributes=*)
    • 기능: 트레이스 컨텍스트(TraceID, SpanID)뿐만 아니라, 분산 트레이싱의 Baggage(전파되는 키-값 쌍)를 로깅 라이브러리(Log4j, Logback)의 MDC(Mapped Diagnostic Context)에 자동으로 주입합니다.
    • 효과: 로그만 봐도 해당 로그가 어떤 트랜잭션(Trace)에서 발생했는지, 상위 서비스에서 전달한 메타데이터가 무엇인지 즉시 파악 가능합니다.
      • * 설정은 모든 MDC 값을 Span 속성으로 캡처하겠다는 의미로, 오버헤드가 크지만 디버깅 가시성은 극대화됩니다.
      • 이 설정은 이 로그의 Thread, CodeNamespace, 라인 수 등 로그의 발생 위치 등을 포함합니다.
  • 실험적 로그 속성 (*.experimental-log-attributes=true, capture-map-message)
    • 단순 텍스트 로그 외에 구조화된 로그(Structured Logging)의 Map 메시지나 마커(Marker)까지 OpenTelemetry Log 레코드로 변환합니다.
  • 코드 레벨 속성 (capture-code-attributes=true)
    • 로그 발생 위치의 소스 파일명, 클래스명, 라인 번호를 수집합니다.
    • 주의: Java에서 라인 번호 추출은 스택 트레이스 연산을 유발하므로 성능 비용이 비쌉니다. 운영(Prod) 환경에서는 신중해야 할 설정입니다.

3.3. HTTP 및 네트워크 (HTTP & Network)

  • 헤더 캡처 (capture-*-headers)
    • 설정: content-length, content-encoding, transfer-encoding 및 전체 헤더(=true) 캡처가 설정 돼있습니다.
    • 의도: HTTP 요청/응답의 크기 및 인코딩 정보를 스팬 속성(http.request.header.*)으로 남겨, 페이로드 관련 문제나 압축 효율 등을 모니터링하려는 목적입니다.
  • 실험적 메트릭 (emit-experimental-metrics=true)
    • 기본적인 처리량/지연시간 외에, 커넥션 풀 상태나 상세 I/O 메트릭 등 아직 Stable 단계로 승격되지 않은 상세 지표를 생성합니다.
  • Netty 계측 (netty.always-create-connect-span=true)
    • Netty 클라이언트가 연결을 맺는 과정(Connection Establishment)을 별도의 스팬으로 생성합니다. TCP 연결 지연이나 DNS 해상도 문제를 분리하여 분석할 때 필수적입니다.

3.4. 데이터베이스 및 보안 (Database & Security)

  • otel.instrumentation.common.db-statement-sanitizer.enabled: false (중요)
    • 기능: SQL 쿼리문에서 파라미터 값(리터럴)을 마스킹하는 기능을 비활성화했습니다.
    • 상세: 기본값은 SELECT * FROM users WHERE id = ? 처럼 처리되지만, 이 설정으로 인해 SELECT * FROM users WHERE id = 'user123'과 같이 쿼리 원문이 그대로 수집됩니다.
    • 보안 경고: 디버깅에는 탁월하지만, 개인정보(PII)나 비밀번호 등이 수집 서버로 전송될 위험이 매우 높으므로 데이터 접근 제어가 필수적입니다.

3.5. 프레임워크 및 라이브러리 (Framework Integrations)

  • Spring Batch (spring-batch.*)
    • 배치 작업의 Job, Step뿐만 아니라 Chunk 단위 처리까지 트레이싱을 확장(experimental.chunk.new-trace=true)했습니다. 대용량 배치 처리 시 병목 구간을 아이템 단위로 추적할 수 있습니다.
  • End User Monitoring (enduser.*.enabled=true)
    • 인증된 사용자 세션에서 사용자 ID나 권한(Role), 스코프 정보를 추출하여 스팬 속성에 추가합니다. “특정 사용자의 요청이 느리다"를 분석할 때 유용합니다.
  • 기타 통합
    • Spring Integration/Camel: 엔터프라이즈 통합 패턴(EIP)의 메시지 흐름을 추적합니다.
    • Micrometer: 애플리케이션 내부에서 Micrometer로 생성한 커스텀 메트릭을 OTLP로 브릿지하여 전송합니다.

4. 요약

이 설정 파일은 성능 오버헤드를 감수하더라도 최대한의 정보를 수집하게 설정해놨습니다.

  1. Security Trade-off: DB 쿼리 파라미터가 그대로 노출(sanitizer=false)되므로, 수집된 데이터(Trace)의 조회 권한 관리가 매우 중요합니다.
  2. Performance Cost: capture-code-attributes (라인 넘버)와 capture-mdc-attributes=* (MDC 전체 복제)는 CPU와 메모리 사용량을 증가시키는 주요 요인입니다.
  3. Full Visibility: 트레이스-로그 연결, 사용자 정보 식별, 배치 청크 추적 등 SRE가 장애 원인을 분석(Root Cause Analysis)하는 데 필요한 거의 모든 맥락 정보를 제공합니다.
수정: 2025-12-12
뒤로 | 홈