Python용 X-Ray SDK 구성

Python용 X-Ray SDK에는 전역 레코더를 제공하는 xray_recorder라는 클래스가 있습니다. 수신 HTTP 호출에 대해 세그먼트를 생성하는 미들웨어를 사용자 지정하도록 전역 레코더를 구성할 수 있습니다.

서비스 플러그인

plugins을 사용하여 애플리케이션을 호스팅하는 서비스에 대한 정보를 기록할 수 있습니다.

플러그인

• Amazon EC2 — 인스턴스 ID, 가용 영역 및 CloudWatch 로그 그룹을 EC2Plugin 추가합니다.

• Elastic Beanstalk – ElasticBeanstalkPlugin이 환경 이름, 버전 레이블 및 배포 ID를 추가합니다.

• Amazon ECS — ECSPlugin이 컨테이너 ID를 추가합니다.

플러그인을 사용하려면 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',)

또한 코드에 설정된 값보다 우선하는 환경 변수를 사용하여 레코더를 구성할 수 있습니다.

다운스트림 호출을 레코딩하도록 라이브러리를 패치하기 전에 플러그인을 구성합니다.

SDK는 플러그인 설정을 사용하여 세그먼트에 origin 필드를 설정하기도 합니다. 이는 애플리케이션을 실행하는 AWS 리소스 유형을 나타냅니다. 여러 플러그인을 사용하는 경우 SDK는 ElasticBeanstalk > EKS > ECS > EC2와 같은 해결 순서를 사용하여 출처를 결정합니다.

샘플링 규칙

SDK는 X-Ray 콘솔에서 정의하는 샘플링 규칙을 사용하여 기록할 요청을 결정합니다. 기본 규칙은 매초 첫 번째 요청을 추적하고, 모든 서비스에서 추가 요청의 5%를 X-Ray로 추적 전송합니다. X-Ray 콘솔에서 추가 규칙을 생성하여 각 애플리케이션에 대해 기록되는 데이터의 양을 사용자 지정합니다.

SDK는 사용자 지정 규칙을 정의된 순서대로 적용합니다. 요청이 여러 사용자 지정 규칙과 일치하는 경우 SDK는 첫 번째 규칙만 적용합니다.

참고

SDK가 X-Ray에 도달하여 샘플링 규칙을 가져올 수 없는 경우 1초가 시작될 때 수신되는 첫 번째 요청의 기본 로컬 규칙과 호스트당 추가 요청의 5% 로 되돌아갑니다. 호스트가 샘플링 API를 직접 호출할 수 있는 권한이 없거나, X-Ray 대몬(daemon)에 연결할 수 없을 경우 이러한 상황이 발생할 수 있고 이 대몬(daemon)은 SDK에서 수행한 API 직접 호출에 대한 TCP 프록시 역할을 합니다.

JSON 문서에서 샘플링 규칙을 불러오도록 SDK를 구성할 수도 있습니다. SDK는 X-Ray 샘플링을 사용할 수 없을 경우 로컬 규칙을 백업으로 사용하거나, 로컬 규칙을 전용으로 사용할 수 있습니다.

예 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())

또한 샘플링을 비활성하하고 모든 수신 요청을 구성하도록 전역 레코더를 구성할 수 있습니다.

예 main.py – 샘플링 비활성화

xray_recorder.configure(sampling=False)

로깅

SDK는 기본 WARNING 로깅 레벨이 있는 Python의 내장 logging 모듈을 사용합니다. aws_xray_sdk 클래스에 대한 로거 참조를 가져오고 이에 대해 setLevel을 호출하여 라이브러리 및 애플리케이션의 나머지에 대해 서로 다른 로그 레벨을 구성합니다.

예 app.py – 로깅

logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)

디버그 로그를 사용하여 수동으로 하위 세그먼트를 생성할 때 미완료 하위 세그먼트와 같은 문제를 식별할 수 있습니다.

코드의 레코더 구성

xray_recorder에 대한 configure 메서드에서 추가 설정을 사용할 수 있습니다.

• context_missing – 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 LOG_ERROR로 설정합니다.

• daemon_address – X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다.

• service – SDK가 세그먼트에 사용하는 서비스 이름을 설정합니다.

• plugins— 애플리케이션 AWS 리소스에 대한 정보를 기록합니다.

• sampling – 샘플링을 비활성화하려면 False로 설정합니다.

• sampling_rules – 샘플링 규칙이 포함된 JSON 파일의 경로를 설정합니다.

예 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 – 샘플링 규칙이 포함된 JSON 파일의 경로를 설정합니다.

settings.py에서 레코더 구성을 활성화하려면 설치된 앱 목록에 Django 미들웨어를 추가합니다.

예 settings.py – 설치된 앱

INSTALLED_APPS = [
    ...
    'django.contrib.sessions',
    'aws_xray_sdk.ext.django',
]

이름이 XRAY_RECORDER인 dict에서 사용 가능한 설정을 구성합니다.

예 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을 사용합니다. 다른 포트에서 수신 대기하도록 대몬(daemon)을 구성한 경우 또는 다른 호스트에서 실행 중인 경우 이 변수를 사용합니다.

  형식

  • 동일한 포트 – address:port

  • 다른 포트 – tcp:address:port udp:address:port

• AWS_XRAY_CONTEXT_MISSING – 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 RUNTIME_ERROR로 설정합니다.

  유효한 값

  • RUNTIME_ERROR— 런타임 예외가 발생합니다.

  • LOG_ERROR – 오류를 기록하고 계속합니다 (기본값).

  • IGNORE_ERROR— 오류를 무시하고 계속합니다.

  열린 요청이 없을 때 실행되는 시작 코드 또는 새 스레드를 생성하는 코드에서 계측된 클라이언트를 사용하려고 하는 경우 누락된 세그먼트 또는 하위 세그먼트와 관련된 오류가 발생할 수 있습니다.

환경 변수는 코드에 설정된 값을 재정의합니다.