X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션 - AWS X-Ray
OpenTelemetry 이해마이그레이션을 위한 OpenTelemetry 개념 이해마이그레이션 개요X-Ray 데몬에서 AWS CloudWatch 에이전트 또는 OpenTelemetry 수집기로 마이그레이션

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션

X-Ray는 애플리케이션 추적 및 관찰성을 위한 기본 계측 표준으로 OpenTelemetry(OTel)로 전환하고 있습니다. 이 전략적 전환은 AWS 업계 모범 사례에 부합하며 고객에게 관찰성 요구 사항에 맞는 보다 포괄적이고 유연하며 미래에 대비한 솔루션을 제공합니다. OpenTelemetry가 업계에서 광범위하게 채택하면 X-Ray와 직접 통합되지 않을 수 AWS 있는 외부 시스템 등 다양한 시스템에서 요청을 추적할 수 있습니다.

이 장에서는 원활한 전환을 위한 권장 사항을 제공하고 애플리케이션 계측 및 관찰성의 최신 기능에 대한 지속적인 지원과 액세스를 보장하기 위해 OpenTelemetry 기반 솔루션으로 마이그레이션하는 것의 중요성을 강조합니다.

OpenTelemetry를 애플리케이션 계측을 위한 관찰성 솔루션으로 채택하는 것이 좋습니다.

주제

OpenTelemetry 이해

OpenTelemetry는 원격 측정 데이터를 수집하기 위한 표준화된 프로토콜과 도구를 제공하는 업계 표준 관찰성 프레임워크입니다. 지표, 로그 및 추적과 같은 원격 측정 데이터를 계측, 생성, 수집 및 내보내는 통합 접근 방식을 제공합니다.

X-Ray SDKs OpenTelemetry 로 마이그레이션하면 다음과 같은 이점을 얻을 수 있습니다.

  • 향상된 프레임워크 및 라이브러리 계측 지원

  • 추가 프로그래밍 언어 지원

  • 자동 계측 기능

  • 유연한 샘플링 구성 옵션

  • 지표, 로그 및 추적의 통합 수집

OpenTelemetry 수집기는 X-Ray 데몬보다 데이터 수집 형식 및 내보내기 대상에 대한 더 많은 옵션을 제공합니다.

에서 OpenTelemetry 지원 AWS

AWS 는 OpenTelemetry 작업을 위한 여러 솔루션을 제공합니다.

  • AWS OpenTelemetry용 배포판

    OpenTelemetry 트레이스를 세그먼트로 X-Ray로 내보냅니다.

    자세한 내용은 AWS Distro for OpenTelemetry를 참조하세요.

  • CloudWatch Application Signals

    사용자 지정 OpenTelemetry 트레이스 및 지표를 내보내 애플리케이션 상태를 모니터링합니다.

    자세한 내용은 Application Signals 작업을 참조하세요.

  • CloudWatch OTel 엔드포인트

    기본 OpenTelemetry 계측과 함께 HTTP OTel 엔드포인트를 사용하여 OpenTelemetry 트레이스를 X-Ray로 내보냅니다.

    자세한 내용은 OTel 엔드포인트 사용을 참조하세요.

AWS CloudWatch에서 OpenTelemetry 사용

AWS CloudWatch는 클라이언트 측 애플리케이션 계측 및 Application Signals, Trace, Map, Metrics, Logs와 같은 네이티브 AWS CloudWatch 서비스를 통해 OpenTelemetry 추적을 지원합니다. 자세한 내용은 OpenTelemetry를 참조하세요.

마이그레이션을 위한 OpenTelemetry 개념 이해

다음 표에서는 X-Ray 개념을 OpenTelemetry에 매핑합니다. 이러한 매핑을 이해하면 기존 X-Ray 계측을 OpenTelemetry로 변환하는 데 도움이 됩니다.

