0. 핵심 요약
• OpenTelemetry는 특정 모니터링 제품이 아니라, 애플리케이션의 로그·메트릭·트레이스를 표준 방식으로 수집하고 전달하기 위한 관측성
(Observability) 프레임워크이다.
• 실무 장애는 “에러 로그가 찍혔는지”보다 “어떤 요청이 어느 구간에서 느려졌는지”를 빠르게 찾는 것이 중요하다.
• OpenTelemetry의 기본 개념을 정리하고, Spring Boot 환경에서 어떤 식으로 적용하면 좋은지 운영 관점으로 정리한다.
1. 정의
• Observability(관측 가능성): 시스템 외부에서 수집한 정보만으로 내부 상태를 추론할 수 있는 능력이다.
• OpenTelemetry(OTel): 애플리케이션에서 발생하는 Trace, Metric, Log 데이터를 생성·수집·전달하기 위한 벤더 중립 오픈소스 표준이다.
• Spring Boot에서는 Micrometer Observation, Actuator, OpenTelemetry Java Agent 또는 OpenTelemetry Spring Boot Starter
등을 조합하여 관측 데이터를 만들 수 있다.
2. 용어 정리
- 실무에서 혼동이 많기 때문에 먼저 용어를 정리함.
3. 왜 로그만으로는 부족한가?
• 단일 서버에서는 로그만으로도 어느 정도 원인 추적이 가능하지만, 서비스가 여러 개로 나뉘면 로그만 보고 요청 흐름을 따라가기 어렵다.
• 예를 들어 API 서버 → 인증 서버 → DB → 외부 API 순서로 호출이 이어질 때, 최종 에러 로그만 보면 어느 단계가 원인인지 바로 알기 어렵다.
• Trace를 적용하면 하나의 요청에 같은 traceId가 붙기 때문에 “이 요청이 어느 서비스에서 얼마 동안 지연됐는지”를 한 흐름으로 볼 수 있다.
4. 사고사례 (원인 → 증상 → 방지책)
□ 사고 1) 외부 API 지연이 내부 장애처럼 보이는 경우
1) 원인
• 외부 API 호출에 Timeout이 없거나 너무 길게 잡혀 있음
• WebClient/RestTemplate 호출이 대기 상태로 누적됨
2) 증상
• 서버 CPU는 높지 않은데 응답이 느려짐
• Thread, Connection, Memory가 천천히 누적됨
• 로그에는 “외부 API가 늦었다”는 정보가 명확히 남지 않음
3) 방지책
• 외부 API 호출 구간을 별도 Span으로 분리
• Timeout, Retry, Circuit Breaker 로그에 traceId를 함께 남김
• 외부 API 응답시간 p95/p99를 Metric으로 수집
□ 사고 2) 특정 API만 느린데 DB 문제인지 애플리케이션 문제인지 모르는 경우
1) 원인
• Controller 로그와 DB 로그가 분리되어 있어 요청 단위 상관관계가 없음
• Slow Query는 보이지만 어떤 사용 요청에서 발생했는지 연결이 어려움
2) 증상
• 운영자는 “API가 느리다”는 현상만 보고 여러 로그를 수동으로 뒤짐
• 장애 복구보다 원인 탐색에 시간이 더 많이 걸림
3) 방지책
• HTTP 요청, Service 처리, DB Query 구간을 Trace로 연결
• Trace 화면에서 가장 오래 걸린 Span을 먼저 확인
• traceId를 애플리케이션 로그 패턴에 포함
□ 사고 3) 서버가 여러 대일 때 원인 서버를 특정하지 못하는 경우
1) 원인
• 로드밸런서를 통해 여러 인스턴스로 요청이 분산됨
• 로그 파일이 서버별로 흩어져 있음
2) 증상
• 장애가 특정 인스턴스에서만 발생해도 전체 서비스 문제처럼 보임
• 어떤 서버의 어떤 요청이 문제였는지 찾기 어려움
3) 방지책
• service.name, host.name, instance.id 같은 Resource Attribute를 반드시 설정
• Metric과 Trace를 인스턴스 기준으로 필터링 가능하게 구성
5. Spring Boot 적용 흐름
OpenTelemetry 적용은 “한 번에 모든 것을 완벽하게”보다, 요청 추적 → 로그 연결 → 메트릭 알림 순서로 단계적으로 적용하는 것이
현실적이다.
1. Actuator/Micrometer 기반으로 기본 HTTP 요청 지표를 수집한다.
2. traceId와 spanId가 로그에 출력되도록 로그 패턴을 정리한다.
3. 외부 API, DB, 메시지 처리 등 장애 영향도가 큰 구간부터 Span을 확인한다.
4. OpenTelemetry Collector를 두고 Jaeger, Zipkin, Grafana Tempo, 상용 APM 등으로 Export한다.
5. 운영 알림은 평균 응답시간보다 p95/p99, 에러율, Timeout 발생 수를 중심으로 잡는다.
6. 운영 관점: “언제 장애가 나는지” 징후(탐지 포인트)
7. 실무 적용 체크리스트(바로 도입 가능한 수준)
(1) 설계
• 서비스 이름(service.name)을 반드시 명확하게 지정
• 외부 API, DB, 메시지 처리 등 장애 영향도가 큰 구간부터 추적 대상 선정
• Trace, Metric, Log 를 따로 보지 않고 traceId 기준으로 연결할 수 있게 설계
(2) 설정
• 로그 패턴에 traceId/spanId 포함
• 운영 환경 sampling 비율 조정
• Collector, Exporter endpoint, 인증 정보는 환경변수 또는 설정 파일로 분리
(3) 운영
• 평균 응답시간보다 p95/p99 기준으로 알림 설정
• Timeout/Retry/Circuit Breaker 발생 건수를 Metric으로 수집
• 개인정보, 토큰, 비밀번호 같은 민감정보가 Span Attribute나 Log에 남지 않도록 필터링
(4) 장애 대응
• 장애 발생 시 먼저 traceId로 전체 요청 흐름 확인
• 가장 오래 걸린 Span을 기준으로 DB, 외부 API, 내부 로직 중 원인 구간을 좁힘
• 장애 후에는 재발 방지를 위해 Metric 알림 기준과 로그 항목을 보완
8. 결론
• OpenTelemetry는 단순히 로그를 많이 남기는 기술이 아니라, 요청 흐름을 기준으로 장애 원인을 좁혀가는 운영 방식이다.
• Spring Boot에서는 Micrometer/Actuator와 함께 적용하면 HTTP 요청, DB, 외부 API 호출을 추적하기 쉬워진다.
• 핵심은 모든 코드를 계측하는 것이 아니라, 장애가 자주 발생하거나 원인 추적이 어려운 구간부터 관측 가능하게 만드는 것이다.
9. Q&A 예상 질문(미리 답변 포함)
Q1) OpenTelemetry를 쓰면 기존 로그는 필요 없나?
• 아니다. OpenTelemetry는 Trace/Metric/Log를 연결하기 위한 기반이고, 실제 원인 분석에는 여전히 로그가 필요하다.
• 다만 로그에 traceId가 같이 남으면 특정 요청의 로그만 빠르게 추적할 수 있다.
Q2) APM 도구와 OpenTelemetry는 같은 것인가?
• 완전히 같지는 않다. APM은 데이터를 보여주고 분석하는 제품에 가깝고, OpenTelemetry는 데이터를 표준 방식으로 만들고
전달하는 계층에 가깝다.
• OpenTelemetry로 수집한 데이터를 Jaeger, Zipkin, Grafana, Datadog 같은 도구로 보낼 수 있다.
Q3) 모든 요청을 100% 수집해도 되나?
• 개발/테스트 환경에서는 100% 수집이 편하지만, 운영에서는 비용과 저장공간 문제가 생길 수 있다.
• 운영 환경에서는 트래픽 규모에 따라 Sampling 비율을 조정하고, 에러 요청은 더 적극적으로 수집하는 전략이 필요하다.
Q4) 보안상 주의할 점은?
• 토큰, 비밀번호, 주민번호, 이메일 전문 등 민감정보를 Span Attribute나 Log에 남기면 안 된다.
• 관측성 데이터도 운영 데이터이므로 접근 권한, 보관 기간, 마스킹 정책을 함께 고려해야 한다.
10. 참고자료
• OpenTelemetry Documentation - https://opentelemetry.io/docs/
• OpenTelemetry Java / Spring Boot Starter - https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/
• Spring Boot Reference - Observability - https://docs.spring.io/spring-boot/reference/actuator/observability.html
⭐발표자 : 남상엽님
0. 핵심 요약
• OpenTelemetry는 특정 모니터링 제품이 아니라, 애플리케이션의 로그·메트릭·트레이스를 표준 방식으로 수집하고 전달하기 위한 관측성
(Observability) 프레임워크이다.
• 실무 장애는 “에러 로그가 찍혔는지”보다 “어떤 요청이 어느 구간에서 느려졌는지”를 빠르게 찾는 것이 중요하다.
• OpenTelemetry의 기본 개념을 정리하고, Spring Boot 환경에서 어떤 식으로 적용하면 좋은지 운영 관점으로 정리한다.
1. 정의
• Observability(관측 가능성): 시스템 외부에서 수집한 정보만으로 내부 상태를 추론할 수 있는 능력이다.
• OpenTelemetry(OTel): 애플리케이션에서 발생하는 Trace, Metric, Log 데이터를 생성·수집·전달하기 위한 벤더 중립 오픈소스 표준이다.
• Spring Boot에서는 Micrometer Observation, Actuator, OpenTelemetry Java Agent 또는 OpenTelemetry Spring Boot Starter
등을 조합하여 관측 데이터를 만들 수 있다.
2. 용어 정리
- 실무에서 혼동이 많기 때문에 먼저 용어를 정리함.
3. 왜 로그만으로는 부족한가?
• 단일 서버에서는 로그만으로도 어느 정도 원인 추적이 가능하지만, 서비스가 여러 개로 나뉘면 로그만 보고 요청 흐름을 따라가기 어렵다.
• 예를 들어 API 서버 → 인증 서버 → DB → 외부 API 순서로 호출이 이어질 때, 최종 에러 로그만 보면 어느 단계가 원인인지 바로 알기 어렵다.
• Trace를 적용하면 하나의 요청에 같은 traceId가 붙기 때문에 “이 요청이 어느 서비스에서 얼마 동안 지연됐는지”를 한 흐름으로 볼 수 있다.
4. 사고사례 (원인 → 증상 → 방지책)
□ 사고 1) 외부 API 지연이 내부 장애처럼 보이는 경우
1) 원인
• 외부 API 호출에 Timeout이 없거나 너무 길게 잡혀 있음
• WebClient/RestTemplate 호출이 대기 상태로 누적됨
2) 증상
• 서버 CPU는 높지 않은데 응답이 느려짐
• Thread, Connection, Memory가 천천히 누적됨
• 로그에는 “외부 API가 늦었다”는 정보가 명확히 남지 않음
3) 방지책
• 외부 API 호출 구간을 별도 Span으로 분리
• Timeout, Retry, Circuit Breaker 로그에 traceId를 함께 남김
• 외부 API 응답시간 p95/p99를 Metric으로 수집
□ 사고 2) 특정 API만 느린데 DB 문제인지 애플리케이션 문제인지 모르는 경우
1) 원인
• Controller 로그와 DB 로그가 분리되어 있어 요청 단위 상관관계가 없음
• Slow Query는 보이지만 어떤 사용 요청에서 발생했는지 연결이 어려움
2) 증상
• 운영자는 “API가 느리다”는 현상만 보고 여러 로그를 수동으로 뒤짐
• 장애 복구보다 원인 탐색에 시간이 더 많이 걸림
3) 방지책
• HTTP 요청, Service 처리, DB Query 구간을 Trace로 연결
• Trace 화면에서 가장 오래 걸린 Span을 먼저 확인
• traceId를 애플리케이션 로그 패턴에 포함
□ 사고 3) 서버가 여러 대일 때 원인 서버를 특정하지 못하는 경우
1) 원인
• 로드밸런서를 통해 여러 인스턴스로 요청이 분산됨
• 로그 파일이 서버별로 흩어져 있음
2) 증상
• 장애가 특정 인스턴스에서만 발생해도 전체 서비스 문제처럼 보임
• 어떤 서버의 어떤 요청이 문제였는지 찾기 어려움
3) 방지책
• service.name, host.name, instance.id 같은 Resource Attribute를 반드시 설정
• Metric과 Trace를 인스턴스 기준으로 필터링 가능하게 구성
5. Spring Boot 적용 흐름
OpenTelemetry 적용은 “한 번에 모든 것을 완벽하게”보다, 요청 추적 → 로그 연결 → 메트릭 알림 순서로 단계적으로 적용하는 것이
현실적이다.
1. Actuator/Micrometer 기반으로 기본 HTTP 요청 지표를 수집한다.
2. traceId와 spanId가 로그에 출력되도록 로그 패턴을 정리한다.
3. 외부 API, DB, 메시지 처리 등 장애 영향도가 큰 구간부터 Span을 확인한다.
4. OpenTelemetry Collector를 두고 Jaeger, Zipkin, Grafana Tempo, 상용 APM 등으로 Export한다.
5. 운영 알림은 평균 응답시간보다 p95/p99, 에러율, Timeout 발생 수를 중심으로 잡는다.
6. 운영 관점: “언제 장애가 나는지” 징후(탐지 포인트)
7. 실무 적용 체크리스트(바로 도입 가능한 수준)
(1) 설계
• 서비스 이름(service.name)을 반드시 명확하게 지정
• 외부 API, DB, 메시지 처리 등 장애 영향도가 큰 구간부터 추적 대상 선정
• Trace, Metric, Log 를 따로 보지 않고 traceId 기준으로 연결할 수 있게 설계
(2) 설정
• 로그 패턴에 traceId/spanId 포함
• 운영 환경 sampling 비율 조정
• Collector, Exporter endpoint, 인증 정보는 환경변수 또는 설정 파일로 분리
(3) 운영
• 평균 응답시간보다 p95/p99 기준으로 알림 설정
• Timeout/Retry/Circuit Breaker 발생 건수를 Metric으로 수집
• 개인정보, 토큰, 비밀번호 같은 민감정보가 Span Attribute나 Log에 남지 않도록 필터링
(4) 장애 대응
• 장애 발생 시 먼저 traceId로 전체 요청 흐름 확인
• 가장 오래 걸린 Span을 기준으로 DB, 외부 API, 내부 로직 중 원인 구간을 좁힘
• 장애 후에는 재발 방지를 위해 Metric 알림 기준과 로그 항목을 보완
8. 결론
• OpenTelemetry는 단순히 로그를 많이 남기는 기술이 아니라, 요청 흐름을 기준으로 장애 원인을 좁혀가는 운영 방식이다.
• Spring Boot에서는 Micrometer/Actuator와 함께 적용하면 HTTP 요청, DB, 외부 API 호출을 추적하기 쉬워진다.
• 핵심은 모든 코드를 계측하는 것이 아니라, 장애가 자주 발생하거나 원인 추적이 어려운 구간부터 관측 가능하게 만드는 것이다.
9. Q&A 예상 질문(미리 답변 포함)
Q1) OpenTelemetry를 쓰면 기존 로그는 필요 없나?
• 아니다. OpenTelemetry는 Trace/Metric/Log를 연결하기 위한 기반이고, 실제 원인 분석에는 여전히 로그가 필요하다.
• 다만 로그에 traceId가 같이 남으면 특정 요청의 로그만 빠르게 추적할 수 있다.
Q2) APM 도구와 OpenTelemetry는 같은 것인가?
• 완전히 같지는 않다. APM은 데이터를 보여주고 분석하는 제품에 가깝고, OpenTelemetry는 데이터를 표준 방식으로 만들고
전달하는 계층에 가깝다.
• OpenTelemetry로 수집한 데이터를 Jaeger, Zipkin, Grafana, Datadog 같은 도구로 보낼 수 있다.
Q3) 모든 요청을 100% 수집해도 되나?
• 개발/테스트 환경에서는 100% 수집이 편하지만, 운영에서는 비용과 저장공간 문제가 생길 수 있다.
• 운영 환경에서는 트래픽 규모에 따라 Sampling 비율을 조정하고, 에러 요청은 더 적극적으로 수집하는 전략이 필요하다.
Q4) 보안상 주의할 점은?
• 토큰, 비밀번호, 주민번호, 이메일 전문 등 민감정보를 Span Attribute나 Log에 남기면 안 된다.
• 관측성 데이터도 운영 데이터이므로 접근 권한, 보관 기간, 마스킹 정책을 함께 고려해야 한다.
10. 참고자료
• OpenTelemetry Documentation - https://opentelemetry.io/docs/
• OpenTelemetry Java / Spring Boot Starter - https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/
• Spring Boot Reference - Observability - https://docs.spring.io/spring-boot/reference/actuator/observability.html
⭐발표자 : 남상엽님