Monitor events for task executions¶

Você pode configurar o Snowflake para registrar um evento que forneça informações sobre o status da execução da tarefa. O evento é registrado na tabela de eventos ativos associada à tarefa.

Por exemplo, suponha que você tenha associado uma tabela de eventos a um banco de dados. Quando uma tarefa nesse banco de dados é executada, o Snowflake registra um evento nessa tabela de eventos.

Você pode configurar um alerta sobre novos dados para monitorar a tabela de eventos. Você pode configurar o alerta para enviar uma notificação quando houver falha na execução de uma tarefa.

As próximas seções explicam como configurar o registro de eventos para capturar os eventos, como configurar o alerta e como interpretar os eventos registrados na tabela de eventos:

Defina o nível de gravidade dos eventos a serem capturados
Configurar um alerta sobre novos dados para eventos de conclusão de tarefas
Consultar a tabela de eventos para eventos de conclusão de tarefas
Informações registradas para eventos de tarefas

Nota

O registro de eventos para tarefas gera custos. Consulte Custos da coleta de dados de telemetria.

Limitações¶

Os eventos de tarefa não são compatíveis com os Snowflake Native Apps.

Defina o nível de gravidade dos eventos a serem capturados¶

Para configurar os eventos de tarefa a serem registrados na tabela de eventos, defina o nível de gravidade dos eventos que deseja capturar na tabela de eventos:

ERROR: eventos para execuções de tarefas com falha.
INFO: eventos para execuções de tarefas bem-sucedidas e com falha.

Para definir o nível, defina o parâmetro LOG_LEVEL para a conta ou o objeto. Você pode definir o nível para:

Todos os objetos da conta,
Todos os objetos em um banco de dados ou esquema.
Uma tarefa específica.

Nota

Se o nível de gravidade não for definido na conta ou no objeto, nenhum evento será capturado.

Por exemplo:

Para capturar eventos e mensagens ao nível de ERROR para todos os objetos da conta, execute ALTER ACCOUNT SET LOG_LEVEL:
```
ALTER ACCOUNT SET LOG_LEVEL = ERROR;
```
Observe que esse nível afeta todos os tipos de objetos na conta, inclusive UDFs, procedimentos armazenados, tabelas dinâmicas e tarefas.
Para capturar eventos e mensagens ao nível de INFO para todos os objetos no banco de dados my_db, execute ALTER DATABASE … SET LOG_LEVEL:
```
ALTER DATABASE my_db SET LOG_LEVEL = INFO;
```
De modo semelhante ao caso da definição do nível na conta, a configuração do nível no banco de dados afeta todos os tipos de objetos no banco de dados, inclusive UDFs, procedimentos armazenados, tabelas dinâmicas e tarefas.
Para capturar eventos de nível ERROR para a tarefa my_task, execute ALTER TASK … SET LOG_LEVEL:
```
ALTER TASK my_task SET LOG_LEVEL = ERROR;
```

Configurar um alerta sobre novos dados para eventos de conclusão de tarefas¶

Depois de definir o nível de gravidade dos eventos de registro, você pode configurar um alerta sobre novos dados para monitorar a tabela de eventos em busca de novos eventos que indiquem uma falha na conclusão de uma tarefa. Um alerta sobre novos dados é acionado quando novas linhas na tabela de eventos são inseridas e atendem à condição especificada no alerta.

Nota

Para criar o alerta sobre novos dados, você deve usar uma função que tenha recebido os privilégios necessários para consultar a tabela de eventos.

Se a condição de alerta consultar a tabela de eventos padrão (SNOWFLAKE.TELEMETRY.EVENTS), exibição predefinida (exibição SNOWFLAKE.TELEMETRY.EVENTS_VIEW), consulte Funções para acesso à tabela de evento padrão e EVENTS_VIEW.

Para gerenciar o acesso à exibição EVENTS_VIEW, consulte Gerenciar o acesso à exibição EVENTS_VIEW.
Se a condição de alerta consultar uma tabela de eventos personalizada, consulte Privilégios de controle de acesso para tabelas de evento.

Para gerenciar o acesso a uma tabela de eventos personalizada, consulte Gerenciamento de acesso a dados de tabela de eventos.

