Plantilla de Pub/Sub a Datadog

La plantilla de Pub/Sub a Datadog es una canalización de transmisión que lee mensajes de una suscripción a Pub/Sub y escribe la carga útil del mensaje en Datadog mediante el uso de un extremo de Datadog. El caso de uso más común de esta plantilla es exportar archivos de registro a Datadog.

Antes de escribir en Datadog, puedes aplicar una función definida por el usuario de JavaScript a la carga útil del mensaje. Los mensajes con fallas de procesamiento se reenvían a un tema de mensajes no enviados de Pub/Sub para solucionar los problemas y volver a procesarlos.

Como una capa adicional de protección para tus claves y secretos de API, también puedes pasar una clave de Cloud KMS junto con el parámetro de clave de API codificado en base64 encriptado con la clave de Cloud KMS. Para obtener más detalles sobre cómo encriptar el parámetro de clave de API, consulta el extremo de encriptación de la API de Cloud KMS.

Requisitos de la canalización

  • La suscripción de Pub/Sub de origen debe existir antes de ejecutar la canalización.
  • El tema sin procesar de Pub/Sub debe existir antes de ejecutar la canalización.
  • Se debe poder acceder a la URL de Datadog desde la red de los trabajadores de Dataflow.
  • La clave de API de Datadog debe generarse y estar disponible.

Parámetros de la plantilla

