Configure event tracing for an app¶
This topic describes how providers can configure event tracing for a Snowflake Native App.
About event tracing in the Snowflake Native App Framework¶
Event tracing allows an app to emit information related to its performance and behavior. The Snowflake Native App Framework supports using the Snowflake logging and tracing functionality to gather this information. An app can emit the following:
Log messages that are independent, detailed messages with information about the state of a specific feature within the app.
Trace events with structured data you can use to get information spanning and grouping multiple parts of an app.
Providers can configure an app to emit events by setting the log and trace levels in the manifest file. See Set the log and trace levels for an app.
Providers can also configure an app to use event sharing to allow the consumer to share the log messages and trace events. See About event sharing for more information.
About event sharing¶
Event sharing allows a provider to configure an app to request that the consumers share the log messages and trace events with the provider. When event sharing is enabled, the log messages and trace events that are inserted into the event table in the consumer account are also inserted into an event table in provider account.
Event sharing allows the provider to collect information about the app’s performance and behavior.
About event definitions¶
Event definitions specify how an app shares log messages and trace events with the provider. Event definitions act as filters on the log message and trace event levels set by the provider. A provider specifies the event definitions for an app when a new app version or patch is published.
Note
Event definitions are optional. If a provider does not specify event definitions for an app consumers can only enable or disable event sharing for all events when the provider enables event tracing.
Mandatory and optional event definitions¶
Providers can set an event definition to be required or optional:
Required event definitions are enabled automatically when the app is installed if the consumer has created an event table.
After installing an app with require event definitions, consumers cannot disable event sharing or the required event definitions. During upgrade, providers can use system functions or the Python Permission SDK to check if the consumer has enabled all required event definitions.
Optional event definitions can be enabled or disable by the consumer as necessary. Optional event definitions require an active event table, but they are not required to install or use the app.
Caution
Event definitions differ from the log and tracing levels set by the provider. Log and tracing levels determine the information that is inserted into the consumer event table. If neither the log or tracing levels are set, then the app does not emit any events.
Event definitions are filters that act on the log messages and trace events. They determine what information is inserted in the provider event table when event sharing is enabled.
Supported event definitions¶
The following table lists currently supported event definitions.
Type
Name
Description
Filter
All
SNOWFLAKE$ALL
Shares all log messages and trace events that the app emits.
*
Errors and warnings
SNOWFLAKE$ERRORS_AND_WARNINGS
Shares logs related to errors, warnings, and fatal events.
RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘FATAL’, ‘ERROR’, ‘WARN’)
Traces
SNOWFLAKE$TRACES
Shares detailed traces of user activities and journeys in the app.
RECORD_TYPE in (‘SPAN’, ‘SPAN_EVENT’)
Usage logs
SNOWFLAKE$USAGE_LOGS
Shares high-level logs related to user actions and app events.
RECORD_TYPE = LOG AND RECORD:severity_text = ‘INFO’
Debug logs
SNOWFLAKE$DEBUG_LOGS
Shares technical logs used to troubleshoot the app.
RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘DEBUG’, ‘TRACE’)
Note
Snowsight only displays events of type All type to the consumer if the provider has not configured the app to use event definitios.
Limitations in apps with containers¶
Snowflake Native Apps with Snowpark Container Services currently only supports the ALL
event definition. Support for additional
event definitions will be added in a future release.
Workflow - Enable event sharing for an app¶
Event sharing allows consumers to share log messages and trace events with the provider.
The following workflow shows how to set up and enable event sharing for an app:
The provider sets the log and trace levels for the app.
The provider adds event definitions top the manifest file.
Event definitions act as filters on the log messages and trace events emitted by the app. Providers can configure event definitions to be required or optional.
The provider sets up an event table in their account.
The provider publishes the app.
When a consumer installs and app, they must set up an event table and enable event sharing. See Enable logging and event sharing for an app for more information on the consumer requirements for event sharing.
Set the log and trace levels for an app¶
To allow an app to use event tracing, a provider must configure the log and trace levels in the manifest file.
To set the log and trace levels for an app, add a configuration
block in the
manifest.yml
file as shown in the following example:
configuration:
...
log_level: INFO
trace_level: ALWAYS
...
This example sets the log and trace levels for the app as follows:
The
log_level
property is set toINFO
The
trace_level
property is set toALWAYS
.
See LOG_LEVEL and TRACE_LEVEL for information on the valid values for these parameters.
Caution
After publishing an app, the log and trace levels cannot be changed. If the log and trace levels are not set in the manifest file, the app does not emit any information.
When the log and trace levels are set for an app, consumers must set up an event table in their account to see the log messages and trace events that the app emits.
To allow the provider to see the log messages and trace events that an app generates, consumers must enable event sharing. See Enable event sharing for an app for more information.
Add an event definition to the manifest file¶
To specify an event definition, a provider adds an entry to the
configuration.telemetry_event_definitions
block of the manifest file as shown in the
following example:
configuration:
telemetry_event_definitions:
- type: ERRORS_AND_WARNINGS
sharing: MANDATORY
- type: DEBUG_LOGS
sharing: OPTIONAL
This example specifies the following event definitions:
A required event definition named
ERRORS_AND_WARNINGS
.An optional event definition named
DEBUG_LOGS
.
See Supported event definitions for more information.
After a consumer install an app, the event definitions appear in the Events and logs tab on the Security page of the app. See Enable logging and event sharing for an app for more information.
Set up an event table in the provider account¶
To collect the log messages and trace events that a consumer shares, a provider must set up an event table by performing the following:
Important
If a provider does not have an event account and active event table inside that account before the consumer installs a app, trace events and log messages are discarded.
Set an account as the events account¶
To store shared logs and 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 accounts 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.
Note
A provider can collect logs and shared events only in the same region where a consumer installs an application. Providers must set up an event account to store shared events in every region where consumers configure event sharing for an application.
To set an account to be the events account for a region, call the SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION system function as shown in the following example:
CALL SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION('<snowflake_region>', '<region_group>', '<account_name>')
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.
Create an event table in the event account¶
To create an event table, run the CREATE EVENT TABLE command as shown in the following example:
CREATE EVENT TABLE event_db.event_schema.my_event_table;
This command specifies the database and schema that contain the event table.
Set the event table as the active event table¶
An account can have multiple event tables, but only one set as the active event table in a Snowflake account at a time. Without an active event table, log messages and trace events that the consumer shares are discarded.
After creating the event table, use the ALTER TABLE (event tables) command to specify that the event table is the active table for the account:
ALTER ACCOUNT SET EVENT_TABLE=event_db.event_schema.my_event_table;
Un-set 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>')
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.
View the event accounts in an 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()
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.
Verify event definitions by using system functions¶
To determine if event sharing is enabled in a consumer account, providers can call the following system functions within the setup script:
SYSTEM$IS_APPLICATION_AUTHORIZED_FOR_TELEMETRY_EVENT_SHARING()
Returns TRUE if the AUTHORIZE_TELEMETRY_EVENT_SHARING property is set, which indicates that event sharing is enabled in the consumer account. Otherwise, this system function returns false.
SYSTEM$IS_APPLICATION_ALL_MANDATORY_TELEMETRY_EVENT_DEFINITIONS_ENABLED()
Returns TRUE if all required event definitions have been enabled in the consumer account. Otherwise, this system function returns false.
Verify event definitions by using the Python Permission SDK¶
The Python Permission SDK provides the following functions to determine if even sharing is enabled in a consumer account:
is_application_authorized_for_telemetry_event_sharing()
Returns TRUE if the AUTHORIZE_TELEMETRY_EVENT_SHARING property is TRUE. Returns FALSE, otherwise.
is_application_all_mandatory_telemetry_event_definitions_enabled()
Returns TRUE if all mandatory event definitions have been enabled in the consumer account.
Considerations when migrating from the existing event sharing functionality¶
When migrating from the existing event sharing functionality to use event definitions, providers should consider the following.
The existing event sharing functionality is equivalent to the OPTIONAL ALL event definition. Published versions and patches of an app that used the existing functionality will have the OPTIONAL ALL event definition by default. Providers do not need to add this event definition to the manifest file.
To begin using event definitions, providers can add supported event definitions to the manifest file. This is applicable to new apps as well as new versions and patches of existing apps.
Note
To being begin requesting more granular log and event sharing, providers only have to add event definitions to the manifest file. No other actions are required for providers.