Na condição de alerta, para consultar os eventos de conclusão de tarefas, selecione as linhas em que resource_attributes:"snow.executable.type" = 'TASK'. Para restringir a lista de eventos, você pode filtrar nas seguintes colunas:

Para restringir os resultados a tarefas em um banco de dados específico, use resource_attributes:"snow.database.name".
Para retornar eventos em que a execução da tarefa falhou, use value:state = 'FAILED'.

Para obter informações sobre os valores registrados para um evento de execução de tarefa, consulte Informações registradas para eventos de tarefas.

Por exemplo, a instrução a seguir cria um alerta sobre novos dados que executa uma ação quando as conclusões de tarefas falham para tarefas no banco de dados my_db. O exemplo pressupõe que:

Sua tabela de eventos ativa é a tabela de eventos padrão (SNOWFLAKE.TELEMETRY.EVENTS).
Você configurou uma integração de notificação por webhook para esse canal do Slack.

CREATE ALERT my_alert_on_task_failures
  IF( EXISTS(
    SELECT * FROM SNOWFLAKE.TELEMETRY.EVENT_TABLE
      WHERE resource_attributes:"snow.executable.type" = 'task'
        AND resource_attributes:"snow.database.name" = 'my_db'
        AND record:"severity_text" = 'ERROR'
        AND value:"state" = 'FAILED'))
  THEN
    BEGIN
      LET result_str VARCHAR;
      (SELECT ARRAY_TO_STRING(ARRAY_AGG(name)::ARRAY, ',') INTO :result_str
         FROM (
           SELECT resource_attributes:"snow.executable.name"::VARCHAR name
             FROM TABLE(RESULT_SCAN(SNOWFLAKE.ALERT.GET_CONDITION_QUERY_UUID()))
             LIMIT 10
         )
      );
      CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
        SNOWFLAKE.NOTIFICATION.TEXT_PLAIN(:result_str),
        '{"my_slack_integration": {}}'
      );
    END;

Consultar a tabela de eventos para eventos de conclusão de tarefas¶

Você também pode consultar a tabela de eventos em busca de eventos que indiquem falha na conclusão de uma tarefa.

Para obter informações sobre a função que você precisa usar para consultar a tabela de eventos e as condições que podem ser usadas para filtrar os resultados, consulte Configurar um alerta sobre novos dados para eventos de conclusão de tarefas.

Por exemplo, para obter o carimbo de data/hora, o nome da tarefa, o ID da consulta e a mensagem de erro para erros com tarefas no banco de dados my_db:

SELECT
    timestamp,
    resource_attributes:"snow.executable.name"::VARCHAR AS task_name,
    resource_attributes:"snow.query.id"::VARCHAR AS query_id,
    value:message::VARCHAR AS error
  FROM my_event_table
  WHERE
    resource_attributes:"snow.executable.type" = 'TASK' AND
    resource_attributes:"snow.database.name" = 'MY_DB' AND
    value:state = 'FAILED'
  ORDER BY timestamp DESC;

+-------------------------+-----------+--------------------------------------+------------------------------------------------------+
| TIMESTAMP               | TASK_NAME | QUERY_ID                             | ERROR                                                |
|-------------------------+-----------+--------------------------------------+------------------------------------------------------|
| 2025-02-18 00:21:19.461 | T1        | 01ba76b5-0107-e56d-0000-a995024f4222 | 002003: SQL compilation error:                       |
|                         |           |                                      | Object 'MY_TABLE' does not exist or not authorized.  |
+-------------------------+-----------+--------------------------------------+------------------------------------------------------+

O exemplo a seguir recupera todas as colunas de erros com tarefas no esquema my_schema:

SELECT *
  FROM my_event_table
  WHERE
    resource_attributes:"snow.executable.type" = 'FAILED' AND
    resource_attributes:"snow.schema.name" = 'MY_SCHEMA' AND
    value:state = 'FAILED'
  ORDER BY timestamp DESC;

