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

As seções a seguir explicam como habilitar o registro de eventos para o Snowpipe, configurar o nível de registro em log e interpretar os eventos registrados na tabela de eventos:

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>"
  }
}

Copy

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"
  }
}

Copy

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"
  }
}

Copy

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>"
  }
}

Copy

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>"
  }
}

Copy

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>"
  }
}

Copy

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>"
  }
}

Copy

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>"
  }
}

Copy

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

Para permitir que os eventos do Snowpipe sejam registrados em uma tabela de eventos, você deve definir o parâmetro LOG_LEVEL no nível do canal ou no nível da conta. LOG_LEVEL determina quais eventos são capturados com base em sua gravidade:

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_LEVEL = ERROR;

Copy

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_LEVEL = INFO;

Copy

Nível de registro em log para cada tipo de evento¶

A tabela a seguir resume o LOG_LEVEL padrão ou recomendado para cada tipo de evento do Snowpipe:

Evento	Nível de registro
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

Detalhes do nível de registro em log de pipe_lifecycle - STOPPED:

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;

Copy

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»