8. 실습 준비 — 공식 LGTM 샘플 띄우기

결론부터

우리 설치 코드를 만들지 않고 Grafana 공식 저장소의 Kubernetes 스택과 example app을 그대로 연결한다

이 장에서 처음 나오는 말3개

kindKubernetes IN Docker

Docker 컨테이너를 노드로 쓰는 로컬 쿠버네티스. 실습이 끝나면 클러스터째 지울 수 있다.

LGTMLoki · Grafana · Tempo · Mimir/Prometheus

Grafana 관측 스택을 짧게 부르는 이름. 이 공식 개발 이미지는 메트릭 저장소로 Prometheus를 묶는다.

OTLPOpenTelemetry Protocol

앱이 메트릭·로그·트레이스를 수집기로 보내는 공통 전송 규약. 이번에는 host 앱이 port-forward를 통해 kind 안의 수집기로 보낸다.

이 장은 Grafana의 docker-otel-lgtm v0.30.2 저장소를 직접 checkout한다. kind에는 그 저장소의 k8s/lgtm.yaml만 적용하고, 데이터도 저장소의 Java rolldice example이 만든다. 우리 레포에는 설치 wrapper·매니페스트·example app을 복제하지 않는다.

공식 샘플이 맡는 범위

공식 파일	이번 실습에서 하는 일
k8s/lgtm.yaml	LGTM Service와 단일 Pod Deployment 생성
run-example.sh	Java rolldice example 실행
RollController.java	임의 지연과 약 30%의 의도적 500 오류 생성
generate-traffic.sh	example endpoint에 반복 요청 전송

공식 앱의 오류는 무작위다. 정상 → 장애 → 회복처럼 구간이 고정되지는 않지만, 메트릭·로그·트레이스가 같은 요청을 가리키는지 확인하고 Explore와 대시보드를 익히기에는 충분하다.

운영에 쓰지 않는다

공식 설명대로 grafana/otel-lgtm은 development · demo · testing 전용이다. 단일 Pod, emptyDir, admin 기본 계정, 리텐션·HA 없음이라는 성질은 공식 샘플을 그대로 썼다고 달라지지 않는다. 이 구성을 온프렘 운영 설치의 출발점으로 복사하지 않는다.

사전 준비

Docker·kind·kubectl 준비는 kind 실습 환경을 먼저 따른다. 공식 Java example은 Java 17 이상, Git, curl도 필요하다. 다음 명령이 모두 성공해야 한다.

docker info
kind version
kubectl version --client
git --version
java -version
curl --version

Docker 런타임에는 CPU 4개 · 메모리 6 GiB 이상, 디스크 약 10 GiB의 여유를 둔다.

docker info --format 'CPUs={{.NCPU}} Memory={{.MemTotal}}'

공식 traffic script는 watch 명령을 사용한다. macOS처럼 watch가 기본으로 없는 환경에서는 설치한 뒤 공식 script를 쓰거나, 아래의 curl 반복 대안을 사용한다.

공식 저장소 받기

작업할 빈 디렉터리에서 태그를 지정해 clone한다.

git clone --depth 1 --branch v0.30.2 \
  https://github.com/grafana/docker-otel-lgtm.git
cd docker-otel-lgtm

태그와 이미지 버전은 다르다

checkout한 소스는 v0.30.2지만 공식 Kubernetes YAML의 이미지는 grafana/otel-lgtm:latest다. 재현 가능한 고정 이미지 설치로 오해하지 말고, 아래에서 실제 image digest를 기록한다.

스택과 example app 실행

1. 전용 kind 클러스터를 만든다

   kind create cluster --name observability-lab
   
   kubectl config use-context kind-observability-lab
   kubectl config set-context --current --namespace=default
   kubectl config current-context
   kubectl version

   특정 Kubernetes 버전을 고정하지 않고 설치된 kind release의 기본 node image를 사용한다. 이 실습은 특정 Kubernetes 기능에 의존하지 않는다. 대신 실제 client·server 버전을 기록하고, 이후 명령의 대상을 kind-observability-lab context와 default namespace로 한 번 정한다.

