Referência da tabela do sistema de eventos de ambiente controlado

2025-05-31

Importante

Esta tabela do sistema está em Visualização Pública.

A tabela de eventos de ambiente controlado registra as ações que você ou seus colaboradores executaram em salas limpas na conta. Esta tabela inclui dados regionais de toda a sua conta.

Para obter mais informações sobre ambientes controlados, consulte O que são os ambientes controlados do Azure Databricks?.

Caminho da tabela: Esta tabela do sistema está localizada em system.access.clean_room_events.

Esquema da tabela do sistema de eventos de ambiente controlado

A tabela do sistema de eventos de sala limpa usa o seguinte esquema:

Nome da coluna	Tipo de dados	Descrição	Exemplo
`account_id`	cadeia de caracteres	O ID da conta do Databricks	`7af234db-66d7-4db3` `-bbf0-956098224879`
`metastore_id`	cadeia de caracteres	O ID do metastore UC	`5a31ba44-bbf4-4174` `-bf33-e1fa078e6765`
`event_id`	cadeia de caracteres	A ID do evento de ambiente controlado	`db52a413-7a0a-4d49` `-b742-7ae5f06bc4b2`
`clean_room_name`	cadeia de caracteres	Nome da sala limpa associada ao evento	`market-analysis`
`central_clean_room_id`	cadeia de caracteres	A ID do ambiente controlado central	`e01b6a78-1336-47e1` `-b63d-3e49aa5b627`
`initiator_global_metastore_id`	cadeia de caracteres	ID global do metastore do colaborador que iniciou o evento	`aws:us-west-2:ec22936d` `-cd29-4421-a88a-883fb356776a`
`event_time`	carimbo de data/hora	O carimbo de data/hora de quando o evento ocorreu	`2023-01-01T01:01:01.123`
`event_type`	cadeia de caracteres	O tipo de evento. Confira Eventos de ambiente controlado registrados em log.	`CLEAN_ROOM_CREATED`
`clean_room_created_metadata`	Estrutura	Os metadados do tipo de evento `CLEAN_ROOM_CREATED`	`{` `"collaborators": [` `{"collaborator_global_metastore_id":` `"aws:us-west-2:ec22936d-cd29-4421-a88a-883fb356776a"},` `{"collaborator_global_metastore_id":` `"azure:westus:3be05a26-5a83-478c-8428-9ef9aa67b5d0"}]` `}`
`clean_room_deleted_metadata`	Estrutura	Os metadados do tipo de evento `CLEAN_ROOM_DELETED`	`{` `"central_clean_room_id": "af0d4563-2267-412c-9d4a` `-8a59c4895c18"` `}`
`run_notebook_started_metadata`	Estrutura	Os metadados do tipo de evento `RUN_NOTEBOOK_STARTED`	`{` `"notebook_name": "Market Analysis",` `"notebook_checksum": "7072696E7468656C6C6F776F7264",` `"run_id": "TaskRunId-634124444694206",` `"notebook_etag": "f2429adc02d548bacc11db6c8891ec2548d38b4798a80810fbc8be784af22931",` `"notebook_update_time": "2025-05-04T03:20:35.000Z"` `}`
`run_notebook_completed_metadata`	Estrutura	Os metadados do tipo de evento `RUN_NOTEBOOK_COMPLETED`	Confira Metadados de execução do notebook concluídos
`clean_room_assets_updated_metadata`	Estrutura	Os metadados do tipo de evento `CLEAN_ROOM_ASSETS_UPDATED`	`{` `"added_assets": [{` `"data_object_type": "TABLE",` `"name": "sales",` `"catalog": "demo"}],` `"updated_assets":[],` `"removed_assets": []` `}`
`asset_review_created_metadata`	Estrutura	Os metadados do tipo de evento `ASSET_REVIEW_CREATED`	Ver Eventos de revisão de ativos de sala limpa
`output_schema_deleted_metadata`	Estrutura	Os metadados do tipo de evento `OUTPUT_SCHEMA_DELETED`	`{` `"name": "output_schema_55555",` `"owner_global_metastore_id": "aws:us-west-2:555555-55...",` `"action": "DELETE",` `"expire_time": "2025-01-14T15:28:19.000Z"` `}`
`initiator_collaborator_alias`	cadeia de caracteres	Alias do colaborador que iniciou o evento. Para salas limpas criadas pela interface do usuário, o valor é `creator` ou `collaborator`. Para salas limpas criadas por meio da API, elas são os valores personalizados especificados na criação.	`creator`

Eventos de ambiente controlado registrados em log

Essa tabela do sistema registra os seguintes eventos:

