Add new duration signal type where the SDK tracks duration & sends it

[Jeehut]

This implements what we had discussed in our call recently, documented in the Pirate Metrics overview task as:

Timed Actions (naming?)

Todo Cihat: SDK has convenience functions for "named screen/function/activity has started" and "named screen/function/activity has finished". This creates a signal that sends "named screen/function/activity has taken x seconds"

I'm posting this as a separate PR because while it was discussed for Pirate Metrics, it's not directly related and can be published as a separate SDK improvement. I feel it could distract/confuse people if combined with Pirate Metrics.

I decided to call the APIs startDurationSignal and stopAndSendDurationSignal. These two functions are the only added public API. The duration will be reported in the parameter TelemetryDeck.Signal.durationInSeconds. The SDK takes care of the duration tracking internally, including making sure the duration only reflects the app's foreground time.

Should I adjust the Swift SDK setup guide? Or write a new doc page about this? Or maybe a blog article?

[kkostov]

@Jeehut What do you think about not isolating these methods to the main actor? There is an unexpected side effect in that integrations will need to dispatch to the main queue to be able to access them (I already encountered this with the navigation API). It seems convenient to be able to use TelemetryDeck from any queue or actor, without "having to think about it too much" while making an app.

[Jeehut]

@kkostov I don't necessarily agree with the navigation feature as navigation is directly related to UI (which is run on the main thread), but I do understand your point with this specific PR. I just reworked the details to use a DispatchQueue instead of @MainActor so you can call it from anywhere. Thank you for the feedback!

[winsmith]

Fantastic work! There's so many cool things we can do with this on the UI

[kkostov]

@Jeehut just to be sure we're on some page:

I think it's fine to use strict concurrency, and it would be beneficial to have API which avoids interacting with the main queue directly.

In iOS, for instance, handling events from other parts of the app often doesn't occur on the main thread (we don't enforce what the concept of "navigation" is for an app). Similarly, in Flutter, navigation events aren't necessarily on the main thread. In all these cases, dispatching could lead to unnecessary contention.

Specifically for session duration, we're interacting with the local cache which happens on a worker queue and either very early or very late in the application lifecycle, I think it's good to avoid interfering with the main queue at these moments.

If you still feel that this is work that must be done main, then it's better to leave the MainActor API so integrations will have a choice to use it without dispatch.

[Jeehut]

@kkostov I'm not sure if you understood my previous message. I changed the implementation in this PR already to accommodate for your feedback since I agree. It's no longer requiring the main thread.

If you want me to also change the thread for the navigation signal sending functions, feel free to open a separate issue since I'll be merging this now and that discussion doesn't belong here. I'm not sure if you requested that change now or already have a solution working with the current implementation for navigation.