X-Ray 개념 OpenTelemetry 개념
X-Ray 레코더 추적기 공급자 및 추적기
서비스 플러그인 리소스 감지기
세그먼트 (서버) 범위
하위 세그먼트 (서버 아님) 범위
X-Ray 샘플링 규칙 OpenTelemetry 샘플링(사용자 지정 가능)
X-Ray 이미터 Span Exporter(사용자 지정 가능)
주석/메타데이터 속성
라이브러리 계측 라이브러리 계측
X-Ray 트레이스 컨텍스트 범위 컨텍스트
X-Ray 트레이스 컨텍스트 전파 W3C 추적 컨텍스트 전파
X-Ray 트레이스 샘플링 OpenTelemetry 트레이스 샘플링
N/A 범위 처리
N/A 와이너리
X-Ray 데몬 OpenTelemetry Collector
참고

OpenTelemetry 개념에 대한 자세한 내용은 OpenTelemetry 설명서를 참조하세요.

기능 비교

다음 표에는 두 서비스에서 지원되는 기능이 나와 있습니다. 이 정보를 사용하여 마이그레이션 중에 해결해야 할 격차를 식별합니다.

Feature X-Ray 계측 OpenTelemetry 계측
라이브러리 계측 지원 지원
X-Ray 샘플링 지원

OTel Java/에서 지원됩니다.NET/Go

ADOT Java/에서 지원됩니다.NET/Python/Node.js
X-Ray 추적 컨텍스트 전파 지원 지원
리소스 감지 지원 지원
세그먼트 주석 지원 지원
세그먼트 메타데이터 지원 지원
제로 코드 자동 계측 Java에서 지원됨

OTel Java/에서 지원됩니다.NET/Python/Node.js

ADOT Java/에서 지원됩니다.NET/Python/Node.js
수동으로 생성 추적 지원 지원

추적 설정 및 구성

OpenTelemetry에서 트레이스를 생성하려면 트레이서가 필요합니다. 애플리케이션에서 추적기 공급자를 초기화하여 추적기를 가져옵니다. 이는 X-Ray 레코더를 사용하여 X-Ray를 구성하고 X-Ray 트레이스에서 세그먼트 및 하위 세그먼트를 생성하는 방법과 유사합니다.

참고

OpenTelemetry Tracer Provider는 X-Ray 레코더보다 더 많은 구성 옵션을 제공합니다.

트레이스 데이터 구조 이해

기본 개념과 기능 매핑을 이해한 후 트레이스 데이터 구조 및 샘플링과 같은 특정 구현 세부 정보에 대해 알아볼 수 있습니다.

OpenTelemetry는 세그먼트 및 하위 세그먼트 대신 스팬을 사용하여 트레이스 데이터를 구성합니다. 각 스팬에는 다음 구성 요소가 포함됩니다.

  • 명칭

  • 고유 ID

  • 시작 및 종료 타임스탬프

  • 스팬 종류

  • 범위 컨텍스트

  • 속성(키-값 메타데이터)

  • 이벤트(타임스탬프 처리된 로그)

  • 다른 스팬에 대한 링크

  • 상태 정보

  • 상위 범위 참조

OpenTelemetry로 마이그레이션하면 스팬이 자동으로 X-Ray 세그먼트 또는 하위 세그먼트로 변환됩니다. 이렇게 하면 기존 CloudWatch 콘솔 환경이 변경되지 않습니다.

스팬 속성 작업

X-Ray SDK는 세그먼트 및 하위 세그먼트에 데이터를 추가하는 두 가지 방법을 제공합니다.

Annotations

필터링 및 검색을 위해 인덱싱되는 키-값 페어

메타데이터

검색을 위해 인덱싱되지 않은 복잡한 데이터가 포함된 키-값 페어

기본적으로 OpenTelemetry 스팬 속성은 X-Ray 원시 데이터의 메타데이터로 변환됩니다. 대신 특정 속성을 주석으로 변환하려면 해당 키를 aws.xray.annotations 속성 목록에 추가합니다.

환경에서 리소스 감지