+-------------------------+-----------------+-------------------------+-------+----------+------------------------------------------------------------+-------+------------------+-------------+-------------------------------+-------------------+------------------------------------------------------------------------------------------------------+-----------+
| TIMESTAMP               | START_TIMESTAMP | OBSERVED_TIMESTAMP      | TRACE | RESOURCE | RESOURCE_ATTRIBUTES                                        | SCOPE | SCOPE_ATTRIBUTES | RECORD_TYPE | RECORD                        | RECORD_ATTRIBUTES | VALUE                                                                                                | EXEMPLARS |
|-------------------------+-----------------+-------------------------+-------+----------+------------------------------------------------------------+-------+------------------+-------------+-------------------------------+-------------------+------------------------------------------------------------------------------------------------------+-----------|
| 2025-02-18 00:21:19.461 | NULL            | 2025-02-18 00:21:19.461 | NULL  | NULL     | {                                                          | NULL  | NULL             | EVENT       | {                             | NULL              | {                                                                                                    | NULL      |
|                         |                 |                         |       |          |   "snow.database.id": 49,                                  |       |                  |             |   "name": "execution.status", |                   |   "message": "002003: SQL compilation error:\nObject 'EMP_TABLE' does not exist or not authorized.", |           |
|                         |                 |                         |       |          |   "snow.database.name": "MY_DB",                        |       |                  |                |   "severity_text": "ERROR"    |                   |   "state": "FAILED"                                                                                  |           |
|                         |                 |                         |       |          |   "snow.executable.id": 518,                               |       |                  |             | }                             |                   | }                                                                                                    |           |
|                         |                 |                         |       |          |   "snow.executable.name": "T1",                            |       |                  |             |                               |                   |                                                                                                      |           |
|                         |                 |                         |       |          |   "snow.executable.type": "TASK",                          |       |                  |             |                               |                   |                                                                                                      |           |
|                         |                 |                         |       |          |   "snow.owner.id": 2601,                                   |       |                  |             |                               |                   |                                                                                                      |           |
|                         |                 |                         |       |          |   "snow.owner.name": "DATA_ADMIN",                         |       |                  |             |                               |                   |                                                                                                      |           |
|                         |                 |                         |       |          |   "snow.owner.type": "ROLE",                               |       |                  |             |                               |                   |                                                                                                      |           |
|                         |                 |                         |       |          |   "snow.query.id": "01ba76b5-0107-e56d-0000-a995024f4222", |       |                  |             |                               |                   |                                                                                                      |           |
|                         |                 |                         |       |          |   "snow.schema.id": 411,                                   |       |                  |             |                               |                   |                                                                                                      |           |
|                         |                 |                         |       |          |   "snow.schema.name": "MY_SCHEMA",                      |       |                  |             |                               |                   |                                                                                                      |              |
|                         |                 |                         |       |          |   "snow.warehouse.id": 41,                                 |       |                  |             |                               |                   |                                                                                                      |           |
|                         |                 |                         |       |          |   "snow.warehouse.name": "INTAKE_WAREHOUSE"                |       |                  |             |                               |                   |                                                                                                      |           |
|                         |                 |                         |       |          | }                                                          |       |                  |             |                               |                   |                                                                                                      |           |
+-------------------------+-----------------+-------------------------+-------+----------+------------------------------------------------------------+-------+------------------+-------------+-------------------------------+-------------------+------------------------------------------------------------------------------------------------------+-----------+

Informações registradas para eventos de tarefas¶

Quando uma tarefa é executada, um evento é registrado na tabela de eventos. As seções a seguir descrevem a linha da tabela de eventos que representa o evento:

Valores da coluna da tabela de eventos
Pares chave-valor na coluna resource_attributes
Pares chave-valor na coluna record

Valores da coluna da tabela de eventos¶

Quando uma tarefa é concluída ou falha, uma linha com os seguintes valores é inserida na tabela de eventos.

Nota

Se uma coluna não estiver listada abaixo, o valor da coluna será NULL para o evento.


