개요

최종 수정: 2026. 1. 16.

계측 개요

애플리케이션 계측(Instrumentation)을 통해 분산 트레이싱, 메트릭, 로그를 수집하는 방법을 안내합니다.

계측이란?

계측은 애플리케이션에서 관측 가능성(Observability) 데이터를 생성하는 과정입니다. 이를 통해 다음을 수집할 수 있습니다:

데이터 유형	설명
트레이스	요청이 시스템을 통과하는 경로 추적
메트릭	요청 수, 지연시간, 에러율 등 수치 데이터
로그	애플리케이션 이벤트 기록

계측 방식

Skuber+ Observability는 두 가지 계측 방식을 지원합니다.

자동 계측 (권장)

코드 변경 없이 애플리케이션을 계측합니다.

자동 계측 옵션

방식	설명	장점	적합한 경우
APM Agent (eBPF)	커널 레벨에서 자동 감지	코드/설정 변경 없음	대부분의 경우
OTel Operator	사이드카 주입	더 상세한 트레이스	세밀한 제어 필요 시

수동 계측

OpenTelemetry SDK를 사용하여 코드에 직접 계측을 추가합니다.

# 예시: OpenTelemetry SDK 사용
tracer.start_span('operation')
meter.create_counter('requests')

수동 계측이 필요한 경우

비즈니스 로직 관련 커스텀 스팬 추가
특정 함수나 메서드 수준의 상세 트레이싱
커스텀 메트릭 생성
자동 계측이 지원하지 않는 프레임워크

자동 계측 vs 수동 계측

항목	자동 계측	수동 계측
코드 변경	불필요	필요
설정 난이도	쉬움	중간~높음
트레이스 상세도	표준	커스터마이징 가능
유지보수	최소	코드와 함께 관리
지원 범위	표준 프레임워크	모든 코드

권장 접근법

먼저 자동 계측 적용 - APM Agent가 기본으로 설치됨
필요시 수동 계측 추가 - 비즈니스 로직 트레이싱
점진적 확장 - 중요한 서비스부터 상세 계측

지원 언어 및 프레임워크

APM Agent 자동 계측 지원

언어	지원 프레임워크
Go	net/http, Gin, Echo, Fiber, gRPC
Java	Spring Boot, Micronaut, Quarkus
Python	Django, Flask, FastAPI
Node.js	Express, Koa, Fastify, NestJS
.NET	ASP.NET Core
Ruby	Rails, Sinatra
Rust	Actix, Rocket

OTel Operator 자동 계측 지원

언어	지원
Java	✅ 완전 지원
Python	✅ 완전 지원
Node.js	✅ 완전 지원
Go	⚠️ 제한적 (수동 권장)
.NET	✅ 완전 지원

수동 계측 SDK

모든 OpenTelemetry 지원 언어에서 수동 계측이 가능합니다:

Java, Python, Node.js, Go, .NET
C++, PHP, Ruby, Rust, Swift, Erlang

프로토콜 지원

APM Agent는 다음 프로토콜을 자동으로 감지하고 계측합니다:

프로토콜	수집 데이터
HTTP/1.1, HTTP/2	메서드, 경로, 상태 코드, 지연시간
gRPC	서비스, 메서드, 상태, 지연시간
Redis	명령어, 키, 지연시간
SQL	쿼리 유형, 테이블, 지연시간
Kafka	토픽, 파티션, 오프셋
DNS	쿼리 타입, 도메인

데이터 흐름

수집 경로

애플리케이션 - 트레이스/메트릭 생성
계측 레이어 - 데이터 캡처 (APM Agent/사이드카/SDK)
OTel Collector - 데이터 처리 및 전송
Host 클러스터 - 중앙 집중 수집
ClickHouse - 영구 저장
대시보드 - 시각화

시작하기

Step 1: 현재 상태 확인

Agent 클러스터를 설치했다면 APM Agent가 이미 동작 중입니다:

kubectl get pods -n skuber-observability -l app.kubernetes.io/name=skuber-apm-agent

Step 2: 트레이스 확인

좌측 메뉴에서 Traces 클릭
서비스 이름으로 필터링
자동 수집된 트레이스 확인

Step 3: 추가 계측 필요 시

요구사항	권장 방법
기본 APM	APM Agent (기본 설치됨)
더 상세한 트레이스	OTel Operator
커스텀 비즈니스 로직	수동 계측

다음 단계

자동 계측 - APM Agent 및 OTel Operator 상세 설정
Java 계측 - Java 애플리케이션 수동 계측
Python 계측 - Python 애플리케이션 수동 계측
Node.js 계측 - Node.js 애플리케이션 수동 계측
Go 계측 - Go 애플리케이션 수동 계측
.NET 계측 - .NET 애플리케이션 수동 계측