View a markdown version of this page

로그 상관 관계에 대한 추적 활성화 - Amazon CloudWatch
트레이스 로그 상관 관계 설정 예제

로그 상관 관계에 대한 추적 활성화

Application Signals에서 로그 상관 관계 추적을 활성화할 수 있습니다. 그러면 트레이스 ID와 범위 ID가 관련 애플리케이션 로그에 자동으로 삽입됩니다. 그런 다음 Application Signals 콘솔에서 트레이스 세부 정보 페이지를 열면 현재 트레이스와 상관 관계가 있는 관련 로그 항목(있는 경우)이 페이지 하단에 자동으로 표시됩니다.

예를 들어 지연 시간 그래프에서 급증을 발견했다고 가정해 보겠습니다. 그래프에서 특정 시점을 선택하여 해당 시점에 대한 진단 정보를 로드할 수 있습니다. 그런 다음 관련 트레이스를 선택하여 추가 정보를 얻습니다. 트레이스 정보를 볼 때 아래로 스크롤하여 트레이스와 관련된 로그를 볼 수 있습니다. 이러한 로그에는 지연 시간 급증을 일으키는 문제와 관련된 패턴이나 오류 코드가 표시될 수 있습니다.

추적 로그 상관관계를 구성하기 전에 애플리케이션 계측

추적 로그 상관관계를 구성하기 전에 Application Signals에 대해 애플리케이션이 이미 계측되어 있어야 합니다. Application Signals 계측은 런타임에 trace_id, span_id 및 trace_flags MDC 값을 채웁니다. 계측이 없으면 이러한 값은 비어 있고(예: trace_id=) 상관관계는 작동하지 않습니다.

추적 로그 상관관계를 달성하기 위해 Application Signals는 다음 사항을 사용합니다.

OpenTelemetry 커뮤니티는 이러한 모든 계측 기능을 제공합니다. Application Signals는 이를 사용하여 트레이스 ID 및 범위 ID와 같은 트레이스 컨텍스트를 애플리케이션 로그에 삽입합니다. 이를 활성화하려면 자동 계측을 활성화하도록 로깅 구성을 수동으로 변경해야 합니다.

애플리케이션이 실행되는 아키텍처에 따라 이 섹션의 단계를 따르는 것 외에도 트레이스 로그 상관 관계를 활성화하도록 환경 변수를 설정해야 할 수도 있습니다.

  • Amazon EKS에서 추가 환경 변수는 필요하지 않습니다. 다음 예제에 설명된 대로 로깅 출력을 구성해야 하며, Container Insights가 로그를 수집할 수 있도록 로거가 stdout에 데이터를 써야 합니다.

  • Amazon ECS에서 추가 환경 변수는 필요하지 않습니다. 다음 예제에 설명된 대로 로깅 출력을 구성해야 하며, Container Insights가 로그를 수집할 수 있도록 로거가 stdout에 데이터를 써야 합니다.

  • Amazon EC2에서는 3단계: 애플리케이션 계측 후 시작 절차의 4단계를 참조하세요.

OpenTelemetry Container Insights는 추적 로그 상관관계를 자동으로 활성화하지 않습니다.

OpenTelemetry 기반 Container Insights 로그 수집 경로(예: CloudWatch Observability EKS 추가 기능을 통해)를 활성화하면 컨테이너 로그가 수집되어 CloudWatch Logs로 전송되지만, Application Signals에 대해 애플리케이션을 계측하거나 해당 로그에 추적 컨텍스트를 주입하지 않습니다. 추적을 로그와 연관시키려면 Application Signals 계측을 별도로 활성화해야 합니다. 그리고 이 페이지에 설명된 대로 로깅 패턴을 구성해야 합니다.

추적 로그 상관관계를 활성화한 후 추적 세부 정보 페이지를 열면 동일한 추적 ID가 포함된 모든 로그 항목이 페이지 하단에 자동으로 나타납니다. 추적 로그 상관관계를 사용하면 수동으로 검색하지 않고도 추적에서 관련 애플리케이션 로그로 빠르게 이동할 수 있습니다.

트레이스 로그 상관 관계 설정 예제

이 섹션에는 여러 환경에서 트레이스 로그 상관 관계를 설정하는 예가 포함되어 있습니다.

Java용 Spring Boot

custom-app이라는 폴더에 Spring Boot 애플리케이션이 있다고 가정해 보겠습니다. 애플리케이션 구성은 일반적으로 다음과 custom-app/src/main/resources/application.yml이라는 YAML 파일입니다.