OpenTelemetry는 Resource Detectors를 사용하여 원격 측정 데이터를 생성하는 리소스에 대한 메타데이터를 수집합니다. 이 메타데이터는 리소스 속성으로 저장됩니다. 예를 들어 원격 측정을 생성하는 엔터티는 Amazon ECS 클러스터 또는 Amazon EC2 인스턴스일 수 있으며, 이러한 엔터티에서 기록할 수 있는 리소스 속성에는 Amazon ECS 클러스터 ARN 또는 Amazon EC2 인스턴스 ID가 포함될 수 있습니다.

샘플링 전략 관리

트레이스 샘플링은 모든 요청 대신 대표적인 요청 하위 집합에서 데이터를 수집하여 비용을 관리하는 데 도움이 됩니다. OpenTelemetry와 X-Ray 모두 샘플링을 지원하지만 다르게 구현합니다.

참고

트레이스를 100% 미만으로 샘플링하면 관찰성 비용이 절감되는 동시에 애플리케이션 성능에 대한 의미 있는 인사이트를 유지할 수 있습니다.

OpenTelemetry는 몇 가지 기본 제공 샘플링 전략을 제공하며 사용자 지정 샘플링 전략을 생성할 수 있습니다. OpenTelemetry에서 X-Ray 샘플링 규칙을 사용하도록 일부 SDK 언어로 X-Ray 원격 샘플러를 구성할 수도 있습니다.

OpenTelemetry의 추가 샘플링 전략은 다음과 같습니다.

  • 상위 기반 샘플링 - 추가 샘플링 전략을 적용하기 전에 상위 범위의 샘플링 결정을 준수합니다.

  • 트레이스 ID 비율 기반 샘플링 - >지정된 비율의 범위를 무작위로 샘플링합니다.

  • 테일 샘플링 - 샘플링 규칙을 적용하여 OpenTelemetry Collector에서 트레이스를 완료합니다.

  • 사용자 지정 샘플러 - 샘플링 인터페이스를 사용하여 자체 샘플링 로직 구현

X-Ray 샘플링 규칙에 대한 자세한 내용은 X-Ray 콘솔의 샘플링 규칙을 참조하세요.

OpenTelemetry 테일 샘플링에 대한 자세한 내용은 테일 샘플링 프로세서를 참조하세요.

추적 컨텍스트 관리

X-Ray SDKs 세그먼트 컨텍스트를 관리하여 트레이스에서 세그먼트와 하위 세그먼트 간의 상위-하위 관계를 올바르게 처리합니다. OpenTelemetry는 유사한 메커니즘을 사용하여 스팬에 올바른 상위 스팬이 있는지 확인합니다. 요청 컨텍스트 전체에 추적 데이터를 저장하고 전파합니다. 예를 들어 애플리케이션이 요청을 처리하고 해당 요청을 나타내는 서버 스팬을 생성하면 OpenTelemetry는 OpenTelemetry 컨텍스트에 서버 스팬을 저장하므로 하위 스팬이 생성될 때 해당 하위 스팬이 컨텍스트의 스팬을 상위로 참조할 수 있습니다.

추적 컨텍스트 전파

X-Ray 및 OpenTelemetry 모두 HTTP 헤더를 사용하여 서비스 간에 추적 컨텍스트를 전파합니다. 이를 통해 다양한 서비스에서 생성된 추적 데이터를 연결하고 샘플링 결정을 유지할 수 있습니다.

X-Ray SDK는 X-Ray 트레이스 헤더를 사용하여 트레이스 컨텍스트를 자동으로 전파합니다. 한 서비스가 다른 서비스를 호출하면 트레이스 헤더에는 트레이스 간 상위-하위 관계를 유지하는 데 필요한 컨텍스트가 포함됩니다.

OpenTelemetry는 컨텍스트 전파를 위해 다음을 포함한 여러 트레이스 헤더 형식을 지원합니다.

  • W3C 추적 컨텍스트(기본값)

  • X-Ray 트레이스 헤더

  • 기타 사용자 지정 형식

참고

하나 이상의 헤더 형식을 사용하도록 OpenTelemetry를 구성할 수 있습니다. 예를 들어 X-Ray 전파기를 사용하여 X-Ray 추적을 지원하는 AWS 서비스에 추적 컨텍스트를 전송합니다.

