Amazon API Gateway 계측 (Instrumenting Amazon API Gateway)

Amazon API Gateway를 통과해 컨테이너 또는 EC2에 호스팅된 서비스로 들어오는 요청에 대해 **유추 스팬(inferred spans)**을 생성해 엔드투엔드 트레이스, 서비스 맵, 샘플링을 지원하는 방법을 안내해요.

출처: 문서

본문

참고: Amazon API Gateway 트레이싱은 프리뷰 상태예요. 이 기능은 프리뷰에요.

Datadog APM은 Amazon API Gateway를 통과해 컨테이너 또는 EC2에 호스팅된 서비스로 들어오는 요청에 대해 유추 스팬을 생성할 수 있어요. 이 스팬은 게이트웨이 자체를 기반으로 엔드투엔드 트레이스, 서비스 맵, 샘플링을 지원해요.

경고: API Gateway가 AWS Lambda와 통합된다면 이 페이지의 지침을 따르지 마세요. Datadog Lambda 레이어는 이미 유추 API Gateway 스팬을 생성해요. 여기에 설명된 프록시 헤더를 추가하면 중복되거나 충돌하는 트레이스가 생성될 수 있어요.

사전 요구 사항

• Amazon API Gateway가 REST API(v1) 또는 HTTP API(v2)로 배포되어 있어야 해요.

참고: HTTP API(v2)를 사용하면 context.requestTimeEpoch가 REST API(v1)가 제공하는 밀리초 정밀도와 달리 초 단위 정밀도를 제공해요. 즉 스팬 기간이 근사값이에요.

• 애플리케이션 컨테이너에 DD_TRACE_INFERRED_PROXY_SERVICES_ENABLED가 설정되어 있어야 해요:

    export DD_TRACE_INFERRED_PROXY_SERVICES_ENABLED=true
  
  

또는 Datadog ECS Fargate CDK 구성물을 통해 활성화할 수 있어요:

  ```typescript
    new DatadogECSFargate(this, 'Datadog', {
      apm: { isEnabled: true, traceInferredProxyServices: true },
    });
    

또는 Datadog ECS Fargate Terraform 모듈을 통해 활성화할 수 있어요:

  module "ecs_fargate_task" { 
    dd_apm = {
      enabled = true,
      trace_inferred_proxy_services = true
    }
  }
  

• 기본 애플리케이션이 지원되는 웹 프레임워크에서 실행 중이어야 해요.

• 애플리케이션 트레이서가 최소 버전을 충족해야 해요.

지원되는 버전 및 웹 프레임워크

설정

REST API (v1)

유추 스팬을 생성하려면 API Gateway가 백엔드 서비스에 다음 헤더를 전달해야 해요:

필요한 헤더를 전달하려면 AWS CDK 또는 AWS Console을 사용할 수 있어요:

AWS CDK

requestParameters 아래에 헤더를 추가하고 $context 변수를 사용해요:

import { DatadogAPIGatewayRequestParameters } from "datadog-cdk-constructs-v2";

// Datadog 통합 정의
const ddIntegration = new apigateway.Integration({
  type: apigateway.IntegrationType.HTTP_PROXY,
  integrationHttpMethod: "ANY",
  options: {
    connectionType: apigateway.ConnectionType.INTERNET,
    requestParameters: DatadogAPIGatewayRequestParameters,
  },
  uri: `http://${loadBalancer.loadBalancerDnsName}`,
});

const api = new apigateway.RestApi(this, "MyApi", {
  restApiName: "my-api-gateway",
  deployOptions: { stageName: "prod" },
  defaultIntegration: ddIntegration, // 여기서 Datadog 계측 적용
});

AWS Console

1. AWS Management Console에서 API Gateway로 이동해 API의 Resources 페이지로 가요.

2. Integration request로 이동해 Edit를 클릭해요.

3. Edit integration request 아래의 URL request headers parameters로 가서 Add request header parameter를 클릭해요.

HTTP API (v2)

유추 스팬을 생성하려면 API Gateway가 백엔드 서비스에 다음 헤더를 전달해야 해요:

참고: v2 API에서 context.requestTimeEpoch는 초 단위 타임스탬프를 반환해요. Datadog은 밀리초를 기대하므로 000을 추가해 1000을 곱해야 해요.

헤더를 주입하는 파라미터 매핑을 연결해요:

   import { DatadogAPIGatewayV2ParameterMapping }
     from 'datadog-cdk-constructs-v2';

   const ddIntegration = new apigatewayv2_integrations.HttpUrlIntegration(
     'HttpUrlIntegration',
     'https://example.com',
     { parameterMapping: DatadogAPIGatewayV2ParameterMapping },
   );

   new apigatewayv2.HttpApi(this, 'HttpApi', {
     apiName: 'my-http-api',
     routes: [{
       path: '/{proxy+}',
       methods: [apigatewayv2.HttpMethod.ANY],
       integration: ddIntegration,
     }],
   });

샘플링 규칙 업데이트

API Gateway 트레이싱을 사용할 때도 헤드 기반 샘플링이 적용돼요. 유추 스팬이 새 트레이스 루트가 되므로, 서비스 값이 Datadog에 표시되는 API Gateway 서비스 이름과 일치하도록 규칙을 업데이트해요.

예를 들어 원래 샘플링 규칙이 다음과 같다면:

# 이전: 업스트림 서비스 샘플링
DD_TRACE_SAMPLING_RULES='[{"service":"pythonapp","sample_rate":0.5}]'

다음 중 한 가지 방식으로 규칙을 업데이트해요:

1. service 값을 Datadog에 표시되는 API Gateway의 이름과 일치하도록 변경해요:

      # 옵션 1: 게이트웨이 루트 스팬 샘플링
      DD_TRACE_SAMPLING_RULES='[{"service":"my-api-gateway","sample_rate":0.5}]'
   
   

1. `service` 키를 제거해 규칙을 모든 루트 스팬에 적용해요:

   ```shell
      # 옵션 2: 모든 루트에 적용
      DD_TRACE_SAMPLING_RULES='[{"sample_rate":0.5}]'
      

더 알아보기 (Learn more)

• Tutorial - Enabling Tracing for a Go Application on Amazon ECS with Fargate
• Amazon ECS on AWS Fargate
• Amazon EKS on AWS Fargate