Set up logging and event sharing for an application¶

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:

• View the log and trace level.

• View the logs and events in the event table.

Considerations for using logging and event sharing¶

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

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

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

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

Configure 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.

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, see Setting up an Event Table.

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

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

• Logging Messages from Functions and Procedures.

• Trace Events for Functions and Procedures.

Set 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

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

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.

Configure an account to store shared events¶

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

The following restrictions apply to account used to store shared events:

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

• 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.

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

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

CALL SYSTEM$SHOW_EVENT_SHARING_ACCOUNTS()

View 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;

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;

View 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

Shared event information available to the provider¶

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

Determining if event sharing is enabled in the consumer account¶

In some contexts, a provider may need to determine if event sharing has been enabled in a consumer account. For example, a provider may need to disable app functionality if the event table is not available.

To determine if event sharing is enabled in a consumer account, providers can call the following system functions when defining the app logic:

• IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER

  Returns true if the app enables event sharing and an active event table is available in the consumer account. Returns false, otherwise.

• IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT

  Returns true if the app was installed in the same account as the application package it is based on. Returns false otherwise.

CREATE OR ALTER VERSIONED SCHEMA app_schema;

CREATE OR REPLACE PROCEDURE app_schema.hidden_sum(num1 float, num2 float)
RETURNS FLOAT
LANGUAGE SQL
EXECUTE AS OWNER
AS $$
  DECLARE
    SUM FLOAT;
  BEGIN
    SYSTEM$LOG('INFO', 'CALCULATE THE SUM OF TWO NUMBERS');
    SUM := :NUM1 + :NUM2;
    RETURN SUM;
  END;
$$;