X-Ray 전파기를 구성하고 사용하여 AWS 서비스 간 추적을 활성화합니다. 이를 통해 트레이스 컨텍스트를 API Gateway 엔드포인트 및 X-Ray를 지원하는 기타 서비스에 전파할 수 있습니다.

라이브러리 계측 사용

X-Ray와 OpenTelemetry 모두 애플리케이션에 추적을 추가하기 위해 최소한의 코드 변경이 필요한 라이브러리 계측을 제공합니다.

X-Ray는 라이브러리 계측 기능을 제공합니다. 이를 통해 애플리케이션 코드 변경을 최소화하면서 사전 구축된 X-Ray 계측을 추가할 수 있습니다. 이러한 계측은 AWS SDK 및 HTTP 클라이언트와 같은 특정 라이브러리와 Spring Boot 또는 Express.js와 같은 웹 프레임워크를 지원합니다.

OpenTelemetry의 계측 라이브러리는 라이브러리 후크 또는 자동 코드 수정을 통해 라이브러리에 대한 세부 범위를 생성하므로 코드 변경이 최소화됩니다.

OpenTelemetry의 Library Instrumentations가 라이브러리를 지원하는지 확인하려면 OpenTelemetry Registry의 OpenTelemetry Registry에서 라이브러리를 검색합니다.

트레이스 내보내기

X-Ray 및 OpenTelemetry는 다양한 방법을 사용하여 트레이스 데이터를 내보냅니다.

X-Ray 트레이스 내보내기

X-Ray SDKs 사용하여 추적 데이터를 전송합니다.

  • 세그먼트 및 하위 세그먼트를 X-Ray 데몬으로 보냅니다.

  • 비차단 I/O에 UDP 사용

  • SDK에서 기본적으로 구성됨

OpenTelemetry 트레이스 내보내기

OpenTelemetry는 구성 가능한 Span Exporters를 사용하여 추적 데이터를 전송합니다.

  • http/protobuf 또는 grpc 프로토콜 사용

  • OpenTelemetry Collector 또는 CloudWatch Agent에서 모니터링하는 엔드포인트로 범위를 내보냅니다.

  • 사용자 지정 내보내기 구성 허용

추적 처리 및 전달

X-Ray와 OpenTelemetry는 모두 추적 데이터를 수신, 처리 및 전달할 구성 요소를 제공합니다.

X-Ray 트레이스 처리

X-Ray 데몬은 트레이스 처리를 처리합니다.

  • X-Ray SDKs에서 UDP 트래픽 수신 대기

  • 세그먼트 및 하위 세그먼트 배치 처리

  • X-Ray 서비스에 배치 업로드

OpenTelemetry 트레이스 처리

OpenTelemetry Collector는 추적 처리를 처리합니다.

  • 계측된 서비스에서 트레이스를 수신합니다.

  • 추적 데이터를 처리하고 선택적으로 수정합니다.

  • 처리된 트레이스를 X-Ray를 포함한 다양한 백엔드로 전송합니다.

참고

AWS CloudWatch Agent는 OpenTelemetry 추적을 수신하여 X-Ray로 전송할 수도 있습니다. 자세한 내용은 OpenTelemetry를 사용하여 지표 및 추적 수집을 참조하세요.

스팬 처리(OpenTelemetry별 개념)

OpenTelemetry는 스팬 프로세서를 사용하여 스팬이 생성될 때 스팬을 수정합니다.

  • 생성 또는 완료 시 스팬 읽기 및 수정 허용

  • 범위 처리를 위한 사용자 지정 로직을 활성화합니다.

소행성(OpenTelemetry-soecific 개념)

OpenTelemetry의 도우미 기능을 사용하면 키-값 데이터를 전파할 수 있습니다.

  • 추적 컨텍스트와 함께 임의의 데이터를 전달할 수 있습니다.

  • 애플리케이션별 정보를 서비스 경계에 전파하는 데 유용합니다.

OpenTelemetry Collector에 대한 자세한 내용은 OpenTelemetry Collector를 참조하세요.

