Aperçu

Utilisez la destination Databricks (Zerobus) des Observability Pipelines pour envoyer des logs vers une table Unity Catalog. La destination diffuse les journaux vers l’API d’ingestion Zerobus et s’authentifie auprès de Databricks avec un principal de service OAuth.

Prérequis

Avant de configurer la destination Databricks (Zerobus), vous devez :

• Configurer un schéma et une table Unity Catalog auxquels le Worker des Observability Pipelines écrit des journaux.
• Configurer un principal de service que le Worker utilise pour s’authentifier auprès de Databricks. Le principal de service a besoin de permissions pour lire et écrire dans la table.

Configurer un schéma et une table

Les exemples SQL dans cette section utilisent les espaces réservés suivants :

Remarque : Les GRANT commandes doivent être exécutées par un administrateur de l’espace de travail Databricks.

Dans l’espace de travail Databricks :

1. Si vous n’êtes pas un administrateur de l’espace de travail Databricks, demandez à un administrateur d’exécuter la commande suivante pour accorder à votre utilisateur la permission de créer un schéma :

   GRANT CREATE SCHEMA ON CATALOG <CATALOG_NAME> TO <USER>;
   

2. Créez le schéma :

   CREATE SCHEMA IF NOT EXISTS <CATALOG_NAME>.<SCHEMA_NAME>
   MANAGED LOCATION '<YOUR_MANAGED_LOCATION>';
   

   • Note: MANAGED LOCATION is optional. See Databricks’ Create Schemas documentation for more information.

3. Si vous n’êtes pas un utilisateur administrateur, demandez à un administrateur d’exécuter la commande suivante pour accorder à votre utilisateur la permission de créer une table dans le schéma :

   GRANT CREATE TABLE ON SCHEMA <CATALOG_NAME>.<SCHEMA_NAME> TO <USER>;
   

4. Exécutez la commande suivante pour créer la table à laquelle les pipelines d’observabilité écrivent les données de journal :

   CREATE TABLE <CATALOG_NAME>.<SCHEMA_NAME>.<TABLE_NAME> (
     host STRING,
     message STRING,
     service STRING,
     source_type STRING,
     timestamp TIMESTAMP
   );
   

   • See Databricks’ Create a Unity Catalog Managed Table documentation for more information.

Le nom de la table entièrement qualifié est catalog.schema.table, par exemple main.obs_pipelines.apache_common_logs. C’est la valeur que vous entrez pour Nom de la table lorsque vous configurez la destination Databricks des pipelines d’observabilité.

Configurez un principal de service

L’API d’ingestion Zerobus de Databricks utilise l’authentification OAuth. Lorsque vous créez le principal de service, le secret client OAuth est généré et l’ID client OAuth est l’UUID du principal de service.

Pour créer un principal de service :

1. Dans votre espace de travail Databricks, accédez à Paramètres utilisateur > Identité et accès > Principaux de service.
2. Cliquez sur Ajouter un principal de service.
3. Après la création du principal de service, générez un secret OAuth pour celui-ci.
   • Prenez note de l’ID d’application du principal de service (ID client) et du secret client OAuth. Vous avez besoin des deux lorsque vous configurez la destination Databricks des pipelines d’observabilité.
4. Exécutez ce SQL dans Databricks pour accorder au principal de service l’accès au catalogue, au schéma et à la table. Remplacez <SERVICE_PRINCIPAL_UUID> par l’ID d’application du principal de service de l’étape précédente :

   GRANT USE CATALOG ON CATALOG <CATALOG_NAME> TO <SERVICE_PRINCIPAL_UUID>;
   GRANT USE SCHEMA ON SCHEMA <CATALOG_NAME>.<SCHEMA_NAME> TO <SERVICE_PRINCIPAL_UUID>;
   GRANT SELECT, MODIFY ON TABLE <CATALOG_NAME>.<SCHEMA_NAME>.<TABLE_NAME> TO <SERVICE_PRINCIPAL_UUID>;
   

Consultez la documentation de Databricks sur Ajouter des principaux de service à votre compte et Accorder des permissions sur un objet pour plus d’informations.

Configuration

Configurez la destination Databricks (Zerobus) lorsque vous mettez en place un pipeline. Vous pouvez mettre en place un pipeline dans l’UI, en utilisant l’API, ou avec Terraform. Les étapes de cette section sont configurées dans l’UI.

Remarque : Les champs de journal qui ne sont pas présents dans le schéma de la table sont supprimés. Par exemple, si un journal a les champs id, name, et host, et que le schéma de la table ne contient que les colonnes name et host, alors le champ id est supprimé et n’est pas écrit dans la table.

Après avoir sélectionné la destination Databricks (Zerobus) dans l’UI du pipeline :

1. Entrez le Point de terminaison d’ingestion pour votre espace de travail Databricks, tel que https://<workspace_id>.zerobus.<region>.cloud.databricks.com. Le Worker envoie des journaux à ce point de terminaison.
2. Entrez le Nom de la table au format catalog.schema.table, tel que main.obs_pipelines.apache_common_logs.
3. Entrez le Point de terminaison du catalogue Unity pour votre espace de travail Databricks, tel que https://<workspace>.cloud.databricks.com. Le Worker utilise ce point de terminaison pour lire le schéma de la table.
4. Dans le champ Auth - ID client, entrez l’ID de l’application du principal de service, tel que abcdefgh-1234-5678-abcd-ef0123456789.
5. Dans le champ Auth - Secret client, entrez l’identifiant de votre secret client OAuth. Si vous le laissez vide, le par défaut est utilisé.

Paramètres optionnels

Mise en mémoire tampon

Toggle the switch to enable Buffering Options. Enable a configurable buffer on your destination to ensure intermittent latency or an outage at the destination doesn’t create immediate backpressure, and allow events to continue to be ingested from your source. Disk buffers can also increase pipeline durability by writing data to disk, ensuring buffered data persists through a Worker restart. See Destination buffers for more information.

• If left unconfigured, your destination uses a memory buffer with a capacity of 500 events.
• To configure a buffer on your destination:
  1. Select the buffer type you want to set (Memory or Disk).
  2. Enter the buffer size and select the unit.
     1. Maximum memory buffer size is 128 GB.
     2. Maximum disk buffer size is 500 GB.
  3. In the Behavior on full buffer dropdown menu, select whether you want to block events or drop new events when the buffer is full.

Convertir les horodatages de chaîne en format d’horodatage

Si vos journaux ont des horodatages au format chaîne et que votre table Databricks a une colonne d’horodatage déclarée comme un TIMESTAMP type, vous devez convertir la chaîne en format d’horodatage avant d’envoyer les journaux à la destination Databricks (Zerobus). Databricks (Zerobus) ne peut convertir le format d’horodatage qu’en son type TIMESTAMP.

Si vous ne convertissez pas l’horodatage de chaîne, le Worker génère une erreur similaire à :

Protobuf encoding failed: Error converting timestamp field: Can't convert '2012-04-23T10[41]15Z' to i64: invalid digit found in string

Pour convertir les horodatages au format chaîne en format d’horodatage :

1. Ajoutez un Processeur personnalisé à votre pipeline.
2. Ajoutez une fonction avec le script personnalisé suivant :

   .timestamp = parse_timestamp!(.timestamp, format: "%+")
   

   See parse_timestamp for more information.

Valeurs par défaut secrètes

These are the defaults used for secret identifiers and environment variables.

Comment fonctionne la destination

Regroupement d’événements

Un lot d’événements est vidé lorsque l’un de ces paramètres est atteint. Voir regroupement d’événements pour plus d’informations.