Monitore o Genie Code e o Genie One com a tabela de rastreamento unificada
Beta
O rastreamento do Genie Code e do Genie One está em Beta. Faz parte da tabela de rastreamento unificado, que também está em Beta. Para ativá-lo, veja Ativar o rastreamento do Genie para um workspace.
O proprietário da tabela de rastreamento e qualquer pessoa com acesso à tabela podem view cada turno do Genie Code e do Genie One na tabela de rastreamento unificada do Unity Gateway como spans OpenTelemetry. Cada turno registra quem perguntou, o prompt, o raciocínio e a resposta visíveis para o usuário, os ativos de dados citados, o resultado e a duração. Também registra as ações que o Genie executou, como executar SQL, criar ou editar dashboards e chamar ferramentas MCP, com seus argumentos.
Como os rastreamentos residem em uma tabela do Unity Catalog que você possui, você pode pedir ao Genie Code ou ao Genie One para analisá-los ou fazer query neles com SQL para:
- Triagem de uma resposta errada : encontre uma troca que um usuário tenha relatado ou avaliado com um polegar para baixo e revise o prompt, o raciocínio, as ações e a resposta de ponta a ponta.
- Monitorar a qualidade : rastreie erros, chamadas de ferramentas com falha e turnos lentos.
- Rastrear adoção : Conte usuários ativos e turns por produto, workspace e canal.
- Governe o que o Genie cria e altera : veja quem criou, editou, publicou ou excluiu dashboards, agentes do Genie, habilidades e tarefas agendadas.
- Suporte a revisões de compliance : pesquise prompts e respostas para um usuário, intervalo de tempo ou palavra-chave.
Requisitos
Todos os seguintes requisitos devem ser verdadeiros antes que os rastreamentos do Genie sejam exportados. Se qualquer requisito estiver faltando, nenhum rastreamento do Genie será escrito.
- O Unity Gateway está habilitado para sua account.
- Um administrador account ativou os recursos beta do Enhanced Unity Gateway na página Previews do console da account. Consulte Gerenciar prévias em nível de account.
- Um administrador de metastore configurou a tabela de rastreamento unificada para o metastore ao qual seu workspace está anexado. Consulte Habilitar a tabela de rastreamento unificada.
- Um administrador de workspace ativou a visualização do Rastreamento do Genie One , a visualização do Rastreamento do Genie Code ou ambos para o workspace. Consulte Ativar o rastreamento do Genie para um workspace.
Para query os traces, você precisa de SELECT na tabela de traces, USE SCHEMA em seu schema e USE CATALOG em seu catalog. Consulte Controlar quem pode ler os traces do Genie.
Ativar o rastreamento do Genie para um workspace
O rastreamento do Genie está desativado por default. Um administrador de workspace ativa a visualização de cada produto separadamente para cada workspace. Ative o Genie One Tracing para rastrear conversas do Genie One e o Genie Code Tracing para rastrear conversas do Genie Code.
- Como administrador do workspace, clique no nome de usuário na barra superior do workspace e, em seguida, clique em Previews (Visualizações ).
- Encontre a prévia de cada produto que você deseja rastrear e ative-a. Consulte Gerenciar prévias no nível do workspace.
Depois de ativar uma visualização, as novas rodadas desse produto no workspace são exportadas para a tabela de rastreamento unificada. Rodadas anteriores não são preenchidas retroativamente.
Para parar de coletar rastreamentos de um produto, desative sua visualização. Novas turns param de ser exportadas. Os rastreamentos que já foram gravados permanecem na tabela até que sua política de retenção os remova.
Os rastreamentos do Genie contêm o texto completo dos prompts do usuário, as respostas do Genie e os argumentos e resultados da ferramenta. O proprietário da tabela de rastreamento e qualquer pessoa com acesso à tabela podem ler este conteúdo, mesmo para conversas e dados aos quais eles não teriam acesso. Os administradores do metastore podem conceder acesso a si mesmos. Como os traces podem incluir dados sensíveis, revise quem pode ler a tabela de traces e defina uma política de retenção antes de ativar o rastreamento do Genie. Consulte Controlar quem pode ler traces do Genie e Limitações.
Encontre rastreamentos do Genie na tabela
Os rastreamentos do Genie compartilham a tabela de rastreamento unificada com outro tráfego do Unity Gateway. Use service_name para selecioná-los:
Produto | Filtrar |
|---|---|
Genie One |
|
Genie Code |
|
Conversas com agentes Genie não estão incluídas. Consulte Limitações.
Na tab Rastreamentos do Unity Gateway, você também pode filtrar Tipo de serviço para Genie para ver apenas os rastreamentos do Genie Code e do Genie One. Veja view rastreamentos na UI.
Analise rastreamentos com o Genie
Para analisar traços do Genie sem escrever SQL, pergunte ao Genie Code ou ao Genie One sobre eles em linguagem simples. Para escrever queries com o Genie Code na página da tabela de traços, consulte Escrever queries com o Genie Code.
Exemplos de solicitações:
- “Investigue os rastros do Genie e encontre quais ferramentas falharam com mais frequência no Genie Code na semana passada.”
- “Investigue os rastros do Genie e liste os usuários que criaram ou editaram painéis com o Genie One nos últimos 30 dias.”
- "Investigue os rastreamentos do Genie e resuma as perguntas mais comuns que as pessoas fizeram ao Genie One ontem."
Se o Genie não encontrar a tabela de trace, inclua o nome dela, como <catalog>.<schema>.<table_name>, na sua pergunta. Você só pode analisar os traces aos quais tem SELECT acesso. Veja Controlar quem pode ler traces do Genie.
Para query os rastreamentos com SQL em vez disso, consulte Consultas de exemplo.
O que um rastreamento do Genie contém
Cada turno do Genie é um trace, e cada linha no trace tem o mesmo trace_id. Um trace tem esses tipos de linhas:
Tipo de linha |
| O que cobre |
|---|---|---|
Intervalo raiz | Genie One: | O turno inteiro: o prompt, a resposta, o resultado e a duração. |
Intervalo da ferramenta | Genie One: | Uma chamada de ferramenta no turno. |
Intervalo de aprovação ou pergunta | Somente Genie One: | Um ponto em que o Genie One pediu ao usuário para aprovar uma chamada de ferramenta ou responder a uma pergunta. Veja Spans do Genie One. |
Span de chamada de modelo | Apenas Genie Code: | Uma chamada de modelo na turn, com sua duração. |
Os rastreamentos incluem apenas o que o usuário viu no chat do Genie, além de timing e resultado. Eles não incluem prompts do sistema, raciocínio oculto ou custo. Para analisar o custo do Genie, consulte Monitorar e entender seu custo do Genie.
Os passos que não aparecem em um trace
Para encontrar e raciocinar sobre os ativos certos, o Genie também executa os passos internos de recuperação e planejamento, como pesquisar tabelas e painéis, ler metadados de ativos e ler ou atualizar a memória do Genie. Esses são os passos não realizam uma ação direta no seu Workspace, portanto, um trace não os inclui ou suas entradas e resultados. O passo que não está no trace não deixa intervalo nem placeholder. Para ver cada passo que o Genie mostrou ao usuário, abra a conversa no Genie e revise seu raciocínio.
Quais chamadas de ferramenta são exportadas
Os rastros incluem chamadas de ferramentas que realizam uma ação em seu workspace ou repassam o trabalho para outro serviço. Por exemplo:
- Executando SQL ou código.
- Criação, edição, publicação ou exclusão de ativos, como dashboards, notebooks, agentes Genie, habilidades e tarefas programadas.
- Alterando compute, pipelines ou jobs.
- Fazer uma pergunta a um Genie Agent ou outro agente, pesquisar na web ou chamar uma ferramenta MCP.
- Fazer uma pergunta ou pedir aprovação ao usuário e enviar notificações.
Para ver quais ferramentas aparecem nos seus traços, use a query em Ver quais ferramentas o Genie usa. O conjunto de chamadas de ferramentas que os rastreamentos incluem pode mudar.
Atributos em cada span
O Unity Gateway adiciona esses atributos a cada span do Genie quando ele grava o span na tabela:
Atributo | Descrição |
|---|---|
| ID do Workspace onde ocorreu a execução do turno. |
| Nome de usuário do usuário que enviou o prompt, como |
| ID do usuário ou service principal que enviou o prompt. |
Use a sintaxe de colchetes para ler atributos cujos nomes contêm pontos, como attributes:['enduser.id']. A sintaxe de crase, como attributes:`enduser.id` , retorna NULL para esses atributos.
Intervalos do Genie One
O span raiz é chamado de invoke_agent OneChat. Ele tem estes atributos:
Atributo | Descrição |
|---|---|
| Defina como |
| ID do chat. Todas as turnos no mesmo chat compartilham esse valor. |
| ID desta resposta. |
| O prompt do usuário, como uma strings JSON. |
| O raciocínio visível para o usuário e a resposta final, como uma strings JSON. |
| Ativos de dados citados na resposta. |
| Status final da resposta. |
| Código de erro mostrado ao usuário, se o turno falhou. |
| ID do usuário que enviou o prompt. |
| ID da conta. |
| ID do metastore. |
| Onde o usuário fez a pergunta, como |
| ID da tarefa agendada que execução este turno, se uma tarefa agendada o disparou. |
Cada chamada de ferramenta exportada é um span filho chamado execute_tool <tool_name> com estes atributos:
Atributo | Descrição |
|---|---|
| Nome da ferramenta ou da ferramenta MCP chamada. |
| ID da chamada da ferramenta. |
| Argumentos enviados para a ferramenta, como JSON. Não registrado para |
| Resultado retornado pela ferramenta. Para |
O intervalo de uma ferramenta tem o status STATUS_CODE_ERROR se a chamada da ferramenta não foi concluída.
Quando o Genie One pede ao usuário para aprovar uma chamada de ferramenta ou responder a uma pergunta, o rastreamento tem um span filho chamado request_approval <tool_name> ou request_answers ask_user_questions. O turno que continua depois que o usuário responde é um rastreamento separado, e o seu span raiz vincula-se ao span de solicitação.
Genie Code spans
O span raiz tem o nome invoke_agent genieCodeAgent ou invoke_agent GenieCodeFullChat. Os spans filhos incluem spans chat para chamadas de modelo e spans tool.execute:<tool_name> para chamadas de ferramenta exportadas. Os atributos comuns incluem:
Atributo | Descrição |
|---|---|
| Nome do agente, no span raiz. |
| ID da conversa ou notebook, no span raiz. Exclusivo em um workspace. |
| O prompt do usuário, como uma strings JSON. |
| A resposta final e o raciocínio visível, como uma strings JSON. |
| Resultado do turno, no span raiz: |
| Nome da ferramenta, nas faixas de ferramentas. |
| ID da chamada da ferramenta, em spans de ferramenta. |
| Argumentos enviados para a ferramenta, como JSON, em spans de ferramenta. |
| Resultado retornado pela ferramenta, como um status, contagem de linhas ou ID de ativo, em spans de ferramentas. |
| Resultado da chamada de ferramenta, em spans de ferramenta, como |
| Defina quando o conteúdo foi deixado fora do intervalo. |
Uma turno com o resultado error tem o status STATUS_CODE_ERROR, assim como uma chamada de ferramenta com falha. Turnos com o resultado cancelled ou aborted, e chamadas de ferramenta que o usuário rejeita, mantêm o status STATUS_CODE_OK ou STATUS_CODE_UNSET.
Para o schema completo da tabela, veja Referência do schema da tabela de trace unificada.
Controlar quem pode ler rastreamentos do Genie
Por default, somente o proprietário da tabela de rastreamento, o administrador do metastore que configurou a tabela de rastreamento, pode consultá-la. Outros administradores de metastore podem dar acesso a si mesmos ou a qualquer outra pessoa. Para dar acesso a outros usuários, como administradores de workspace ou proprietários de dados, conceda USE CATALOG, USE SCHEMA e SELECT. Consulte Permissões e controle de acesso.
Sem um filtro de linha, qualquer pessoa com SELECT pode ver todos os rastreamentos na tabela, incluindo prompts e respostas do Genie de cada workspace anexado ao metastore. O Databricks recomenda que você limite o acesso com uma política de filtro de linha de controle de acesso baseado em atributos (ABAC). Por exemplo, você pode filtrar linhas em attributes:workspace_id para que os admins de cada Workspace vejam apenas os rastreamentos do Genie de seus próprios Workspace. Cada span tem workspace_id, então o filtro mantém os spans de raiz e de ferramenta de um turno juntos. Veja Permissões e controle de acesso.
Exemplos de query
Substitua <catalog>.<schema>.<table_name> pelo caminho da sua tabela de rastreamento. Inclua um filtro time para obter o melhor desempenho. Consulte query com SQL ou um notebook.
A maioria dessas queries lê da view genie_turns, então crie a view primeiro. Colunas como product, requester e prompt existem apenas na view, não na tabela de trace. As queries que leem a tabela de trace diretamente dizem isso.
Criar uma view das interações do Genie
Esta view retorna uma linha por turno do Genie com os campos comuns extraídos. As colunas channel, scheduled_task_id e error_code aplicam-se apenas ao Genie One, e run_outcome aplica-se apenas ao Genie Code.
Uma view lê a tabela de rastreamento com os privilégios do proprietário, portanto, qualquer pessoa para quem você conceder SELECT na view pode ler os rastreamentos do Genie que ela retorna. Conceda SELECT na view apenas para usuários que têm permissão para ler esses rastreamentos.
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');
Acompanhar adoção
Conte turnos e usuários ativos por dia para cada produto nos últimos 30 dias:
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;
Desmembre o uso do Genie One por workspace e canal:
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;
Triagem de uma resposta relatada
Encontre os turnos recentes de um usuário que menciona uma palavra-chave:
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;
Em seguida, liste cada span nesse turno, incluindo cada chamada de ferramenta exportada com seus argumentos e resultados. Esta query lê a tabela de rastreamento diretamente:
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;
Para reproduzir um chat inteiro em ordem, filtre pelo ID da conversa. Os IDs de conversa do Genie Code são exclusivos apenas dentro de um workspace, portanto, filtre também pelo workspace:
SELECT time, prompt, response
FROM <catalog>.<schema>.genie_turns
WHERE conversation_id = '<conversation_id>'
AND workspace_id = '<workspace_id>'
ORDER BY time;
Monitorar erros e latência
Conte os turnos que falharam por código de erro ou resultado nos últimos 7 dias:
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;
Relatar percentis de latência por produto por dia:
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;
Veja quais ferramentas o Genie usa
Classifique as ferramentas exportadas que o Genie Code e o Genie One chamaram com mais frequência, com sua taxa de falha. Esta query lê a tabela de rastreamento diretamente:
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;
Revise os ativos que o Genie One criou ou alterou
Liste os dashboards, Genie Agents, skills e tarefas agendadas que o Genie One criou, editou, publicou ou excluiu nos últimos 30 dias e quem solicitou cada alteração. Esta query lê a tabela de rastreamento diretamente:
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;
Revise tarefas agendadas
Liste as tarefas agendadas que executaram turnos do Genie One, quem é o proprietário dos turnos e com que frequência eles falharam:
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;
Analisar o feedback positivo e negativo
Quando um usuário avalia uma resposta do Genie Code ou do Genie One com um polegar para cima ou para baixo, a avaliação é salva na tabela de anotações ao lado da tabela de rastreamento. A tabela de anotações está no mesmo catálogo e esquema que a tabela de rastreamento e tem o mesmo nome com _otel_annotations no lugar de _otel_spans. Por exemplo, se a sua tabela de rastreamento for main.ai_gateway.unity_gateway_otel_spans, a tabela de anotações será main.ai_gateway.unity_gateway_otel_annotations. Cada avaliação tem name = 'user_feedback', um value de true para um polegar para cima ou false para um polegar para baixo, e um target_id que corresponde ao trace_id da curva.
A tabela de anotações registra cada alteração em uma classificação, então use a linha mais recente para cada annotation_id. Para listar os turnos que os usuários avaliaram positivamente (polegar para baixo) nos últimos 30 dias, execução:
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;
Para ver o que o Genie fez em um desses turnos, use o trace_id com a query de span em Avalie uma resposta reportada.
Classificar perguntas com funções de AI
Use funções de AI para agrupar prompts por tópico, por exemplo, para encontrar os tipos de pergunta mais comuns:
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;
Limitações
- O rastreamento do Genie está em versão Beta. A entrega do rastro é feita com o melhor esforço, portanto, use logs de auditoria como sistema de registro para compliance.
- Os rastreamentos do Genie One não incluem intervalos de chamada de modelo.
- As conversas com Genie Agents não são rastreadas. Quando o Genie One ou o Genie Code envia uma pergunta a um Genie Agent, o rastreamento inclui a chamada da ferramenta
ask_genie_spaceouaskGenieSpace, mas não os passos que o Genie Agent seguiu para respondê-la. Para monitorar o uso do Genie Agent, consulte Monitorar o uso do Genie Agent com logs de auditoria e alertas. - Cada atributo Genie One é limitado a 180 KiB, o que é menor que o limite de atributo de 3 MiB para a tabela de rastreamento unificada, e um turno Genie One exporta no máximo 128 spans de ferramentas. Quando um payload é truncado, o span tem o atributo
databricks.trace.payload_truncated. - Excluir uma conversa do Genie não exclui seus traces. Os traces só são removidos pela sua política de retenção da tabela.
- Todas as limitações da tabela de rastreamento unificada também se aplicam. Consulte Limitações.