Event table overview¶

(Preview version of Event table overview)

As your Snowflake objects — including procedures and UDFs — emit telemetry data, Snowflake collects the data in an event table whose data is available for queries. Snowflake includes an event table by default, but you can also create a new one.

To collect telemetry data, you must have an active event table and have set telemetry levels to allow data collection. If you don’t already have an active event table, Snowflake makes the default event table the active event table.

When collecting telemetry data, you incur costs. To understand these costs — or to reduce or avoid these costs — see Costs of telemetry data collection.

What is an event table?¶

An event table is a special kind of database table with a predefined set of columns. The table’s structure supports the data model for OpenTelemetry, a framework for handling telemetry data. When an event table is active, Snowflake collects telemetry data in the table — including data that Snowflake itself generates and data that you emit by instrumenting your handler code using certain APIs. You can view the collected data by executing SQL queries.

After installation, Snowflake includes a default event table called SNOWFLAKE.TELEMETRY.EVENTS. This event table is active and collects data until you deactivate it. You can also create your own.

To collect telemetry data, you must have an active event table. For more information, see Associate the event table with an object.

Default event table¶

By default, Snowflake includes a default event table named SNOWFLAKE.TELEMETRY.EVENTS. You can use this event table instead of creating your own. If you do not already have an active event table, Snowflake makes the default table the active event table.

By default, Snowflake also includes a predefined view called SNOWFLAKE.TELEMETRY.EVENTS_VIEW view, with which you more securely make event table data available to a range of users. You can manage access to the view with a row access policy.

Note

The default event table supports only a subset of DDL commands supported for event tables you create or for regular tables. For more information, see Working with event tables.

Roles for access to the default event table and EVENTS_VIEW¶

Snowflake includes the following predefined application roles you can use to manage access to the default event table and EVENTS_VIEW view.

EVENTS_VIEWER:

Role with privileges to execute a SELECT statement on the EVENTS_VIEW view.

EVENTS_ADMIN:

Role with the following privileges:

SELECT, TRUNCATE, DELETE on the default event table.
SELECT on the EVENTS_VIEW view of the default event table.
USAGE on the following stored procedures:
- ADD_ROW_ACCESS_POLICY_ON_EVENTS_VIEW
- DROP_ROW_ACCESS_POLICY_ON_EVENTS_VIEW
This role also has privileges to execute a stored procedure to apply a row access policy (RAP) on the EVENTS_VIEW view whose data is based on the default event table.

Managing access to EVENTS_VIEW¶

You can manage access to data in the EVENTS_VIEW view with row access policies. Snowflake provides stored procedures you can use to add and remove a row access policy to the EVENT_VIEW view.

ADD_ROW_ACCESS_POLICY_ON_EVENTS_VIEW(VARCHAR, ARRAY) — Binds a row access policy to the specified columns in the EVENTS_VIEW.
DROP_ROW_ACCESS_POLICY_ON_EVENTS_VIEW(VARCHAR) — Deletes the specified row access policy bound to the EVENTS_VIEW.

Note

You must have the EVENTS_ADMIN role to execute these procedures.

Using row access policies on the EVENT_VIEW view is an Enterprise Edition feature.

Create an event table¶

To create an event table for capturing log and trace event data, execute the CREATE EVENT TABLE command and specify a name for the event table. You will use the event table name later to enable the table to capture log and trace data produced by stored procedures, UDFs, and UDTFs.

Note that when you create an event table, you do not specify the columns in the table. An event table already has a set of predefined columns, as described in Event table columns.

You must use a role that is granted the CREATE EVENT TABLE privilege.

Note

Replication of event tables is not currently supported. Any event tables that are contained in primary databases are skipped during replication.

For example, to create an event table with the name my_events, execute the following statement:

CREATE EVENT TABLE my_database.my_schema.my_events;

Copy

Associate the event table with an object¶

To capture of telemetry data, you must specify the object on which the event table is active. This specifies the scope of objects from which Snowflake captures telemetry data.

The following table lists the objects with which you can associate an event, along with the privileges required to make the association.

Object	Privileges required	Scope of objects whose data is collected
Account	ACCOUNTADMIN role. OWNERSHIP or INSERT privileges for the event table.	Procedures and UDFs in the account.
Database	ACCOUNTADMIN role. OWNERSHIP or INSERT privileges for the event table.	Procedures and UDFs in the specified database.
Native app	ACCOUNTADMIN role. OWNERSHIP or INSERT privileges for the event table.	Procedures and UDFs in the specified native app.

For example, if you associate telemetry_database.telemetry_schema.my_events as the event table for the my_database database, Snowflake will (depending on how you’ve specified telemetry levels), capture telemetry data for procedures and UDFs in my_database in the telemetry_database.telemetry_schema.my_events event table.

Note

If you haven’t created an event table, Snowflake uses the default event table to collect telemetry data.

An order of precedence determines which event table is used to collect telemetry data for an object. In that precedence order, an event table associated with a database or application takes precedence over an event table associated with an account.

Account » Database
Account » Application

In other words, if you have event tables associated with both your account and a database my_database, telemetry data generated by objects in my_database will be collected in the database’s event table. For other databases in the account that don’t have an associated event table, telemetry data will be collected in the event table associated with the account.

For the broadest scope, associate an event table with the account itself.

Setting the active event table¶

To specify the object for which an event table is active, execute the ALTER <object> command on the object, setting the EVENT_TABLE parameter to the name of your event table.

Setting the event table for the account¶

Note

