Modello da Pub/Sub a Datadog

Il modello da Pub/Sub a Datadog è una pipeline di inserimento flussi che legge i messaggi da una sottoscrizione Pub/Sub e scrive il payload dei messaggi a Datadog utilizzando un endpoint Datadog. Il caso d'uso più comune per questo modello è esportare i file di log in Datadog.

Prima di scrivere in Datadog, puoi applicare una funzione JavaScript definita dall'utente al payload del messaggio. Tutti i messaggi che riscontrano errori di elaborazione vengono inoltrati a un argomento Pub/Sub non elaborato per ulteriore risoluzione dei problemi e rielaborazione.

Come ulteriore livello di protezione per i tuoi secret e le tue chiavi API, puoi anche passare una chiave Cloud KMS insieme al parametro della chiave API con codifica Base64 e criptato con la chiave Cloud KMS. Per ulteriori dettagli sulla crittografia del parametro della chiave API, consulta Endpoint di crittografia dell'API Cloud KMS.

Requisiti della pipeline

  • La sottoscrizione Pub/Sub di origine deve esistere prima dell'esecuzione della pipeline.
  • L'argomento non elaborato di Pub/Sub deve esistere prima dell'esecuzione della pipeline.
  • L'URL Datadog deve essere accessibile dalla rete dei worker Dataflow.
  • La chiave API Datadog deve essere generata e disponibile.

Parametri del modello