spring:
  application:
    name: custom-app
  config:
    import: optional:configserver:${CONFIG_SERVER_URL:http://localhost:8888/}
    
...

트레이스 로그 상관 관계를 활성화하려면 다음 로깅 구성을 추가하세요.

spring:
  application:
    name: custom-app
  config:
    import: optional:configserver:${CONFIG_SERVER_URL:http://localhost:8888/}
    
...    

logging:
  pattern:
    level: trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p
Spring Boot 및 XML 구성은 대안입니다.

Spring Bootapplication.yml(logging.pattern.level) 접근 방식과 다음 섹션에 표시된 Logback/Log4j2/Log4j XML 구성 접근 방식은 대안입니다. 단, 둘 중 하나만 사용해야 합니다. application.yml에서 패턴을 설정하면 Spring Boot의 기본 Logback 구성이 자동으로 패턴을 선택하므로 별도의 logback.xml이 필요하지 않습니다.

EKS 및 ECS: stdout에 로그 쓰기

Container Insights는 컨테이너 내부에 쓴 파일이 아닌 컨테이너의 stdout/stderr에서 로그를 수집합니다. 콘솔에 쓰도록 로거를 구성합니다(stdout). app.log와 같은 파일에 쓰는 FileAppender는 추적 태그가 지정된 줄을 올바르게 생성하지만, 해당 줄은 수집되지 않으며 추적 세부 정보 페이지에 상관관계가 있는 것으로 표시되지 않습니다. 파일에 로깅해야 하는 경우 해당 파일(예: 공유 볼륨을 읽는 사이드카 수집기)을 추가로 전송해야 합니다. 이 작업은 이 페이지의 범위를 벗어납니다.

Java용 Logback

로깅 구성(예: logback.xml)에서 트레이스 컨텍스트 trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p를 인코더의 pattern에 삽입합니다. 예를 들어, 다음 구성은 로그 메시지 앞에 트레이스 컨텍스트를 추가합니다.

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
  <encoder> 
    <pattern>trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n</pattern> 
  </encoder>
</appender>

Logback의 인코더에 대한 자세한 내용은 Logback 설명서의 Encoders를 참조하세요.

Java용 Log4j

로깅 구성(예: log4j2.xml)에서 트레이스 컨텍스트 trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p를 PatternLayout에 삽입합니다. 예를 들어, 다음 구성은 로그 메시지 앞에 트레이스 컨텍스트를 추가합니다.

<Appenders>
  <Console name="CONSOLE" target="SYSTEM_OUT">
    <PatternLayout pattern="trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n"/>
  </Console>
</Appenders>

Log4j2의 패턴 레이아웃에 대한 자세한 내용은 Log4j2 설명서의 Pattern Layout을 참조하세요.

Java용 Log4j

로깅 구성(예: log4j.xml)에서 트레이스 컨텍스트 trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %5p를 PatternLayout에 삽입합니다. 예를 들어, 다음 구성은 로그 메시지 앞에 트레이스 컨텍스트를 추가합니다.

<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %5p - %m%n"/>
  </layout>
</appender>

Log4j의 패턴 레이아웃에 대한 자세한 내용은 Log4j 설명서의 Class Layout을 참조하세요.

Python

애플리케이션을 실행하는 동안 환경 변수 OTEL_PYTHON_LOG_CORRELATION을 true로 설정합니다. 자세한 내용은 Python OpenTelemetry 설명서의 Enable trace context injection을 참조하세요.

Node.js

추적 컨텍스트 주입을 지원하는 로깅 라이브러리에 대해 Node.js에서 이를 활성화하는 방법에 대한 자세한 내용은 Node.js용 Pino, Winston 또는 Bunyan 자동 계측의 NPM 사용 설명서를 참조하세요.

설정 확인

애플리케이션을 다시 배포한 후 로그 줄에 채워진 trace_id가 표시되는지 확인합니다(예: kubectl logs pod-name 실행). 그런 다음 Application Signals 콘솔에서 추적 세부 정보 페이지를 열고 상관관계가 있는 로그 항목이 페이지 하단에 나타나는지 확인합니다.

Amazon EKS에서 로그는 Container Insights 애플리케이션 로그 그룹(/aws/containerinsights/cluster-name/application 또는 OpenTelemetry Container Insights 로그 경로가 활성화된 경우 /aws/otel/containerinsights/cluster-name/application)에 씁니다.