To execute this command, you must use the ACCOUNTADMIN role.

In addition, you must have both of the following privileges:

OWNERSHIP privilege for the account.
OWNERSHIP or INSERT privileges for the event table.

See the documentation on the ALTER ACCOUNT command for more information on the privileges needed to execute ALTER ACCOUNT.

For example, to set up the event table named my_events in the schema my_schema in the database my_database as the active event table for your account, execute the following statement:

ALTER ACCOUNT SET EVENT_TABLE = my_database.my_schema.my_events;

Copy

As shown above, you must specify the fully-qualified name of the event table.

To disassociate an event table from an account, execute the ALTER ACCOUNT command and unset the EVENT_TABLE parameter. For example:

ALTER ACCOUNT UNSET EVENT_TABLE;

Copy

You can confirm the EVENT_TABLE value with the SHOW PARAMETERS command:

SHOW PARAMETERS LIKE 'event_table' IN ACCOUNT;

Copy

Setting the event table for a database¶

To set up the event table named my_events in the schema my_schema in the database my_database as the active event table for the database my_database, execute the following statement:

ALTER DATABASE my_database SET EVENT_TABLE = my_database.my_schema.my_events;

Copy

To disassociate an event table from a database, execute the ALTER ACCOUNT command and unset the EVENT_TABLE parameter. For example:

ALTER DATABASE my_database UNSET EVENT_TABLE;

Copy

You can confirm the EVENT_TABLE value with the SHOW PARAMETERS command:

SHOW PARAMETERS LIKE 'event_table' IN DATABASE my_database;

Copy

Set the level for log and trace events¶

You can manage the level of log and trace event data stored in the event table by setting the log or trace level. Before logging or tracing, use these settings to make sure you’re capturing the amount and kind of data you want.

For more information, see Setting levels for logging, metrics, and tracing.

ALTER DATABASE¶

(Preview excerpt from ALTER DATABASE)

Modifies the properties for an existing database.

Database modifications include the following:

Changing the name of the database or changing the Time Travel data retention period (if you are using Snowflake Enterprise Edition or higher).
Enabling and managing database replication and failover.

Syntax¶

ALTER DATABASE [ IF EXISTS ] <name> RENAME TO <new_db_name>

ALTER DATABASE [ IF EXISTS ] <name> SWAP WITH <target_db_name>

ALTER DATABASE [ IF EXISTS ] <name> SET [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
                                        [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
                                        [ EXTERNAL_VOLUME = <external_volume_name> ]
                                        [ CATALOG = <catalog_integration_name> ]
                                        [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
                                        [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
                                        [ LOG_LEVEL = '<log_level>' ]
                                        [ TRACE_LEVEL = '<trace_level>' ]
                                        [ STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED } ]
                                        [ EVENT_TABLE = <event_table_name> ]
                                        [ COMMENT = '<string_literal>' ]

ALTER DATABASE <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER DATABASE <name> UNSET TAG <tag_name> [ , <tag_name> ... ]

ALTER DATABASE [ IF EXISTS ] <name> UNSET { DATA_RETENTION_TIME_IN_DAYS         |
                                            MAX_DATA_EXTENSION_TIME_IN_DAYS     |
                                            EXTERNAL_VOLUME                     |
                                            CATALOG                             |
                                            DEFAULT_DDL_COLLATION               |
                                            STORAGE_SERIALIZATION_POLICY        |
                                            EVENT_TABLE = <event_table_name>    |
                                            COMMENT
                                          }
                                          [ , ... ]

Copy

Parameters¶

EVENT_TABLE = event_table_name
Specifies the fully-qualified name of the event table that should collect telemetry data from objects in the database, such as procedures and UDFs.

For more information, see Associate the event table with an object.

Associating an event table with a database is available in Enterprise Edition or higher.

ALTER APPLICATION¶

(Preview excerpt from ALTER APPLICATION)

Modifies the properties of an installed Snowflake Native App. Use ALTER APPLICATION to upgrade an app to a specific version or patch. This command also sets other properties for an app.

Syntax¶

ALTER APPLICATION [ IF EXISTS ] <name> SET
  [ COMMENT = '<string-literal>' ]
  [ SHARE_EVENTS_WITH_PROVIDER = { TRUE | FALSE } ]
  [ EVENT_TABLE = <event_table_name> ]
  [ DEBUG_MODE = { TRUE | FALSE } ]

ALTER APPLICATION [ IF EXISTS ] <name> UNSET
  [ COMMENT ]
  [ EVENT_TABLE ]
  [ DEBUG_MODE ]

Copy

Parameters¶

EVENT_TABLE = event_table_name
Specifies the fully-qualified name of the event table that should collect telemetry data from objects in the application, such as procedures and UDFs.

For more information, see Associate the event table with an object.

Associating an event table with an application is available in Enterprise Edition or higher.

Parameters¶

(Preview excerpt from Parameters)

Snowflake provides parameters that let you control the behavior of your account, individual user sessions, and objects. All the parameters have default values, which can be set and then overridden at different levels depending on the parameter type (account, session, or object).

EVENT_TABLE¶

Type:

Account — Can be set for Account

Type:

Object — Can be set for Account » Database and Account » Application (in Enterprise Edition or higher.)

Data Type:

String

Description:

Specifies the name of the event table for logging messages from stored procedures and UDFs contained by the object with which the event table is associated.

Associating an event table with an application or database is available in Enterprise Edition or higher.

Values:

Any existing event table created by executing the CREATE EVENT TABLE command.

Default:

None