X-Ray 개념에 대한 자세한 내용은 X-Ray 개발자 안내서의 X-Ray 개념을 참조하세요.

마이그레이션 개요

이 섹션에서는 마이그레이션에 필요한 코드 변경 사항에 대한 개요를 제공합니다. 아래 목록은 언어별 지침 및 X-Ray 데몬 마이그레이션 단계입니다.

중요

X-Ray 계측에서 OpenTelemetry 계측으로 완전히 마이그레이션하려면 다음을 수행해야 합니다.

  1. X-Ray SDK 사용량을 OpenTelemetry 솔루션으로 대체

  2. X-Ray 데몬을 CloudWatch 에이전트 또는 OpenTelemetry Collector로 교체(X-Ray Exporter 사용)

신규 및 기존 애플리케이션에 대한 권장 사항

신규 및 기존 애플리케이션의 경우 다음 솔루션을 사용하여 애플리케이션에서 추적을 활성화하는 것이 좋습니다.

계측

  • OpenTelemetry SDKs

  • AWS OpenTelemetry 계측용 배포판

데이터 수집

  • OpenTelemetry Collector

  • CloudWatch 에이전트

OpenTelemetry 기반 솔루션으로 마이그레이션한 후에도 CloudWatch 환경은 동일하게 유지됩니다. CloudWatch 콘솔의 트레이스 및 트레이스 맵 페이지에서 동일한 형식으로 트레이스를 보거나 X-Ray APIs를 통해 트레이스 데이터를 검색할 수 있습니다.

설정 변경 내용 추적

X-Ray 설정을 OpenTelemetry 설정으로 바꿔야 합니다.

X-Ray 및 OpenTelemetry 설정 비교
Feature X-Ray SDK OpenTelemetry
기본 구성

  • X-Ray 중앙 집중식 샘플링

  • X-Ray 추적 컨텍스트 전파

  • X-Ray 데몬으로 트레이스 내보내기

  • OpenTelemetry Collector 또는 CloudWatch Agent(HTTP/gRPC)로 트레이스 내보내기

  • W3C 추적 컨텍스트 전파
수동 구성

  • 로컬 샘플링 규칙

  • 리소스 감지 플러그인

  • X-Ray 샘플링(일부 언어에서는 제공되지 않을 수 있음)

  • 리소스 감지

  • X-Ray 추적 컨텍스트 전파

라이브러리 계측 변경 사항

AWS SDK, HTTP 클라이언트, 웹 프레임워크 및 기타 라이브러리용 X-Ray 라이브러리 계측 대신 OpenTelemetry Library 계측을 사용하도록 코드를 업데이트합니다. 그러면 X-Ray 추적 대신 OpenTelemetry 추적이 생성됩니다.

참고

코드 변경 사항은 언어와 라이브러리에 따라 다릅니다. 자세한 지침은 언어별 마이그레이션 가이드를 참조하세요.

Lambda 환경 계측 변경 사항

Lambda 함수에서 OpenTelemetry를 사용하려면 다음 설정 옵션 중 하나를 선택합니다.

  1. 자동 계측 Lambda 계층 사용:

  2. Lambda 함수에 대한 OpenTelemetry를 수동으로 설정합니다.

    • X-Ray UDP 범위 내보내기를 사용하여 Simple Span 프로세서 구성

    • X-Ray Lambda 전파기 설정

추적 데이터 수동 생성

X-Ray 세그먼트 및 하위 세그먼트를 OpenTelemetry Spans로 바꿉니다.

  • OpenTelemetry Tracer를 사용하여 스팬 생성

  • Spans에 속성 추가(X-Ray 메타데이터 및 주석과 동일)

중요

X-Ray로 전송하는 경우:

  • 서버 범위를 X-Ray 세그먼트로 변환

  • 다른 스팬은 X-Ray 하위 세그먼트로 변환됩니다.

  • 속성은 기본적으로 메타데이터로 변환됩니다.

속성을 주석으로 변환하려면 해당 키를 aws.xray.annotations 속성 목록에 추가합니다. 자세한 내용은 사용자 지정 X-Ray 주석 활성화를 참조하세요.

