Sign In

UI Event Transactions

We recommend implementing this feature for mobile and desktop SDKs.

UI event transactions aim to capture transactions based on user interactions, such as clicks, scroll events, pinches, etc. The UI events the SDK can hook into might vary depending on the platform. UI event transactions are an expansion to transactions generated automatically by the SDK, which are referred to as auto-generated transactions in this document.

Creating transactions for a single UI event without any spans would be fruitless. Instead, the SDK shall use a UI event as the entry point to a possibly meaningful transaction. It should wait to see if it can add any auto-generated spans to the transaction. If it can, it shall keep and send the transaction. If not, the SDK should discard the empty transaction. A combination of two concepts is needed to implement the wait-and-see logic: idle transactions and wait-for-children. Check out the specification below to see how those two concepts work together with covering multiple edge cases. The following description is drastically simplified:

  • Idle-transactions: The SDK starts an idle timeout for the transaction when starting it. When the transaction or any of its spans starts a new span, it resets the timeout. The SDK finishes the transaction when the timeout succeeds.
  • Wait-for-children: A transaction waits for all its child spans to finish before finishing itself.

Before diving into the specification with all the edge cases, let's look at two simple examples:

  1. The user clicks a button that triggers some requests to the backend and stores data in the local database. The SDK can create a meaningful transaction in that case.
  2. The user clicks a button that solely validates some form data and triggers nothing that the SDK can automatically instrument. The SDK could only create a transaction without any spans, which would be valueless.

Specification

Users can change the idleTimeout via the SDK config options. The default is 3.0 seconds.

The specification is written in the Gherkin syntax.

Copied
Scenario: Starting UI Event transactions
    Given an instrumentable UI event
    Then the SDK starts a UI event transaction 
    And starts the idle timeout with idleTimeout of the options

Scenario: Wait for children when starting span
    Given a UI event transaction
    When the SDK starts a child span
    Then the SDK cancels the idle timeout
    And waits for the child to finish

Scenario: Start timeout when the last span finishes
    Given a UI event transaction
    And the transaction has one or multiple running child spans
    And the transaction is waiting for its children to finish
    When the SDK finishes the last child span
    Then the SDK starts the idle timeout

Scenario: Don't reset timeout when the second last span finishes
    Given a UI event transaction
    And the transaction has two running child spans
    When the SDK finishes the first child span
    Then the SDK doesn't reset the idle timeout
    And waits for the children to finish

Scenario: Discard UI event transactions without child spans
    Given a UI event transaction
    And the transaction has no child spans
    When the idleTimeout times out
    Then the SDK discards the transaction 

Scenario: Set time to last finished child span
    Given a UI event transaction
    And the transaction has one finished child span
    And the transaction has one running child span
    When the running child span finishes
    Then the SDK finishes the transaction
    And trims the end time of the transaction to the one of the last finished
        child span

Scenario: Same UI element with same event
    Given an ongoing UI event transaction
    When the user triggers the same UI event with the same type for the same
        UI element
    Then the SDK resets the timeout
    And doesn't create a new transaction

# If your SDK binds auto-genrated transactions to the scope see binding
# to scope
Scenario: Same UI element with different event
    Given an ongoing UI event transaction
    When the user triggers the same UI element with a different event
    Or the user triggers a different UI element
    Then the SDK finishes the ongoing transaction
    And sets the status to OK
    And waits for the children to finish
    And cancels the timeout
    And starts a new transaction

Binding to scope

On platforms mainly interacting with the static API, such as mobile, it's typical to bind auto-generated transactions to the scope so that users can access them via the static API. We recommend binding UI event transactions to the scope on these platforms. The following extra rules apply as UI event transactions could interfere with other auto-generated transactions.

Copied
Scenario: Same UI element with different event
    Given an ongoing UI event transaction
    When the user triggers the same UI element with a different event
    Or the user triggers a different UI element
    Then the SDK finishes the ongoing transaction
    And sets the status to OK
    And waits for the children to finish
    And cancels the timeout
    And removes the ongoing transaction from the scope
    And starts a new transaction
    And puts the new transaction on the scope

Scenario: UI event triggered but transaction ended
    Given an auto-generated transaction from a any UI event
    And the transaction already  is finished
    When the user triggers the same UI event
    Then the SDK starts a new UI event transaction

Scenario: Manually created transaction bound to the scope
    Given an ongoing manually created transaction by the user bound to the
        scope
    When the SDK creates a new UI event transaction
    Then the SDK doesn't add the UI event transaction to the scope

Screen load transactions

This section deals specifically with auto-generated transactions for loading screens. If your SDK has other types of auto-generated transactions, please update the specification here.

Copied
Scenario: Ongoing UI event transaction
    Given an ongoing UI event transaction
    When the SDK creates a new screen load transaction
    Then the SDK finishes the ongoing UI event transaction
    And removes it from the scope
    And sets the status to canceled
    And waits for its children to finish

Scenario: Ongoing screen load transaction
    Given an ongoing screen load transaction
    When the SDK starts a new UI event transaction
    Then the SDK doesn't bind the new UI event transaction to the scope

Transaction name

The user should be able to identify to which UI element the UI event transaction belongs on which screen by only looking at the transaction name. Choose whatever works best for your specific platform. Be attentive not to use any PII in the transaction name. One recommendation is screen name + view identifier || accessibility identifier. On Android, this would map to LoginActivity.login_button, and on Cocoa, to YourApp.LoginViewController.loginButton.

You can edit this page on GitHub.