From ff51a11dc9e573a15fb09483b172f08780754fbf Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 17 Nov 2022 09:53:13 +0100 Subject: [PATCH 01/20] Add docs for UI event transactions Add specification for UI event transactions with Gherkin syntax. --- src/components/sidebar.tsx | 1 + .../sdk/performance/ui-event-transactions.mdx | 173 ++++++++++++++++++ 2 files changed, 174 insertions(+) create mode 100644 src/docs/sdk/performance/ui-event-transactions.mdx diff --git a/src/components/sidebar.tsx b/src/components/sidebar.tsx index 61bb4e1d2e..0a759170ae 100644 --- a/src/components/sidebar.tsx +++ b/src/components/sidebar.tsx @@ -226,6 +226,7 @@ export default () => { Rate Limiting Span Operations + UI Event Transactions Dynamic Sampling Context OpenTelemetry Support diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx new file mode 100644 index 0000000000..6495f50691 --- /dev/null +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -0,0 +1,173 @@ +--- +title: "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](https://cucumber.io/docs/gherkin/reference/). + +**1. 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 +``` + +**5. 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 +``` + +**4. 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 +``` + +**3. 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 +``` + +**2. 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 +``` + +**3. 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 +``` + +**6. 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 +``` + +**10. Same UI element with different event** +If your SDK binds transactions to the scope see 11. +``` +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 + +**11. 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 +``` + +**11. UI event triggered but transaction ended** +``` +Given an auto-generated transaction from a any event +And the transaction finished +When the user triggers the same event +Then the SDK starts a new transaction +``` + +**6. 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 +``` + +**7. 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 +``` + +**8. Manually created transaction on the scope** +``` +Given an ongoing manually transaction bound to the scope by the user +When the SDK creates a new auto-generated transaction +Then the SDK doesn't add the new auto-generated transaction to the scope +``` + +## Transaction name + +**12. Transaction name** +``` +When the user clicks a button +Then the SDK starts a transaction +And the transaction name is the [[screen.name](http://screen.name/)](http://screen.name) + [[view.id](http://view.id/)](http://view.id) or the accessibility identifier of the view (e.g. `LoginActivity.login_button`) +``` + +**13. Transaction name [[view.id](http://view.id/)](http://view.id) or accessibility identifier not specified** +``` +When the user clicks a button +And the button has no [[view.id](http://view.id/)](http://view.id) or accessibility identifier +Then the SDK doesn't start a transaction +And prints a warning to the console +``` From 09d797b854d9d3b758bd060ec59e388858facf38 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 17 Nov 2022 10:25:01 +0100 Subject: [PATCH 02/20] Gherkin syntax --- .../sdk/performance/ui-event-transactions.mdx | 222 +++++++++--------- 1 file changed, 107 insertions(+), 115 deletions(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 6495f50691..daea23394a 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -27,7 +27,8 @@ Before diving into the specification with all the edge cases, let's look at two 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. +SDK can automatically instrument. The SDK could only create a transaction without any spans, which would +be valueless. # Specification @@ -35,124 +36,115 @@ Users can change the `idleTimeout` via the SDK config options. The default is 3. The specification is written in the [Gherkin syntax](https://cucumber.io/docs/gherkin/reference/). -**1. 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 -``` - -**5. 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 -``` - -**4. 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 -``` - -**3. 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 -``` - -**2. 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 -``` - -**3. 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 -``` - -**6. 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 -``` - -**10. Same UI element with different event** -If your SDK binds transactions to the scope see 11. -``` -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 +```Gherkin +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 -**11. 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 -``` - -**11. UI event triggered but transaction ended** -``` -Given an auto-generated transaction from a any event -And the transaction finished -When the user triggers the same event -Then the SDK starts a new transaction -``` - -**6. 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 -``` - -**7. 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 -``` - -**8. Manually created transaction on the scope** -``` -Given an ongoing manually transaction bound to the scope by the user -When the SDK creates a new auto-generated transaction -Then the SDK doesn't add the new auto-generated transaction to the 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. + +```Gherkin +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. + +```Gherkin +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 From c6c52b08e9159897310b7c31626cb89141f3b9de Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 17 Nov 2022 10:38:20 +0100 Subject: [PATCH 03/20] transaction name --- .../sdk/performance/ui-event-transactions.mdx | 31 ++++++++----------- 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index daea23394a..8ee145d3df 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -74,15 +74,18 @@ Scenario: Set time to last 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 + 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 + 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 +# 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 @@ -121,7 +124,8 @@ Scenario: UI event triggered but transaction ended 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 + 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 ``` @@ -149,17 +153,8 @@ Scenario: Ongoing screen load transaction ## Transaction name -**12. Transaction name** -``` -When the user clicks a button -Then the SDK starts a transaction -And the transaction name is the [[screen.name](http://screen.name/)](http://screen.name) + [[view.id](http://view.id/)](http://view.id) or the accessibility identifier of the view (e.g. `LoginActivity.login_button`) -``` - -**13. Transaction name [[view.id](http://view.id/)](http://view.id) or accessibility identifier not specified** -``` -When the user clicks a button -And the button has no [[view.id](http://view.id/)](http://view.id) or accessibility identifier -Then the SDK doesn't start a transaction -And prints a warning to the console -``` +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`. From ab0582c3be754344046bcdaf38903c712d88009c Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 09:57:31 +0100 Subject: [PATCH 04/20] Update src/docs/sdk/performance/ui-event-transactions.mdx Co-authored-by: Roman Zavarnitsyn --- src/docs/sdk/performance/ui-event-transactions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 8ee145d3df..9b660c851f 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -84,7 +84,7 @@ Scenario: Same UI element with same event 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 +# If your SDK binds auto-generated transactions to the scope see binding # to scope Scenario: Same UI element with different event Given an ongoing UI event transaction From 51773517295a3303df8fa0d6d1b550ecfcfdd455 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 10:04:22 +0100 Subject: [PATCH 05/20] Schedule timer --- src/docs/sdk/performance/ui-event-transactions.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 9b660c851f..9273c81098 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -17,7 +17,7 @@ two concepts is needed to implement the wait-and-see logic: __idle transactions_ __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. +* __Idle-transactions__: The SDK schedule 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. @@ -40,7 +40,7 @@ The specification is written in the [Gherkin syntax](https://cucumber.io/docs/gh 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 + And schedule the idle timeout with idleTimeout of the options Scenario: Wait for children when starting span Given a UI event transaction @@ -48,7 +48,7 @@ Scenario: Wait for children when starting span Then the SDK cancels the idle timeout And waits for the child to finish -Scenario: Start timeout when the last span finishes +Scenario: Schedule 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 From da01a922428a0816730c1efaaa995416d5cc06b7 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 10:11:54 +0100 Subject: [PATCH 06/20] Add don't overwrite existing status --- src/docs/sdk/performance/ui-event-transactions.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 9273c81098..83cf2832b6 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -77,6 +77,13 @@ Scenario: Set time to last finished child span And trims the end time of the transaction to the one of the last finished child span +Scenario: Don't overwrite existing status of UI event transactions + Given a UI event transaction + And the UI event transaction has a status + When the SDK finishes the UI event transaction + Then it keeps the status + And doesn't overwrite it + 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 From 7e75f53067b74c6c89bbaac910d60a294fb9f460 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 10:18:12 +0100 Subject: [PATCH 07/20] schedule fixes --- .../sdk/performance/ui-event-transactions.mdx | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 83cf2832b6..8932ea8daf 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -48,24 +48,17 @@ Scenario: Wait for children when starting span Then the SDK cancels the idle timeout And waits for the child to finish -Scenario: Schedule timeout when the last span finishes +Scenario: Schedule idle 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 + Then the SDK schedules the idle timeout 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 + When the idle timeout times out Then the SDK discards the transaction Scenario: Set time to last finished child span @@ -88,7 +81,7 @@ 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 + Then the SDK reschedule the idle timeout And doesn't create a new transaction # If your SDK binds auto-generated transactions to the scope see binding @@ -100,7 +93,7 @@ Scenario: Same UI element with different event 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 cancels the idle timeout And starts a new transaction ``` @@ -119,7 +112,7 @@ Scenario: Same UI element with different event 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 cancels the idle timeout And removes the ongoing transaction from the scope And starts a new transaction And puts the new transaction on the scope From 985b167ae882126ebb4ec4aab62735aa6a5a6942 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 10:21:52 +0100 Subject: [PATCH 08/20] remove accessibility identifier --- src/docs/sdk/performance/ui-event-transactions.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 8932ea8daf..7d0d23c3ba 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -155,6 +155,8 @@ Scenario: Ongoing screen load transaction 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`. +attentive not to use any PII in the transaction name. One recommendation is +`screen name + view identifier`. On Android, this would map to +`LoginActivity.login_button`, and on Cocoa, to `YourApp.LoginViewController.loginButton`. If the UI element +doesn't have a view identifier, it's acceptable that the SDK doesn't start a UI event transaction and logs +a warning to inform the user. From 66a259c787b391a54cedf07a31b817f8cc96c16c Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 10:23:50 +0100 Subject: [PATCH 09/20] Explain what Cocoa uses as view ID --- src/docs/sdk/performance/ui-event-transactions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 7d0d23c3ba..4e94a683c1 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -159,4 +159,4 @@ attentive not to use any PII in the transaction name. One recommendation is `screen name + view identifier`. On Android, this would map to `LoginActivity.login_button`, and on Cocoa, to `YourApp.LoginViewController.loginButton`. If the UI element doesn't have a view identifier, it's acceptable that the SDK doesn't start a UI event transaction and logs -a warning to inform the user. +a warning to inform the user. The Cocoa SDK uses the method the UI element calls as the view identifier. From 0379e246542d2c9537f5453e9d66de29a761e616 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 10:32:56 +0100 Subject: [PATCH 10/20] manually created transaction bound to scope --- src/docs/sdk/performance/ui-event-transactions.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 4e94a683c1..b6feced672 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -123,11 +123,15 @@ Scenario: UI event triggered but transaction ended When the user triggers the same UI event Then the SDK starts a new UI event transaction +# The SDK adds auto-generated spans to the transaction bound to the scope. +# UI event transactions need auto-generated spans not to be empty. Therefore, +# the SDK can't start a UI event transaction if there is already a +# transaction bound to the scope by the user. 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 + When the user triggers the a UI event + Then the SDK doesn't start a UI event transaction ``` From 5ebf5ebcb8896173200d66d71bf034b443db5540 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 14:44:36 +0100 Subject: [PATCH 11/20] Update src/docs/sdk/performance/ui-event-transactions.mdx Co-authored-by: Roman Zavarnitsyn --- src/docs/sdk/performance/ui-event-transactions.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index b6feced672..123d6bbe0c 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -66,7 +66,8 @@ Scenario: Set time to last finished child span 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 + Then the SDK schedules the idle timeout + And the SDK finishes the transaction after timeout And trims the end time of the transaction to the one of the last finished child span From 6e4ac9d200eb9f3686a361093157f9101b147f78 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 14:45:53 +0100 Subject: [PATCH 12/20] Update src/docs/sdk/performance/ui-event-transactions.mdx Co-authored-by: Roman Zavarnitsyn --- src/docs/sdk/performance/ui-event-transactions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 123d6bbe0c..3ad1a715d8 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -119,7 +119,7 @@ Scenario: Same UI element with different event 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 + Given an auto-generated transaction from 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 From b48af6ffd043822bb0df702fd13d505968182cbe Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 14:46:04 +0100 Subject: [PATCH 13/20] Update src/docs/sdk/performance/ui-event-transactions.mdx Co-authored-by: Roman Zavarnitsyn --- src/docs/sdk/performance/ui-event-transactions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 3ad1a715d8..24ced5c0df 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -120,7 +120,7 @@ Scenario: Same UI element with different event Scenario: UI event triggered but transaction ended Given an auto-generated transaction from any UI event - And the transaction already is finished + And the transaction is already finished When the user triggers the same UI event Then the SDK starts a new UI event transaction From 2a30bec31f97b89d9ad1cf89a92870239b1f714f Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 14:46:17 +0100 Subject: [PATCH 14/20] Update src/docs/sdk/performance/ui-event-transactions.mdx Co-authored-by: Roman Zavarnitsyn --- src/docs/sdk/performance/ui-event-transactions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 24ced5c0df..6f418aa604 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -150,7 +150,7 @@ Scenario: Ongoing UI event transaction And sets the status to canceled And waits for its children to finish -Scenario: Ongoing screen load transaction +Scenario: Ongoing screen load/navigation 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 From d635fa5a8611d4768f4038120bc9b4290b1c14b4 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 14:45:20 +0100 Subject: [PATCH 15/20] minor fix --- src/docs/sdk/performance/ui-event-transactions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 6f418aa604..f9e7453c0d 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -67,7 +67,7 @@ Scenario: Set time to last finished child span And the transaction has one running child span When the running child span finishes Then the SDK schedules the idle timeout - And the SDK finishes the transaction after timeout + And the SDK finishes the transaction after the idle timeout And trims the end time of the transaction to the one of the last finished child span From 2cece83ed985e88ff9abe8e4cdbc53a1ec7e5615 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 14:58:05 +0100 Subject: [PATCH 16/20] fixes --- src/docs/sdk/performance/ui-event-transactions.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index f9e7453c0d..845af1978a 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -40,7 +40,8 @@ The specification is written in the [Gherkin syntax](https://cucumber.io/docs/gh Scenario: Starting UI Event transactions Given an instrumentable UI event Then the SDK starts a UI event transaction - And schedule the idle timeout with idleTimeout of the options + And schedules to finish the UIEventTransaction with + the idle timeout of the options Scenario: Wait for children when starting span Given a UI event transaction @@ -105,6 +106,10 @@ transactions to the scope so that users can access them via the static API. We r transactions to the scope on these platforms. The following extra rules apply as UI event transactions could interfere with other auto-generated transactions. +The SDK adds auto-generated spans to the transaction bound to the scope. UI event transactions need +auto-generated spans not to be empty. Therefore, the SDK shouldn't start a UI event transaction if there +is already an ongoing screen load/navigation transaction or a transaction bound to the scope by the user. + ```Gherkin Scenario: Same UI element with different event Given an ongoing UI event transaction @@ -124,10 +129,6 @@ Scenario: UI event triggered but transaction ended When the user triggers the same UI event Then the SDK starts a new UI event transaction -# The SDK adds auto-generated spans to the transaction bound to the scope. -# UI event transactions need auto-generated spans not to be empty. Therefore, -# the SDK can't start a UI event transaction if there is already a -# transaction bound to the scope by the user. Scenario: Manually created transaction bound to the scope Given an ongoing manually created transaction by the user bound to the scope @@ -153,7 +154,7 @@ Scenario: Ongoing UI event transaction Scenario: Ongoing screen load/navigation 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 + Then the SDK doesn't start a UI event transaction ``` ## Transaction name From 387fbe510310ece7a84c312dd8ed3d423dfff155 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 18 Nov 2022 14:58:59 +0100 Subject: [PATCH 17/20] navigation transaction --- src/docs/sdk/performance/ui-event-transactions.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 845af1978a..136efe11fb 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -137,7 +137,7 @@ Scenario: Manually created transaction bound to the scope ``` -### Screen load transactions +### Screen load/navigation 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. @@ -152,7 +152,7 @@ Scenario: Ongoing UI event transaction And waits for its children to finish Scenario: Ongoing screen load/navigation transaction - Given an ongoing screen load transaction + Given an ongoing screen load/navigation transaction When the SDK starts a new UI event transaction Then the SDK doesn't start a UI event transaction ``` From e81ad0d05fdb780c67741e0a34971216a4c3cfc3 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Mon, 21 Nov 2022 08:47:01 +0100 Subject: [PATCH 18/20] Update src/docs/sdk/performance/ui-event-transactions.mdx Co-authored-by: Roman Zavarnitsyn --- src/docs/sdk/performance/ui-event-transactions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index 136efe11fb..dccba00981 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -153,7 +153,7 @@ Scenario: Ongoing UI event transaction Scenario: Ongoing screen load/navigation transaction Given an ongoing screen load/navigation transaction - When the SDK starts a new UI event transaction + When the user triggers a UI event Then the SDK doesn't start a UI event transaction ``` From 5a3d7e197656850c7368bf2b6e255460c04ecb2c Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Mon, 21 Nov 2022 08:47:12 +0100 Subject: [PATCH 19/20] Update src/docs/sdk/performance/ui-event-transactions.mdx Co-authored-by: Roman Zavarnitsyn --- src/docs/sdk/performance/ui-event-transactions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index dccba00981..f3ef957c4e 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -132,7 +132,7 @@ Scenario: UI event triggered but transaction ended Scenario: Manually created transaction bound to the scope Given an ongoing manually created transaction by the user bound to the scope - When the user triggers the a UI event + When the user triggers a UI event Then the SDK doesn't start a UI event transaction ``` From 93ff13709a33065a31cafb6333d260e82d4b2bb8 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Mon, 21 Nov 2022 08:55:53 +0100 Subject: [PATCH 20/20] add option --- src/docs/sdk/performance/ui-event-transactions.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/performance/ui-event-transactions.mdx index f3ef957c4e..0d75d7b995 100644 --- a/src/docs/sdk/performance/ui-event-transactions.mdx +++ b/src/docs/sdk/performance/ui-event-transactions.mdx @@ -4,6 +4,12 @@ title: "UI Event Transactions" We recommend implementing this feature for mobile and desktop SDKs. +UI event transactions are enabled by setting the SDK config option `enableUserInteractionTracing`, +which we recommend enabling per default. Remember that this feature will generate many +transactions, which can significantly impact running out of quota. Therefore, it might be safer to +disable this feature per default when adding it and enable it per default in an upcoming major SDK +release. + 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 @@ -136,7 +142,6 @@ Scenario: Manually created transaction bound to the scope Then the SDK doesn't start a UI event transaction ``` - ### Screen load/navigation transactions This section deals specifically with auto-generated transactions for loading screens. If your SDK has