CLEAN_ROOM_CREATED: o usuário cria uma nova sala limpa.
CLEAN_ROOM_DELETED: o usuário exclui um ambiente controlado.
RUN_NOTEBOOK_STARTED: o usuário inicia um notebook em um ambiente controlado.
RUN_NOTEBOOK_COMPLETED: uma execução de notebook foi concluída. Verifique o run_notebook_completed_metadata para ver se a execução foi bem-sucedida ou não.
CLEAN_ROOM_ASSETS_UPDATED: Os ativos de uma sala limpa estão atualizados. Isso pode incluir adicionar, atualizar ou excluir ativos.
OUTPUT_SCHEMA_DELETED: um esquema de saída expira e é excluído. O initiator_global_metastore_id desse tipo de evento é sempre system porque a exclusão ocorre quando o esquema de saída expira.
ASSET_REVIEW_CREATED: o usuário analisa um ativo de sala limpa. Isso pode incluir revisões geradas pelo sistema em nome do usuário.

Para evitar registros duplicados, apenas um registro é emitido para cada evento em salas limpas em que os colaboradores pertencem ao mesmo metastore. Para ambientes controlados em que os colaboradores pertencem a metastores separados, registros exclusivos são emitidos de cada colaborador.

Esquema de metadados de execução de notebook concluído

A coluna run_notebook_completed_metadata contém informações de metadados para eventos RUN_NOTEBOOK_COMPLETED. Se uma tabela de saída foi criada pela execução do notebook, as informações são registradas usando o struct output_schema.

A coluna run_notebook_completed_metadata usa o seguinte esquema:

notebook_name: "example_notebook"
run_id: "TaskRunId-55555129818570"
state: "SUCCESS"
duration_in_seconds: 120
output_schema:
  name: "output_schema_123450129818570"
  owner_global_metastore_id: "aws:us-west-2:55555e-55bc-55a5-55ab-555d5ec16013"
  action: "CREATE"
  expire_time: "2025-01-14T15:28:19.000Z"
  assets_added:
    0:
    name: "important_data"
    data_object_type: "TABLE"

Eventos de revisão de ativos de sala limpa

A tabela de sistemas registra metadados sobre ações de revisão, como aprovações, rejeições e aprovações automáticas executadas em ativos de sala limpa individuais. Os diferentes tipos de revisão retornam os seguintes structs:

Aprovação:

{
  "asset_name": "Market Analysis",
  "data_object_type": "NOTEBOOK_FILE",
 "notebook_metadata: {
    “etag": "f2429adc02d548bacc11db6c8891ec2548d38b4798a80810fbc8be784af22931",
  }
  "review_state": "APPROVED",
  "review_subreason": null,
  "auto_approval_rule_id": null,
}

Rejeição:

{
  "asset_name": "Market Analysis",
  "data_object_type": "NOTEBOOK_FILE",
 "notebook_metadata: {
    “etag": "f2429adc02d548bacc11db6c8891ec2548d38b4798a80810fbc8be784af22931",
  }
  "review_state": "REJECTED",
  "review_subreason": null,
  "auto_approval_rule_id": null,
}

Aprovação automática:

{
  "asset_name": "Market Analysis",
  "data_object_type": "NOTEBOOK_FILE",
 "notebook_metadata: {
    “etag": "f2429adc02d548bacc11db6c8891ec2548d38b4798a80810fbc8be784af22931",
  }
  "review_state": "APPROVED",
  "review_subreason": "AUTO_APPROVED",
  "auto_approval_rule_id": "d0ec563f-6d58-4f38-99c0-376b779e3747",
}

Monitorar o uso faturável de ambiente controlado

Para saber mais sobre o uso e os custos de ambiente controlado você pode unir essa tabela à tabela billing.usage usando a coluna central_clean_room_id. Na tabela billing.usage, o uso de ambiente controlado é atribuído usando a chave usage_metadata.central_clean_room_id.

Consultas de exemplo

As seguintes consultas de exemplo ajudam você a obter informações sobre a atividade de ambiente controlado em sua conta:

Listar todos os eventos de um ambiente controlado especificado
Listar todos os eventos iniciados por um colaborador especificado
Listar todos os colaboradores relevantes dos ambientes controlados
Listar as execuções de notebook mais lentas
Taxa de execução de êxito para cada notebook
Listar todos os eventos em que uma tabela especificada foi adicionada a clean rooms

Listar todos os eventos de um ambiente controlado especificado

Substitua :central_clean_room_id pela ID central da sala limpa, que pode ser encontrada no painel de detalhes da sala limpa ao lado da ID Central.

