Surveiller Genie Code et Genie One avec la table de trace unifiée
Beta
Le suivi de Genie Code et Genie One est en version bêta. Il fait partie de la table de suivi unifiée, qui est également en version bêta. Pour l'activer, consultez la section Activer le suivi Genie pour un workspace.
Le propriétaire de la table de trace, ainsi que toute personne ayant accès à la table, peut consulter chaque tour de Genie Code et de Genie One dans la table de trace unifiée de Unity Gateway en tant qu’étendues OpenTelemetry. Chaque tour enregistre l’auteur de la demande, l’invite, le raisonnement et la réponse visibles par l’utilisateur, les assets de données cités, le résultat et la durée. Il enregistre également les actions effectuées par Genie, telles que l’exécution de SQL, la création ou la modification de tableaux de bord et l’appel d’outils MCP, avec leurs arguments.
Comme les traces se trouvent dans une table Unity Catalog dont vous êtes propriétaire, vous pouvez demander à Genie Code ou Genie One de les analyser, ou les query avec SQL, pour :
- Tri de réponse incorrecte : recherchez un tour signalé par un utilisateur ou ayant reçu un pouce vers le bas, puis examinez le prompt, le raisonnement, les actions et la réponse de bout en bout.
- Surveillance de la qualité : suivez les erreurs, les échecs d’appel d’outil et les tours lents.
- Suivre l'adoption : comptez les utilisateurs actifs et les tours par produit, par workspace et par canal de distribution.
- Gouverner ce que Genie crée et modifie : voyez qui a créé, modifié, publié ou supprimé des dashboards, des Genie Agents, des compétences et des tâches planifiées.
- Prise en charge des revues de conformité : recherchez des invites et des réponses pour un utilisateur, une plage horaire ou un mot-clé.
Exigences
Tout ce qui suit doit être vrai avant que les traces de Genie ne soient exportées. Si une exigence manque, aucune trace Genie n’est écrite.
- Unity Gateway est activée pour votre compte.
- Un administrateur de compte a activé les fonctionnalités bêta de la passerelle Unity améliorée depuis la page Aperçus de la console de compte. Consultez Gérer les aperçus au niveau du compte.
- Un administrateur de metastore a configuré la table de suivi unifiée pour le metastore auquel votre workspace est attaché. Voir Activer la table de suivi unifiée.
- Un administrateur de workspace a activé la version préliminaire de Genie One Tracing , la version préliminaire de Genie Code Tracing , ou les deux, pour le workspace. Voir Activer le traçage Genie pour un workspace.
Pour query les traces, vous avez besoin de SELECT sur la table de traces, USE SCHEMA sur son schéma et USE CATALOG sur son catalogue. Voir Contrôler qui peut lire les traces Genie.
Activer le suivi Genie pour un workspace
Le suivi Genie est désactivé default. Un administrateur de workspace active la préversion de chaque produit séparément pour chaque workspace. Activez le suivi Genie One pour suivre les conversations Genie One et le suivi Genie Code pour suivre les conversations Genie Code.
- En tant qu'administrateur du workspace, cliquez sur votre nom d'utilisateur dans la barre supérieure du workspace, puis cliquez sur Previews .
- Trouvez l’aperçu de chaque produit que vous souhaitez suivre et activez-le. Consultez Gérer les aperçus au niveau du workspace.
Une fois que vous activez un aperçu, les nouveaux tours pour ce produit dans le workspace sont exportés vers la table de trace unifiée. Les tours précédents ne sont pas remplis.
Pour arrêter la collecte des traces pour un produit, désactivez son aperçu. Les nouveaux tours ne sont plus exportés. Les traces déjà écrites restent dans la table jusqu'à ce que votre politique de rétention les supprime.
Les traces Genie contiennent le texte intégral des invites des utilisateurs, des réponses de Genie, ainsi que des arguments et des résultats des outils. Le propriétaire de la table de traces, ainsi que toute personne ayant accès à cette table, peut lire ce contenu, même pour les conversations et les données auxquelles il n’aurait pas accès autrement. Les administrateurs de métastore peuvent se donner accès eux-mêmes. Comme les traces peuvent contenir des données sensibles, vérifiez qui peut lire la table de traces et définissez une politique de rétention avant d’activer le traçage Genie. Consultez Contrôler qui peut lire les traces Genie et Limites.
Trouver des traces Genie dans la table
Les traces Genie partagent la table de trace unifiée avec d’autres trafics Unity Gateway. Utilisez service_name pour les sélectionner :
Produit | Filtrer |
|---|---|
Genie One |
|
Genie Code |
|
Les conversations avec les agents Genie ne sont pas incluses. Voir Limitations.
Dans le Traces tab de Unity Gateway, vous pouvez également filtrer le Type de service sur Genie pour voir uniquement les traces de Genie Code et de Genie One. Voir Afficher les traces dans l’interface utilisateur.
Analyser les traces avec Genie
Pour analyser les traces de Genie sans écrire de SQL, demandez à Genie Code ou Genie One de vous les expliquer en langage simple. Pour écrire des queries avec Genie Code depuis la page de la table de traces, voir Write queries with Genie Code.
Exemples d’invites :
- « Étudier les traces de Genie et découvrir quels outils ont le plus souvent échoué dans Genie Code la semaine dernière. »
- "Analyser les traces Genie et répertorier les utilisateurs qui ont créé ou modifié des tableaux de bord avec Genie One au cours des 30 derniers jours."
- « Étudier les traces de Genie et résumer les questions les plus posées hier à Genie One. »
Si Genie ne trouve pas la table de trace, incluez son nom, tel que <catalog>.<schema>.<table_name>, dans votre question. Vous pouvez analyser uniquement les traces auxquelles vous avez un accès SELECT. Voir Contrôler qui peut lire les traces de Genie.
Pour query les traces avec SQL, voir Exemples de query.
Ce que contient une trace Genie
Chaque tour Genie est une trace, et chaque ligne de la trace possède le même trace_id. Une trace comporte ces types de lignes :
Type de ligne |
| Ce qu’elle couvre |
|---|---|---|
Portée racine | Genie One : | L'ensemble du tour : l'invite, la réponse, le résultat et la durée. |
Portée de l’outil | Genie One : | Un appel d’outil dans le tour. |
Durée d'approbation ou de question | Genie One uniquement : | Point auquel Genie One a demandé à l'utilisateur d'approuver un appel d'outil ou de répondre à une question. Voir Plages Genie One. |
Portée de l’appel du modèle | Genie Code uniquement : | Un appel de modèle dans le tour, avec sa durée. |
Les traces incluent uniquement ce que l’utilisateur a vu dans le chat Genie, ainsi que le timing et le résultat. Elles n’incluent pas les invites système, le raisonnement masqué ou le coût. Pour analyser le coût de Genie, consultez Surveiller et comprendre le coût de Genie.
Étapes qui n’apparaissent pas dans une trace
Pour rechercher et analyser les bons assets, Genie exécute également des étapes internes de récupération et de planification, telles que la recherche de tables et de tableaux de bord, la lecture de métadonnées d'asset et la lecture ou la mise à jour de la mémoire de Genie. Ces étapes n'effectuent pas d'action directe dans votre workspace, une trace ne les inclut donc pas, ni leurs entrées et résultats. Une étape qui ne figure pas dans la trace ne laisse aucun span et aucun espace réservé. Pour voir chaque étape que Genie a montrée à l'utilisateur, ouvrez la conversation dans Genie et examinez son raisonnement.
Quels appels d'outil sont exportés
Les traces incluent des appels d'outils qui effectuent une action dans votre workspace ou qui confient du travail à un autre service. Par exemple :
- Exécution de SQL ou de code.
- Création, modification, publication ou suppression d’assets, tels que des tableaux de bord, des Notebook, des agents Genie, des compétences et des tâches planifiées.
- Changement de compute, de pipelines ou de jobs.
- Poser une question à un agent Genie Agent ou à un autre agent, effectuer une recherche sur le Web ou appeler un outil MCP.
- Poser une question à l'utilisateur ou lui demander une approbation, et envoyer des notifications.
Pour voir quels outils apparaissent dans vos traces, utilisez la query dans Voir quels outils Genie utilise. L’ensemble des appels d’outils que les traces incluent peut changer.
Attributs sur chaque span
Unity Gateway ajoute ces attributs à chaque span Genie lorsqu’elle écrit le span dans la table :
Attribuer | Description |
|---|---|
| ID du workspace où le tour a été exécuté. |
| Nom d'utilisateur de l'utilisateur ayant envoyé l'invite, tel que |
| ID de l'utilisateur ou du Service Principal ayant envoyé l'invite. |
Utilisez la syntaxe avec crochets pour lire les attributs dont les noms contiennent des points, tels que attributes:['enduser.id']. La syntaxe avec backticks, telle que attributes:`enduser.id` , renvoie NULL pour ces attributs.
Étendues Genie One
L'étendue racine est nommée invoke_agent OneChat. Elle comporte les attributs suivants :
Attribuer | Description |
|---|---|
| Définir sur |
| ID du chat. Tous les tours du même chat partagent cette valeur. |
| ID de cette réponse. |
| L’invite de l’utilisateur, sous forme de chaîne JSON. |
| Le raisonnement et la réponse finale visibles par l'utilisateur, sous forme de chaîne JSON. |
| Assets de données cités dans la réponse. |
| Statut final de la réponse. |
| Code d’erreur affiché à l’utilisateur si le tour a échoué. |
| ID de l'utilisateur ayant envoyé l'invite. |
| ID du compte. |
| ID du métastore. |
| L’endroit où l’utilisateur a posé la question, comme |
| ID de la tâche planifiée qui a exécuté ce tour, si une tâche planifiée l'a déclenché. |
Chaque appel d'outil exporté est une étendue enfant nommée execute_tool <tool_name> avec les attributs suivants :
Attribuer | Description |
|---|---|
| Nom de l'outil ou de l'outil MCP appelé. |
| ID de l'appel d'outil. |
| Arguments envoyés à l'outil, au format JSON. Non enregistré pour |
| Résultat renvoyé par l’outil. Pour |
Une période de l’outil a le statut STATUS_CODE_ERROR si l’appel de l’outil ne s’est pas terminé.
Lorsque Genie One demande à l’utilisateur d’approuver un appel d’outil ou de répondre à une question, la trace comporte une étendue enfant nommée request_approval <tool_name> ou request_answers ask_user_questions. Le tour qui continue après que l’utilisateur a répondu est une trace séparée, et son étendue racine Link à l’étendue de la demande.
Étentes de Genie Code
L’étendue racine est nommée invoke_agent genieCodeAgent ou invoke_agent GenieCodeFullChat. Les étendues enfants incluent chat étendues pour les appels de modèle et tool.execute:<tool_name> étendues pour les appels d’outil exportés. Parmi les attributs courants, citons :
Attribuer | Description |
|---|---|
| Nom de l'agent, sur la span racine. |
| ID de la conversation ou du notebook sur la span racine. Unique dans un workspace. |
| L’invite de l’utilisateur, sous forme de chaîne JSON. |
| La réponse finale et le raisonnement visible, sous forme de chaîne JSON. |
| Résultat du tour, sur l’étendue racine : |
| Nom de l'outil, sur les étendues d'outil. |
| ID de l'appel d'outil, sur les plages d'outils. |
| Arguments envoyés à l'outil, au format JSON, sur les spans d'outil. |
| Résultat retourné par l’outil, tel qu’un statut, un nombre de lignes ou un ID d’asset, sur les étendues d’outil. |
| Résultat de l'appel d'outil, sur les spans d'outil, tels que |
| Défini lorsque du contenu a été omis de l’étendue. |
Un tour avec le résultat error a le statut STATUS_CODE_ERROR, tout comme un appel d’outil échoué. Les tours avec le résultat cancelled ou aborted, ainsi que les appels d’outils rejetés par l’utilisateur, conservent le statut STATUS_CODE_OK ou STATUS_CODE_UNSET.
Pour le schéma complet de la table, voir Référence du schéma de la table de trace unifiée.
Contrôler qui peut lire les traces Genie
Par default, seul le propriétaire de la table de traces, l’administrateur du metastore qui a configuré la table de traces, peut query cette table. Les autres administrateurs du metastore peuvent leur accorder l’accès ou l’accorder à toute autre personne. Pour donner accès à d’autres utilisateurs, tels que les administrateurs de workspace ou les propriétaires de données, accordez USE CATALOG, USE SCHEMA et SELECT. Voir Autorisations et contrôle d’accès.
Sans filtre de lignes, toute personne disposant de SELECT peut voir toutes les traces dans la table, y compris les invites Genie et les réponses de chaque workspace attaché au metastore. Databricks recommande d’étendre l’accès avec une politique de filtre de lignes basée sur le contrôle d’accès basé sur les attributs (ABAC). Par exemple, vous pouvez filtrer les lignes sur attributes:workspace_id afin que les administrateurs de chaque workspace ne voient que les traces Genie de leur propre workspace. Chaque étendue a workspace_id, donc le filtre garde les étendues racine et outil d’un tour ensemble. Voir Autorisations et contrôle d’accès.
Exemples de query
Remplacez <catalog>.<schema>.<table_name> par le chemin de votre table de traces. Incluez un filtre time pour des performances optimales. Voir Query with SQL or a notebook.
La plupart de ces queries lisent à partir de la vue genie_turns, donc créez la vue en premier. Les colonnes telles que product, requester et prompt n'existent que dans la vue, pas dans la table de trace. Les queries qui lisent directement la table de trace le précisent.
Créer une vue des tours Genie
Cette vue renvoie une ligne par tour de Genie avec les champs communs extraits. Les colonnes channel, scheduled_task_id et error_code s’appliquent uniquement à Genie One, et run_outcome s’applique uniquement à Genie Code.
Une vue lit la table des traces avec les privilèges de son propriétaire. Par conséquent, toute personne à laquelle vous accordez SELECT sur la vue peut lire les traces Genie qu'elle renvoie. N'accordez SELECT sur la vue qu'aux utilisateurs autorisés à lire ces traces.
CREATE OR REPLACE VIEW <catalog>.<schema>.genie_turns AS
SELECT
trace_id,
time,
date,
CASE
WHEN service_name = 'genie-code-agent' THEN 'Genie Code'
ELSE 'Genie One'
END AS product,
attributes:['enduser.id']::string AS requester,
attributes:workspace_id::string AS workspace_id,
attributes:['gen_ai.conversation.id']::string AS conversation_id,
attributes:['gen_ai.input.messages']::string AS prompt,
attributes:['gen_ai.output.messages']::string AS response,
attributes:['databricks.genie.channel']::string AS channel,
attributes:['databricks.genie.scheduled_task_id']::string AS scheduled_task_id,
attributes:['databricks.genie.error_code']::string AS error_code,
attributes:['databricks.genie_code.run.outcome']::string AS run_outcome,
status.code AS status_code,
(end_time_unix_nano - start_time_unix_nano) / 1e6 AS duration_ms
FROM <catalog>.<schema>.<table_name>
WHERE (parent_span_id IS NULL OR parent_span_id = '')
AND service_name IN ('genie-code-agent', 'Genie One');
Suivre l’adoption
Comptez les tours et les utilisateurs actifs par jour pour chaque produit au cours des 30 derniers jours :
SELECT
date,
product,
COUNT(*) AS turns,
COUNT(DISTINCT requester) AS active_users
FROM <catalog>.<schema>.genie_turns
WHERE time >= current_timestamp() - INTERVAL 30 DAYS
GROUP BY date, product
ORDER BY date DESC, product;
Répartition de l’utilisation de Genie One par workspace et par canal de distribution :
SELECT
workspace_id,
channel,
COUNT(*) AS turns,
COUNT(DISTINCT requester) AS active_users
FROM <catalog>.<schema>.genie_turns
WHERE product = 'Genie One'
AND time >= current_timestamp() - INTERVAL 30 DAYS
GROUP BY workspace_id, channel
ORDER BY turns DESC;
Trier une réponse signalée
Rechercher les échanges récents d’un utilisateur mentionnant un mot-clé :
SELECT trace_id, time, product, conversation_id, prompt, response
FROM <catalog>.<schema>.genie_turns
WHERE requester = '<user_name>'
AND prompt ILIKE '%gross margin%'
AND time >= current_timestamp() - INTERVAL 7 DAYS
ORDER BY time DESC;
Listez ensuite chaque période de ce tour, y compris chaque appel d’outil exporté avec ses arguments et son résultat. Cette query lit directement la table de trace :
SELECT
name,
status.code AS status_code,
(end_time_unix_nano - start_time_unix_nano) / 1e6 AS duration_ms,
attributes:['gen_ai.tool.name']::string AS tool_name,
attributes:['gen_ai.tool.call.arguments']::string AS tool_arguments,
attributes:['gen_ai.tool.call.result']::string AS tool_result
FROM <catalog>.<schema>.<table_name>
WHERE trace_id = '<trace_id>'
ORDER BY start_time_unix_nano;
Pour relire une conversation entière dans l’ordre, filtrez sur l’ID de conversation. Les ID de conversation de Genie Code ne sont uniques qu’au sein d’un workspace, donc filtrez aussi sur le workspace :
SELECT time, prompt, response
FROM <catalog>.<schema>.genie_turns
WHERE conversation_id = '<conversation_id>'
AND workspace_id = '<workspace_id>'
ORDER BY time;
Surveiller les erreurs et la latence
Compter les tours ayant échoué par code d'erreur ou résultat au cours des 7 derniers jours :
SELECT
product,
COALESCE(error_code, run_outcome) AS failure_reason,
COUNT(*) AS failed_turns
FROM <catalog>.<schema>.genie_turns
WHERE status_code = 'STATUS_CODE_ERROR'
AND time >= current_timestamp() - INTERVAL 7 DAYS
GROUP BY product, failure_reason
ORDER BY failed_turns DESC;
Rapporter les percentiles de latence par produit et par jour :
SELECT
date,
product,
percentile_approx(duration_ms, 0.5) AS p50_ms,
percentile_approx(duration_ms, 0.95) AS p95_ms
FROM <catalog>.<schema>.genie_turns
WHERE time >= current_timestamp() - INTERVAL 14 DAYS
GROUP BY date, product
ORDER BY date DESC, product;
Voir les outils utilisés par Genie
Classer les outils exportés que Genie Code et Genie One appellent le plus souvent, avec leur taux d’échec. Cette query lit directement la table de trace :
SELECT
CASE
WHEN service_name = 'genie-code-agent' THEN 'Genie Code'
ELSE 'Genie One'
END AS product,
attributes:['gen_ai.tool.name']::string AS tool_name,
COUNT(*) AS calls,
COUNT_IF(status.code = 'STATUS_CODE_ERROR') AS failed_calls,
ROUND(100 * COUNT_IF(status.code = 'STATUS_CODE_ERROR') / COUNT(*), 1) AS failure_pct
FROM <catalog>.<schema>.<table_name>
WHERE (
(service_name = 'Genie One' AND name LIKE 'execute_tool %')
OR (service_name = 'genie-code-agent' AND name LIKE 'tool.execute:%')
)
AND time >= current_timestamp() - INTERVAL 30 DAYS
GROUP BY product, tool_name
ORDER BY calls DESC;
Examiner les assets créés ou modifiés par Genie One
Répertoriez les tableaux de bord, les Genie Agents, les compétences et les tâches planifiées que Genie One a créés, modifiés, publiés ou supprimés au cours des 30 derniers jours, ainsi que les personnes qui ont demandé chaque changement. Cette query lit directement la table de trace :
SELECT
time,
attributes:['enduser.id']::string AS requester,
attributes:workspace_id::string AS workspace_id,
attributes:['gen_ai.tool.name']::string AS tool_name,
attributes:['gen_ai.tool.call.arguments']::string AS tool_arguments,
attributes:['gen_ai.tool.call.result']::string AS tool_result
FROM <catalog>.<schema>.<table_name>
WHERE service_name = 'Genie One'
AND name LIKE 'execute_tool %'
AND regexp_like(
attributes:['gen_ai.tool.name']::string,
'^(create|edit|publish|delete|update|remove)_'
)
AND time >= current_timestamp() - INTERVAL 30 DAYS
ORDER BY time DESC;
Examiner les tâches planifiées
Répertoriez les tâches planifiées qui ont exécuté des tours de Genie One, qui les possède et à quelle fréquence elles ont échoué :
SELECT
scheduled_task_id,
requester,
COUNT(*) AS runs,
COUNT_IF(status_code = 'STATUS_CODE_ERROR') AS failed_runs
FROM <catalog>.<schema>.genie_turns
WHERE scheduled_task_id IS NOT NULL
AND time >= current_timestamp() - INTERVAL 30 DAYS
GROUP BY scheduled_task_id, requester
ORDER BY runs DESC;
Examiner les feedbacks pouces levés et baissés
Lorsqu'un utilisateur évalue une réponse de Genie Code ou Genie One avec un pouce vers le haut ou un pouce vers le bas, l'évaluation est enregistrée dans la table d'annotations à côté de la table de trace. La table d’annotations se trouve dans le même catalogue et le même schéma que la table de trace, et porte le même nom avec _otel_annotations à la place de _otel_spans. Par exemple, si votre table de trace est main.ai_gateway.unity_gateway_otel_spans, la table d’annotations est main.ai_gateway.unity_gateway_otel_annotations. Chaque évaluation possède name = 'user_feedback', un value de true pour un pouce vers le haut ou false pour un pouce vers le bas, et un target_id qui correspond au trace_id du tour.
La table d’annotations enregistre chaque modification apportée à une évaluation ; utilisez donc la ligne la plus récente pour chaque annotation_id. Pour répertorier les tours que les utilisateurs ont évalués avec un pouce vers le bas au cours des 30 derniers jours, exécutez :
WITH feedback AS (
SELECT
target_id AS trace_id,
value::boolean AS thumbs_up,
annotation_change_type,
ROW_NUMBER() OVER (PARTITION BY annotation_id ORDER BY updated_at DESC) AS rn
FROM <catalog>.<schema>.<annotations_table_name>
WHERE name = 'user_feedback'
AND target_type = 'TRACE'
)
SELECT t.time, t.product, t.requester, t.prompt, t.response
FROM feedback f
JOIN <catalog>.<schema>.genie_turns t ON t.trace_id = f.trace_id
WHERE f.rn = 1
AND f.annotation_change_type <> 'delete'
AND NOT f.thumbs_up
AND t.time >= current_timestamp() - INTERVAL 30 DAYS
ORDER BY t.time DESC;
Pour voir ce que Genie a fait dans l’un de ces tours, utilisez le trace_id avec la query span dans Trier une réponse signalée.
Classer les questions avec des fonctions IA
Utilisez des fonctions IA pour regrouper les prompts par sujet, par exemple pour trouver les types de questions les plus courants :
SELECT
ai_classify(prompt, ARRAY('finance', 'sales', 'operations', 'hr', 'other')) AS topic,
COUNT(*) AS turns
FROM <catalog>.<schema>.genie_turns
WHERE product = 'Genie One'
AND time >= current_timestamp() - INTERVAL 7 DAYS
GROUP BY topic
ORDER BY turns DESC;
Limitations
- Le traçage Genie est en version bêta. La remise de traces se fait au mieux. Par conséquent, utilisez les logs d’audit comme système d’enregistrement pour la conformité.
- Les traces Genie One n’incluent pas les portées d’appel de modèle.
- Les conversations avec les agents Genie Agents ne sont pas tracées. Lorsque Genie One ou Genie Code envoie une question à un agent Genie Agent, la trace inclut l’appel d’outil
ask_genie_spaceouaskGenieSpace, mais pas les étapes que l’agent Genie Agent a suivies pour y répondre. Pour surveiller l’utilisation de l’agent Genie Agent, consultez Surveiller l’utilisation de l’agent Genie Agent avec des logs d’audit et des alertes. - Chaque attribut de Genie One est limité à 180 Kio, ce qui est inférieur à la limite d'attribut de 3 Mio pour la table de trace unifiée, et un tour de Genie One exporte au plus 128 spans d'outil. Lorsqu'une charge utile est tronquée, le span possède l'attribut
databricks.trace.payload_truncated. - Supprimer une conversation Genie ne supprime pas ses traces. Les traces ne sont supprimées que par votre politique de rétention des tables.
- Toutes les limitations de la table de trace unifiée s’appliquent également. Voir Limitations.