Vorlage "Pub/Sub für Datadog"

Die Vorlage "Pub/Sub für Datadog" ist eine Streamingpipeline, die Nachrichten aus einem Pub/Sub-Abo liest und die Nutzlast der Nachricht mithilfe von Datadog-Endpunkten in Datadog schreibt. Der häufigste Anwendungsfall für diese Vorlage ist das Exportieren von Logdateien in Datadog.

Vor dem Schreiben in Datadog können Sie eine benutzerdefinierte JavaScript-Funktion auf die Nachrichtennutzlast anwenden. Alle Nachrichten, bei denen Verarbeitungsfehler auftreten, werden zur weiteren Fehlerbehebung und erneuten Verarbeitung an ein unverarbeitetes Thema in Pub/Sub weitergeleitet.

Als zusätzlichen Schutz für Ihre API-Schlüssel und -Secrets können Sie auch einen Cloud KMS-Schlüssel zusammen mit dem base64-codierten API-Schlüsselparameter übergeben, der mit dem Cloud KMS-Schlüssel verschlüsselt ist. Weitere Informationen zum Verschlüsseln des API-Schlüsselparameters finden Sie unter Cloud KMS API-Verschlüsselungsendpunkt.

Pipelineanforderungen

  • Das als Quelle dienende Pub/Sub-Abo muss vorhanden sein, bevor Sie die Pipeline ausführen.
  • Das Pub/Sub-Thema für nicht verarbeitete Datensätze muss vorhanden sein, bevor die Pipeline ausgeführt wird.
  • Auf die Datadog-URL muss über das Netzwerk der Dataflow-Worker zugegriffen werden können.
  • Der Datadog API-Schlüssel muss generiert und verfügbar sein.

Vorlagenparameter