Coluna	Tipo de dados	Descrição
`timestamp`	TIMESTAMP_NTZ	O carimbo de data/hora UTC em que um evento foi criado.
`observed_timestamp`	TIMESTAMP_NTZ	Uma hora UTC usada para registros. Atualmente, esse é o mesmo valor que está na coluna `timestamp`.
`resource_attributes`	OBJECT	Atributos que identificam a tarefa que foi executada.
`record_type`	STRING	O tipo de evento, que é `EVENT` para execuções de tarefas.
`record`	OBJECT	Detalhes sobre o status da execução da tarefa.
`value`	VARIANT	O status da execução da tarefa e, se a execução falhar, a mensagem de erro da falha.

Pares chave-valor na coluna `resource_attributes`¶

A coluna resource_attributes contém um valor OBJECT com os seguintes pares chave-valor:


Nome de atributo	Tipo de atributo	Descrição	Exemplo
`snow.database.id`	INTEGER	O identificador interno/gerado pelo sistema do banco de dados que contém a tarefa.	`12345`
`snow.database.name`	VARCHAR	O nome do banco de dados que contém a tarefa.	`MY_DATABASE`
`snow.executable.id`	INTEGER	O identificador interno/gerado pelo sistema da tarefa que foi executada.	`12345`
`snow.executable.name`	VARCHAR	O nome da tarefa que foi executada.	`MY_TASK`
`snow.executable.type`	VARCHAR	O tipo do objeto. O valor é `TASK` para eventos de tarefas.	`TASK`
`snow.owner.id`	INTEGER	O identificador interno/gerado pelo sistema da função com o privilégio OWNERSHIP na tarefa.	`12345`
`snow.owner.name`	VARCHAR	O nome da função com o privilégio OWNERSHIP na tarefa.	`MY_ROLE`
`snow.owner.type`	VARCHAR	O tipo de função que possui o objeto, por exemplo `ROLE`. . Se um Snowflake Native App possui o objeto, o valor é `APPLICATION`. . Snowflake retorna NULL se você excluir o objeto porque um objeto excluído não tem uma função de proprietário.	`ROLE`
`snow.query.id`	VARCHAR	ID da consulta que executou a tarefa.	`01ba7614-0107-e56c-0000-a995024f304a`
`snow.schema.id`	INTEGER	O identificador interno/gerado pelo sistema do esquema que contém a tarefa.	`12345`
`snow.schema.name`	VARCHAR	O nome do esquema que contém a tarefa.	`MY_SCHEMA`
`snow.warehouse.id`	INTEGER	O identificador interno/gerado pelo sistema do warehouse usado para executar a tarefa.	`12345`
`snow.warehouse.name`	VARCHAR	O nome do warehouse usado para executar a tarefa.	`MY_WAREHOUSE`

Pares chave-valor na coluna `record`¶

A coluna record contém um valor OBJECT com os seguintes pares chave-valor:


Chave	Tipo	Descrição	Exemplo
`name`	VARCHAR	O nome do evento. O valor é `execution.status` para execuções de tarefas.	`execution.status`
`severity_text`	VARCHAR	O nível de gravidade do evento, que é um dos seguintes valores: `INFO`: a execução da tarefa foi bem-sucedida. `ERROR`: a execução da tarefa falhou.	`INFO`

Pares chave-valor na coluna `value`¶

A coluna value contém um valor VARIANT com os seguintes pares chave-valor:


Chave	Tipo	Descrição	Exemplo
`state`	VARCHAR	O estado da execução da tarefa, que pode ser um dos seguintes valores: `SUCCEEDED`: a execução da tarefa foi bem-sucedida. `ERROR`: a execução da tarefa falhou.	`SUCCEEDED`
`message`	VARCHAR	Se o valor em `state` for `ERROR`, essa coluna incluirá a mensagem de erro.

Monitor events for task executions¶

Limitações¶

Defina o nível de gravidade dos eventos a serem capturados¶

Configurar um alerta sobre novos dados para eventos de conclusão de tarefas¶

Consultar a tabela de eventos para eventos de conclusão de tarefas¶

Informações registradas para eventos de tarefas¶

Valores da coluna da tabela de eventos¶

Pares chave-valor na coluna resource_attributes¶

Pares chave-valor na coluna record¶

Pares chave-valor na coluna value¶

Pares chave-valor na coluna `resource_attributes`¶

Pares chave-valor na coluna `record`¶

Pares chave-valor na coluna `value`¶