X-Ray 데몬에서 AWS CloudWatch 에이전트 또는 OpenTelemetry 수집기로 마이그레이션

CloudWatch 에이전트 또는 OpenTelemetry 수집기를 사용하여 계측된 애플리케이션에서 추적을 수신하여 X-Ray로 전송할 수 있습니다.

참고

CloudWatch 에이전트 버전 1.300025.0 이상은 OpenTelemetry 트레이스를 수집할 수 있습니다. X-Ray 데몬 대신 CloudWatch 에이전트를 사용하면 관리해야 하는 에이전트 수가 줄어듭니다. 자세한 내용은 CloudWatch 에이전트를 사용하여 지표, 로그 및 추적 수집을 참조하세요.

Amazon EC2 또는 온프레미스 서버에서 마이그레이션

중요

포트 충돌을 방지하기 위해 CloudWatch 에이전트 또는 OpenTelemetry 수집기를 사용하기 전에 X-Ray 데몬 프로세스를 중지합니다.

기존 X-Ray 데몬 설정

데몬 설치

기존 X-Ray 데몬 사용량은 다음 방법 중 하나를 사용하여 설치되었습니다.

수동 설치

X-Ray 데몬 Amazon S3 버킷에서 실행 파일을 다운로드하고 실행합니다.

자동 설치

이 스크립트를 사용하여 인스턴스를 시작할 때 데몬을 설치합니다.

#!/bin/bash
curl https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm \
    -o /home/ec2-user/xray.rpm
yum install -y /home/ec2-user/xray.rpm
데몬 구성

기존 X-Ray 데몬 사용량은 다음 중 하나를 사용하여 구성되었습니다.

  • 명령줄 인수

  • 구성 파일(xray-daemon.yaml)

예 구성 파일 사용
./xray -c ~/xray-daemon.yaml
데몬 실행

기존 X-Ray 데몬 사용이 다음 명령으로 시작되었습니다.

~/xray-daemon$ ./xray -o -n us-east-1
데몬 제거

Amazon EC2 인스턴스에서 X-Ray 데몬을 제거하려면:

  1. 데몬 서비스를 중지합니다.

    systemctl stop xray

  2. 구성 파일을 삭제합니다.

    rm ~/path/to/xray-daemon.yaml

  3. 구성된 경우 로그 파일을 제거합니다.

    참고

    로그 파일 위치는 구성에 따라 다릅니다.

    • 명령줄 구성: /var/log/xray-daemon.log

    • 구성 파일: LogPath 설정 확인

CloudWatch 에이전트 설정

에이전트 설치

설치 지침은 온프레미스 서버에 CloudWatch 에이전트 설치를 참조하세요.

에이전트 구성

  1. 구성 파일을 생성하여 추적 수집을 활성화합니다. 자세한 내용은 CloudWatch 에이전트 구성 파일 생성을 참조하세요.

  2. IAM 권한 설정:

    • IAM 역할을 연결하거나 에이전트의 자격 증명을 지정합니다. 자세한 내용은 IAM 역할 설정을 참조하세요.

    • 역할 또는 자격 증명에 xray:PutTraceSegments 권한이 포함되어 있는지 확인합니다.

에이전트 시작

에이전트를 시작하는 지침은 명령줄을 사용하여 CloudWatch 에이전트 시작을 참조하세요.

OpenTelemetry 수집기 설정

수집기 설치

운영 체제용 OpenTelemetry 수집기를 다운로드하여 설치합니다. 지침은 수집기 설치를 참조하세요.

수집기 구성

수집기에서 다음 구성 요소를 구성합니다.

  • awsproxy 확장

    X-Ray 샘플링에 필요

  • OTel 수신기

    애플리케이션에서 추적을 수집합니다.

  • Xray 내보내기

    추적을 X-Ray로 전송합니다.

예 샘플 수집기 구성 - otel-collector-config.yaml
extensions:
  awsproxy:
    endpoint: 127.0.0.1:2000
  health_check:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 127.0.0.1:4317
      http:
        endpoint: 127.0.0.1:4318

