Monitoramento de eventos para o Snowpipe¶

Você pode configurar o Snowflake para registrar eventos que fornecem informações detalhadas sobre o status de seus canais. Esses eventos são capturados na tabela de eventos ativa associada ao canal.

Ao monitorar esses eventos, você pode obter insights sobre as seguintes áreas:

Mudanças no status do canal: rastreie o estado operacional de seus Snowpipe.
Progresso do processamento de arquivos: entenda a jornada dos arquivos através do sistema Snowpipe.
Resumo de estatísticas de ingestão periódicas, agregadas: obtenha estatísticas resumidas sobre a ingestão de dados.

Além disso, você pode configurar alertas para as seguintes condições críticas:

Alto volume de arquivos recebidos
Latências de ingestão altas
Erros de canal
Erros de arquivo

The following sections explain how to enable event logging for Snowpipe, configure the severity level for log events, and interpret the events recorded in the event table:

Tipos de eventos Snowpipe: saiba mais sobre as diferentes categorias de eventos e seus detalhes.
Defina o nível de gravidade dos eventos a serem capturados: configure quais eventos são registrados com base em sua importância.
Consulte a tabela de evento para eventos do Snowpipe: descubra como recuperar e analisar dados de eventos.
Informações registradas para eventos Snowpipe: entenda a estrutura e o significado dos dados dentro das colunas da tabela de eventos.

Cuidado

Os eventos de registro em log do Snowpipe incorrem em custos. Para obter mais informações, consulte Custos da coleta de dados de telemetria.

Tipos de eventos do Snowpipe¶

Os eventos do Snowpipe são identificados pelo atributo name dentro da coluna RECORD de sua tabela de eventos.

file_lifecycle¶

Os eventos file_lifecycle rastreiam a jornada de um arquivo através do sistema Snowpipe. O estado de um arquivo pode ser RECEIVED, INGESTED ou ERRORED.

RECEIVED: um evento é emitido quando o Snowpipe recebe uma solicitação de arquivo. O canal pode ignorar esse arquivo se tiver sido processado anteriormente; nesses casos, o atributo skipped indica isso.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "file_lifecycle",
    "severity_text": "DEBUG"
  },
  "RECORD_ATTRIBUTES": {
    "snow.file.path": "<a/path/to/a/file>"
  },
  "VALUE": {
    "notification_channel": "<notification_channel>",
    "file_content_key": "<file_content_key>",
    "last_modified_time": "<last_modified_time>",
    "state": "<received_or_skipped>"
  }
}

INGESTED: um evento é emitido depois que o arquivo é ingerido com sucesso pelo Snowpipe.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "file_lifecycle",
    "severity_text": "DEBUG"
  },
  "RECORD_ATTRIBUTES": {
    "snow.file.path": "<a/path/to/a/file>"
  },
  "VALUE": {
    "notification_channel": "<notification_channel>",
    "file_content_key": "<file_content_key>",
    "state": "ingested"
  }
}

ERRORED: um evento é emitido se o arquivo não for ingerido pelo Snowpipe.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "file_lifecycle",
    "severity_text": "ERROR"
  },
  "RECORD_ATTRIBUTES": {
    "snow.file.path": "<a/path/to/a/file>"
  },
  "VALUE": {
    "notification_channel": "<notification_channel>",
    "file_content_key": "<file_content_key>",
    "first_error_message": "<first_error_message>",
    "first_error_line_number": "<some_number>",
    "first_error_character_pos": "<some_character_pos>",
    "error_count": "<error_count>",
    "error_limit": "<error_limit>",
    "file_state": "FAILED"
  }
}

notification_received¶

Este evento é emitido quando o Snowflake recebe uma mensagem de notificação.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "notification_channel_name": "<notification_channel_name>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "notification_received",
    "severity_text": "TRACE"
  },
  "VALUE": {
    "file_path": "<a/path/to/a/file>",
    "file_content_key": "<file_content_key>",
    "upstream_event_time": "<upstream_event_time>"
  }
}

notification_channel_errored¶

