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:

  1. The provider sets the log and trace levels for the app.

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

  3. The provider sets up an event table in their account.

  4. 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
  ...
Copy

This example sets the log and trace levels for the app as follows:

  • The log_level property is set to INFO

  • The trace_level property is set to ALWAYS.

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
Copy

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:

  1. Set an account as the event account.

  2. Create an event table in the event account.

  3. Set the event table as the active event table in event account.

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>')
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.

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

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

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>')
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.

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()
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.

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.

Language: English