Monitorar eventos para execuções de tarefas¶

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_EVENT_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 de tarefa no nível ERROR para todos os objetos compatíveis na conta, execute ALTER ACCOUNT SET LOG_EVENT_LEVEL:
```
ALTER ACCOUNT SET LOG_EVENT_LEVEL = ERROR;
```
A configuração de LOG_EVENT_LEVEL no nível da conta aplica-se a eventos de log (tipo de registro EVENT) para cargas de trabalho compatíveis na conta, incluindo tarefas. Ela não substitui LOG_LEVEL para mensagens de log de APIs de registro. Para obter mais informações, consulte Parâmetros.
Para capturar eventos de tarefa no nível INFO para todos os objetos compatíveis no banco de dados my_db, execute ALTER DATABASE … SET LOG_EVENT_LEVEL:
```
ALTER DATABASE my_db SET LOG_EVENT_LEVEL = INFO;
```
Semelhante ao caso de definir o nível na conta, a definição do nível no banco de dados afeta os eventos de log dos tipos de objeto compatíveis no banco de dados.
Para capturar eventos no nível ERROR para a tarefa my_task, execute ALTER TASK … SET LOG_EVENT_LEVEL:
```
ALTER TASK my_task SET LOG_EVENT_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.

Monitorar eventos para execuções de tarefas¶

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`¶