Présentation

Utilisez la destination Databricks (Zerobus) des Observability Pipelines pour envoyer des logs vers un tableau Databricks Unity Catalog. La destination diffuse les logs vers le Zerobus Ingest API 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 un tableau Unity Catalog dans lesquels l’Observability Pipelines Worker écrit les logs.
• Configurer un principal de service que le Worker utilise pour s’authentifier auprès de Databricks. Le principal de service doit disposer de l’autorisation de lire et d’écrire dans le tableau.

Configurer un schéma et un tableau

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

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

Dans l’espace de travail Databricks :

1. Si vous n’êtes pas administrateur d’espace de travail Databricks, demandez à un administrateur d’exécuter la commande suivante pour accorder à votre utilisateur l’autorisation 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 l’autorisation de créer un tableau sur le schéma :

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

4. Exécutez la commande suivante pour créer le tableau dans laquelle Observability Pipelines écrit les logs :

   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 complet du tableau est catalog.schema.table, par exemple main.obs_pipelines.apache_common_logs. C’est la valeur que vous saisissez pour Table Name lorsque vous configurez la destination Databricks Observability Pipelines.

Configurez un principal de service

Le Zerobus Ingest API 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 correspond à 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. Une fois le principal de service créé, générez un secret OAuth pour celui-ci.
   • Notez l’ID d’application (ID client) du principal de service ainsi que le secret client OAuth. Vous avez besoin des deux pour configurer la destination Databricks d’Observability Pipelines.
4. Exécutez ce SQL dans Databricks pour accorder au principal de service l’accès au catalogue, au schéma et à le tableau. Remplacez <SERVICE_PRINCIPAL_UUID> par l’ID d’application du principal de service obtenu à 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 Databricks Ajouter des principaux de service à votre compte et Accorder des autorisations sur un objet pour plus d’informations.

Configuration

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

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

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

1. Saisissez le Ingestion Endpoint de votre espace de travail Databricks, tel que https://<workspace_id>.zerobus.<region>.cloud.databricks.com. Le Worker envoie les logs à cet endpoint.
2. Saisissez le Table Name au format catalog.schema.table, tel que main.obs_pipelines.apache_common_logs.
3. Saisissez le Unity Catalog Endpoint de votre espace de travail Databricks, tel que https://<workspace>.cloud.databricks.com. Le Worker utilise cet endpoint pour lire le schéma du tableau.
4. Dans le champ Auth - Client ID, saisissez l’ID d’application du principal de service, tel que abcdefgh-1234-5678-abcd-ef0123456789.
5. Dans le champ Auth - Client Secret, saisissez l’identifiant de votre secret client OAuth. Si vous le laissez vide, le default 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 5 TB.
        • Note: For Worker versions 2.20.x and older, the 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 sous forme de chaîne au format horodatage

Si vos logs contiennent des horodatages sous forme de chaîne et que votre tableau Databricks possède une colonne d’horodatage déclarée en tant que type TIMESTAMP, vous devez convertir la chaîne au format horodatage avant d’envoyer les logs vers 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 sous forme 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 sous forme de chaîne au format 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.

Type de données des valeurs de champ de log

Les valeurs des champs de log doivent correspondre au type de données de leur colonne correspondante dans le schéma du tableau. Par exemple, si le schéma du tableau définit message comme STRING, mais que le champ message d’un log entrant est un objet, tel que {"message": {"some": "string"}}, le Worker ne peut pas encoder l’événement, abandonne le lot entier et génère une erreur similaire à :

error=Some(EncodingError { message: "Failed to encode batch: SerializingError(Arrow JSON decoding error: Json error: whilst decoding field 'message': expected string got {...})" }) request_id=1142 error_type="request_failed" stage="sending"

Pour éviter cette erreur, utilisez le Processeur personnalisé afin de convertir les champs de log dans le type de données attendu par le schéma du tableau.

Valeurs par défaut des secrets

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

Métriques de santé

Pour les métriques de composants et les métriques de tampon de destination émises par toutes les destinations, consultez la documentation sur les Métriques d’utilisation des pipelines. Pour filtrer ou regrouper par métriques de destination Databricks, utilisez le tag component_type:databricks_zerobus.

Comment fonctionne la destination

Traitement par lots d’événements

Un lot d’événements est vidé lorsque l’un de ces paramètres est atteint. Consultez Regroupement d’événements par destination pour plus d’informations.