Créer un moniteur à l’aide de l’API

  • Article

Cette page explique comment créer un moniteur dans Databricks en utilisant le Kit de développement logiciel (SDK) Databricks et décrit tous les paramètres utilisés dans les appels d’API. L’API REST vous permet également de créer et gérer des moniteurs. Pour obtenir des informations de référence, consultez les Informations de référence sur le Kit de développement logiciel (SDK) Lakehouse Monitoring et les Informations de référence sur les API REST.

Vous pouvez créer un moniteur sur n’importe quelle table Delta managée ou externe inscrite dans Unity Catalog. Un seul moniteur peut être créé dans un metastore Unity Catalog pour n’importe quelle table.

Spécifications

L’API Lakehouse Monitoring est intégrée dans databricks-sdk 0.28.0 et ultérieur. Pour utiliser la version la plus récente de l’API, utilisez la commande suivante au début de votre notebook pour installer le client Python :

%pip install "databricks-sdk>=0.28.0"

Pour vous authentifier afin d’utiliser le Kit de développement logiciel (SDK) Databricks dans votre environnement, consultez Authentification.

Types de profils

Quand vous créez un moniteur, vous sélectionnez un des types de profils suivants : TimeSeries, InferenceLog ou Snapshot. Cette section décrit brièvement chaque option. Pour plus d’informations, consultez la de référence de l’API ou la référence de l’API REST.

Remarque

  • Lorsque vous créez un profil de série chronologique ou d’inférence, le moniteur analyse uniquement les données des 30 jours précédant sa création. Une fois le moniteur créé, toutes les nouvelles données sont traitées.
  • Les moniteurs créés à partir d’affichages matérialisés et de tables de diffusion en continu ne prennent pas en charge le traitement incrémentiel.

Conseil

Pour les profils TimeSeries et Inference, il est recommandé d’activer le flux des changements de données (CDF) sur votre table. Lorsque le CDF est activé, seules les données nouvellement ajoutées sont traitées, plutôt que de retraiter l’intégralité de la table toutes les actualisations. Cela rend l’exécution plus efficace et réduit les coûts à mesure que vous mettez à l’échelle la surveillance sur de nombreuses tables.

TimeSeries profil

Un profil TimeSeries compare les distributions de données entre les fenêtres de temps. Pour un profil TimeSeries, vous devez fournir les éléments suivants :

  • Colonne timestamp (timestamp_col). Le type de données de colonne timestamp doit être TIMESTAMP ou un type pouvant être converti en timestamps à l’aide de la fonction PySpark to_timestamp.
  • Ensemble de granularities sur lequel calculer les métriques. Les granularités disponibles sont « 5 minutes », « 30 minutes », « 1 heure », « 1 jour », « n semaine(s) », « 1 mois », « 1 an ».
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"])
)

InferenceLog profil

Un InferenceLog profil est similaire à un TimeSeries profil, mais inclut également des métriques de qualité de modèle. Pour un InferenceLog profil, les paramètres suivants sont requis :

Paramètre Description
problem_type MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION ou MonitorInferenceLogProblemType.PROBLEM_TYPE_REGRESSION
prediction_col Colonne contenant les valeurs prédites du modèle.
timestamp_col Colonne contenant l’horodatage de la demande d’inférence.
model_id_col Colonne contenant l’ID du modèle utilisé pour la prédiction.
granularities Détermine comment partitionner les données dans des fenêtres dans le temps. Valeurs possibles : « 5 minutes », « 30 minutes », « 1 heure », « 1 jour », « n semaine(s) », « 1 mois », « 1 an ».

Il existe également un paramètre facultatif :

Paramètre facultatif : Description
label_col Colonne contenant la vérité au sol pour les prédictions de modèle. 
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorInferenceLog, MonitorInferenceLogProblemType

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  inference_log=MonitorInferenceLog(
        problem_type=MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION,
        prediction_col="preds",
        timestamp_col="ts",
        granularities=["30 minutes", "1 day"],
        model_id_col="model_ver",
        label_col="label", # optional
  )
)

Pour les profils InferenceLog, les tranches sont créées automatiquement en fonction des valeurs distinctes de model_id_col.

Snapshot profil

Contrairement à TimeSeries, un Snapshot profil surveille la façon dont le contenu complet de la table change au fil du temps. Les métriques sont calculées sur toutes les données de la table et surveillent l’état de la table à chaque actualisation du moniteur.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorSnapshot

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  snapshot=MonitorSnapshot()
)

