Modelo do Pub/Sub para o Datadog

O modelo do Pub/Sub para o Datadog é um pipeline de streaming que lê mensagens de uma assinatura do Pub/Sub e grava o payload da mensagem no Datadog usando um endpoint do Datadog. O caso de uso mais comum para esse modelo é exportar arquivos de registros para o Datadog.

Antes de gravar no Datadog, aplique uma função JavaScript definida pelo usuário ao payload da mensagem. Todas as mensagens que apresentam falhas de processamento são encaminhadas para um tópico não processado do Pub/Sub para posterior resolução de problemas e reprocessamento.

Como uma camada extra de proteção para suas chaves de API e secrets, você também pode passar uma chave do Cloud KMS com o parâmetro de chave de API codificado em base64 criptografado com a chave do Cloud KMS. Para mais detalhes sobre como criptografar o parâmetro de chave de API, consulte o endpoint de criptografia da API Cloud KMS.

Requisitos de pipeline

  • A inscrição do Pub/Sub de origem precisa existir antes da execução do pipeline.
  • O tópico do Pub/Sub precisa existir antes de o pipeline ser executado.
  • O URL do Datadog precisa ser acessível pela rede dos workers do Dataflow.
  • A chave da API Datadog precisa ser gerada e estar disponível.

Parâmetros do modelo

