Setting Up Logging and Event Sharing for an Application

Snowflake logo in black (no text) Preview Feature — Open

Available to accounts in all non-government AWS regions. For details on other supported cloud platforms contact your Snowflake representative.

This topic describes how to set up logging and event sharing to troubleshoot an installed application.

This topic provides information on setting up logging and event sharing as a provider. Refer to Enabling Logging and Event Sharing for an Application for the consumer requirements for configuring this feature.

Logging and trace events allow you to collect information about an application to troubleshoot errors. Using logging and trace events, you can also get a better idea of how your application runs and improve your application later.

Workflow for Setting Up Logging and Event Sharing as a Provider

As a provider, you can set up logging and event sharing for an application by performing the following:

  1. Review the considerations for using logging and event sharing.

  2. Configure logging and trace events for functions and stored procedures.

  3. Set the log and trace level in the manifest file.

  4. Configure an account to store shared events.

After the consumer installs an application and enables logging and event sharing, you can view logging and event information shared by the installed application:

Considerations for Using Logging and Event Sharing

Before using logging and event sharing for an application, you must consider the following:

  • You are responsible for all costs associated with event sharing on the provider side, including data ingestion and storage.

  • You must have an account to store shared events in each region where you want to support event sharing.

  • You must define the default log level and trace level for an application in the manifest file.

Configuring Logging and Trace Events In Functions and Procedures

The Native Apps Framework requires an event table to store log messages and trace events generated from functions and stored procedures in an application.

Note

If the consumer of your application does not set up an event table and make it the active table before installing the application, event and logging data are discarded.

An account can have multiple event tables, but only one of them can be set as the active event table for a Snowflake account at a time. Without an active event table, log messages and trace events generated by the application are not captured. This is true even if the functions and procedures in an application call the logging and trace event APIs.

To create an event table, use the CREATE EVENT TABLE command. For more information, refer to Setting up an Event Table.

After code has recorded log messages and trace events, you can query recorded data.

For information about recording and querying log and trace data, refer to the following:

Setting the Log and Trace Level in the Manifest File

To set the default log and trace event levels for a version of an application, set the log_level and trace_level parameters in the manifest file as shown in the following example:

artifacts:
  setup_script: setup.sql
configuration:
  trace_level: OFF
  log_level: DEBUG
Copy

When a provider enables tracing, a Snowflake Native App automatically captures the start and end times for all queries and stored procedure calls.

Note

Publishing a Snowflake Native App with the trace_level property set to a value other than OFF might expose calls to hidden stored procedures to any user in the consumer account who can view the event table.

See Setting Trace Level and Setting Log Level for information on supported values for trace_level and log_level.

When the Snowflake Native App is initially installed, it uses the log levels defined in the manifest file. If the log level is changed in a subsequent upgrade, the new log level takes effect after the upgrade process completes.

The log and trace level can only be set within the manifest file. The consumer is not allowed to modify the log level using the ALTER APPLICATION or ALTER DATABASE commands.

Similarly, any session level settings for the logging level are ignored by the application.

Configuring an Account to Store Shared Events

To store logs and shared events, you must select an account to hold an event table. This can be any account that a provider can access. However, if your organization has multiple providers publishing application packages, consider using a Snowflake account dedicated to store shared events from the consumer.

The following restrictions apply to the shared events account:

  • You must use the ORGADMIN role to set an account as the events account.

  • The account must have an active event table.

  • The specified account cannot be any of the following:

    • A locked or suspended account.

    • A reader account.

    • A trial account.

    • A Snowflake managed account.

Note

You can collect logs and shared events only in the same region where a consumer installs an application. Therefore, you must set up an account to store shared events in every region where consumers configure event sharing for an application.

Setting an Account as the Events Account

To set an account to be the events account for a region, call the SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION system function:

CALL SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION('<snowflake_region>', '<region_group>', '<account_name>')
Copy

Where:

snowflake_region

Specifies the region where the account is located, for example: AWS_US_WEST_2, AWS_US_EAST_1.

region_group

Specifies the region group, for example: PUBLIC. Refer to Region Groups for details.

account_name

Specifies the account name. If another account is already set as the events account in the specified region, running this command changes the events account to be the account specified here.

Un-setting an Account as the Events Account

To unset an account to be the events account for a region, call the SYSTEM$UNSET_EVENT_SHARING_ACCOUNT_FOR_REGION system function:

CALL SYSTEM$UNSET_EVENT_SHARING_ACCOUNT_FOR_REGION('<snowflake_region>', '<region_group>', '<account_name>')
Copy

Where:

snowflake_region

Specifies the region where the account is located, for example: AWS_US_WEST_2, AWS_US_EAST_1.

region_group

Specifies the region group, for example: PUBLIC.

account_name

Specifies the account name.

Viewing Event Accounts in the Provider’s Organization

To show events accounts in a provider’s organization, call the SYSTEM$SHOW_EVENT_SHARING_ACCOUNTS system function:

CALL SYSTEM$SHOW_EVENT_SHARING_ACCOUNTS()
Copy

Note

You must use the ORGADMIN role to call this function.

This system function returns a string in JSON format containing a list of event accounts within the organization. Because the metadata takes some time to propagate to all regions, this function might experience some delay when showing latest events account after the user set/unset an events account for the organization.

Viewing the Logging and Trace Event Levels Defined in an Application Package

Use the DESCRIBE APPLICATION command to view the logging level of an installed application, as shown in the following command:

DESC APPLICATION HelloSnowflake;
Copy

Use the SHOW VERSIONS command to view the logging level the application versions defined in an application package, as shown in the following example:

SHOW VERSIONS
  IN APPLICATION PACKAGE HelloSnowflake;
Copy

Viewing the Logs and Events in the Event Table

To view the logs and events stored in the event table, use the SELECT command as shown in the following example:

SELECT * FROM EVENT_DB.EVENT_SCHEMA.MY_EVENT_TABLE
Copy

Shared Event Information Available to the Provider

The following sections describe the information that the Native Apps Framework shares with providers.

Application Event Context Shared with the Provider

To help providers easily identify the source of the shared events, the following fields are populated into the RESOURCE_ATTRIBUTES column of the event table when they are shared with the provider:

  • snow.application.package.name

  • snow.application.consumer.organization

  • snow.application.consumer.name

  • snow.listing.name

  • snow.listing.global_name

Fields That Are Not Shared with the Provider

To protect consumer information, the following fields from the RESOURCE_ATTRIBUTES column are not shared with provider:

  • snow.database.id

  • snow.database.name

  • snow.schema.id

  • snow.executable.id

  • snow.owner.name

  • snow.owner.id

  • snow.warehouse.name

  • snow.warehouse.id

  • snow.query.id

  • snow.session.id

  • snow.session.role.primary.name

  • snow.session.role.primary.id

  • snow.user.name

  • snow.user.id

  • db.user

Instead of directly sharing the snow.database.name and snow.query.id fields with the provider, Snowflake shares the hash values (SHA-1) of these two fields as the following fields:

  • snow.database.hash

  • snow.query.hash

Snowflake provides the SHA-1 function used to mask these attributes. Consumers can calculate the hash values for the database name and query id, and use them as reference values when contacting the provider.

Language: English