# API Gateway REST API를 사용하여 AWS X-Ray 설정
<a name="apigateway-enabling-xray"></a>

이 단원에서는 API Gateway REST API를 사용하여 [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html)를 설정하는 방법에 대한 자세한 내용을 알아볼 수 있습니다.

**Topics**
+ [API Gateway에 대한 X-Ray 추적 모드](#apigateway-tracing-modes)
+ [X-Ray 추적에 대한 권한](#set-up-xray-tracing-permissions)
+ [API Gateway 콘솔에서 X-Ray 추적 활성화](#apigateway-xray-console-setup)
+ [API Gateway CLI를 사용하여 AWS X-Ray 추적 활성화](#apigateway-xray-cli-setup)

## API Gateway에 대한 X-Ray 추적 모드
<a name="apigateway-tracing-modes"></a>

애플리케이션을 경유하는 요청 경로는 트레이스 ID로 트레이스됩니다. 트레이스는 단일 요청(보통 HTTP `GET` 또는 `POST` 요청)에 의해 생성된 모든 세그먼트를 수집합니다.

API Gateway API에 대한 두 가지 추적 모드가 있습니다.
+ **수동**: API 단계에서 X-Ray 추적을 활성화하지 않은 경우 이 모드가 기본 설정입니다. 이 접근 방식에서는 업스트림 서비스에서 X-Ray를 활성화한 경우에만 API Gateway API를 추적합니다.
+ **활성**: API Gateway API 단계에 이 설정이 있으면 API Gateway는 X-Ray에서 지정한 샘플링 알고리즘을 기반으로 API 호출 요청을 자동으로 샘플링합니다.

  단계에서 활성 추적을 활성화할 때 역할이 이미 존재하지 않으면, API Gateway가 사용자의 계정에 서비스 연결 역할을 생성합니다. 그 역할의 이름은 `AWSServiceRoleForAPIGateway`이고 이 역할에는 `APIGatewayServiceRolePolicy` 관리형 정책이 연결됩니다. 서비스 연결 역할에 대한 자세한 내용은 [서비스 연결 역할 사용](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) 단원을 참조하십시오.
**참고**  
X-Ray는 API가 수신하는 요청의 대표 샘플을 여전히 제공하면서 추적이 효율적으로 수행되도록 샘플링 알고리즘을 적용합니다. 기본 샘플링 알고리즘은 초당 1회 요청인데, 요청의 5%가 이 제한을 넘어서 샘플링됩니다.

API Gateway 관리 콘솔, API Gateway CLI 또는 AWS SDK를 사용하여 API에 대한 추적 모드를 변경할 수 있습니다.

## X-Ray 추적에 대한 권한
<a name="set-up-xray-tracing-permissions"></a>

단계에서 활성 추적을 활성화할 때 역할이 이미 존재하지 않으면, API Gateway가 사용자의 계정에 서비스 연결 역할을 생성합니다. 그 역할의 이름은 `AWSServiceRoleForAPIGateway`이고 이 역할에는 `APIGatewayServiceRolePolicy` 관리형 정책이 연결됩니다. 서비스 연결 역할에 대한 자세한 내용은 [서비스 연결 역할 사용](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) 단원을 참조하십시오.

## API Gateway 콘솔에서 X-Ray 추적 활성화
<a name="apigateway-xray-console-setup"></a>

Amazon API Gateway 콘솔을 사용하여 API 단계에서 활성 추적을 활성화할 수 있습니다.

이러한 단계에서는 단계에 API를 이미 배포한 것으로 가정합니다.

1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.

1. API를 선택하고 기본 탐색 창에서 **스테이지**를 선택합니다.

1. **스테이지** 창에서 스테이지를 선택합니다.

1. **로그 및 추적** 섹션에서 **편집**을 선택합니다.

1. 활성 X-Ray 추적을 활성화하려면 **X-Ray 추적**에서 X-Ray 추적을 활성화합니다.

1. **변경 사항 저장**을 선택합니다.

API 단계에 대해 X-Ray를 활성화한 후에는 X-Ray 관리 콘솔을 사용하여 추적 및 서비스 맵을 볼 수 있습니다.

## API Gateway CLI를 사용하여 AWS X-Ray 추적 활성화
<a name="apigateway-xray-cli-setup"></a>

다음 [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) 명령은 활성 X-Ray 추적이 있는 스테이지를 생성합니다.

```
aws apigateway create-stage \
    --rest-api-id {{rest-api-id}} \
    --stage-name {{stage-name}} \
    --deployment-id {{deployment-id}} \
    --region {{region}} \
    --tracing-enabled=true
```

출력은 다음과 같습니다.

```
{
    "tracingEnabled": true, 
    "stageName": {{stage-name}}, 
    "cacheClusterEnabled": false, 
    "cacheClusterStatus": "NOT_AVAILABLE", 
    "deploymentId": {{deployment-id}}, 
    "lastUpdatedDate": 1533849811, 
    "createdDate": 1533849811, 
    "methodSettings": {}
}
```

다음 [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) 명령은 활성 X-Ray 추적이 없는 스테이지를 생성합니다.

```
aws apigateway create-stage \
    --rest-api-id {{rest-api-id}} \
    --stage-name {{stage-name}} \
    --deployment-id {{deployment-id}} \
    --region {{region}} \
    --tracing-enabled=false
```

출력은 다음과 같습니다.

```
{
    "tracingEnabled": false, 
    "stageName": {{stage-name}}, 
    "cacheClusterEnabled": false, 
    "cacheClusterStatus": "NOT_AVAILABLE", 
    "deploymentId": {{deployment-id}}, 
    "lastUpdatedDate": 1533849811, 
    "createdDate": 1533849811, 
    "methodSettings": {}
}
```

다음 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)는 배포된 API에 대한 활성 X-Ray 추적을 켭니다.

```
aws apigateway update-stage \
    --rest-api-id {{rest-api-id}} \
    --stage-name {{stage-name}} \
    --patch-operations op=replace,path=/tracingEnabled,value=true
```

다음 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html)는 배포된 API에 대한 활성 X-Ray 추적을 끕니다.

```
aws apigateway update-stage \
    --rest-api-id {{rest-api-id}} \
    --stage-name {{stage-name}} \
    --region {{region}} \
    --patch-operations op=replace,path=/tracingEnabled,value=false
```

출력은 다음과 같습니다.

```
{
    "tracingEnabled": false, 
    "stageName": {{stage-name}}, 
    "cacheClusterEnabled": false, 
    "cacheClusterStatus": "NOT_AVAILABLE", 
    "deploymentId": {{deployment-id}}, 
    "lastUpdatedDate": 1533850033, 
    "createdDate": 1533849811, 
    "methodSettings": {}
}
```

API 단계에 대해 X-Ray를 활성화한 후에는 X-Ray CLI를 사용하여 추적 정보를 가져옵니다. 자세한 내용은 [AWS CLI를 통한 X-Ray API 사용](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-tutorial)를 참조하세요.