Parámetros obligatorios

  • inputSubscription: Es la suscripción a Pub/Sub desde la que se lee la entrada. Por ejemplo, projects/your-project-id/subscriptions/your-subscription-name
  • url: La URL de la API de registros de Datadog. Esta URL se debe poder enrutar desde la VPC en la que se ejecuta la canalización. Consulta los registros de envío (https://docs.datadoghq.com/api/latest/logs/#send-logs) en la documentación de Datadog para obtener más información. Por ejemplo, https://http-intake.logs.datadoghq.com.
  • outputDeadletterTopic: El tema de Pub/Sub al que se reenviarán los mensajes que no se pueden entregar. Por ejemplo, projects/<PROJECT_ID>/topics/<TOPIC_NAME>

Parámetros opcionales

  • apiKey: La clave de API de Datadog. Debes proporcionar este valor si apiKeySource se configura como PLAINTEXT o KMS. Para obtener más información, consulta la API y las claves de aplicación (https://docs.datadoghq.com/account_management/api-app-keys/) en la documentación de Datadog.
  • batchCount: El tamaño del lote para enviar varios eventos a Datadog. El valor predeterminado es 1 (sin lotes).
  • parallelism: Es la cantidad máxima de solicitudes paralelas. El valor predeterminado es 1 (sin paralelismo).
  • includePubsubMessage: Indica si se debe incluir el mensaje de Pub/Sub completo en la carga útil. El valor predeterminado es true (todos los elementos, incluido el de datos, se incluyen en la carga útil).
  • apiKeyKMSEncryptionKey: La clave de Cloud KMS que se usará para desencriptar la clave de API. Debes proporcionar este parámetro si apiKeySource se configura como KMS. Si se proporciona la clave de Cloud KMS, debes pasar una clave de API encriptada. Por ejemplo, projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name.
  • apiKeySecretId: El ID del Secret de Secret Manager para la clave de API. Debes proporcionar este parámetro si apiKeySource se configura como SECRET_MANAGER. Por ejemplo, projects/your-project-id/secrets/your-secret/versions/your-secret-version.
  • apiKeySource: Es la fuente de la clave de API. Se admiten los siguientes valores: PLAINTEXT, KMS y SECRET_MANAGER. Debes proporcionar este parámetro si usas Secret Manager. Si apiKeySource se configura como KMS, también debes proporcionar apiKeyKMSEncryptionKey y API Key encriptado. Si apiKeySource se configura como SECRET_MANAGER, también debes proporcionar apiKeySecretId. Si apiKeySource se configura como PLAINTEXT, también debes proporcionar apiKey.
  • javascriptTextTransformGcsPath: El URI de Cloud Storage del archivo .js que define la función definida por el usuario (UDF) de JavaScript que se usará. Por ejemplo, gs://my-bucket/my-udfs/my_file.js
  • javascriptTextTransformFunctionName: Es el nombre de la función definida por el usuario (UDF) de JavaScript que se usará. Por ejemplo, si el código de tu función de JavaScript es myTransform(inJson) { /*...do stuff...*/ }, el nombre de la función es myTransform. Para ver ejemplos de UDF de JavaScript, consulta Ejemplos de UDF (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples).
  • javascriptTextTransformReloadIntervalMinutes: Define el intervalo que los trabajadores pueden verificar para detectar cambios en la UDF de JavaScript a fin de volver a cargar los archivos. La configuración predeterminada es 0.

Función definida por el usuario

Para extender esta plantilla, puedes escribir una función definida por el usuario (UDF). La plantilla llama a la UDF para cada elemento de entrada. Las cargas útiles de elementos se serializan como cadenas JSON. Para obtener más información, consulta Crea funciones definidas por el usuario para plantillas de Dataflow.

Especificación de la función

La UDF tiene la siguiente especificación:

  • Entrada: el campo de datos del mensaje de Pub/Sub, serializado como una cadena JSON.
  • Resultado: Los datos del evento que se enviarán al extremo del sitio de Datadog. El resultado debe ser una cadena o un objeto JSON en cadena.

Ejecuta la plantilla

Console

  1. Ve a la página Crear un trabajo a partir de una plantilla de Dataflow.
    2. Ir a Crear un trabajo a partir de una plantilla
  2. En el campo Nombre del trabajo, ingresa un nombre de trabajo único.
  3. Opcional: Para Extremo regional, selecciona un valor del menú desplegable. La región predeterminada es us-central1.

    Para obtener una lista de regiones en las que puedes ejecutar un trabajo de Dataflow, consulta Ubicaciones de Dataflow.

  4. En el menú desplegable Plantilla de Dataflow, selecciona the Pub/Sub to Datadog template.
  5. En los campos de parámetros proporcionados, ingresa los valores de tus parámetros.
  6. Haga clic en Ejecutar trabajo.

gcloud

En tu shell o terminal, ejecuta la plantilla:

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

Reemplaza lo siguiente:

  • JOB_NAME: Es el nombre del trabajo que elijas
  • REGION_NAME: La región en la que deseas implementar tu trabajo de Dataflow, por ejemplo, us-central1
  • VERSION: Es la versión de la plantilla que deseas usar.

    Puedes usar los siguientes valores:

    • latest para usar la última versión de la plantilla, que está disponible en la carpeta superior non-dated en el bucket gs://dataflow-templates-REGION_NAME/latest/
    • el nombre de la versión, como 2023-09-12-00_RC00, para usar una versión específica de la plantilla, que se puede encontrar anidada en la carpeta superior con fecha correspondiente en el bucket gs://dataflow-templates-REGION_NAME/
  • STAGING_LOCATION: la ubicación para los archivos locales de etapa de pruebas (por ejemplo, gs://your-bucket/staging).
  • INPUT_SUBSCRIPTION_NAME: Es el nombre de la suscripción a Pub/Sub.
  • API_KEY: La clave de API de Datadog
  • URL: Es la URL del extremo de Datadog (por ejemplo, https://http-intake.logs.datadoghq.com).
  • DEADLETTER_TOPIC_NAME: Es el nombre del tema de Pub/Sub.
  • JAVASCRIPT_FUNCTION es el nombre de la función definida por el usuario (UDF) de JavaScript que deseas usar.

    Por ejemplo, si el código de tu función de JavaScript es myTransform(inJson) { /*...do stuff...*/ }, el nombre de la función es myTransform. Para ver ejemplos de UDF de JavaScript, consulta Ejemplos de UDF.

  • PATH_TO_JAVASCRIPT_UDF_FILE: El URI de Cloud Storage del archivo .js que define la función definida por el usuario (UDF) de JavaScript que deseas usar, por ejemplo:gs://my-bucket/my-udfs/my_file.js
  • BATCH_COUNT: Es el tamaño del lote que se debe usar para enviar varios eventos a Datadog.
  • PARALLELISM: Es la cantidad de solicitudes paralelas que se usarán para enviar eventos a Datadog.

API

Para ejecutar la plantilla con la API de REST, envía una solicitud POST HTTP. Para obtener más información de la API y sus permisos de autorización, 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"
   }
}

Reemplaza lo siguiente:

  • PROJECT_ID: El ID del proyecto de Google Cloud en el que deseas ejecutar el trabajo de Dataflow.
  • JOB_NAME: Es el nombre del trabajo que elijas
  • LOCATION: La región en la que deseas implementar tu trabajo de Dataflow, por ejemplo, us-central1
  • VERSION: Es la versión de la plantilla que deseas usar.

    Puedes usar los siguientes valores:

    • latest para usar la última versión de la plantilla, que está disponible en la carpeta superior non-dated en el bucket gs://dataflow-templates-REGION_NAME/latest/
    • el nombre de la versión, como 2023-09-12-00_RC00, para usar una versión específica de la plantilla, que se puede encontrar anidada en la carpeta superior con fecha correspondiente en el bucket gs://dataflow-templates-REGION_NAME/
  • STAGING_LOCATION: la ubicación para los archivos locales de etapa de pruebas (por ejemplo, gs://your-bucket/staging).
  • INPUT_SUBSCRIPTION_NAME: Es el nombre de la suscripción a Pub/Sub.
  • API_KEY: La clave de API de Datadog
  • URL: Es la URL del extremo de Datadog (por ejemplo, https://http-intake.logs.datadoghq.com).
  • DEADLETTER_TOPIC_NAME: Es el nombre del tema de Pub/Sub.
  • JAVASCRIPT_FUNCTION es el nombre de la función definida por el usuario (UDF) de JavaScript que deseas usar.

    Por ejemplo, si el código de tu función de JavaScript es myTransform(inJson) { /*...do stuff...*/ }, el nombre de la función es myTransform. Para ver ejemplos de UDF de JavaScript, consulta Ejemplos de UDF.

  • PATH_TO_JAVASCRIPT_UDF_FILE: El URI de Cloud Storage del archivo .js que define la función definida por el usuario (UDF) de JavaScript que deseas usar, por ejemplo:gs://my-bucket/my-udfs/my_file.js
  • BATCH_COUNT: Es el tamaño del lote que se debe usar para enviar varios eventos a Datadog.
  • PARALLELISM: Es la cantidad de solicitudes paralelas que se usarán para enviar eventos a Datadog.

¿Qué sigue?