Pub/Sub to Datadog 템플릿

Pub/Sub to Datadog 템플릿은 Pub/Sub 구독에서 메시지를 읽고 Datadog 엔드포인트를 사용해서 메시지 페이로드를 Datadog에 기록하는 스트리밍 파이프라인입니다. 이 템플릿의 가장 일반적인 사용 사례는 로그 파일을 Datadog로 내보내는 것입니다.

Datadog에 기록하기 전 메시지 페이로드에 JavaScript 사용자 정의 함수를 적용할 수 있습니다. 처리 실패가 발생한 메시지는 추가적인 문제 해결 및 재처리를 위해 Pub/Sub 처리 불가 주제로 전달됩니다.

API 키 및 보안 비밀에 대한 추가 보호 레이어로, Cloud KMS 키로 암호화된 base64 인코딩 API 키 매개변수와 함께 Cloud KMS 키를 전달할 수도 있습니다. API 키 매개변수 암호화에 대한 자세한 내용은 Cloud KMS API 암호화 엔드포인트를 참조하세요.

파이프라인 요구사항

  • 파이프라인을 실행하기 전에 소스 Pub/Sub 구독이 있어야 합니다.
  • 파이프라인을 실행하기 전에 Pub/Sub 처리되지 않은 주제가 있어야 합니다.
  • Datadog URL은 Dataflow 작업자 네트워크에서 액세스할 수 있어야 합니다.
  • Datadog API 키는 생성되고 사용 가능해야 합니다.

템플릿 매개변수