2. 공식 Kubernetes 예제를 적용한다

   kubectl apply -f k8s/lgtm.yaml
   kubectl rollout status deployment/lgtm --timeout=300s

   첫 명령은 공식 README의 명령 그대로다. YAML은 수정하지 않는다. 이 장부터 11장까지는 위에서 정한 current context와 namespace를 사용하므로 --context와 -n을 반복하지 않는다.

3. 상태와 실제 image digest를 기록한다

   kubectl get pod,service
   kubectl get pod -l app=lgtm \
     -o jsonpath='LGTM image={.items[0].spec.containers[0].image}{"\n"}LGTM imageID={.items[0].status.containerStatuses[0].imageID}{"\n"}'

4. 터미널 A에서 공식 port-forward를 연다

   kubectl port-forward service/lgtm \
     3000:3000 3200:3200 4040:4040 4317:4317 4318:4318 9090:9090

   Grafana뿐 아니라 OTLP gRPC·HTTP 포트도 전달한다. host에서 실행하는 example app이 이 경로로 kind 안의 OpenTelemetry Collector에 신호를 보낸다.

5. 터미널 B에서 공식 Java example을 실행한다

   cd docker-otel-lgtm
   ./run-example.sh

   처음에는 Maven dependency와 OpenTelemetry Java agent를 받으므로 시간이 걸린다. 준비되면 http://127.0.0.1:8080/rolldice가 열린다.

6. 터미널 C에서 공식 traffic script를 실행한다

   cd docker-otel-lgtm
   ./generate-traffic.sh

   이 script는 여러 언어 example의 포트를 함께 호출한다. Java example만 실행했다면 8080의 응답만 보이는 것이 정상이다. watch가 없다면 다음 대안으로 Java endpoint만 반복 호출한다.

   while true; do
     curl -s http://127.0.0.1:8080/rolldice
     sleep 1
   done

7. Grafana에서 데이터소스를 확인한다

   http://127.0.0.1:3000을 열고 admin / admin으로 로그인한다. Connections → Data sources에 Prometheus·Loki·Tempo가 있으면 된다.

🔎 관찰 포인트: rolldice는 일부 요청을 약간 기다리게 하고 약 30%에서 500을 반환한다. 브라우저의 숫자 하나보다 터미널 B의 성공 로그와 오류 stack trace가 섞여 나오는지를 먼저 본다.

안 뜰 때 어디를 보나

증상	먼저 볼 것
Docker 연결 실패	Docker Desktop 또는 Colima가 실행 중인지 docker info로 확인
공식 YAML 다운로드·image pull 실패	GitHub·Docker Hub egress, proxy, 사내 CA 확인
LGTM rollout timeout	kubectl logs deploy/lgtm
run-example.sh가 바로 종료	Java 17 이상과 Maven dependency·Java agent 다운로드 경로 확인
앱은 뜨지만 신호가 없음	터미널 A에서 4317·4318 port-forward가 열려 있는지 확인
generate-traffic.sh: watch: command not found	watch를 설치하거나 위 while 대안 사용
3000·4317·4318 포트 충돌	점유 프로세스를 종료한 뒤 공식 port-forward 다시 실행

지금은 세 터미널과 클러스터를 유지한다. 다음 장에서 공식 앱의 무작위 오류를 세 신호로 조사한다.

참고 자료

• Grafana docker-otel-lgtm — Run lgtm in Kubernetes — 공식 apply와 port-forward 절차
• Grafana docker-otel-lgtm — Build and run the example app — 공식 앱 실행과 traffic 생성 절차
• kind Quick Start — 전용 클러스터 생성과 삭제
• OpenTelemetry OTLP exporter 설정 — endpoint에서 신호별 경로를 만드는 규칙

9. 공식 앱 조사rolldice의 무작위 오류와 지연을 메트릭·로그·트레이스로 직접 오간다.