Parâmetros obrigatórios

  • inputSubscription: o tópico do Pub/Sub em que a entrada será lida. Por exemplo: projects/your-project-id/subscriptions/your-subscription-name.
  • url: o URL da API Datadog Logs. Esse URL precisa ser roteável a partir da VPC em que o pipeline é executado. Para mais informações, consulte "Enviar registros" (https://docs.datadoghq.com/api/latest/logs/#send-logs) na documentação do Datadog. Exemplo: https://http-intake.logs.datadoghq.com.
  • outputDeadletterTopic: o tópico do Pub/Sub para encaminhar mensagens não entregues. Por exemplo, projects/<PROJECT_ID>/topics/<TOPIC_NAME>.

Parâmetros opcionais

  • apiKey: a chave de API do Datadog. Forneça esse valor se apiKeySource estiver definido como PLAINTEXT ou KMS. Para mais informações, consulte "Chaves de API e do aplicativo" (https://docs.datadoghq.com/account_management/api-app-keys/) na documentação do Datadog.
  • batchCount: o tamanho do lote para enviar vários eventos para o Datadog. O padrão é 1 (sem lotes).
  • parallelism: o número máximo de solicitações paralelas. O padrão é 1 (sem paralelismo).
  • includePubsubMessage: indica se a mensagem Pub/Sub completa no payload será incluída. O padrão é false (somente o elemento de dados está incluído no payload).
  • apiKeyKMSEncryptionKey: a chave do Cloud KMS a ser usada para descriptografar a chave de API. Forneça esse parâmetro se apiKeySource estiver definido como KMS. Se a chave do Cloud KMS for fornecida, será necessário passar uma chave de API criptografada. Por exemplo, projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name.
  • apiKeySecretId: o ID do secret do Secret Manager para a chave de API. Forneça esse parâmetro se apiKeySource estiver definido como SECRET_MANAGER. Exemplo: projects/your-project-id/secrets/your-secret/versions/your-secret-version.
  • apiKeySource: a fonte da chave de API. Os seguintes valores são aceitos: PLAINTEXT, KMS e SECRET_MANAGER. Forneça esse parâmetro se estiver usando o Secret Manager. Se apiKeySource estiver definido como KMS, também será necessário fornecer apiKeyKMSEncryptionKey e criptografar API Key. Se apiKeySource estiver definido como SECRET_MANAGER, você também precisará fornecer apiKeySecretId. Se apiKeySource estiver definido como PLAINTEXT, você também precisará fornecer apiKey.
  • javascriptTextTransformGcsPath: o URI do Cloud Storage do arquivo .js que define a função JavaScript definida pelo usuário (UDF) a ser usada. Por exemplo, gs://my-bucket/my-udfs/my_file.js.
  • javascriptTextTransformFunctionName: o nome da função JavaScript definida pelo usuário (UDF) a ser usada. Por exemplo, se o código de função do JavaScript for myTransform(inJson) { /*...do stuff...*/ }, o nome da função será myTransform. Para exemplos de UDFs em JavaScript, consulte os exemplos de UDF (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples).
  • javascriptTextTransformReloadIntervalMinutes: defina o intervalo que os workers podem verificar se há alterações na UDF em JavaScript para recarregar os arquivos. Padrão: 0.

Função definida pelo usuário

Também é possível estender esse modelo escrevendo uma função definida pelo usuário (UDF). O modelo chama a UDF para cada elemento de entrada. Os payloads dos elementos são serializados como strings JSON. Para mais informações, consulte Criar funções definidas pelo usuário para modelos do Dataflow.

Especificação da função

A UDF tem a seguinte especificação:

  • Entrada: o campo de dados da mensagem do Pub/Sub, serializado como uma string JSON.
  • Saída: os dados do evento a serem enviados ao endpoint do registro do Datadog. A saída precisa ser uma string ou um objeto JSON em string.

Executar o modelo

Console

  1. Acesse a página Criar job usando um modelo do Dataflow.
    2. Acesse Criar job usando um modelo
  2. No campo Nome do job, insira um nome exclusivo.
  3. Opcional: em Endpoint regional, selecione um valor no menu suspenso. A região padrão é us-central1.

    Para ver uma lista de regiões em que é possível executar um job do Dataflow, consulte Locais do Dataflow.

  4. No menu suspenso Modelo do Dataflow, selecione the Pub/Sub to Datadog template.
  5. Nos campos de parâmetro fornecidos, insira os valores de parâmetro.
  6. Cliquem em Executar job.

gcloud

No shell ou no terminal, execute o modelo:

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

Substitua:

  • JOB_NAME: um nome de job de sua escolha
  • REGION_NAME: a região onde você quer implantar o job do Dataflow, por exemplo, us-central1
  • VERSION: a versão do modelo que você quer usar

    Use estes valores:

  • STAGING_LOCATION: o local para fase de testes de arquivos locais (por exemplo, gs://your-bucket/staging)
  • INPUT_SUBSCRIPTION_NAME: o nome da assinatura do Pub/Sub
  • API_KEY: chave de API do Datadog
  • URL: o URL do endpoint do Datadog (por exemplo, https://http-intake.logs.datadoghq.com).
  • DEADLETTER_TOPIC_NAME: o nome do tópico do Pub/Sub
  • JAVASCRIPT_FUNCTION: o nome da função definida pelo usuário (UDF) do JavaScript que você quer usar

    Por exemplo, se o código de função do JavaScript for myTransform(inJson) { /*...do stuff...*/ }, o nome da função será myTransform. Para amostras de UDFs do JavaScript, consulte os exemplos de UDF.

  • PATH_TO_JAVASCRIPT_UDF_FILE: O URI do Cloud Storage do arquivo .js que define a função definida pelo usuário (UDF) do JavaScript que você quer usar, por exemplo, gs://my-bucket/my-udfs/my_file.js
  • BATCH_COUNT: o tamanho do lote a ser usado para enviar vários eventos para o Datadog
  • PARALLELISM: o número de solicitações paralelas a serem usadas para enviar eventos para o Datadog

API

Para executar o modelo usando a API REST, envie uma solicitação HTTP POST. Para mais informações sobre a API e os respectivos escopos de autorização, consulte 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"
   }
}

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud em que você quer executar o job do Dataflow
  • JOB_NAME: um nome de job de sua escolha
  • LOCATION: a região onde você quer implantar o job do Dataflow, por exemplo, us-central1
  • VERSION: a versão do modelo que você quer usar

    Use estes valores:

  • STAGING_LOCATION: o local para fase de testes de arquivos locais (por exemplo, gs://your-bucket/staging)
  • INPUT_SUBSCRIPTION_NAME: o nome da assinatura do Pub/Sub
  • API_KEY: chave de API do Datadog
  • URL: o URL do endpoint do Datadog (por exemplo, https://http-intake.logs.datadoghq.com).
  • DEADLETTER_TOPIC_NAME: o nome do tópico do Pub/Sub
  • JAVASCRIPT_FUNCTION: o nome da função definida pelo usuário (UDF) do JavaScript que você quer usar

    Por exemplo, se o código de função do JavaScript for myTransform(inJson) { /*...do stuff...*/ }, o nome da função será myTransform. Para amostras de UDFs do JavaScript, consulte os exemplos de UDF.

  • PATH_TO_JAVASCRIPT_UDF_FILE: O URI do Cloud Storage do arquivo .js que define a função definida pelo usuário (UDF) do JavaScript que você quer usar, por exemplo, gs://my-bucket/my-udfs/my_file.js
  • BATCH_COUNT: o tamanho do lote a ser usado para enviar vários eventos para o Datadog
  • PARALLELISM: o número de solicitações paralelas a serem usadas para enviar eventos para o Datadog

A seguir