필수 매개변수

  • inputSubscription: 입력을 읽어올 Pub/Sub 구독입니다. (예: projects/your-project-id/subscriptions/your-subscription-name)
  • url: Datadog Logs API URL입니다. 이 URL은 파이프라인이 실행되는 VPC에서 라우팅할 수 있어야 합니다. 자세한 내용은 Datadog 문서의 로그 보내기(https://docs.datadoghq.com/api/latest/logs/#send-logs)를 참조하세요. (예: https://http-intake.logs.datadoghq.com)
  • outputDeadletterTopic: 전달할 수 없는 메시지를 전달할 Pub/Sub 주제입니다. (예: projects/<PROJECT_ID>/topics/<TOPIC_NAME>)

선택적 매개변수

  • apiKey: Datadog API 키입니다. apiKeySourcePLAINTEXT 또는 KMS로 설정된 경우 이 값을 제공해야 합니다. 자세한 내용은 Datadog 문서의 API 및 애플리케이션 키(https://docs.datadoghq.com/account_management/api-app-keys/)를 참조하세요.
  • batchCount: Datadog에 여러 이벤트를 전송하기 위한 배치 크기입니다. 기본값은 1입니다(일괄 처리 없음).
  • parallelism: 최대 동시 요청 수입니다. 기본값은 1입니다(동시 로드 없음).
  • includePubsubMessage: 페이로드에 전체 Pub/Sub 메시지를 포함할지 여부입니다. 기본값은 true입니다(데이터 요소를 포함한 모든 요소가 페이로드에 포함됨).
  • apiKeyKMSEncryptionKey: API 키를 복호화하는 데 사용할 Cloud KMS 키입니다. apiKeySourceKMS로 설정된 경우 이 매개변수를 제공해야 합니다. Cloud KMS 키가 제공되면 암호화된 API 키를 전달해야 합니다. (예: projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name)
  • apiKeySecretId: API 키의 Secret Manager 보안 비밀 ID입니다. apiKeySourceSECRET_MANAGER로 설정된 경우 이 매개변수를 제공해야 합니다. (예: projects/your-project-id/secrets/your-secret/versions/your-secret-version).
  • apiKeySource: API 키의 소스입니다. PLAINTEXT, KMS, SECRET_MANAGER 값이 지원됩니다. Secret Manager를 사용하는 경우에는 이 매개변수를 제공해야 합니다. apiKeySourceKMS로 설정된 경우 apiKeyKMSEncryptionKey 및 암호화된 API Key도 제공해야 합니다. apiKeySourceSECRET_MANAGER로 설정된 경우 apiKeySecretId도 제공해야 합니다. apiKeySourcePLAINTEXT로 설정된 경우 apiKey도 제공해야 합니다.
  • javascriptTextTransformGcsPath: 사용할 JavaScript 사용자 정의 함수(UDF)를 정의하는 .js 파일의 Cloud Storage URI입니다. 예를 들면 gs://my-bucket/my-udfs/my_file.js입니다.
  • javascriptTextTransformFunctionName : 사용할 JavaScript 사용자 정의 함수(UDF)의 이름입니다. 예를 들어 JavaScript 함수가 myTransform(inJson) { /*...do stuff...*/ }이면 함수 이름은 myTransform입니다. 샘플 JavaScript UDF는 UDF 예시(https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples)를 참조하세요.
  • javascriptTextTransformReloadIntervalMinutes: 작업자가 파일을 새로고침하기 위해 JavaScript UDF 변경사항을 확인할 수 있는 간격을 정의합니다. 기본값은 0입니다.

사용자 정의 함수

선택적으로 사용자 정의 함수(UDF)를 작성하여 이 템플릿을 확장할 수 있습니다. 템플릿이 각 입력 요소에 대해 UDF를 호출합니다. 요소 페이로드는 JSON 문자열로 직렬화됩니다. 자세한 내용은 Dataflow 템플릿에 대한 사용자 정의 함수 만들기를 참조하세요.

함수 사양

UDF의 사양은 다음과 같습니다.

  • 입력: JSON 문자열로 직렬화된 Pub/Sub 메시지 데이터 필드입니다.
  • 출력: Datadog 로그 엔드포인트로 전송할 이벤트 데이터입니다. 출력은 문자열 또는 문자열화된 JSON 객체여야 합니다.

템플릿 실행

콘솔

  1. Dataflow 템플릿에서 작업 만들기 페이지로 이동합니다.
  2. 템플릿에서 작업 만들기로 이동
  3. 작업 이름 필드에 고유한 작업 이름을 입력합니다.
  4. (선택사항): 리전 엔드포인트의 드롭다운 메뉴에서 값을 선택합니다. 기본 리전은 us-central1입니다.

    Dataflow 작업을 실행할 수 있는 리전 목록은 Dataflow 위치를 참조하세요.

  5. Dataflow 템플릿 드롭다운 메뉴에서 the Pub/Sub to Datadog template을 선택합니다.
  6. 제공된 매개변수 필드에 매개변수 값을 입력합니다.
  7. 작업 실행을 클릭합니다.

gcloud

셸 또는 터미널에서 템플릿을 실행합니다.

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/Cloud_PubSub_to_Datadog \
    --region REGION_NAME \
    --staging-location STAGING_LOCATION \
    --parameters \
inputSubscription=projects/PROJECT_ID/subscriptions/INPUT_SUBSCRIPTION_NAME,\
apiKey=API_KEY,\
url=URL,\
outputDeadletterTopic=projects/PROJECT_ID/topics/DEADLETTER_TOPIC_NAME,\
javascriptTextTransformGcsPath=PATH_TO_JAVASCRIPT_UDF_FILE,\
javascriptTextTransformFunctionName=JAVASCRIPT_FUNCTION,\
batchCount=BATCH_COUNT,\
parallelism=PARALLELISM

다음을 바꿉니다.

  • JOB_NAME: 선택한 고유한 작업 이름
  • REGION_NAME: Dataflow 작업을 배포할 리전(예: us-central1)
  • VERSION: 사용할 템플릿 버전

    다음 값을 사용할 수 있습니다.

  • STAGING_LOCATION: 로컬 파일의 스테이징 위치(예: gs://your-bucket/staging)
  • INPUT_SUBSCRIPTION_NAME: Pub/Sub 구독 이름
  • API_KEY: Datadog의 API 키
  • URL: Datadog 엔드포인트의 URL(예: https://http-intake.logs.datadoghq.com)
  • DEADLETTER_TOPIC_NAME: Pub/Sub 주제 이름
  • JAVASCRIPT_FUNCTION: 사용할 자바스크립트 사용자 정의 함수(UDF)의 이름입니다.

    예를 들어 자바스크립트 함수가 myTransform(inJson) { /*...do stuff...*/ }이면 함수 이름은 myTransform입니다. 샘플 JavaScript UDF는 UDF 예시를 참조하세요.

  • PATH_TO_JAVASCRIPT_UDF_FILE: 사용할 JavaScript 사용자 정의 함수(UDF)를 정의하는 .js 파일의 Cloud Storage URI입니다. 예를 들면 gs://my-bucket/my-udfs/my_file.js입니다.
  • BATCH_COUNT: Datadog에 여러 이벤트를 전송하기 위해 사용할 배치 크기
  • PARALLELISM: Datadog에 이벤트를 전송하기 위해 사용할 동시 요청 수

API

REST API를 사용하여 템플릿을 실행하려면 HTTP POST 요청을 전송합니다. API 및 승인 범위에 대한 자세한 내용은 projects.templates.launch를 참조하세요.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates-LOCATION/VERSION/Cloud_PubSub_to_Datadog
{
   "jobName": "JOB_NAME",
   "environment": {
       "ipConfiguration": "WORKER_IP_UNSPECIFIED",
       "additionalExperiments": []
   },
   "parameters": {
       "inputSubscription": "projects/PROJECT_ID/subscriptions/INPUT_SUBSCRIPTION_NAME",
       "apiKey": "API_KEY",
       "url": "URL",
       "outputDeadletterTopic": "projects/PROJECT_ID/topics/DEADLETTER_TOPIC_NAME",
       "javascriptTextTransformGcsPath": "PATH_TO_JAVASCRIPT_UDF_FILE",
       "javascriptTextTransformFunctionName": "JAVASCRIPT_FUNCTION",
       "batchCount": "BATCH_COUNT",
       "parallelism": "PARALLELISM"
   }
}

다음을 바꿉니다.

  • PROJECT_ID: Dataflow 작업을 실행하려는 Google Cloud 프로젝트 ID
  • JOB_NAME: 선택한 고유한 작업 이름
  • LOCATION: Dataflow 작업을 배포할 리전(예: us-central1)
  • VERSION: 사용할 템플릿 버전

    다음 값을 사용할 수 있습니다.

  • STAGING_LOCATION: 로컬 파일의 스테이징 위치(예: gs://your-bucket/staging)
  • INPUT_SUBSCRIPTION_NAME: Pub/Sub 구독 이름
  • API_KEY: Datadog의 API 키
  • URL: Datadog 엔드포인트의 URL(예: https://http-intake.logs.datadoghq.com)
  • DEADLETTER_TOPIC_NAME: Pub/Sub 주제 이름
  • JAVASCRIPT_FUNCTION: 사용할 자바스크립트 사용자 정의 함수(UDF)의 이름입니다.

    예를 들어 자바스크립트 함수가 myTransform(inJson) { /*...do stuff...*/ }이면 함수 이름은 myTransform입니다. 샘플 JavaScript UDF는 UDF 예시를 참조하세요.

  • PATH_TO_JAVASCRIPT_UDF_FILE: 사용할 JavaScript 사용자 정의 함수(UDF)를 정의하는 .js 파일의 Cloud Storage URI입니다. 예를 들면 gs://my-bucket/my-udfs/my_file.js입니다.
  • BATCH_COUNT: Datadog에 여러 이벤트를 전송하기 위해 사용할 배치 크기
  • PARALLELISM: Datadog에 이벤트를 전송하기 위해 사용할 동시 요청 수

다음 단계