Go를 SDK 위한 X-Ray 설정하기

환경 변수를 통해, Config 객체를 Configure 호출하거나, 기본값을 가정하여 X-Ray SDK for Go의 구성을 지정할 수 있습니다. 환경 변수는 모든 기본값보다 우선하는 Config 값보다 우선합니다.

Sections

서비스 플러그인
샘플링 규칙
로깅
환경 변수
configure 사용

서비스 플러그인

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

플러그인

Amazon EC2 — 인스턴스 ID, 가용 영역 및 CloudWatch 로그 그룹을 EC2Plugin 추가합니다.
Elastic Beanstalk – ElasticBeanstalkPlugin이 환경 이름, 버전 레이블 및 배포 ID를 추가합니다.
Amazon ECS — 컨테이너 ID를 ECSPlugin 추가합니다.

플러그인을 사용하려면 다음 패키지 중 하나를 가져옵니다.


"github.com/aws/aws-xray-sdk-go/awsplugins/ec2"
"github.com/aws/aws-xray-sdk-go/awsplugins/ecs"
"github.com/aws/aws-xray-sdk-go/awsplugins/beanstalk"

각 플러그인에는 플러그인을 로드하는 명시적 Init() 함수 호출이 있습니다.

예 ec2.Init()


import (
	"os"

	"github.com/aws/aws-xray-sdk-go/awsplugins/ec2"
	"github.com/aws/aws-xray-sdk-go/xray"
)

func init() {
  // conditionally load plugin
  if os.Getenv("ENVIRONMENT") == "production" {
    ec2.Init()
  }

  xray.Configure(xray.Config{
    ServiceVersion: "1.2.3",
  })
}

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

샘플링 규칙

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

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

참고

샘플링 규칙을 가져오기 위해 X-Ray에 연결할 SDK 수 없는 경우 1초마다 첫 번째 요청의 기본 로컬 규칙으로 되돌아가고 호스트당 추가 요청의 5% 로 되돌아갑니다. 이는 호스트가 샘플링을 APIs 호출할 권한이 없거나 에서 걸려온 호출에 대한 TCP API 프록시 역할을 하는 X-Ray 데몬에 연결할 수 없는 경우에 발생할 수 있습니다. SDK

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

예 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에서 샘플링 결정을 내립니다.

백업 규칙을 제공하려면 를 사용하여 로컬 샘플링 JSON 파일을 NewCentralizedStrategyWithFilePath 가리키십시오.

예 main.go – 로컬 샘플링 규칙


s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})

로컬 규칙만 사용하려면 를 사용하여 로컬 샘플링 JSON 파일을 NewLocalizedStrategyFromFilePath 가리키십시오.

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


s, _ := sampling.NewLocalizedStrategyFromFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})

로깅

참고

xray.Config{} 필드인 LogLevel 및 LogFormat은 버전 1.0.0-rc.10부터 사용 중지됩니다.

X-Ray는 로깅을 위해 다음 인터페이스를 사용합니다. 기본 로거는 LogLevelInfo 이상에서 stdout에 씁니다.


type Logger interface {
	Log(level LogLevel, msg fmt.Stringer)
}

const (
	LogLevelDebug LogLevel = iota + 1
	LogLevelInfo
	LogLevelWarn
	LogLevelError
)

예 `io.Writer`에 쓰기


xray.SetLogger(xraylog.NewDefaultLogger(os.Stderr, xraylog.LogLevelError))

환경 변수

환경 변수를 사용하여 SDK Go용 X-Ray를 구성할 수 있습니다. SDK는 다음 변수를 지원합니다.

AWS_XRAY_CONTEXT_MISSING – 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 RUNTIME_ERROR로 설정합니다.
유효한 값
- RUNTIME_ERROR— 런타임 예외가 발생합니다.
- LOG_ERROR – 오류를 기록하고 계속합니다 (기본값).
- IGNORE_ERROR— 오류를 무시하고 계속합니다.
열린 요청이 없을 때 실행되는 시작 코드 또는 새 스레드를 생성하는 코드에서 계측된 클라이언트를 사용하려고 하는 경우 누락된 세그먼트 또는 하위 세그먼트와 관련된 오류가 발생할 수 있습니다.
AWS_XRAY_TRACING_NAME— 세그먼트에 사용할 서비스 이름을 설정합니다. SDK
AWS_XRAY_DAEMON_ADDRESS – X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다. 기본적으로 는 추적 데이터를 SDK 127.0.0.1:2000 전송합니다. 다른 포트에서 수신 대기하도록 대몬(daemon)을 구성한 경우 또는 다른 호스트에서 실행 중인 경우 이 변수를 사용합니다.
AWS_XRAY_CONTEXT_MISSING— 누락된 컨텍스트 오류를 SDK 처리하는 방법을 결정하려면 값을 설정합니다. 열린 요청이 없을 때 시작 코드 또는 새 스레드를 생성하는 코드에서 구성된 클라이언트를 사용하려고 하는 경우 누락된 세그먼트 또는 하위 세그먼트와 관련된 오류가 발생할 수 있습니다.
- RUNTIME_ERROR— 기본적으로 SDK 는 런타임 예외가 발생하도록 설정되어 있습니다.
- LOG_ERROR – 오류를 기록하고 계속합니다.

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

configure 사용

Configure방법을 사용하여 SDK Go용 X-Ray를 구성할 수도 있습니다. Configure다음과 같은 선택적 필드와 함께 하나의 인수인 Config 객체를 취합니다.

DaemonAddr: 이 문자열은 X-Ray 대몬(daemon) 리스너의 호스트 및 포트를 지정합니다. 지정하지 않으면 X-Ray는 AWS_XRAY_DAEMON_ADDRESS 환경 변수의 값을 사용합니다. 해당 값이 설정되어 있지 않으면 "127.0.0.1:2000"을 사용합니다.
ServiceVersion: 이 문자열은 서비스 버전을 지정합니다. 지정하지 않으면 X-Ray는 빈 문자열("")을 사용합니다.
SamplingStrategy: 이 SamplingStrategy 객체는 트레이스되는 애플리케이션 호출을 지정합니다. 지정하지 않으면 X-Ray는 xray/resources/DefaultSamplingRules.json에 정의된 전략을 가져오는 LocalizedSamplingStrategy를 사용합니다.
StreamingStrategy: 이 StreamingStrategy 객체는 true가 RequiresStreaming반환될 때 세그먼트를 스트리밍할지 여부를 지정합니다. 지정하지 않으면 X-Ray는 하위 세그먼트 수가 20보다 크면 샘플링된 세그먼트를 스트림하는 DefaultStreamingStrategy를 사용합니다.
ExceptionFormattingStrategy: 이 ExceptionFormattingStrategy 객체는 여러 예외를 처리하는 방법을 지정합니다. 지정하지 않으면 X-Ray는 DefaultExceptionFormattingStrategy를 error 유형의 XrayError, 오류 메시지 및 스택 추적과 함께 사용합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

Go용 X-Ray SDK

수신 요청