Parametri obbligatori

  • inputSubscription : la sottoscrizione Pub/Sub da cui leggere l'input. ad esempio projects/your-project-id/subscriptions/your-subscription-name).
  • url : l'URL dell'API Datadog Logs. Questo URL deve essere instradabile dal VPC in cui viene eseguita la pipeline. Per ulteriori informazioni, consulta Invia log (https://docs.datadoghq.com/api/latest/logs/#send-logs) nella documentazione di Datadog. Esempio: https://http-intake.logs.datadoghq.com.
  • outputDeadletterTopic : l'argomento Pub/Sub a cui inoltrare i messaggi non recapitabili. Ad esempio, projects/<PROJECT_ID>/topics/<TOPIC_NAME>.

Parametri facoltativi

  • apiKey : la chiave API Datadog. Devi specificare questo valore se apiKeySource è impostato su PLAINTEXT o KMS. Per saperne di più, vedi API e chiavi applicazione (https://docs.datadoghq.com/account_management/api-app-keys/) nella documentazione Datadog.
  • batchCount : la dimensione del batch per l'invio di più eventi a Datadog. Il valore predefinito è 1 (nessun raggruppamento).
  • parallelism : il numero massimo di richieste parallele. Il valore predefinito è 1 (nessun parallelismo).
  • includePubsubMessage : indica se includere il messaggio Pub/Sub completo nel payload. Il valore predefinito è false (solo l'elemento dei dati è incluso nel payload).
  • apiKeyKMSEncryptionKey : la chiave Cloud KMS da utilizzare per decriptare la chiave API. Devi fornire questo parametro se apiKeySource è impostato su KMS. Se viene fornita la chiave Cloud KMS, devi passarla in una chiave API criptata. ad esempio projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name).
  • apiKeySecretId : l'ID secret di Secret Manager per la chiave API. Devi fornire questo parametro se apiKeySource è impostato su SECRET_MANAGER. (Esempio: projects/your-project-id/secrets/your-secret/versions/your-secret-version).
  • apiKeySource : l'origine della chiave API. Sono supportati i seguenti valori: PLAINTEXT, KMS e SECRET_MANAGER. Devi fornire questo parametro se utilizzi Secret Manager. Se il criterio apiKeySource è impostato su KMS, devi anche fornire apiKeyKMSEncryptionKey e API Key criptato. Se apiKeySource è impostato su SECRET_MANAGER, devi fornire anche apiKeySecretId. Se apiKeySource è impostato su PLAINTEXT, devi fornire anche apiKey.
  • javascriptTextTransformGcsPath : l'URI Cloud Storage del file .js che definisce la funzione definita dall'utente (UDF) JavaScript da utilizzare. Ad esempio, gs://my-bucket/my-udfs/my_file.js.
  • javascriptTextTransformFunctionName : il nome della funzione definita dall'utente (UDF) JavaScript da utilizzare. Ad esempio, se il codice della funzione JavaScript è myTransform(inJson) { /*...do stuff...*/ }, il nome della funzione è myTransform. Per esempi di funzioni JavaScript definite dall'utente, consulta gli esempi di funzioni definite dall'utente (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples).
  • javascriptTextTransformReloadIntervalMinutes : definisci l'intervallo che i worker possono verificare per le modifiche della funzione JavaScript definita dall'utente per ricaricare i file. Il valore predefinito è 0.

Funzione definita dall'utente

Facoltativamente, puoi estendere questo modello scrivendo una funzione definita dall'utente dall'utente. Il modello chiama la funzione definita dall'utente per ogni elemento di input. I payload degli elementi sono serializzati come stringhe JSON. Per ulteriori informazioni, consulta Creare funzioni definite dall'utente per i modelli Dataflow.

Specifica della funzione

La funzione definita dall'utente ha la seguente specifica:

  • Input: il campo dati del messaggio Pub/Sub, serializzato come stringa JSON.
  • Output: i dati sugli eventi da inviare all'endpoint del log di Datadog. L'output deve essere una stringa o un oggetto JSON con stringhe.

Esegui il modello

Console

  1. Vai alla pagina Crea job da modello di Dataflow.
    2. Vai a Crea job da modello
  2. Nel campo Nome job, inserisci un nome univoco per il job.
  3. (Facoltativo) Per Endpoint a livello di regione, seleziona un valore dal menu a discesa. La regione predefinita è us-central1.

    Per un elenco di regioni in cui è possibile eseguire un job Dataflow, consulta Località di Dataflow.

  4. Dal menu a discesa Modello Dataflow, seleziona the Pub/Sub to Datadog template.
  5. Inserisci i valori parametro negli appositi campi.
  6. Fai clic su Esegui job.

gcloud

Nella shell o nel terminale, esegui il modello:

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

Sostituisci quanto segue:

  • JOB_NAME: un nome job univoco a tua scelta
  • REGION_NAME: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempio us-central1
  • VERSION: la versione del modello che vuoi utilizzare

    Puoi utilizzare i seguenti valori:

    • latest per utilizzare la versione più recente del modello, disponibile nella cartella padre non con data del bucket: gs://dataflow-templates-REGION_NAME/latest/
    • il nome della versione, ad esempio 2023-09-12-00_RC00, per utilizzare una versione specifica del modello, che è possibile trovare nidificata nella rispettiva cartella principale con data nel bucket: gs://dataflow-templates-REGION_NAME/
  • STAGING_LOCATION: la posizione per i file locali di gestione temporanea (ad esempio, gs://your-bucket/staging)
  • INPUT_SUBSCRIPTION_NAME: il nome della sottoscrizione Pub/Sub
  • API_KEY: chiave API di Datadog
  • URL: l'URL dell'endpoint di Datadog (ad esempio, https://http-intake.logs.datadoghq.com)
  • DEADLETTER_TOPIC_NAME: il nome dell'argomento Pub/Sub
  • JAVASCRIPT_FUNCTION: il nome della funzione definita dall'utente (UDF) JavaScript che vuoi utilizzare

    Ad esempio, se il codice della funzione JavaScript è myTransform(inJson) { /*...do stuff...*/ }, il nome della funzione è myTransform. Per esempi di funzioni JavaScript definite dall'utente, consulta gli esempi di funzioni definite dall'utente.

  • PATH_TO_JAVASCRIPT_UDF_FILE: L'URI Cloud Storage del file .js che definisce la funzione JavaScript definita dall'utente che vuoi utilizzare, ad esempio gs://my-bucket/my-udfs/my_file.js
  • BATCH_COUNT: la dimensione del batch da utilizzare per inviare più eventi a Datadog
  • PARALLELISM: il numero di richieste parallele da utilizzare per l'invio di eventi a Datadog

API

Per eseguire il modello utilizzando l'API REST, invia una richiesta POST HTTP. Per maggiori informazioni sull'API e sui relativi ambiti di autorizzazione, consulta 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"
   }
}

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto Google Cloud in cui vuoi eseguire il job Dataflow
  • JOB_NAME: un nome job univoco a tua scelta
  • LOCATION: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempio us-central1
  • VERSION: la versione del modello che vuoi utilizzare

    Puoi utilizzare i seguenti valori:

    • latest per utilizzare la versione più recente del modello, disponibile nella cartella padre non con data del bucket: gs://dataflow-templates-REGION_NAME/latest/
    • il nome della versione, ad esempio 2023-09-12-00_RC00, per utilizzare una versione specifica del modello, che è possibile trovare nidificata nella rispettiva cartella principale con data nel bucket: gs://dataflow-templates-REGION_NAME/
  • STAGING_LOCATION: la posizione per i file locali di gestione temporanea (ad esempio, gs://your-bucket/staging)
  • INPUT_SUBSCRIPTION_NAME: il nome della sottoscrizione Pub/Sub
  • API_KEY: chiave API di Datadog
  • URL: l'URL dell'endpoint di Datadog (ad esempio, https://http-intake.logs.datadoghq.com)
  • DEADLETTER_TOPIC_NAME: il nome dell'argomento Pub/Sub
  • JAVASCRIPT_FUNCTION: il nome della funzione definita dall'utente (UDF) JavaScript che vuoi utilizzare

    Ad esempio, se il codice della funzione JavaScript è myTransform(inJson) { /*...do stuff...*/ }, il nome della funzione è myTransform. Per esempi di funzioni JavaScript definite dall'utente, consulta gli esempi di funzioni definite dall'utente.

  • PATH_TO_JAVASCRIPT_UDF_FILE: L'URI Cloud Storage del file .js che definisce la funzione JavaScript definita dall'utente che vuoi utilizzare, ad esempio gs://my-bucket/my-udfs/my_file.js
  • BATCH_COUNT: la dimensione del batch da utilizzare per inviare più eventi a Datadog
  • PARALLELISM: il numero di richieste parallele da utilizzare per l'invio di eventi a Datadog

Passaggi successivi