processors:
  batch:

exporters:
  awsxray:
    region: 'us-east-1'

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [awsxray]
  extensions: [awsproxy, health_check]
중요

xray:PutTraceSegments 권한을 사용하여 AWS 자격 증명을 구성합니다. 자세한 내용은 자격 증명 지정을 참조하세요.

수집기 시작

구성 파일을 사용하여 수집기를 실행합니다.

otelcol --config=otel-collector-config.yaml

Amazon ECS에서 마이그레이션

중요

작업 역할에는 사용하는 수집기에 대한 xray:PutTraceSegments 권한이 있어야 합니다.

포트 충돌을 방지하기 위해 동일한 호스트에서 CloudWatch 에이전트 또는 OpenTelemetry 수집기 컨테이너를 실행하기 전에 기존 X-Ray 데몬 컨테이너를 중지합니다.

CloudWatch 에이전트 사용

  1. Amazon ECR 퍼블릭 갤러리에서 도커 이미지를 가져옵니다.

  2. 라는 구성 파일을 생성합니다cw-agent-otel.json.

    {
  "traces": {
    "traces_collected": {
      "xray": {
        "tcp_proxy": {
          "bind_address": "0.0.0.0:2000"
        }
      },
      "otlp": {
        "grpc_endpoint": "0.0.0.0:4317",
        "http_endpoint": "0.0.0.0:4318"
      }
    }
  }
}

  3. Systems Manager Parameter Store에 구성을 저장합니다.

    1. https://console.aws.amazon.com/systems-manager/ 엽니다.

    2. 파라미터 생성을 선택합니다.

    3. 다음 값을 입력합니다.

      • 이름: /ecs/cwagent/otel-config

      • 티어: 표준

      • 유형: 문자열

      • 데이터 유형: 텍스트

      • 값: [여기에 cw-agent-otel.json 구성 붙여넣기]

  4. 브리지 네트워크 모드를 사용하여 작업 정의를 생성합니다.

    사용하는 네트워크 모드에 따라 작업 정의의 구성이 달라집니다. 기본값은 브리지 네트워킹이며, 기본 VPC에서 사용할 수 있습니다. 브리지 네트워크에서 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT환경 변수를 설정하여 OpenTelemetry SDK에 CloudWatch 에이전트의 엔드포인트와 포트를 알려줍니다. 또한 애플리케이션의 OpenTelemetry SDK에서 Collector 컨테이너로 트레이스를 전송하려면 애플리케이션 컨테이너에서 Collector 컨테이너로 연결되는 링크를 생성해야 합니다.

    예 CloudWatch 에이전트 작업 정의
    {
    "containerDefinitions": [
        {
            "name": "cwagent",
            "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest",
            "portMappings": [
                {
                    "containerPort": 4318,
                    "hostPort": 4318,
                    "protocol": "tcp"
                },
                {
                    "containerPort": 4317,
                    "hostPort": 4317,
                    "protocol": "tcp"
                },
                {
                    "containerPort": 2000,
                    "hostPort": 2000,
                    "protocol": "tcp"
                }
            ],
            "secrets": [
                {
                    "name": "CW_CONFIG_CONTENT",
                    "valueFrom": "/ecs/cwagent/otel-config"
                }
            ]
        },
        {
            "name": "application",
            "image": "APPLICATION_IMAGE",
            "links": ["cwagent"],
            "environment": [
                {
                    "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
                    "value": "http://cwagent:4318/v1/traces"
                }
            ]
        }
    ]
}

자세한 내용은 Amazon ECS에서 Amazon EC2 인스턴스 수준 지표를 수집하도록 CloudWatch 에이전트 배포를 참조하세요.

