SDK 설정과 리소스 속성

목표

SDK 를 환경변수로 설정하고, 리소스 속성을 시맨틱 컨벤션에 맞게 확정하고, 쿠버네티스에서 인스턴스 식별자를 Downward API 로 주입합니다. 마지막으로 스팬 이름 카디널리티를 검사하는 린터를 직접 만듭니다.

왜 중요한가

계측에서 되돌리기 가장 어려운 결정이 리소스 속성입니다. 코드는 언제든 고칠 수 있지만 service.name 을 바꾸는 순간 대시보드, 알림, 서비스 그래프, 그리고 과거 데이터와의 연결이 전부 끊깁니다. 그래서 스팬을 늘리기 전에 이것부터 확정합니다. 같은 이유로 이름 규약이 중요합니다. deployment.environment 와 deployment.environment.name 은 사람 눈에는 같아 보이지만 시스템에는 완전히 다른 두 속성이고, 대시보드 변수는 그중 하나만 읽습니다. 스팬 이름도 마찬가지입니다. 이름에 ID 가 섞이면 백엔드의 집계 뷰가 통째로 무너지는데, 이 사고는 배포 직후가 아니라 몇 주 뒤 "서비스 그래프가 이상하다"는 형태로 발견됩니다. 그래서 사람 기억이 아니라 CI 가 막아야 합니다.

단계

1. /root/otca-sdk/otel.env 를 만들고 OTEL_SERVICE_NAME=checkout-api, OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.observability.svc:4317, OTEL_EXPORTER_OTLP_PROTOCOL=grpc 를 씁니다. 한 줄에 하나씩 키=값 형태입니다.
2. 같은 파일에 OTEL_RESOURCE_ATTRIBUTES 를 추가합니다. 값은 쉼표로 이은 service.version=2.7.1, deployment.environment.name=prod, service.namespace=commerce 입니다. 옛 이름 deployment.environment 는 쓰지 마세요.
3. 같은 파일에 OTEL_TRACES_SAMPLER=parentbased_traceidratio, OTEL_TRACES_SAMPLER_ARG=0.1, OTEL_PROPAGATORS=tracecontext,baggage 를 추가합니다.
4. 같은 파일에 상한 네 개를 추가합니다. OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT=64, OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT=2048, OTEL_BSP_MAX_QUEUE_SIZE=4096, OTEL_BSP_MAX_EXPORT_BATCH_SIZE=512.
5. /root/otca-sdk/deployment.yaml 에 Deployment 를 씁니다. metadata.name: checkout-api, metadata.namespace: otca-sdk. 첫 컨테이너의 env 에 POD_NAME(fieldRef metadata.name), POD_NAMESPACE(fieldRef metadata.namespace), OTEL_SERVICE_NAME=checkout-api, OTEL_EXPORTER_OTLP_ENDPOINT(4317 포함), 그리고 OTEL_RESOURCE_ATTRIBUTES 를 넣되 그 값에 deployment.environment.name=prod, service.instance.id=$(POD_NAME), k8s.namespace.name=$(POD_NAMESPACE) 가 들어가야 합니다.
6. 네임스페이스 otca-sdk 를 만들고 5단계의 매니페스트를 클러스터에 적용합니다.
7. /root/otca-sdk/span-names.txt 에 스팬 이름을 6줄 이상 적습니다. 그중 최소 4줄은 GET /... 처럼 HTTP 메서드로 시작해야 하고, 최소 3줄은 :id 자리표시자를 포함해야 합니다. 세 자리 이상 연속된 숫자나 UUID 는 한 줄도 있으면 안 됩니다.
8. /root/otca-sdk/lint-span-names.sh 를 작성합니다. 첫 번째 인자로 받은 파일에 세 자리 이상 연속 숫자나 UUID 형태가 들어 있으면 해당 줄을 출력하고 0 이 아닌 코드로 종료하고, 없으면 0 으로 종료합니다.

참고

• 1~4단계는 모두 같은 파일 /root/otca-sdk/otel.env 에 씁니다. export 접두어를 붙여도 되고 안 붙여도 됩니다.
• 5단계의 OTEL_RESOURCE_ATTRIBUTES 는 value: >- 접힘 블록으로 여러 줄에 나눠 써도 됩니다.
• 8단계 검증은 여러분이 만든 span-names.txt(통과해야 함)와 채점기가 만든 ID·UUID 목록(막아야 함) 두 가지로 이뤄집니다.
• 흔한 실수 1: 프로토콜은 grpc 인데 엔드포인트 포트를 4318 로 적는 것. 연결 자체가 실패합니다.
• 흔한 실수 2: service.instance.id 에 파드 이름을 문자열로 하드코딩하는 것.

단계 8개

1. 서비스 이름과 엔드포인트
2. 리소스 속성 확정
3. 샘플러와 전파기
4. 스팬 크기와 큐 상한
5. Downward API 로 인스턴스 식별자 주입
6. 클러스터에 적용
7. 저카디널리티 스팬 이름 목록
8. 스팬 이름 린터