Actualiser et afficher les résultats de l’analyse

Pour actualiser les tables de métriques, utilisez run_refresh. Par exemple :

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.run_refresh(
    table_name=f"{catalog}.{schema}.{table_name}"
)

Lorsque vous appelez run_refresh à partir d’un bloc-notes, les tables de métriques de surveillance sont créées ou mises à jour. Ce calcul s’exécute sur le calcul serverless, et non sur le cluster auquel le notebook est attaché. Vous pouvez continuer à exécuter des commandes dans le notebook pendant que les statistiques du moniteur sont mises à jour.

Pour plus d’informations sur les statistiques stockées dans les tables de métriques, consultez Surveiller les tables de métriques Les tables de métriques sont des tables Unity Catalog. Vous pouvez les interroger dans des notebooks ou dans l’Explorateur de requêtes SQL et les afficher dans l’Explorateur de catalogues.

Pour afficher l’historique de toutes les actualisations associées à un moniteur, utilisez list_refreshes.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.list_refreshes(
    table_name=f"{catalog}.{schema}.{table_name}"
)

Pour obtenir l’état d’une exécution spécifique qui a été mise en file d’attente, en cours d’exécution ou terminée, utilisez get_refresh.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
run_info = w.quality_monitors.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

w.quality_monitors.get_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id = run_info.refresh_id
)

Pour annuler une actualisation mise en file d’attente ou en cours d’exécution, utilisez cancel_refresh.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
run_info = w.quality_monitors.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

w.quality_monitors.cancel_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id=run_info.refresh_id
)

Afficher les paramètres du moniteur

Vous pouvez passer en revue les paramètres du moniteur à l’aide de l’API get_monitor.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.get(f"{catalog}.{schema}.{table_name}")

Planifier

Pour configurer un moniteur pour qu’il s’exécute sur une base planifiée, utilisez le schedule paramètre de create_monitor:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries, MonitorCronSchedule

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"]),
  schedule=MonitorCronSchedule(
        quartz_cron_expression="0 0 12 * * ?", # schedules a refresh every day at 12 noon
        timezone_id="PST",
    )
)

Pour plus d’informations, consultez expressions cron .

Notifications

Pour configurer les notifications pour un moniteur, utilisez le paramètre notifications de create_monitor :

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries, MonitorNotifications, MonitorDestination

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"]),
  notifications=MonitorNotifications(
        # Notify the given email when a monitoring refresh fails or times out.
        on_failure=MonitorDestination(
            email_addresses=["your_email@domain.com"]
        )
    )
)

Un nombre maximal de 5 adresses e-mail est pris en charge par type d’événement (par exemple, « on_failure »).

Contrôler l’accès aux tables de métriques

Les tables de métriques et le tableau de bord créés par un moniteur appartiennent à l’utilisateur qui a créé le moniteur. Vous pouvez utiliser les privilèges Unity Catalog pour contrôler l’accès aux tables de métriques. Pour partager des tableaux de bord au sein d’un espace de travail, utilisez le bouton Partager en haut à droite du tableau de bord.

Supprimer un moniteur

Pour supprimer un moniteur :

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.delete(table_name=f"{catalog}.{schema}.{table_name}")

Cette commande ne supprime pas les tables de profils et le tableau de bord créé par le moniteur. Vous devez supprimer ces ressources dans une étape distincte, ou vous pouvez les enregistrer à un autre emplacement.

Exemples de notebooks

Les exemples de notebooks suivants montrent comment créer un moniteur, actualiser le moniteur et examiner les tables de métriques qu’il crée.

Exemple de notebook : table de fonctionnalités de série chronologique

Ce notebook illustre la création d’un moniteur de type TimeSeries.

Exemple de notebook TimeSeries Lakehouse Monitor

Obtenir le notebook

Exemple de notebook : profil d’inférence (régression)

Ce bloc-notes montre comment créer un moniteur de type InferenceLog pour un problème de régression.

Exemple de notebook de régression Lakehouse Monitor d’inférence

Obtenir le notebook

Exemple de notebook : profil d’inférence (classification)

Ce bloc-notes montre comment créer un InferenceLog moniteur de type pour un problème de classification.

Exemple de notebook de classification Lakehouse Monitor d’inférence

Obtenir le notebook

Exemple de notebook : Profil d’instantané

Ce notebook illustre la création d’un moniteur de type Snapshot.

Exemple de notebook Snapshot Lakehouse Monitor

Obtenir le notebook