OpenTelemetry 수집기 사용

  1. Docker Hubotel/opentelemetry-collector-contrib에서 Docker 이미지를 가져옵니다. https://hub.docker.com/r/otel/opentelemetry-collector-contrib

  2. Amazon EC2 수집기 구성 섹션에 표시된 것과 동일한 콘텐츠를 otel-collector-config.yaml 사용하여 라는 구성 파일을 생성하되 대신를 사용하도록 엔드포인트를 업데이트0.0.0.0합니다127.0.0.1.

  3. Amazon ECS에서이 구성을 사용하려면 Systems Manager Parameter Store에 구성을 저장할 수 있습니다. 먼저 Systems Manager Parameter Store 콘솔로 이동하여 새 파라미터 생성을 선택합니다. 다음 정보를 사용하여 새 파라미터를 생성합니다.

    • 이름: /ecs/otel/config(이 이름은 수집기의 작업 정의에서 참조됨)

    • 티어: 표준

    • 유형: 문자열

    • 데이터 유형: 텍스트

    • 값: [여기에 otel-collector-config.yaml 구성 붙여넣기]

  4. 브리지 네트워크 모드를 예로 사용하여 OpenTelemetry 수집기를 배포하는 작업 정의를 생성합니다.

    작업 정의에서 구성은 사용하는 네트워킹 모드에 따라 달라집니다. 기본값은 브리지 네트워킹이며, 기본 VPC에서 사용할 수 있습니다. 브리지 네트워크에서 OpenTelemetry SDK에 OpenTelemetry OpenTelemetry Collector의 엔드포인트와 포트를 알리도록 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 환경 변수를 설정합니다. 또한 애플리케이션의 OpenTelemetry SDK에서 Collector 컨테이너로 트레이스를 전송하려면 애플리케이션 컨테이너에서 Collector 컨테이너로 연결되는 링크를 생성해야 합니다.

    예 OpenTelemetry 수집기 작업 정의
    {
    "containerDefinitions": [
        {
            "name": "otel-collector",
            "image": "otel/opentelemetry-collector-contrib",
            "portMappings": [
                {
                    "containerPort": 2000,
                    "hostPort": 2000
                },
                {
                    "containerPort": 4317,
                    "hostPort": 4317
                },
                {
                    "containerPort": 4318,
                    "hostPort": 4318
                }
            ],
            "command": [
                "--config",
                "env:SSM_CONFIG"
            ],
            "secrets": [
                {
                    "name": "SSM_CONFIG",
                    "valueFrom": "/ecs/otel/config"
                }
            ]
        },
        {
            "name": "application",
            "image": "APPLICATION_IMAGE",
            "links": ["otel-collector"],
            "environment": [
                {
                    "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
                    "value": "http://otel-collector:4318/v1/traces"
                }
            ]
        }
    ]
}

Elastic Beanstalk에서 마이그레이션

중요

포트 충돌을 방지하기 위해 CloudWatch 에이전트를 사용하기 전에 X-Ray 데몬 프로세스를 중지합니다.

기존 X-Ray 데몬 통합은 Elastic Beanstalk 콘솔을 사용하거나 구성 파일로 애플리케이션 소스 코드에서 X-Ray 데몬을 구성하여 활성화되었습니다.

CloudWatch 에이전트 사용

Amazon Linux 2 플랫폼에서 구성 파일을 사용하여 CloudWatch 에이전트를 .ebextensions 구성합니다.

  1. 프로젝트 루트.ebextensions에 라는 디렉터리 생성

  2. 디렉터리 cloudwatch.config 내에 다음 콘텐츠.ebextensions가 포함된 라는 파일을 생성합니다.

    files:
  "/opt/aws/amazon-cloudwatch-agent/etc/config.json":
    mode: "0644"
    owner: root
    group: root
    content: |
      {
        "traces": {
          "traces_collected": {
            "otlp": {
              "grpc_endpoint": "12.0.0.1:4317",
              "http_endpoint": "12.0.0.1:4318"
            }
          }
        }
      }
container_commands:
  start_agent:
    command: /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -c file:/opt/aws/amazon-cloudwatch-agent/etc/config.json -s

  3. 배포 시 애플리케이션 소스 번들에 .ebextensions 디렉터리 포함

Elastic Beanstalk 구성 파일에 대한 자세한 내용은 구성 파일을 사용한 고급 환경 사용자 지정을 참조하세요.