Este evento é emitido quando um erro ocorre enquanto o Snowflake está lendo mensagens de um canal de notificação. Isso normalmente indica um erro de configuração do usuário, como um problema de autorização.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "notification_channel_name": "<notification_channel_name>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "notification_channel_errored",
    "severity_text": "ERROR"
  },
  "VALUE": {
    "first_error_message": "<error_message>"
  }
}

pipe_lifecycle¶

Este evento é emitido quando o status de um canal muda. O novo status pode ser RUNNING, PAUSED, STOPPED ou STALLED.

Para os status de canal RUNNING ou PAUSED:

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "pipe_lifecycle",
    "severity_text": "INFO"
  },
  "VALUE": {
    "state": "<running_or_paused>"
  }
}

Para os status de canal STOPPED_* ou STALLED_*: esses status indicam que um canal parou inesperadamente o processamento de arquivos.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "pipe_lifecycle",
    "severity_text": "<WARN_or_ERROR>"
  },
  "VALUE": {
    "state": "<pipe_status>",
    "error_message": "<error_message>"
  }
}

Os estados severity_text para STOPPED_* ou STALLED_* dependem do motivo específico:

WARN se o canal parou por causa das seguintes razões:

STOPPED_BY_SNOWFLAKE_ADMIN
STOPPED_CLONED
STOPPED_FEATURE_DISABLED

ERROR se o canal parou por causa das seguintes razões:

STOPPED_STAGE_ALTERED
STOPPED_STAGE_DROPPED
STOPPED_FILE_FORMAT_DROPPED
STOPPED_NOTIFICATION_INTEGRATION_DROPPED
STOPPED_MISSING_PIPE
STOPPED_MISSING_TABLE
STALLED_COMPILATION_ERROR
STALLED_INITIALIZATION_ERROR
STALLED_EXECUTION_ERROR
STALLED_INTERNAL_ERROR
STALLED_STAGE_PERMISSION_ERROR

pipe_throttled¶

Este evento é emitido se um Snowpipe for limitado.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "pipe_throttled",
    "severity_text": "WARN"
  },
  "VALUE": {
    "throttled_files": "<throttled_file_name_list>"
  }
}

Definição do nível de gravidade dos eventos a serem capturados¶

To enable Snowpipe events to be recorded in an event table, you must set the LOG_EVENT_LEVEL parameter at either the pipe level or the account level. LOG_EVENT_LEVEL determines which log events are captured based on their severity. For more information, see Parâmetros and New LOG_EVENT_LEVEL parameter to control events.

ERROR: use para eventos que sinalizam uma mudança que requer intervenção humana para ser resolvida.
WARN: use para eventos que sinalizam um problema que pode ser resolvido sem intervenção humana.
INFO: use para eventos iniciados pelo usuário que são geralmente úteis e não são eventos de alto volume.
DEBUG: use para eventos de alto volume.
TRACE: o nível mais baixo de registro em log, que captura informações muito detalhadas.

Cuidado

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

Exemplos:

Para capturar eventos em nível de ERROR para todos os objetos em uma conta, execute o seguinte código:

ALTER ACCOUNT <my_account_name> SET LOG_EVENT_LEVEL = ERROR;

Para capturar eventos em nível de INFO para um canal específico, execute o seguinte código:

ALTER PIPE <my_pipe_name> SET LOG_EVENT_LEVEL = INFO;

Severity level for each event type¶

The following table summarizes the default or recommended severity for each Snowpipe event type when you use LOG_EVENT_LEVEL:


Evento	Severity
file_lifecycle - RECEIVED, INGESTED	DEBUG
file_lifecycle - ERRORED	ERROR
notification_received	TRACE
notification_channel_errored	ERROR
pipe_lifecycle - RUNNING, PAUSED	INFO
pipe_lifecycle - STOPPED	WARN ou ERROR (consulte a seção a seguir)
pipe_throttled	WARN

pipe_lifecycle - STOPPED severity details:

WARN se o canal parou por causa das seguintes razões:

STOPPED_BY_SNOWFLAKE_ADMIN
STOPPED_CLONED
STOPPED_FEATURE_DISABLED

ERROR se o canal parou por causa das seguintes razões:

