리포지토리에는 Kubernetes 클러스터 내에서 실행되도록 미리 설정된 다중 서비스 Java 애플리케이션이 포함되어 있습니다. 본 샘플 앱은 REST API를 갖춘 기본 노트 앱으로 데이터를 추가 및 변경할 수 있습니다. Kubernetes 포드 컨테이너를 만드는 데 필요한 docker-compose YAML 파일은 docker 디렉터리에 있습니다. 이 튜토리얼에서는 애플리케이션의 컨테이너를 빌드하는 service-docker-compose-k8s.yaml 파일을 사용합니다.
notes 및 calendar 디렉토리에는 Maven 또는 Gradle로 애플리케이션을 빌드하는 두 세트의 Dockerfile이 있습니다. 이 튜토리얼에서는 Maven 빌드를 사용하지만, Gradle에 더 익숙하다면 해당 빌드 명령의 변경 사항을 사용하여 Maven 빌드를 사용할 수 있습니다.
notes 앱용 Kubernetes 설정 파일, calendar 앱, Datadog Agent 파일은 kubernetes 디렉터리에 있습니다.
샘플 애플리케이션을 가져오는 프로세스에는 docker 폴더에서 이미지를 빌드하고, 이를 레지스트리에 업로드한 다음, kubernetes 폴더에서 Kubernetes 리소스를 생성하는 작업이 포함됩니다.
클러스터 시작하기
재사용하려는 GKE 클러스터가 아직 없는 경우 다음 명령을 실행하여 하나 생성하고 다음과 같이 <VARIABLES>를 사용하려는 값으로 변경합니다.
앱을 실행하려면 REST API 를 호출하기 위한 외부 IP 주소를 알아야 합니다. 먼저 다음 명령으로 목록 출력에서 notes-app-deploy 포드를 찾아 해당 노드를 확인합니다.
kubectl get pods -o wide
다음 명령의 출력에서 해당 노드 이름을 찾아 외부 IP 값을 확인합니다.
kubectl get nodes -o wide
제시된 예제에서 notes-app은 외부 IP가 35.196.6.199인 노드 gke-java-tracing-gke-default-pool-ccbd5526-dd3d에서 실행 중입니다.
다른 터미널을 열고 앱을 실행하기 위한 API 요청을 보냅니다. 노트 애플리케이션은 데이터를 동일한 컨테이너에서 실행 중인 인메모리 H2 데이터베이스에 저장하는 REST API입니다. 다음과 같이 몇 가지 명령을 보내세요.
curl '<EXTERNAL_IP>:30080/notes'
[]
curl -X POST '<EXTERNAL_IP>:30080/notes?desc=hello'
{"id":1,"description":"hello"}
curl '<EXTERNAL_IP>:30080/notes?id=1'
{"id":1,"description":"hello"}
curl '<EXTERNAL_IP>:30080/notes'
[{"id":1,"description":"hello"}]
애플리케이션 실행을 확인한 후 추적을 활성화할 수 있도록 중단합니다.
kubectl delete -f notes-app.yaml
추적 활성화
이제 Java 애플리케이션이 작동하므로 추적을 활성화하도록 구성하면 됩니다.
프로젝트에 Java 추적 패키지를 추가합니다. Agent는 GKE 클러스터에서 실행되므로 Dockerfile이 올바르게 설정되었는지 확인하세요. 아무것도 추가 설치할 필요가 없습니다. notes/dockerfile.notes.maven 파일을 열고 dd-java-agent를 다운로드하는 줄의 주석 처리를 해제합니다.
RUN curl -Lo dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'
같은 notes/dockerfile.notes.maven 파일 내에서 추적 없이 실행할 ENTRYPOINT 줄을 주석 처리합니다. 그런 다음 추적 기능을 활성화하여 애플리케이션을 실행하는 ENTRYPOINT 줄의 주석 처리를 제거합니다.
참고: 이 샘플 명령의 플래그, 특히 샘플 속도는 이 튜토리얼이 적용되지 않은 환경에는 적합하지 않을 수 있습니다. 실제 환경에서 어떤 플래그를 사용해야 하는지에 대해 살펴보려면 추적 설정을 참고하세요.
Universal Service Tags는 다양한 버전 및 배포 환경에서 추적된 서비스를 식별하여 Datadog 내에서 상관 관계를 분석하고 검색 및 필터링에 사용할 수 있도록 합니다. Unified Service Tagging에 사용되는 세 가지 환경 변수는 DD_SERVICE, DD_ENV, DD_VERSION입니다. Kubernetes로 배포된 애플리케이션의 경우, 이러한 환경 변수는 배포 YAML 파일 내, 특히 배포 오브젝트, 포드 사양, 포드 컨테이너 템플릿에 추가할 수 있습니다.
이 튜토리얼의 경우, kubernetes/notes-app.yaml 파일에 이미 배포 오브젝트, 포드 사양 및 포드 컨테이너 템플릿에 관하여 노트 애플리케이션의 환경 변수가 정의되어 있습니다. 다음은 그 예시입니다.
API 키를 노출하지 않는 보다 안전한 배포에 대해서는 시크릿 사용에 대한 지침을 참조하세요. 아울러, us1 외의 Datadog 사이트를 사용하는 경우 datadoghq.com를 해당 사이트로 변경하세요.
앱을 시작해 자동 추적을 확인합니다.
이전과 동일한 단계에 따라 notes 앱을 kubectl create -f notes-app.yaml을 통해 배포하고 해당 앱이 실행되는 노드의 외부 IP 주소를 확인합니다.
몇 가지 Curl 명령을 실행하여 앱을 실행합니다.
curl '<EXTERNAL_IP>:30080/notes'
[]
curl -X POST '<EXTERNAL_IP>:30080/notes?desc=hello'
{"id":1,"description":"hello"}
curl '<EXTERNAL_IP>:30080/notes?id=1'
{"id":1,"description":"hello"}
curl '<EXTERNAL_IP>:30080/notes'
[{"id":1,"description":"hello"}]
잠시 기다린 다음 Datadog에서 APM > 트레이스로 이동합니다. API 호출과 대응되는 트레이스 목록을 확인할 수 있습니다.
h2는 이 튜토리얼에 대해 내장된 인메모리 데이터베이스이며, notes는 Spring Boot 애플리케이션입니다. 추적 목록에는 모든 스팬, 시작 시점, 스팬과 함께 추적된 리소스, 그리고 소요 시간이 표시됩니다.
몇 분이 지난 후에도 트레이스를 확인할 수 없다면 트레이스 검색 필드에서 모든 필터를 해제합니다. 때론 사용하지 않는 ENV 등 환경 변수에 대해 필터링되었을 수 있습니다.
트레이스 검사
트레이스 페이지에서 POST /notes 트레이스를 클릭해 각 스팬에 걸리는 시간 및 스팬 완료 전 발생한 다른 스팬을 나타내는 플레임(Flame) 그래프를 확인할 수 있습니다. 그래프 상단의 막대는 이전 화면에서 선택한 스팬입니다. (이 경우 메모 애플리케이션의 최초 엔트리 포인트입니다.)
바의 너비는 완료되는 데 소요된 시간을 나타냅니다. 낮은 깊이의 막대는 높은 깊이의 막대 수명 동안 완료된 스팬을 나타냅니다.
POST 트레이스의 불꽃 그래프는 이와 비슷한 형태입니다.
GET /notes 트레이스는 이와 비슷한 형태입니다.
추적 설정
Java 추적 라이브러리는 Java에 내장된 Agent 및 모니터링 지원을 사용합니다. Dockerfile의 플래그 -javaagent:../dd-java-agent.jar는 JVM에 Java 추적 라이브러리의 위치를 알려 Java Agent로 실행할 수 있도록 합니다. Java Agent에 대한 자세한 내용은 https://www.baeldung.com/java-instrumentation에서 확인하세요.
dd.trace.sample.rate 플래그는 이 애플리케이션의 샘플링 속도를 설정합니다. Dockerfile의 ENTRYPOINT 명령은 값을 1로 설정합니다. 즉, notes 서비스의 모든 요청 100%가 분석 및 표시를 위해 Datadog 백엔드로 전송됩니다. 저용량 테스트 애플리케이션에는 적합하나 프로덕션 환경이나 고용량 환경에서는 데이터 양이 매우 많아질 수 있어 권장하지 않습니다. 대신 일부 요청을 샘플링할 수 있습니다. 0에서 1 사이의 값을 선택하세요. 예를 들어, -Ddd.trace.sample.rate=0.1는 요청의 10%에 대한 트레이스를 Datadog으로 전송합니다. 관련 정보는 추적 설정 지정 및 샘플링 메커니즘에서 자세히 살펴보세요.
명령에서 샘플링 속도 플래그가 -jar 플래그 앞에 나타나는 것을 확인할 수 있습니다. 이는 이 플래그가 애플리케이션이 아닌 Java Virtual Machine의 파라미터이기 때문입니다. 애플리케이션에 Java Agent를 추가할 때 플래그를 올바른 위치에 지정해야 합니다.
Java 애플리케이션에 수동 계측 추가
자동 계측은 편리하지만 때때로 더욱 세분화된 스팬을 원할 수 있습니다. Datadog의 Java DD 트레이스 API를 사용하면 어노테이션이나 코드로 코드 내 스팬을 지정할 수 있습니다.
다음 단계에서는 빌드 스크립트를 수정하여 Java 추적 라이브러리를 다운로드하고, 코드에 어노테이션을 추가하여 샘플 메서드를 추적하는 방법을 알아봅니다.
현재 애플리케이션 배포를 삭제합니다.
kubectl delete -f notes-app.yaml
/notes/src/main/java/com/datadog/example/notes/NotesHelper.java를 엽니다. 이 예제에는 주석 처리된 코드가 포함되어 있으며, 코드에서 커스텀 추적을 설정하는 다양한 방법을 보여줍니다.
애플리케이션의 특정 코드 블록에 대해 별도의 스팬을 생성할 수도 있습니다. 스팬 내에 서비스 및 리소스 이름 태그와 오류 처리 태그를 추가합니다. 이러한 태그를 추가하면 Datadog 시각화에서 스팬과 메트릭을 보여주는 플레임 그래프가 생성됩니다. 프라이빗 메서드를 수동으로 추적하는 줄의 주석 처리를 제거합니다.
Tracertracer=GlobalTracer.get();// Tags can be set when creating the spanSpanspan=tracer.buildSpan("manualSpan1").withTag(DDTags.SERVICE_NAME,"NotesHelper").withTag(DDTags.RESOURCE_NAME,"privateMethod1").start();try(Scopescope=tracer.activateSpan(span)){// Tags can also be set after creationspan.setTag("postCreationTag",1);Thread.sleep(30);Log.info("Hello from the custom privateMethod1");
그리고 오류에 태그를 설정하는 줄도 있습니다.
}catch(Exceptione){// Set error on spanspan.setTag(Tags.ERROR,true);span.setTag(DDTags.ERROR_MSG,e.getMessage());span.setTag(DDTags.ERROR_TYPE,e.getClass().getName());finalStringWritererrorString=newStringWriter();e.printStackTrace(newPrintWriter(errorString));span.setTag(DDTags.ERROR_STACK,errorString.toString());Log.info(errorString.toString());}finally{span.finish();}
수동 추적을 위한 종속성을 구성하는 notes/pom.xml 줄을 열고 주석 처리를 제거하여 Maven 빌드를 업데이트하세요. dd-trace-api 라이브러리는 @Trace 어노테이션에 사용되고, opentracing-util 와 opentracing-api는 수동 스팬 생성에 사용됩니다.
애플리케이션을 다시 빌드하고 이전과 동일한 단계에 따라 GCR에 업로드한 후, docker 디렉터리에서 다음 명령을 실행합니다.
이전과 동일한 단계에 따라 notes 앱을 kubectl create -f notes-app.yaml을 통해 배포하고 해당 앱이 실행되는 노드의 외부 IP 주소를 확인합니다.
일부 HTTP 요청, 특히 GET 요청을 다시 전송합니다.
트레이스 탐색기에서 새로운 GET 요청 중 하나를 클릭한 다음 이와 같은 불꽃 그래프를 확인하세요.
getAll 함수가 커스텀 추적을 포함하므로 스택 트레이스(stack trace)에서 상위 수준의 상세 정보를 확인할 수 있습니다.
수동 스팬을 생성한 privateMethod는 다른 호출과 별도의 블록으로 표시되며 다른 색상으로 강조 표시됩니다.@Trace 어노테이션을 사용한 다른 메서드는 GET 요청(notes 애플리케이션)과 동일한 서비스와 색상으로 표시됩니다. 커스텀 계측은 코드의 핵심 부분을 강조 표시하고 모니터링해야 할 때 유용합니다.
단일 애플리케이션 추적은 좋은 시작이지만 추적의 진정한 가치는 서비스를 통한 요청의 흐름을 확인하는 데 있습니다. 이것을 _분산 추적_이라고 부릅니다.
샘플 프로젝트에 calendar라는 두 번째 애플리케이션이 포함되어 있습니다. 이 애플리케이션은 호출 시 임의의 날짜를 반환합니다. 메모 애플리케이션의 POST 엔드포인트는 add_date라는 두 번째 쿼리 파라미터를 포함합니다. y로 설정되어 있는 경우 메모는 캘린더 애플리케이션을 호출하여 메모에 추가할 날짜를 가져옵니다.
이전에 메모 앱에서 했던 작업과 마찬가지로, dd-java-agent을 Dockerfile의 시작 명령에 추가하여 calendar 앱에 추적을 설정합니다.calendar/dockerfile.calendar.maven를 열고 dd-java-agent를 다운로드하는지 확인합니다.
RUN curl -Lo dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'
같은 calendar/dockerfile.calendar.maven 파일 내에서 추적 없이 실행할 ENTRYPOINT 줄을 주석 처리합니다. 그런 다음 추적 기능을 활성화하여 애플리케이션을 실행하는 ENTRYPOINT 줄의 주석 처리를 제거합니다.
curl -X POST '<EXTERNAL_IP>:30080/notes?desc=hello_again&add_date=y'
{"id":1,"description":"hello_again with date 2022-11-06"}
트레이스 탐색기에서 다음 최신 트레이스를 클릭하여 두 서비스 간의 분산 트레이스를 확인하세요.
notes 애플리케이션에서는 아무것도 변경하지 않았습니다. Datadog은 notes에서 calendar로의 HTTP 호출에 사용되는 okHttp라이브러리와 notes 및 calendar에서 HTTP 요청을 수신하는 데 사용되는 Jetty 라이브러리를 모두 자동으로 계측합니다. 이를 통해 트레이스 정보를 한 애플리케이션에서 다른 애플리케이션으로 전달하여 분산 트레이스를 캡처할 수 있습니다.