Créer un moniteur à l’aide de l’API
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 êtreTIMESTAMP
ou un type pouvant être converti en timestamps à l’aide de la fonction PySparkto_timestamp
. - Ensemble de
granularities
sur lequel calculer les métriques. Les granularités disponibles sont « 5 minutes », « 30 minutes », « 1 heure », « 1 jour », « 1 semaine », « 2 semaines », « 3 semaines », « 4 semaines », « 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 », « 1 semaine », « 2 semaines », « 3 semaines », « 4 semaines », « 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
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
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
Exemple de notebook : Profil d’instantané
Ce notebook illustre la création d’un moniteur de type Snapshot
.