기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS X-Ray Python용 SDK
**참고**
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.
Python용 X-Ray SDK는 트레이스 데이터를 생성하고 X-Ray 대몬(daemon)에 보내기 위한 클래스 및 메서드를 제공하는 Python 웹 애플리케이션용 라이브러리 집합입니다. 트레이스 데이터에는 애플리케이션에서 제공하는 수신 HTTP 요청과 애플리케이션이 AWS SDK, HTTP 클라이언트 또는 SQL 데이터베이스 커넥터를 사용하여 다운스트림 서비스에 수행하는 호출에 대한 정보가 포함됩니다. 또한 수동으로 세그먼트를 생성하고 디버그 정보를 주석 및 메타데이터에 추가할 수도 있습니다.
`pip`로 SDK를 다운로드할 수 있습니다.
```
$ pip install aws-xray-sdk
```
**참고**
Python용 X-Ray SDK는 오픈 소스 프로젝트입니다. 프로젝트를 따르고 GitHub([github.com/aws/aws-xray-sdk-python](https://github.com/aws/aws-xray-sdk-python))에서 문제 및 풀 요청을 제출할 수 있습니다.
Django 또는 Flask를 사용하는 경우 [ SDK 미들웨어를 애플리케이션에 추가하는 것부터](xray-sdk-python-middleware.md) 시작하여 수신 요청을 추적합니다. 미들웨어는 각 트레이스 요청에 대한 [세그먼트](xray-concepts.md#xray-concepts-segments)를 생성하고, 응답이 전송되면 세그먼트를 완료합니다. 세그먼트가 열려 있는 동안에는 SDK 클라이언트의 메서드를 이용해 정보를 세그먼트에 추가하고 하위 세그먼트를 만들어 다운스트림 호출을 트레이스할 수 있습니다. 또한 SDK는 세그먼트가 열려 있는 동안 애플리케이션에서 발생하는 예외를 자동으로 기록합니다. 다른 애플리케이션의 경우 [세그먼트를 수동으로 만들 수 있습니다](xray-sdk-python-middleware.md#xray-sdk-python-middleware-manual).
계측되는 애플리케이션 또는 서비스에 의해 호출되는 Lambda 함수의 경우, Lambda는 [추적 헤더](xray-concepts.md#xray-concepts-tracingheader)를 읽고 샘플링된 요청을 자동으로 추적합니다. 그 밖의 함수의 경우 수신 요청을 샘플링 및 추적하도록 [Lambda를 구성](xray-services-lambda.md)합니다. 어느 경우든, Lambda는 세그먼트를 생성하여 X-Ray SDK에 제공합니다.
**참고**
Lambda의 X-Ray SDK는 선택 사항입니다. 이를 함수에 사용하지 않는 경우 여전히 서비스 맵에 Lambda 서비스용 노드와 각 Lambda 함수용 노트 하나가 포함됩니다. SDK를 추가하면 함수 코드를 계측하여 Lambda에 의해 기록되는 함수 세그먼트에 하위 세그먼트를 추가할 수 있습니다. 자세한 정보는 [AWS Lambda 및 AWS X-Ray](xray-services-lambda.md)을 참조하세요.
Lambda로 계측된 Python 함수의 예는 [작업자](scorekeep-lambda.md#scorekeep-lambda-worker)을 참조하십시오.
다음으로 Python용 X-Ray SDK를 사용하여 [애플리케이션의 라이브러리를 패치함](xray-sdk-python-patching.md)으로써 다운스트림 호출을 구성합니다. SDK는 다음 라이브러리를 지원합니다.
**지원되는 라이브러리**
+ `[botocore](https://pypi.python.org/pypi/botocore)`, `[boto3](https://pypi.python.org/pypi/boto3)`- AWS SDK for Python (Boto) 클라이언트를 계측합니다.
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)` – Amazon DynamoDB 클라이언트의 PynamoDB 버전을 구성합니다.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)` — Python 클라이언트용 [비동기](https://docs.python.org/3/library/asyncio.html) 통합 SDK 버전을 구성합니다.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)` – 상위 HTTP 클라이언트를 구성합니다.
+ `[httplib](https://docs.python.org/2/library/httplib.html)`– [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html) - 하위 HTTP 클라이언트와 이러한 클라이언트를 사용하는 상위 라이브러리를 계측합니다.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)` – SQLite 클라이언트를 구성합니다.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)` – MySQL 클라이언트를 구성합니다.
+ `[pg8000](https://pypi.org/project/pg8000/)` – 순수 Python을 구성합니다.
+ `[psycopg2](https://pypi.org/project/psycopg2/)` – PostgreSQL 데이터베이스 어댑터를 구성합니다.
+ `[pymongo](https://pypi.org/project/pymongo/)` – MongoDB 클라이언트를 구성합니다.
+ `[pymysql](https://pypi.org/project/PyMySQL/)` – MySQL 및 MariaDB 클라이언트에 기반한 PyMySQL을 구성합니다.
애플리케이션이 AWS SQL 데이터베이스 또는 기타 HTTP 서비스를 호출할 때마다 SDK는 하위 세그먼트에 호출에 대한 정보를 기록합니다. 서비스 내에서 액세스하는 AWS 서비스 리소스는 트레이스 맵에 다운스트림 노드로 표시되어 개별 연결에서 오류 및 제한 문제를 식별하는 데 도움이 됩니다.
SDK를 사용하기 시작한 후에, [레코더와 미들웨어를 구성](xray-sdk-python-configuration.md)하여 SDK 동작을 구성하십시오. 플러그인을 추가해 애플리케이션을 실행하는 컴퓨팅 리소스에 대한 데이터를 기록하고, 샘플링 규칙을 정의해 샘플링 동작을 구성하고, 로그 레벨을 설정해 애플리케이션 로그의 SDK에서 표시되는 정보 수준을 조절할 수 있습니다.
요청에 대한 추가 정보와 애플리케이션이 [주석 및 메타데이터](xray-sdk-python-segment.md)에서 하는 작업을 기록합니다. 주석은 [필터 표현식](xray-console-filters.md)과 함께 사용할 수 있도록 인덱싱된 단순한 키 값 쌍이기 때문에, 특정 데이터를 포함한 트레이스를 검색할 수 있습니다. 메타데이터 항목은 제한이 적으며 JSON으로 직렬화할 수 있는 모든 객체와 어레이를 기록할 수 있습니다.
**주석 및 메타데이터**
주석 및 메타데이터는 X SDK를 사용하여 세그먼트에 추가하는 임의의 텍스트입니다. 주석은 필터 표현식에서 사용하기 위해 인덱싱됩니다. 메타데이터는 인덱싱되지 않지만 X-Ray 콘솔 또는 API를 사용하여 원시 세그먼트에서 볼 수 있습니다. X-Ray에 대한 읽기 액세스가 부여된 사용자는 누구나 이 데이터를 볼 수 있습니다.
코드에 구성된 클라이언트가 많이 있다면, 구성된 클라이언트로 만든 각 직접 호출의 하위 세그먼트를 대량으로 보관하는 요청 세그먼트 하나를 만들 수 있습니다. [사용자 지정 하위 세그먼트](xray-sdk-python-subsegments.md)의 클라이언트 호출을 래핑해 하위 세그먼트를 조직하고 그룹화할 수 있습니다. 전체 함수 또는 코드 섹션에 대한 사용자 지정 하위 세그먼트를 생성할 수 있습니다. 그런 다음 상위 세그먼트에 모든 것을 적는 대신 하위 세그먼트에 메타데이터 및 주석을 레코딩할 수 있습니다.
SDK의 클래스 및 메서드에 대한 참조 문서는 [AWS X-Ray SDK for Python API Reference](https://docs.aws.amazon.com/xray-sdk-for-python/latest/reference)를 참조하십시오.
## 요구 사항
Python용 X-Ray SDK는 다음 언어 및 라이브러리 버전을 지원합니다.
+ **Python** – 2.7, 3.4, 및 최신 버전
+ **Django** – 1.10 이상
+ **Flask** – 0.10 이상
+ **aiohttp** – 2.3.0 이상
+ **AWS SDK for Python (Boto)** – 1.4.0 이상
+ **botocore** – 1.5.0 이상
+ **enum** – 0.4.7 이상, Python 버전 3.4.0 이하인 경우
+ **jsonpickle** – 1.0.0 이상
+ **setuptools** – 40.6.3 이상
+ **wrapt** – 1.11.0 이상
## 종속성 관리
Python용 X-Ray SDK는 `pip`에서 사용할 수 있습니다.
+ **패키지** – `aws-xray-sdk`
SDK를 `requirements.txt` 파일에 종속성으로 추가합니다.
**Example requirements.txt**
```
aws-xray-sdk==2.4.2
boto3==1.4.4
botocore==1.5.55
Django==1.11.3
```
Elastic Beanstalk를 사용하여 애플리케이션을 배포하는 경우 Elastic Beanstalk은 `requirements.txt`의 모든 패키지를 자동으로 설치합니다.
# Python용 X-Ray SDK 구성
**참고**
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.
Python용 X-Ray SDK에는 전역 레코더를 제공하는 `xray_recorder`라는 클래스가 있습니다. 수신 HTTP 호출에 대해 세그먼트를 생성하는 미들웨어를 사용자 지정하도록 전역 레코더를 구성할 수 있습니다.
**Topics**
+ [서비스 플러그인](#xray-sdk-python-configuration-plugins)
+ [샘플링 규칙](#xray-sdk-python-configuration-sampling)
+ [로깅](#xray-sdk-python-configuration-logging)
+ [코드의 레코더 구성](#xray-sdk-python-middleware-configuration-code)
+ [Django의 레코더 구성](#xray-sdk-python-middleware-configuration-django)
+ [환경 변수](#xray-sdk-python-configuration-envvars)
## 서비스 플러그인
`plugins`을 사용하여 애플리케이션을 호스팅하는 서비스에 대한 정보를 기록할 수 있습니다.
**플러그인**
+ Amazon EC2 — `EC2Plugin`은 인스턴스 ID, 가용 영역 및 CloudWatch Logs 그룹을 추가합니다.
+ Elastic Beanstalk – `ElasticBeanstalkPlugin`이 환경 이름, 버전 레이블 및 배포 ID를 추가합니다.
+ Amazon ECS — `ECSPlugin`이 컨테이너 ID를 추가합니다.
![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/ko_kr/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png)
플러그인을 사용하려면 `xray_recorder`에서 `configure`를 호출합니다.
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
xray_recorder.configure(service='My app')
plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin')
xray_recorder.configure(plugins=plugins)
patch_all()
```
**참고**
`plugins`는 튜플로 전달되므로 단일 플러그인을 지정할 때는 반드시 후행 `,`를 포함해야 합니다. 예: `plugins = ('EC2Plugin',)`
또한 코드에 설정된 값보다 우선하는 [환경 변수](#xray-sdk-python-configuration-envvars)를 사용하여 레코더를 구성할 수 있습니다.
다운스트림 호출을 레코딩하도록 [라이브러리를 패치하기](xray-sdk-python-patching.md) 전에 플러그인을 구성합니다.
SDK는 플러그인 설정을 사용하여 세그먼트에 `origin` 필드를 설정하기도 합니다. 이는 애플리케이션을 실행하는 AWS 리소스 유형을 나타냅니다. 여러 플러그인을 사용하는 경우 SDK는 ElasticBeanstalk> EKS> ECS> EC2 순서로 확인하여 오리진을 결정합니다.
## 샘플링 규칙
SDK는 X-Ray 콘솔에서 정의하는 샘플링 규칙을 사용하여 기록할 요청을 결정합니다. 기본 규칙은 매초 첫 번째 요청을 추적하고, 모든 서비스에서 추가 요청의 5%를 X-Ray로 추적 전송합니다. [X-Ray 콘솔에서 추가 규칙을 생성](xray-console-sampling.md)하여 각 애플리케이션에 대해 기록되는 데이터의 양을 사용자 지정합니다.
SDK는 사용자 지정 규칙을 정의된 순서대로 적용합니다. 요청이 여러 사용자 지정 규칙과 일치하는 경우 SDK는 첫 번째 규칙만 적용합니다.
**참고**
SDK가 샘플링 규칙을 가져오기 위해 X-Ray에 연결할 수 없는 경우, 매초 첫 번째 요청과 호스트당 추가 요청의 5%에 대한 기본 로컬 규칙으로 되돌아갑니다. 호스트가 샘플링 API를 직접 호출할 수 있는 권한이 없거나, X-Ray 대몬(daemon)에 연결할 수 없을 경우 이러한 상황이 발생할 수 있고 이 대몬(daemon)은 SDK에서 수행한 API 직접 호출에 대한 TCP 프록시 역할을 합니다.
JSON 문서에서 샘플링 규칙을 불러오도록 SDK를 구성할 수도 있습니다. SDK는 X-Ray 샘플링을 사용할 수 없을 경우 로컬 규칙을 백업으로 사용하거나, 로컬 규칙을 전용으로 사용할 수 있습니다.
**Example sampling-rules.json**
```
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
이 예에서는 하나의 사용자 지정 규칙과 기본 규칙을 정의합니다. 사용자 지정 규칙은 최소 추적 요청 수 없이 5% 샘플링 비율을 `/api/move/` 아래 경로에 적용합니다. 기본 규칙은 매초 최초 요청과 추가 요청의 10%를 추적합니다.
로컬로 규칙의 정의할 때의 단점은 고정 대상이 X-Ray 서비스를 통해 관리되는 대신, 레코더의 각 인스턴스별로 독립적으로 적용된다는 것입니다. 호스트를 많이 배포할수록 고정 속도가 크게 증대하기 때문에 기록되는 데이터의 양을 제어하기가 어려워집니다.
에서는 샘플링 속도를 수정할 수 AWS Lambda없습니다. 구성된 서비스가 함수를 호출하는 경우 해당 서비스에서 샘플링한 요청을 생성한 호출이 Lambda에 의해 기록됩니다. 활성 추적이 활성화되고 트레이스 헤더가 없는 경우 Lambda에서 샘플링 결정을 내립니다.
백업 샘플링 규칙을 구성하려면 다음 예제와 같이 `xray_recorder.configure`를 호출합니다. 이 예제에서 *rules*는 규칙의 딕셔너리이거나 샘플링 규칙이 포함된 JSON 파일의 절대 경로입니다.
```
xray_recorder.configure(sampling_rules=rules)
```
로컬 규칙만 사용하려면 `LocalSampler`를 사용하여 레코더를 구성합니다.
```
from aws_xray_sdk.core.sampling.local.sampler import LocalSampler
xray_recorder.configure(sampler=LocalSampler())
```
또한 샘플링을 비활성하하고 모든 수신 요청을 구성하도록 전역 레코더를 구성할 수 있습니다.
**Example main.py – 샘플링 비활성화**
```
xray_recorder.configure(sampling=False)
```
## 로깅
SDK는 기본 `WARNING` 로깅 레벨이 있는 Python의 내장 `logging` 모듈을 사용합니다. `aws_xray_sdk` 클래스에 대한 로거 참조를 가져오고 이에 대해 `setLevel`을 호출하여 라이브러리 및 애플리케이션의 나머지에 대해 서로 다른 로그 레벨을 구성합니다.
**Example app.py – 로깅**
```
logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)
```
디버그 로그를 사용하여 [수동으로 하위 세그먼트를 생성](xray-sdk-python-subsegments.md)할 때 미완료 하위 세그먼트와 같은 문제를 식별할 수 있습니다.
## 코드의 레코더 구성
`xray_recorder`에 대한 `configure` 메서드에서 추가 설정을 사용할 수 있습니다.
+ `context_missing` – 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 `LOG_ERROR`로 설정합니다.
+ `daemon_address` – X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다.
+ `service` – SDK가 세그먼트에 사용하는 서비스 이름을 설정합니다.
+ `plugins` - 애플리케이션의 AWS 리소스에 대한 정보를 기록합니다.
+ `sampling` – 샘플링을 비활성화하려면 `False`로 설정합니다.
+ `sampling_rules` – [샘플링 규칙](#xray-sdk-python-configuration-sampling)이 포함된 JSON 파일의 경로를 설정합니다.
**Example main.py – 컨텍스트 누락 예외 비활성화**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(context_missing='LOG_ERROR')
```
## Django의 레코더 구성
Django 프레임워크를 사용하는 경우 Django `settings.py` 파일을 사용하여 전역 레코더의 옵션을 구성할 수 있습니다.
+ `AUTO_INSTRUMENT` (Django 전용) – 기본 제공 데이터베이스 및 템플릿 렌더링 작업을 위한 하위 세그먼트를 기록합니다.
+ `AWS_XRAY_CONTEXT_MISSING` – 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 `LOG_ERROR`로 설정합니다.
+ `AWS_XRAY_DAEMON_ADDRESS` – X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다.
+ `AWS_XRAY_TRACING_NAME` – SDK가 세그먼트에 사용하는 서비스 이름을 설정합니다.
+ `PLUGINS` - 애플리케이션의 AWS 리소스에 대한 정보를 기록합니다.
+ `SAMPLING` – 샘플링을 비활성화하려면 `False`로 설정합니다.
+ `SAMPLING_RULES` – [샘플링 규칙](#xray-sdk-python-configuration-sampling)이 포함된 JSON 파일의 경로를 설정합니다.
`settings.py`에서 레코더 구성을 활성화하려면 설치된 앱 목록에 Django 미들웨어를 추가합니다.
**Example settings.py – 설치된 앱**
```
INSTALLED_APPS = [
...
'django.contrib.sessions',
'aws_xray_sdk.ext.django',
]
```
이름이 `XRAY_RECORDER`인 dict에서 사용 가능한 설정을 구성합니다.
**Example settings.py – 설치된 앱**
```
XRAY_RECORDER = {
'AUTO_INSTRUMENT': True,
'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR',
'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000',
'AWS_XRAY_TRACING_NAME': 'My application',
'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'),
'SAMPLING': False,
}
```
## 환경 변수
환경 변수를 사용하여 Python용 X-Ray SDK를 구성할 수 있습니다. SDK는 다음 변수를 지원합니다:
+ `AWS_XRAY_TRACING_NAME` – SDK가 세그먼트에 사용하는 서비스 이름을 설정합니다. 프로그래밍 방식으로 설정한 서비스 이름을 재정의합니다.
+ `AWS_XRAY_SDK_ENABLED` – `false`로 설정하면 SDK가 비활성화됩니다. 이 환경 변수가 false로 설정되지 않은 한 SDK는 기본적으로 활성화됩니다.
+ 비활성화될 경우, 글로벌 레코더가 대몬(daemon)으로 전송되지 않는 더미 세그먼트 및 하위 세그먼트를 자동으로 생성하고 자동 패치가 비활성화됩니다. 미들웨어는 글로벌 레코더 위에 래퍼로 기록됩니다. 또한 미들웨어를 통한 세그먼트 및 하위 세그먼트 생성은 모두 더미 세그먼트와 더미 하위 세그먼트가 됩니다.
+ 환경 변수 또는 `aws_xray_sdk` 라이브러리에서 `global_sdk_config` 객체와 직접 상호 작용을 통해 `AWS_XRAY_SDK_ENABLED` 값을 설정합니다. 환경 변수에 대한 설정은 이러한 상호 작용을 재정의합니다.
+ `AWS_XRAY_DAEMON_ADDRESS` – X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다. 기본적으로 SDK는 추적 데이터(UDP)와 샘플링(TCP) 모두에 `127.0.0.1:2000`을 사용합니다. [다른 포트에서 수신 대기](xray-daemon-configuration.md)하도록 대몬(daemon)을 구성한 경우 또는 다른 호스트에서 실행 중인 경우 이 변수를 사용합니다.
**형식**
+ **동일한 포트** – `address:port`
+ **다른 포트** – `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING` – 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 `RUNTIME_ERROR`로 설정합니다.
**유효한 값**
+ `RUNTIME_ERROR`— 런타임 예외가 발생합니다.
+ `LOG_ERROR` – 오류를 기록하고 계속합니다 (기본값).
+ `IGNORE_ERROR`— 오류를 무시하고 계속합니다.
열린 요청이 없을 때 실행되는 시작 코드 또는 새 스레드를 생성하는 코드에서 계측된 클라이언트를 사용하려고 하는 경우 누락된 세그먼트 또는 하위 세그먼트와 관련된 오류가 발생할 수 있습니다.
환경 변수는 코드에 설정된 값을 재정의합니다.
# Python 미들웨어용 X-Ray SDK로 수신 요청 추적하기
**참고**
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.
미들웨어를 애플리케이션에 추가하고 세그먼트 이름을 구성하면 Python용 X-Ray SDK는 샘플링된 각 요청에 대해 세그먼트를 생성합니다. 이 세그먼트에는 HTTP 요청의 시간, 메서드 및 배치가 포함됩니다. 추가로 구성하면 이 세그먼트의 하위 세그먼트가 생성됩니다.
Python용 X-Ray SDK는 수신 HTTP 요청을 구성하기 위한 다음 미들웨어를 지원합니다.
+ Django
+ Flask
+ Bottle
**참고**
AWS Lambda 함수의 경우 Lambda는 샘플링된 각 요청에 대한 세그먼트를 생성합니다. 자세한 정보는 [AWS Lambda 및 AWS X-Ray](xray-services-lambda.md)을 참조하세요.
Lambda로 계측된 Python 함수의 예는 [작업자](scorekeep-lambda.md#scorekeep-lambda-worker)을 참조하십시오.
다른 프레임워크의 스크립트 또는 Python 애플리케이션의 경우, [세그먼트를 수동으로 만들 수 있습니다](#xray-sdk-python-middleware-manual).
각 세그먼트에는 서비스 맵 안에서 애플리케이션을 식별하는 이름이 있습니다. 이 세그먼트의 이름이 정적으로 지정되도록 하거나, 수신 요청의 호스트 헤더를 기반으로 SDK가 동적으로 이름을 지정하도록 구성할 수 있습니다. 동적 이름 지정을 사용하면 요청의 도메인 이름에 따라 그룹을 추적하고 이름이 예상 패턴과 일치하지 않을 경우(예: 호스트 헤더가 위조된 경우) 기본 이름을 적용할 수 있습니다.
**전달된 요청**
로드 밸런서 또는 기타 중개자가 애플리케이션으로 요청을 전달하는 경우, X-Ray는 IP 패킷 내 소스 IP가 아니라 요청의 `X-Forwarded-For` 헤더로부터 클라이언트 IP를 가져옵니다. 전달된 요청에 대해 기록된 클라어언트 IP는 위조될 수 있으므로 신뢰하면 안 됩니다.
요청이 전달되면 SDK는 세그먼트에 추가 필드를 설정하여 이를 나타냅니다. 세그먼트에 `x_forwarded_for`로 설정된 `true` 필드가 포함된 경우 클라이언트 IP는 HTTP 요청의 `X-Forwarded-For` 헤더로부터 가져옵니다.
미들웨어는 다음 정보를 포함하는 `http` 블록으로 각 수신 요청에 대한 세그먼트를 생성합니다.
+ **HTTP 메서드** – GET, POST, PUT, DELETE 등.
+ **클라이언트 주소** – 요청을 전송한 클라이언트의 IP 주소.
+ **응답 코드** – 완료된 요청의 HTTP 응답 코드.
+ **시간** – 시작 시간(요청 수신) 및 종료 시간(응답 전송).
+ **유저 에이전트** — 요청에서 가져온 `user-agent`입니다.
+ **콘텐츠 길이** — 응답의 `content-length`입니다.
**Topics**
+ [애플리케이션(Django)에 미들웨어 추가](#xray-sdk-python-adding-middleware-django)
+ [애플리케이션(Flask)에 미들웨어 추가](#xray-sdk-python-adding-middleware-flask)
+ [애플리케이션(Bottle)에 미들웨어 추가](#xray-sdk-python-adding-middleware-bottle)
+ [수동으로 Python 코드 구성](#xray-sdk-python-middleware-manual)
+ [세그먼트 이름 지정 전략 구성](#xray-sdk-python-middleware-naming)
## 애플리케이션(Django)에 미들웨어 추가
`MIDDLEWARE` 파일에서 `settings.py` 목록에 미들웨어를 추가합니다. 기타 미들웨어에서 실패한 요청이 레코딩되도록 X-Ray 미들웨어가 `settings.py` 파일에서 첫 번째 줄에 있어야 합니다.
**Example settings.py - Python 미들웨어용 X-Ray SDK**
```
MIDDLEWARE = [
'aws_xray_sdk.ext.django.middleware.XRayMiddleware',
'django.middleware.security.SecurityMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.common.CommonMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.clickjacking.XFrameOptionsMiddleware'
]
```
`settings.py` 파일의 `INSTALLED_APPS` 목록에 X-Ray SDK Django 앱을 추가하세요. 이렇게 하면 앱을 시작하는 동안 X-Ray 레코더를 구성할 수 있습니다.
**Example settings.py - Python Django 앱용 X-Ray SDK**
```
INSTALLED_APPS = [
'aws_xray_sdk.ext.django',
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
]
```
[`settings.py` 파일](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django)에서 세그먼트 이름을 구성합니다.
**Example settings.py – 세그먼트 이름**
```
XRAY_RECORDER = {
'AWS_XRAY_TRACING_NAME': 'My application',
'PLUGINS': ('EC2Plugin',),
}
```
이는 X-Ray 레코더가 기본 샘플링 속도로 Django 애플리케이션에서 제공하는 요청을 추적하도록 지시합니다. 사용자 지정 샘플링 규칙을 적용하거나 기타 설정을 변경하도록 [Django 설정 파일의 레코더를 구성](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django)할 수 있습니다.
**참고**
`plugins`는 튜플로 전달되므로 단일 플러그인을 지정할 때는 반드시 후행 `,`를 포함해야 합니다. 예: `plugins = ('EC2Plugin',)`
## 애플리케이션(Flask)에 미들웨어 추가
Flask 애플리케이션을 구성하려면 먼저 `xray_recorder`에서 세그먼트 이름을 구성해야 합니다. 그런 다음 `XRayMiddleware` 함수를 사용하여 Flask 애플리케이션을 코드로 패치합니다.
**Example app.py**
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
app = Flask(__name__)
xray_recorder.configure(service='My application')
XRayMiddleware(app, xray_recorder)
```
이는 X-Ray 레코더가 기본 샘플링 속도로 Flask 애플리케이션에서 제공하는 요청을 추적하도록 지시합니다. 사용자 지정 샘플링 규칙을 적용하거나 기타 설정을 변경하도록 [레코더를 코드로 구성](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code)할 수 있습니다.
## 애플리케이션(Bottle)에 미들웨어 추가
Bottle 애플리케이션을 구성하려면 먼저 `xray_recorder`에서 세그먼트 이름을 구성해야 합니다. 그런 다음 `XRayMiddleware` 함수를 사용하여 Bottle 애플리케이션을 코드로 패치합니다.
**Example app.py**
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.bottle.middleware import XRayMiddleware
app = Bottle()
xray_recorder.configure(service='fallback_name', dynamic_naming='My application')
app.install(XRayMiddleware(xray_recorder))
```
이는 X-Ray 레코더가 기본 샘플링 속도로 Bottle 애플리케이션에서 제공하는 요청을 추적하도록 지시합니다. 사용자 지정 샘플링 규칙을 적용하거나 기타 설정을 변경하도록 [레코더를 코드로 구성](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code)할 수 있습니다.
## 수동으로 Python 코드 구성
Django 또는 Flask를 사용하지 않는 경우 세그먼트를 수동으로 만들 수 있습니다. 수신되는 각 요청에 대해 세그먼트를 생성하거나 패치된 HTTP 또는 AWS SDK 클라이언트 주위에 세그먼트를 생성하여 레코더가 하위 세그먼트를 추가할 컨텍스트를 제공할 수 있습니다.
**Example main.py – 수동 구성**
```
from aws_xray_sdk.core import xray_recorder
# Start a segment
segment = xray_recorder.begin_segment('segment_name')
# Start a subsegment
subsegment = xray_recorder.begin_subsegment('subsegment_name')
# Add metadata and annotations
segment.put_metadata('key', dict, 'namespace')
subsegment.put_annotation('key', 'value')
# Close the subsegment and segment
xray_recorder.end_subsegment()
xray_recorder.end_segment()
```
## 세그먼트 이름 지정 전략 구성
AWS X-Ray 는 *서비스 이름을* 사용하여 애플리케이션을 식별하고 애플리케이션이 사용하는 다른 애플리케이션, 데이터베이스, 외부 APIs 및 AWS 리소스와 구분합니다. X-Ray SDK는 수신 요청에 대한 세그먼트를 생성할 때 해당 세그먼트의 [이름 필드](xray-api-segmentdocuments.md#api-segmentdocuments-fields)에 애플리케이션의 서비스 이름을 기록합니다.
X-Ray SDK는 HTTP 요청 헤더의 호스트 이름 뒤에 세그먼트를 지정할 수 있습니다. 그러나 이 헤더가 위조되면 서비스 맵에 예기치 않은 노드가 발생할 수 있습니다. 위조된 호스트 헤더가 포함된 요청으로 인해 SDK가 잘못된 세그먼트 이름을 지정하는 현상을 방지하려면 들어오는 요청의 기본 이름을 지정해야 합니다.
애플리케이션이 여러 도메인의 요청을 처리하는 경우, 동적 이름 지정 전략을 사용하여 이를 세그먼트 이름에 반영하도록 SDK를 구성할 수 있습니다. 동적 이름 지정 전략을 사용하면 SDK가 예상 패턴과 일치하는 요청에 호스트 이름을 사용하고, 그렇지 않은 요청에 기본 이름을 적용할 수 있습니다.
예를 들어, 하나의 애플리케이션이 세 개의 하위 도메인 (`www.example.com`, `api.example.com`, `static.example.com`) 에 요청을 전송할 수 있습니다. `*.example.com` 패턴으로 동적 이름 지정 전략을 사용하여 각 하위도메인의 세그먼트를 서로 다른 이름으로 표시하면 서비스 맵에 서비스 노드가 세 개 생깁니다. 이 패턴에 맞지 않는 호스트 이름의 요청이 애플리케이션에 수신되면, 사용자가 지정한 대체 이름의 네 번째 노드가 서비스 맵에 표시됩니다.
모든 요청 세그먼트에 같은 이름을 사용하려면 [이전 섹션](#xray-sdk-python-adding-middleware-django)에 나온 것처럼 레코더를 구성할 때 애플리케이션 이름을 지정합니다.
동적 이름 지정 전략은 호스트 이름이 일치해야 하는 패턴 및 HTTP 요청의 호스트 이름이 패턴과 일치하지 않는 경우 사용할 기본 이름을 정의합니다. Django에서 동적으로 세그먼트에 이름을 지정하려면 `DYNAMIC_NAMING` 설정을 [settings.py](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django) 파일에 추가합니다.
**Example settings.py – 동적 이름 지정**
```
XRAY_RECORDER = {
'AUTO_INSTRUMENT': True,
'AWS_XRAY_TRACING_NAME': 'My application',
'DYNAMIC_NAMING': '*.example.com',
'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin')
}
```
패턴에서 '\$1'를 사용하여 문자열을 일치시키거나 '?'를 사용하여 단일 문자를 일치시킬 수 있습니다. Flask의 경우 [ 레코더를 코드로 구성합니다](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code).
**Example main.py – 세그먼트 이름**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='My application')
xray_recorder.configure(dynamic_naming='*.example.com')
```
**참고**
코드에 정의한 기본 서비스 이름을 `AWS_XRAY_TRACING_NAME` [환경 변수](xray-sdk-python-configuration.md#xray-sdk-python-configuration-envvars)를 사용하여 재정의할 수 있습니다.
# 다운스트림 호출 구성을 위해 라이브러리 패치
**참고**
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.
다운스트림 호출을 구성하려면 Python용 X-Ray SDK를 사용하여 애플리케이션이 사용하는 라이브러리를 패치합니다. Python용 X-Ray SDK는 다음 라이브러리를 패치할 수 있습니다.
**지원되는 라이브러리**
+ `[botocore](https://pypi.python.org/pypi/botocore)`, `[boto3](https://pypi.python.org/pypi/boto3)`- AWS SDK for Python (Boto) 클라이언트를 계측합니다.
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)` – Amazon DynamoDB 클라이언트의 PynamoDB 버전을 구성합니다.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)` — Python 클라이언트용 [비동기](https://docs.python.org/3/library/asyncio.html) 통합 SDK 버전을 구성합니다.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)` – 상위 HTTP 클라이언트를 구성합니다.
+ `[httplib](https://docs.python.org/2/library/httplib.html)`– [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html) - 하위 HTTP 클라이언트와 이러한 클라이언트를 사용하는 상위 라이브러리를 계측합니다.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)` – SQLite 클라이언트를 구성합니다.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)` – MySQL 클라이언트를 구성합니다.
+ `[pg8000](https://pypi.org/project/pg8000/)` – 순수 Python을 구성합니다.
+ `[psycopg2](https://pypi.org/project/psycopg2/)` – PostgreSQL 데이터베이스 어댑터를 구성합니다.
+ `[pymongo](https://pypi.org/project/pymongo/)` – MongoDB 클라이언트를 구성합니다.
+ `[pymysql](https://pypi.org/project/PyMySQL/)` – MySQL 및 MariaDB 클라이언트에 기반한 PyMySQL을 구성합니다.
패치된 라이브러리를 사용하면 Python용 X-Ray SDK는 직접 호출에 대한 하위 세그먼트를 생성하고 요청 및 응답의 정보를 기록합니다. SDK가 SDK 미들웨어 또는 AWS Lambda에서 하위 세그먼트를 생성하려면 세그먼트를 사용할 수 있어야 합니다.
**참고**
SQLAlchemy ORM을 사용하는 경우, SQLAlchemy 세션의 SDK 버전과 쿼리 클래스를 가져와서 SQL 쿼리를 구성할 수 있습니다. 지침은 [SQLAlchemy ORM 사용](https://github.com/aws/aws-xray-sdk-python/blob/master/README.md#use-sqlalchemy-orm)을 참조하십시오.
사용 가능한 모든 라이브러리를 패치하려면 `aws_xray_sdk.core`에서 `patch_all` 함수를 사용합니다. `httplib` 및 `urllib`와 같은 일부 라이브러리는 `patch_all(double_patch=True)`을 호출하여 이중 패치 적용을 활성화해야 할 수 있습니다 .
**Example main.py – 지원되는 모든 라이브러리 패치**
```
import boto3
import botocore
import requests
import sqlite3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all()
```
단일 라이브러리에 패치를 적용하려면 라이브러리 이름의 튜플을 사용하여 `patch`를 호출합니다. 이를 위해서는 단일 요소 목록을 제공해야 합니다.
**Example main.py – 특정 라이브러리 패치**
```
import boto3
import botocore
import requests
import mysql-connector-python
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch
libraries = (['botocore'])
patch(libraries)
```
**참고**
라이브러리를 패치하는 데 사용한 키가 라이브러리 이름과 맞지 않는 경우도 있습니다. 일부 키는 하나 이상의 라이브러리에 대해 별칭 역할을 합니다.
`httplib` – `[httplib](https://docs.python.org/2/library/httplib.html)` 및 [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html)
`mysql` – `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`
## 비동기 작업에 대한 컨텍스트 추적
`asyncio` 통합 라이브러리의 경우 또는 [비동기 함수에 대한 하위 세그먼트를 생성](xray-sdk-python-subsegments.md)하려면 비동기 컨텍스트를 사용하여 Python용 X-Ray SDK도 구성해야 합니다. `AsyncContext` 클래스를 가져와서 이 클래스의 인스턴스를 X-Ray 레코더에 전달합니다.
**참고**
AIOHTTP와 같은 웹 프레임워크 지원 라이브러리는 `aws_xray_sdk.core.patcher` 모듈을 통해 처리되지 않습니다. 이들은 지원되는 라이브러리의 `patcher` 카탈로그에 나타나지 않습니다.
**Example main.py – aioboto3 패치**
```
import asyncio
import aioboto3
import requests
from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())
from aws_xray_sdk.core import patch
libraries = (['aioboto3'])
patch(libraries)
```
# Python용 X-Ray AWS SDK를 사용하여 SDK 호출 추적
**참고**
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.
애플리케이션이를 호출 AWS 서비스 하여 데이터를 저장하거나, 대기열에 쓰거나, 알림을 보내면 Python용 X-Ray SDK는 [하위 세그먼트](xray-sdk-python-subsegments.md)의 다운스트림 호출을 추적합니다. 해당 서비스(예: Amazon S3 버킷 또는 Amazon SQS 대기열) 내에서 액세스하는 추적 AWS 서비스 및 리소스는 X-Ray 콘솔의 추적 맵에 다운스트림 노드로 표시됩니다.
Python용 X-Ray SDK는 라이브러리를 패치할 때 모든 AWS SDK 클라이언트를 자동으로 계측합니다. [`botocore`](xray-sdk-python-patching.md) 개별 클라이언트를 구성할 수는 없습니다.
모든 서비스의 경우, X-Ray 콘솔에서 호출된 API의 이름을 볼 수 있습니다. 서비스 하위 집합에 대해서는 X-Ray SDK가 세그먼트에 정보를 추가하여 서비스 맵에서 추가 세분화를 제공합니다.
예를 들어 계측된 DynamoDB 클라이언트에서 직접 호출을 생성하는 경우 SDK가 특정 테이블을 대상으로 한 직접 호출에 대해 테이블 이름을 세그먼트에 추가합니다. 콘솔에서, 각 테이블이 개별 노드로 서비스 맵에 표시되고, 특정 테이블을 대상으로 하지 않은 직접 호출에 대해 일반 DynamoDB 노드가 표시됩니다.
**Example 항목을 저장하기 위한 DynamoDB 직접 호출에 대한 하위 세그먼트**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
명명된 리소스에 액세스할 때 다음 서비스를 호출할 경우 서비스 맵에 추가 노드가 생성됩니다. 특정 리소스를 대상으로 하지 않는 경우 서비스를 직접 호출하면 해당 서비스에 대한 일반 노드가 생성됩니다.
+ **Amazon DynamoDB** – 테이블 이름
+ **Amazon Simple Storage Service** –버킷 및 키 이름
+ **Amazon Simple Queue Service** – 대기열 이름
# Python용 X-Ray SDK를 사용하여 다운스트림 HTTP 웹 서비스에 대한 호출 추적하기
**참고**
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.
애플리케이션이 마이크로서비스 또는 퍼블릭 HTTP API를 호출하면 Python용 X-Ray SDK를 사용하여 해당 호출을 구성하고 API를 서비스 그래프에 다운스트림 서비스로 추가할 수 있습니다.
HTTP 클라이언트를 구성하려면 발신 호출을 생성할 때 사용하는 [라이브러리를 패치](xray-sdk-python-patching.md)합니다. `requests` 또는 Python의 내장 HTTP 클라이언트를 사용하는 경우 더 이상 수행할 작업이 없습니다. `aiohttp`의 경우 [비동기 컨텍스트](xray-sdk-python-patching.md#xray-sdk-python-patching-async)를 사용하여 레코더를 구성합니다.
`aiohttp` 3의 클라이언트 API를 사용하면, SDK에서 제공하는 추적 구성의 인스턴스로 `ClientSession`의 클라이언트 API도 함께 구성해야 합니다.
**Example [`aiohttp` 3 클라이언트 API](https://github.com/aws/aws-xray-sdk-python#trace-aiohttp-client-requests)**
```
from aws_xray_sdk.ext.aiohttp.client import aws_xray_trace_config
async def foo():
trace_config = aws_xray_trace_config()
async with ClientSession(loop=loop, trace_configs=[trace_config]) as session:
async with session.get(url) as resp
await resp.read()
```
다운스트림 웹 API에 대한 직접 호출을 계측할 때 Python용 X-Ray SDK가 HTTP 요청 및 응답에 대한 정보가 포함된 하위 세그먼트를 기록합니다. X-Ray는 하위 세그먼트를 사용하여 원격 API에 대해 추정된 세그먼트를 생성합니다.
**Example 다운스트림 HTTP 호출에 대한 하위 세그먼트**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example 다운스트림 HTTP 호출에 대한 추정된 세그먼트**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# Python용 X-Ray SDK를 사용하여 사용자 지정 하위 세그먼트 생성하기
**참고**
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.
하위 세그먼트는 추적의 [세그먼트](xray-concepts.md#xray-concepts-segments)를 확장하여 요청을 처리하기 위해 완료된 작업에 대한 세부 정보를 표시합니다. 계측되는 클라이언트에서 직접 호출할 때마다, X-Ray SDK는 하위 세그먼트 안에 생성된 정보를 기록합니다. 추가 하위 세그먼트를 생성하여 다른 하위 세그먼트를 그룹화하거나, 코드 섹션의 성능을 평가하거나, 주석 및 메타데이터를 기록할 수 있습니다.
하위 세그먼트를 관리하려면 `begin_subsegment` 및 `end_subsegment` 메서드를 사용합니다.
**Example main.py – 사용자 지정 하위 세그먼트**
```
from aws_xray_sdk.core import xray_recorder
subsegment = xray_recorder.begin_subsegment('annotations')
subsegment.put_annotation('id', 12345)
xray_recorder.end_subsegment()
```
동기식 함수에 대한 하위 세그먼트를 생성하려면 `@xray_recorder.capture` 데코레이터를 사용합니다. 하위 세그먼트에 대한 이름을 캡처 함수에 전달하거나 그대로 두고 함수 이름을 사용할 수 있습니다.
**Example main.py – 함수 하위 세그먼트**
```
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('## create_user')
def create_user():
...
```
비동기 함수의 경우 `@xray_recorder.capture_async` 데코레이터를 사용하며, 비동기 컨텍스트를 레코더에 전달합니다.
**Example main.py – 비동기 함수 하위 세그먼트**
```
from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())
@xray_recorder.capture_async('## create_user')
async def create_user():
...
async def main():
await myfunc()
```
하위 세그먼트를 세그먼트 또는 다른 하위 세그먼트 내에서 생성하면 Python용 X-Ray SDK가 해당 하위 세그먼트에 대해 ID를 생성하고 시작 시간 및 종료 시간을 기록합니다.
**Example 메타데이터가 포함된 하위 세그먼트**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
# Python용 X-Ray SDK로 세그먼트에 주석 및 메타데이터 추가하기
**참고**
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.
주석 및 메타데이터와 함께 요청, 환경 또는 애플리케이션에 대한 추가 정보를 기록할 수 있습니다. X-Ray SDK에서 생성하는 세그먼트 또는 사용자가 생성하는 사용자 지정 하위 세그먼트에 주석 및 메타데이터를 추가할 수 있습니다.
**주석**은 문자열, 숫자 또는 부울 값과 결합한 키-값 페어입니다. 주석은 [필터 표현식](xray-console-filters.md)에서 사용하기 위해 인덱싱됩니다. 주석은 콘솔의 트레이스를 그룹화할 때 사용할 데이터를 기록하거나 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API를 직접 호출할 때 사용하세요.
**메타데이터**는 객체 및 목록을 포함한 모든 유형의 값을 가질 수 있는 키-값 페어지만, 필터 표현식에 사용할 수 있도록 인덱싱되지는 않습니다. 트레이스에 저장하고 싶지만 검색에는 사용하지 않을 추가 데이터는 메타데이터를 사용하여 기록하십시오.
세그먼트에는 주석과 메타데이터 외에 [사용자 ID 문자열](#xray-sdk-python-segment-userid)도 기록할 수 있습니다. 사용자 ID는 세그먼트의 별도 필드에 기록되면 검색용으로 인덱스되지 않습니다.
**Topics**
+ [Python용 X-Ray SDK로 주석 기록하기](#xray-sdk-python-segment-annotations)
+ [Python용 X-Ray SDK로 메타데이터 기록하기](#xray-sdk-python-segment-metadata)
+ [Python용 X-Ray SDK로 사용자 ID 기록하기](#xray-sdk-python-segment-userid)
## Python용 X-Ray SDK로 주석 기록하기
주석을 사용하여 검색용으로 인덱싱할 정보를 세그먼트나 하위 세그먼트에 기록하십시오.
**주석 요구 사항**
+ **키** - X-Ray 주석의 키는 최대 500자의 영숫자를 포함할 수 있습니다. 점이나 마침표(.) 이외의 공백이나 기호를 사용할 수 없습니다.
+ **값** - X-Ray 주석의 값은 최대 1,000자의 유니코드 문자를 포함할 수 있습니다.
+ **주석** 수 - 트레이스당 최대 50개의 주석을 사용할 수 있습니다.
**주석 기록 방법**
1. `xray_recorder`에서 현재 세그먼트나 하위 세그먼트의 참조를 가져오십시오.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
또는
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. 문자열 키, 부울, 숫자 또는 문자열 값으로 `put_annotation`을 직접 호출합니다.
```
document.put_annotation("mykey", "my value");
```
다음 예에서는 점이 포함된 문자열 키와 부울, 숫자 또는 문자열 값을 사용하여 `putAnnotation`을 직접 호출하는 방법을 보여줍니다.
```
document.putAnnotation("testkey.test", "my value");
```
또는 `put_annotation`에서 `xray_recorder` 방법을 사용할 수 있습니다. 이 방법은 현재의 하위 세그먼트나 열려있는 하위 세그먼트가 없을 경우 해당 세그먼트에서 레코드 주석을 기록합니다.
```
xray_recorder.put_annotation("mykey", "my value");
```
SDK는 세그먼트 문서의 `annotations` 객체에 주석을 키-값 페어로 기록합니다. 같은 키로 `put_annotation`을 두 번 직접 호출하면 같은 세그먼트나 하위 세그먼트에 기록했던 값을 덮어씁니다.
특정 값을 포함한 주석이 있는 트레이스를 찾으려면 `annotation[key]` 키워드를 [필터 표현식](xray-console-filters.md)에 사용하십시오.
## Python용 X-Ray SDK로 메타데이터 기록하기
**주의**
순환 참조가 있는 객체를 Python용 X-Ray SDK의 메타데이터 값으로 추가하지 마세요. 이러한 객체는 JSON으로 직렬화할 수 없으며 SDK에서 무한 루프를 생성할 수 있습니다. 또한 성능 문제를 방지하기 위해 크고 복잡한 객체를 메타데이터로 추가하지 마세요.
메타데이터를 이용해 검색용으로 인덱싱하지 않아도 되는 정보를 세그먼트나 하위 세그먼트에 기록하십시오. 메타데이터 값은 문자열, 숫자, 부울 또는 JSON 객체나 어레이에 직렬화할 수 있는 모든 객체가 될 수 있습니다.
**메타데이터 기록 방법**
1. `xray_recorder`에서 현재 세그먼트나 하위 세그먼트의 참조를 가져오십시오.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
또는
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. 문자열 키, 부울, 숫자, 문자열 또는 객체 값 및 문자열 네임스페이스와 함께 `put_metadata`를 직접 호출합니다.
```
document.put_metadata("my key", "my value", "my namespace");
```
또는
키와 값만 이용해 `put_metadata`를 직접 호출합니다.
```
document.put_metadata("my key", "my value");
```
또는 `put_metadata`에서 `xray_recorder` 방법을 사용할 수 있습니다. 이 방법은 현재의 하위 세그먼트나 열려있는 하위 세그먼트가 없을 경우 해당 세그먼트에서 메타데이터를 기록합니다.
```
xray_recorder.put_metadata("my key", "my value");
```
네임스페이스를 지정하지 않으면, SDK는 `default`를 사용합니다. 같은 키로 `put_metadata`을 두 번 직접 호출하면 같은 세그먼트나 하위 세그먼트에 기록했던 값을 덮어씁니다.
## Python용 X-Ray SDK로 사용자 ID 기록하기
사용자 ID를 요청 세그먼트에 기록하여 요청을 보낸 사용자를 식별합니다.
**사용자 ID 기록 방법**
1. `xray_recorder`에서 현재 세그먼트에 대한 참조를 가져옵니다.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
1. 요청을 보낸 사용자의 문자열 ID로 `setUser`를 직접 호출합니다.
```
document.set_user("U12345");
```
컨트롤러에서 `set_user`를 직접 호출하면 애플리케이션이 요청을 처리하는 순간부터 사용자 ID를 기록할 수 있습니다.
사용자 ID의 트레이스를 찾으려면, `user` 키워드를 [필터 표현식](xray-console-filters.md)에 적용하십시오.
# 서버리스 환경에 배포된 웹 프레임워크 구성
**참고**
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.
Python용 AWS X-Ray SDK는 서버리스 애플리케이션에 배포된 웹 프레임워크 계측을 지원합니다. 서버리스는 운영상의 책임을 AWS로 전환하여 민첩성과 혁신을 높일 수 있도록 하는 클라우드의 네이티브 아키텍처입니다.
서버리스 아키텍처는 서버를 고려하지 않고 애플리케이션 및 서비스를 구축하고 실행할 수 있게 해주는 소프트웨어 애플리케이션입니다. 서버 또는 클러스터 프로비저닝, 패치 적용, 운영 체제 유지 관리 및 용량 프로비저닝과 같은 인프라 관리 작업을 덜어냅니다. 거의 모든 유형의 애플리케이션 또는 백엔드 서비스를 서버리스 솔루션으로 구축할 수 있으며, 애플리케이션을 고가용성으로 실행하고 확장하는 데 필요한 모든 사항이 자동으로 처리됩니다.
이 자습서에서는 서버리스 환경에 배포된 Flask 또는 Django와 같은 웹 프레임워크 AWS X-Ray 에서를 자동으로 계측하는 방법을 보여줍니다. 애플리케이션의 X-Ray 계측을 사용하면 Amazon API Gateway에서 시작하여 AWS Lambda 함수를 통해 수행된 모든 다운스트림 호출과 애플리케이션이 수행한 발신 호출을 볼 수 있습니다.
Python용 X-Ray SDK는 다음 Python 애플리케이션 프레임워크를 지원합니다.
+ Flask 버전 0.8 이상
+ Django 버전 1.0 이상
이 튜토리얼에서는 Lambda에 배포되고 API Gateway에서 호출되는 서버리스 애플리케이션 예시를 개발합니다. 이 튜토리얼에서는 Zappa를 사용하여 애플리케이션을 Lambda에 자동으로 배포하고 API 게이트웨이 엔드포인트를 구성합니다.
## 사전 조건
+ [Zappa](https://github.com/Miserlou/Zappa)
+ [Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python.html) – 버전 2.7 또는 3.6.
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) - AWS CLI 가 계정으로 구성되어 있고 애플리케이션을 배포할 AWS 리전 것인지 확인합니다.
+ [Pip](https://pypi.org/project/pip/)
+ [Virtualenv](https://virtualenv.pypa.io/en/latest/)
## 단계 1: 환경 조성
이 단계에서는 `virtualenv`를 사용하여 애플리케이션을 호스팅할 가상 환경을 만듭니다.
1. 를 사용하여 애플리케이션의 디렉터리를 AWS CLI생성합니다. 그런 다음 새 디렉터리로 변경합니다.
```
mkdir serverless_application
cd serverless_application
```
1. 다음에는 새 디렉터리에서 가상 환경을 생성합니다. 다음 명령을 사용하여 활성화합니다.
```
# Create our virtual environment
virtualenv serverless_env
# Activate it
source serverless_env/bin/activate
```
1. 환경에 X-Ray, Flask, Zappa 및 Requests 라이브러리를 설치합니다.
```
# Install X-Ray, Flask, Zappa, and Requests into your environment
pip install aws-xray-sdk flask zappa requests
```
1. `serverless_application` 디렉터리에 애플리케이션 코드를 추가합니다. 이 예제에서는 Flasks의 [Hello World](https://flask.palletsprojects.com/en/3.0.x/quickstart/) 예제를 빌드합니다.
`serverless_application` 디렉터리에서 `my_app.py`라는 파일 만듭니다. 그런 다음 텍스트 편집기를 사용하여 다음 명령을 추가합니다. 이 애플리케이션은 Requests 라이브러리를 계측하고, Flask 애플리케이션의 미들웨어를 패치하고, 엔드포인트 `'/'`를 엽니다.
```
# Import the X-Ray modules
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
from aws_xray_sdk.core import patcher, xray_recorder
from flask import Flask
import requests
# Patch the requests module to enable automatic instrumentation
patcher.patch(('requests',))
app = Flask(__name__)
# Configure the X-Ray recorder to generate segments with our service name
xray_recorder.configure(service='My First Serverless App')
# Instrument the Flask application
XRayMiddleware(app, xray_recorder)
@app.route('/')
def hello_world():
resp = requests.get("https://aws.amazon.com")
return 'Hello, World: %s' % resp.url
```
## 2단계: Zappa 환경 생성 및 배포
이 단계에서는 Zappa를 사용하여 자동으로 API 게이트웨이 엔드포인트를 구성한 후 Lambda에 배포합니다.
1. `serverless_application` 디렉터리에서 Zappa를 실행합니다. 이 예제에서는 기본 설정을 사용했지만, 기본 설정을 사용자 지정할 경우 Zappa가 구성 지침을 표시합니다.
```
zappa init
```
```
What do you want to call this environment (default 'dev'): dev
...
What do you want to call your bucket? (default 'zappa-*******'): zappa-*******
...
...
It looks like this is a Flask application.
What's the modular path to your app's function?
This will likely be something like 'your_module.app'.
We discovered: my_app.app
Where is your app's function? (default 'my_app.app'): my_app.app
...
Would you like to deploy this application globally? (default 'n') [y/n/(p)rimary]: n
```
1. X-Ray 활성화하기 `zappa_settings.json` 파일을 열고 예제와 비슷한지 확인합니다.
```
{
"dev": {
"app_function": "my_app.app",
"aws_region": "us-west-2",
"profile_name": "default",
"project_name": "serverless-exam",
"runtime": "python2.7",
"s3_bucket": "zappa-*********"
}
}
```
1. 구성 파일의 한 항목으로 `"xray_tracing": true`를 추가합니다.
```
{
"dev": {
"app_function": "my_app.app",
"aws_region": "us-west-2",
"profile_name": "default",
"project_name": "serverless-exam",
"runtime": "python2.7",
"s3_bucket": "zappa-*********",
"xray_tracing": true
}
}
```
1. 애플리케이션을 배포합니다. 그러면 자동으로 API 게이트웨이 엔드포인트가 구성되고 코드가 Lambda로 업로드됩니다.
```
zappa deploy
```
```
...
Deploying API Gateway..
Deployment complete!: https://**********.execute-api.us-west-2.amazonaws.com/dev
```
## 3단계: API Gateway에 X-Ray 추적 활성화하기
이 단계에서는 API 게이트웨이 콘솔과 상호 작용을 통해 X-Ray 추적을 활성화합니다.
1. 에 로그인 AWS Management Console 하고 [https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/) API Gateway 콘솔을 엽니다.
1. 새로 생성한 API를 찾습니다. 이 URL은 `serverless-exam-dev`과 유사해야 합니다.
1. **단계**를 선택합니다.
1. 배포 단계의 이름을 선택합니다. 기본값은 `dev`입니다.
1. **Logs/Tracing(로그/추적)** 탭에서 **Enable X-Ray Tracing(X-Ray 추적 활성화)** 확인란을 선택합니다.
1. **변경 사항 저장(Save Changes)**을 선택합니다.
1. 브라우저에서 엔드포인트에 액세스합니다. 예제 `Hello World` 애플리케이션을 사용한 경우 다음과 같이 표시되어야 합니다.
```
"Hello, World: https://aws.amazon.com/"
```
## 4단계: 생성된 추적 보기
이 단계에서는 X-Ray 콘솔과 상호 작용을 통해 예제 애플리케이션이 생성하는 추적을 확인합니다. 추적 분석에 대한 자세한 내용은 [서비스 맵 보기](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap)를 참조하십시오.
1. 에 로그인 AWS Management Console 하고 [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) X-Ray 콘솔을 엽니다.
1. API 게이트웨이, Lambda 함수 및 Lambda 컨테이너에 의해 생성된 세그먼트를 봅니다.
1. Lambda 함수 세그먼트 아래에서 하위 세그먼트 `My First Serverless App`을 봅니다. 그 다음에 두 번째 하위 세그먼트 `https://aws.amazon.com`이 나옵니다.
1. 초기화 시, Lambda가 세 번째 하위 세그먼트 `initialization`도 생성할 수 있습니다.
![\[추적 세그먼트 보기\]](http://docs.aws.amazon.com/ko_kr/xray/latest/devguide/images/serverless-traceView.png)
![\[서비스 그래프 보기\]](http://docs.aws.amazon.com/ko_kr/xray/latest/devguide/images/serverless-serviceView.png)
## 5단계: 정리
원치 않는 비용이 누적되지 않도록 항상 더 이상 사용하지 않는 리소스는 종료하십시오. 이 자습서에서 알 수 있듯이 Zappa와 같은 도구는 서버리스 배포를 간소화합니다.
Lambda, API 게이트웨이 및 Amazon S3에서 애플리케이션을 제거하려면 AWS CLI를 사용하여 프로젝트 디렉터리에서 다음 명령을 실행합니다.
```
zappa undeploy dev
```
## 다음 단계
AWS 클라이언트를 추가하고 X-Ray로 계측하여 애플리케이션에 더 많은 기능을 추가합니다. [서버리스 온 AWS](https://aws.amazon.com/serverless)에서 서버리스 컴퓨팅 옵션에 대해 자세히 알아보십시오.