Erforderliche Parameter

  • inputSubscription: Das Pub/Sub-Abo, aus dem die Eingabe gelesen werden soll. (Beispiel: projects/your-project-id/subscriptions/your-subscription-name).
  • url: Die URL der Datadog Logs API. Diese URL muss von der VPC, in der die Pipeline ausgeführt wird, weitergeleitet werden können. Weitere Informationen finden Sie in der Datadog-Dokumentation unter „Logs senden“ (https://docs.datadoghq.com/api/latest/logs/#send-logs). (Beispiel: https://http-intake.logs.datadoghq.com).
  • outputDeadletterTopic: Das Pub/Sub-Thema als Weiterleitungsziel für nicht zustellbare Nachrichten. Beispiel: projects/<PROJECT_ID>/topics/<TOPIC_NAME>.

Optionale Parameter

  • apiKey: Der Datadog API-Schlüssel. Sie müssen diesen Wert angeben, wenn apiKeySource auf PLAINTEXT oder KMS festgelegt ist. Weitere Informationen finden Sie in der Datadog-Dokumentation unter „API- und Anwendungsschlüssel“ (https://docs.datadoghq.com/account_management/api-app-keys/).
  • batchCount: Die Batchgröße zum Senden mehrerer Ereignisse an Datadog. Die Standardeinstellung ist 1 (keine Batchverarbeitung).
  • parallelism: Die maximale Anzahl an parallelen Anfragen. Die Standardeinstellung ist 1 (keine Parallelität).
  • includePubsubMessage: Gibt an, ob die vollständige Pub/Sub-Nachricht in die Nutzlast aufgenommen werden soll. Der Standardwert ist false (nur das Datenelement ist in der Nutzlast enthalten).
  • apiKeyKMSEncryptionKey: Der Cloud KMS-Schlüssel, der zum Entschlüsseln des API-Schlüssels verwendet werden soll. Sie müssen diesen Parameter angeben, wenn apiKeySource auf KMS festgelegt ist. Wenn der Cloud KMS-Schlüssel bereitgestellt wird, müssen Sie einen verschlüsselten API-Schlüssel übergeben. (Beispiel: projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name).
  • apiKeySecretId: Die geheime ID des Secret Manager für den API-Schlüssel. Sie müssen diesen Parameter angeben, wenn apiKeySource auf SECRET_MANAGER festgelegt ist. Beispiel: projects/your-project-id/secrets/your-secret/versions/your-secret-version.
  • apiKeySource: Die Quelle des API-Schlüssels. Die folgenden Werte werden unterstützt: PLAINTEXT, KMS und SECRET_MANAGER. Sie müssen diesen Parameter angeben, wenn Sie Secret Manager verwenden. Wenn apiKeySource auf KMS gesetzt ist, müssen Sie auch apiKeyKMSEncryptionKey und verschlüsseltes API Key angeben. Wenn apiKeySource auf SECRET_MANAGER gesetzt ist, müssen Sie auch apiKeySecretId angeben. Wenn apiKeySource auf PLAINTEXT gesetzt ist, müssen Sie auch apiKey angeben.
  • javascriptTextTransformGcsPath Der Cloud Storage-URI der .js-Datei, in der die zu verwendende benutzerdefinierte JavaScript-Funktion (UDF) definiert wird. Beispiel: gs://my-bucket/my-udfs/my_file.js.
  • javascriptTextTransformFunctionName Der Name der benutzerdefinierten JavaScript-Funktion (UDF), die verwendet werden soll. Wenn Ihre JavaScript-Funktion beispielsweise myTransform(inJson) { /*...do stuff...*/ } ist, lautet der Funktionsname myTransform. Beispiele für JavaScript-UDFs finden Sie unter „UDF-Beispiele“ (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples).
  • javascriptTextTransformReloadIntervalMinutes : Definieren Sie das Intervall, in dem die Worker möglicherweise nach JavaScript-UDF-Änderungen suchen, um die Dateien neu zu laden. Die Standardeinstellung ist 0.

Benutzerdefinierte Funktion

Optional können Sie diese Vorlage erweitern, indem Sie eine benutzerdefinierte Funktion (UDF) schreiben. Die Vorlage ruft die UDF für jedes Eingabeelement auf. Nutzlasten von Elementen werden als JSON-Strings serialisiert. Weitere Informationen finden Sie unter Benutzerdefinierte Funktionen für Dataflow-Vorlagen erstellen.

Funktionsspezifikation

UDFs haben die folgende Spezifikation:

  • Eingabe: Das Feld der Pub/Sub-Nachrichtendaten, das als JSON-String serialisiert ist.
  • Ausgabe: Die Ereignisdaten, die an den Datadog Log-Endpunkt gesendet werden sollen. Die Ausgabe muss ein String oder ein String-JSON-Objekt sein.

Führen Sie die Vorlage aus.

Console

  1. Rufen Sie die Dataflow-Seite Job aus Vorlage erstellen auf.
    2. Zur Seite "Job aus Vorlage erstellen“
  2. Geben Sie im Feld Jobname einen eindeutigen Jobnamen ein.
  3. Optional: Wählen Sie für Regionaler Endpunkt einen Wert aus dem Drop-down-Menü aus. Die Standardregion ist us-central1.

    Eine Liste der Regionen, in denen Sie einen Dataflow-Job ausführen können, finden Sie unter Dataflow-Standorte.

  4. Wählen Sie im Drop-down-Menü Dataflow-Vorlage die Option the Pub/Sub to Datadog templateaus.
  5. Geben Sie Ihre Parameterwerte in die Parameterfelder ein.
  6. Klicken Sie auf Job ausführen.

gcloud

Führen Sie die Vorlage in der Shell oder im Terminal aus:

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

Ersetzen Sie dabei Folgendes:

  • JOB_NAME: ein eindeutiger Jobname Ihrer Wahl
  • REGION_NAME: die Region, in der Sie Ihren Dataflow-Job bereitstellen möchten, z. B. us-central1
  • VERSION: Die Version der Vorlage, die Sie verwenden möchten

    Sie können die folgenden Werte verwenden:

    • latest zur Verwendung der neuesten Version der Vorlage, die im nicht datierten übergeordneten Ordner im Bucket verfügbar ist: gs://dataflow-templates-REGION_NAME/latest/
    • Den Versionsnamen wie 2023-09-12-00_RC00, um eine bestimmte Version der Vorlage zu verwenden. Diese ist verschachtelt im jeweiligen datierten übergeordneten Ordner im Bucket enthalten: gs://dataflow-templates-REGION_NAME/.
  • STAGING_LOCATION: der Speicherort für das Staging lokaler Dateien (z. B. gs://your-bucket/staging)
  • INPUT_SUBSCRIPTION_NAME: der Name des Pub/Sub-Abos
  • API_KEY: API-Schlüssel von Datadog
  • URL: die URL für den Datadog-Endpunkt (z. B. https://http-intake.logs.datadoghq.com)
  • DEADLETTER_TOPIC_NAME: der Name des Pub/Sub-Themas
  • JAVASCRIPT_FUNCTION: ist der Name der benutzerdefinierten JavaScript-Funktion (UDF), die Sie verwenden möchten.

    Wenn Ihre JavaScript-Funktion beispielsweise myTransform(inJson) { /*...do stuff...*/ } ist, lautet der Funktionsname myTransform. Beispiele für JavaScript-UDFs finden Sie unter UDF-Beispiele.

  • PATH_TO_JAVASCRIPT_UDF_FILE Der Cloud Storage-URI der Datei .js, in der die benutzerdefinierte JavaScript-Funktion (UDF) definiert wird, die Sie verwenden möchten. Beispiel: gs://my-bucket/my-udfs/my_file.js
  • BATCH_COUNT: die Batchgröße zum Senden mehrerer Ereignisse an Datadog
  • PARALLELISM: die Anzahl der parallelen Anfragen, die zum Senden von Ereignissen an Splunk verwendet werden sollen

API

Senden Sie eine HTTP-POST-Anfrage, um die Vorlage mithilfe der REST API auszuführen. Weitere Informationen zur API und ihren Autorisierungsbereichen finden Sie unter 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"
   }
}

Ersetzen Sie dabei Folgendes:

  • PROJECT_ID: die ID des Google Cloud-Projekts, in dem Sie den Dataflow-Job ausführen möchten
  • JOB_NAME: ein eindeutiger Jobname Ihrer Wahl
  • LOCATION: die Region, in der Sie Ihren Dataflow-Job bereitstellen möchten, z. B. us-central1
  • VERSION: Die Version der Vorlage, die Sie verwenden möchten

    Sie können die folgenden Werte verwenden:

    • latest zur Verwendung der neuesten Version der Vorlage, die im nicht datierten übergeordneten Ordner im Bucket verfügbar ist: gs://dataflow-templates-REGION_NAME/latest/
    • Den Versionsnamen wie 2023-09-12-00_RC00, um eine bestimmte Version der Vorlage zu verwenden. Diese ist verschachtelt im jeweiligen datierten übergeordneten Ordner im Bucket enthalten: gs://dataflow-templates-REGION_NAME/.
  • STAGING_LOCATION: der Speicherort für das Staging lokaler Dateien (z. B. gs://your-bucket/staging)
  • INPUT_SUBSCRIPTION_NAME: der Name des Pub/Sub-Abos
  • API_KEY: API-Schlüssel von Datadog
  • URL: die URL für den Datadog-Endpunkt (z. B. https://http-intake.logs.datadoghq.com)
  • DEADLETTER_TOPIC_NAME: der Name des Pub/Sub-Themas
  • JAVASCRIPT_FUNCTION: ist der Name der benutzerdefinierten JavaScript-Funktion (UDF), die Sie verwenden möchten.

    Wenn Ihre JavaScript-Funktion beispielsweise myTransform(inJson) { /*...do stuff...*/ } ist, lautet der Funktionsname myTransform. Beispiele für JavaScript-UDFs finden Sie unter UDF-Beispiele.

  • PATH_TO_JAVASCRIPT_UDF_FILE Der Cloud Storage-URI der Datei .js, in der die benutzerdefinierte JavaScript-Funktion (UDF) definiert wird, die Sie verwenden möchten. Beispiel: gs://my-bucket/my-udfs/my_file.js
  • BATCH_COUNT: die Batchgröße zum Senden mehrerer Ereignisse an Datadog
  • PARALLELISM: die Anzahl der parallelen Anfragen, die zum Senden von Ereignissen an Splunk verwendet werden sollen

Nächste Schritte