STOPPED_STAGE_ALTERED
STOPPED_STAGE_DROPPED
STOPPED_FILE_FORMAT_DROPPED
STOPPED_NOTIFICATION_INTEGRATION_DROPPED
STOPPED_MISSING_PIPE
STOPPED_MISSING_TABLE
STALLED_COMPILATION_ERROR
STALLED_INITIALIZATION_ERROR
STALLED_EXECUTION_ERROR
STALLED_INTERNAL_ERROR
STALLED_STAGE_PERMISSION_ERROR

Consulta de eventos do Snowpipe na tabela de eventos¶

Antes de consultar, certifique-se de ter configurado uma tabela de eventos e configurado o nível de gravidade desejado para os eventos a serem capturados.

O exemplo de consulta a seguir mostra como recuperar eventos do Snowpipe, como os gerados durante a ingestão de arquivos:

SELECT
    record_type,
    record:"name" AS event_name,
    record:"severity_text" AS log_level,
    resource_attributes:"snow.database.name" AS database_name,
    resource_attributes:"snow.schema.name" AS schema_name,
    resource_attributes:"snow.pipe.name" AS pipe_name,
    record_attributes,
    PARSE_JSON(value):file_content_key AS file_content_key,
    PARSE_JSON(value):state AS state
FROM {my_event_table_name}
ORDER BY state;

Exemplo de saída (ingestão de arquivo bem-sucedida):

A saída a seguir mostra os eventos RECEIVED e INGESTED de um arquivo, o que indica processamento bem-sucedido:


SCOPE	RECORD_TYPE	EVENT_NAME	LOG_LEVEL	DATABASE_NAME	SCHEMA_NAME	PIPE_NAME	RECORD_ATTRIBUTES	FILE_CONTENT_KEY	STATE
[NULL]	EVENT	«file_lifecycle»	«DEBUG»	«TESTDB»	«TESTSH»	«MYPIPE»	{ «snow.file.path»: «data_0_0_0.event» }	«ba1f2511fc30423bdbb183fe33f3dd0f»	«INGESTED»
[NULL]	EVENT	«file_lifecycle»	«DEBUG»	«TESTDB»	«TESTSH»	«MYPIPE»	{ «snow.file.path»: «data_0_0_0.event» }	«ba1f2511fc30423bdbb183fe33f3dd0f»	«RECEIVED»

Informações registradas em log para eventos do Snowpipe¶

As seções a seguir descrevem as colunas-chave e seu conteúdo dentro da tabela de eventos para eventos do Snowpipe. Se uma coluna não estiver explicitamente listada nas seções a seguir, seu valor será NULL para eventos do Snowpipe.

Valores da coluna da tabela de eventos¶


Coluna	Tipo de dados	Descrição
timestamp	TIMESTAMP_NTZ	O carimbo de data/hora no formato UTC em que o evento foi criado.
resource_attributes	OBJECT	Atributos que identificam o evento do Snowpipe, como nomes de banco de dados, esquema e canal.
record_type	STRING	O tipo de evento registrado. Para eventos do Snowpipe, este valor é sempre EVENT.
record	OBJECT	Contém informações detalhadas sobre o status da execução do evento do Snowpipe, incluindo nome e severity_text.
value	VARIANT	Informações adicionais específicas do evento do Snowpipe. Se a tarefa do Snowpipe falhou, isto inclui a mensagem de erro.

Pares de chave-valor na coluna resource_attributes¶

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


Nome do atributo	Tipo de atributo	Descrição	Exemplo
snow.database.name	VARCHAR	O nome do banco de dados associado ao canal.	«MY_DATABASE»
snow.schema.name	VARCHAR	O nome do esquema associado ao canal.	«MY_SCHEMA_NAME»
snow.pipe.name	VARCHAR	O nome do canal.	«MY_PIPE_NAME»
notification_channel_name	VARCHAR	O nome do canal de notificação que recebeu a mensagem ou encontrou um erro.	«arn:aws:sqs:us-west-2:774383465531:sf-snowpipe-AIDA3»

Pares de chave-valor na coluna de registro¶

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


Chave	Tipo	Descrição	Exemplo
nome	VARCHAR	O nome do evento.	«pipe_lifecycle»
severity_text	VARCHAR	O nível de gravidade do evento.	«INFO»