SELECT
 event_time, initiator_global_metastore_id, event_type,
 CASE
   WHEN event_type = 'CLEAN_ROOM_CREATED' THEN to_json(clean_room_created_metadata)
   WHEN event_type = 'CLEAN_ROOM_DELETED' THEN to_json(clean_room_deleted_metadata)
   WHEN event_type = 'RUN_NOTEBOOK_STARTED' THEN to_json(run_notebook_started_metadata)
   WHEN event_type = 'RUN_NOTEBOOK_COMPLETED' THEN to_json(run_notebook_completed_metadata)
   WHEN event_type = 'CLEAN_ROOM_ASSETS_UPDATED' THEN to_json(clean_room_assets_updated_metadata)
   WHEN event_type = 'OUTPUT_SCHEMA_DELETED' THEN to_json(output_schema_deleted_metadata)
   WHEN event_type = 'ASSET_REVIEW_CREATED' THEN to_json(asset_review_created_metadata)
   ELSE ""
 END AS event_metadata
 FROM system.access.clean_room_events
 WHERE central_clean_room_id = :central_clean_room_id
ORDER BY event_time DESC

Listar todos os eventos iniciados por um colaborador especificado

Para o :initiator_global_metastore_id parâmetro, insira a ID global do metastore do colaborador, também conhecida como identificador de compartilhamento. Para :collaborator_alias, insira o alias do colaborador. Por padrão, os dois aliases possíveis são creator para o criador da sala limpa e collaborator para a outra parte.

SELECT
 clean_room_name, central_clean_room_id, event_type, event_time,
 CASE
   WHEN event_type = 'CLEAN_ROOM_CREATED' THEN to_json(clean_room_created_metadata)
   WHEN event_type = 'CLEAN_ROOM_DELETED' THEN to_json(clean_room_deleted_metadata)
   WHEN event_type = 'RUN_NOTEBOOK_STARTED' THEN to_json(run_notebook_started_metadata)
   WHEN event_type = 'RUN_NOTEBOOK_COMPLETED' THEN to_json(run_notebook_completed_metadata)
   WHEN event_type = 'CLEAN_ROOM_ASSETS_UPDATED' THEN to_json(clean_room_assets_updated_metadata)
   WHEN event_type = 'OUTPUT_SCHEMA_DELETED' THEN to_json(output_schema_deleted_metadata)
   WHEN event_type = 'ASSET_REVIEW_CREATED' THEN to_json(asset_review_created_metadata)
   ELSE ""
 END AS event_metadata
 FROM system.access.clean_room_events
 WHERE initiator_global_metastore_id = :initiator_global_metastore_id AND (initiator_collaborator_alias = :collaborator_alias OR initiator_collaborator_alias IS NULL)
 ORDER BY clean_room_name, event_time DESC

Listar todos os colaboradores relevantes dos ambientes controlados

SELECT DISTINCT explode(transform(clean_room_created_metadata.collaborators, x -> x.collaborator_global_metastore_id)) AS collaborator
FROM system.access.clean_room_events
WHERE event_type = 'CLEAN_ROOM_CREATED'

Listar as execuções de notebook mais lentas

SELECT
 clean_room_name,
 run_notebook_completed_metadata.notebook_name AS notebook_name,
 run_notebook_completed_metadata.duration_in_seconds AS duration_in_seconds,
 run_notebook_completed_metadata.run_id AS run_id
FROM system.access.clean_room_events
WHERE event_type = 'RUN_NOTEBOOK_COMPLETED'
 AND run_notebook_completed_metadata.state = 'SUCCESS'
 AND run_notebook_completed_metadata.duration_in_seconds IS NOT NULL
ORDER BY duration_in_seconds DESC

Taxa de execução de êxito para cada notebook

SELECT
 clean_room_name,
 run_notebook_completed_metadata.notebook_name AS notebook_name,
 ROUND(COUNT(CASE WHEN run_notebook_completed_metadata.state = 'SUCCESS' THEN 1 END) * 1.0 / COUNT(*) * 100) AS success_rate
FROM system.access.clean_room_events
WHERE event_type = 'RUN_NOTEBOOK_COMPLETED'
GROUP BY clean_room_name, notebook_name
ORDER BY clean_room_name, notebook_name

Listar todos os eventos em que uma tabela especificada foi adicionada a ambientes controlados

Para o parâmetro :table_name_string, insira o nome da tabela especificado.

SELECT
  clean_room_name,
  initiator_global_metastore_id,
  event_time,
  clean_room_assets_updated_metadata
FROM
  system.access.clean_room_events
WHERE
  event_type = 'CLEAN_ROOM_ASSETS_UPDATED'
  AND exists(
    clean_room_assets_updated_metadata.added_assets,
    item -> item.data_object_type = 'TABLE'
    AND item.name = :table_name_string
  )
ORDER BY
  clean_room_name,
  event_time DESC