Skip to content

Commit 7b0bb82

Browse files
rtrieuclaudedomalessi
authored
[DOCS-14020] Split SDK advanced_config partials into use-case buckets (#37509)
* [DOCS-14020] Split SDK advanced_config partials into use-case buckets Creates 53 new cdocs partials under layouts/shortcodes/mdoc/en/sdk/ by extracting sections from the 8 existing advanced_config partials into 9 topic-scoped directories: - add_custom_context (7 SDKs) - track_user_ids (7 SDKs) - modify_drop_events (5 SDKs) - track_navigation (5 SDKs) - track_user_interactions (6 SDKs) - track_network_requests (7 SDKs) - track_errors (6 SDKs) - track_ui_latency (4 SDKs) - manage_sessions (6 SDKs) Existing advanced_config partials and all pages that use them are untouched. New partials are ready to be consumed by the use-case pages created in Phase 4. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Update layouts/shortcodes/mdoc/en/sdk/manage_sessions/ios.mdoc.md Co-authored-by: domalessi <111786334+domalessi@users.noreply.github.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: domalessi <111786334+domalessi@users.noreply.github.com>
1 parent b5712d6 commit 7b0bb82

53 files changed

Lines changed: 3171 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎layouts/shortcodes/mdoc/en/sdk/add_custom_context/android.mdoc.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
### Track attributes
2+
3+
```kotlin
4+
// Adds an attribute to all future RUM events
5+
GlobalRumMonitor.get().addAttribute(key, value)
6+
7+
// Removes an attribute to all future RUM events
8+
GlobalRumMonitor.get().removeAttribute(key)
9+
```
10+
11+
[1]: https://app.datadoghq.com/rum/application/create
12+
[2]: /real_user_monitoring/android
13+
[3]: /real_user_monitoring/android/data_collected

‎layouts/shortcodes/mdoc/en/sdk/add_custom_context/flutter.mdoc.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
### Set a custom global attribute
2+
3+
To set a custom global attribute, use `DdRum.addAttribute`.
4+
5+
* To add or update an attribute, use `DdRum.addAttribute`.
6+
* To remove the key, use `DdRum.removeAttribute`.
7+
8+
[1]: https://app.datadoghq.com/rum/application/create
9+
[14]: /real_user_monitoring/application_monitoring/flutter/data_collected

‎layouts/shortcodes/mdoc/en/sdk/add_custom_context/ios.mdoc.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
### Set a custom global attribute
2+
3+
To set a custom global attribute, use `RUMMonitor.shared().addAttribute(forKey:value:)`.
4+
5+
* To add an attribute, use `RUMMonitor.shared().addAttribute(forKey: "<KEY>", value: "<VALUE>")`.
6+
* To update the value, use `RUMMonitor.shared().addAttribute(forKey: "<KEY>", value: "<UPDATED_VALUE>")`.
7+
* To remove the key, use `RUMMonitor.shared().removeAttribute(forKey: "<KEY_TO_REMOVE>")`.
8+
9+
For better performance in bulk operations (modifying multiple attributes at once), use `.addAttributes(_:)` and `.removeAttributes(forKeys:)`.
10+
11+
**Note**: You can't create facets on custom attributes if you use spaces or special characters in your key names. For example, use `forKey: "store_id"` instead of `forKey: "Store ID"`.
12+
13+
[1]: https://app.datadoghq.com/rum/application/create
14+
[2]: /real_user_monitoring/application_monitoring/ios
15+
[6]: /real_user_monitoring/application_monitoring/ios/data_collected/?tab=session#default-attributes

‎layouts/shortcodes/mdoc/en/sdk/add_custom_context/kotlin_multiplatform.mdoc.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
### Track attributes
2+
3+
```kotlin
4+
// Adds an attribute to all future RUM events
5+
GlobalRumMonitor.get().addAttribute(key, value)
6+
7+
// Removes an attribute to all future RUM events
8+
GlobalRumMonitor.get().removeAttribute(key)
9+
```
10+
11+
[1]: https://app.datadoghq.com/rum/application/create
12+
[3]: /real_user_monitoring/application_monitoring/kotlin_multiplatform/data_collected

‎layouts/shortcodes/mdoc/en/sdk/add_custom_context/react_native.mdoc.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
### Global attributes
2+
3+
You can keep global attributes to track information about a specific session, such as A/B testing configuration, ad campaign origin, or cart status. These attributes are attached to all future Logs, Spans, and RUM events.
4+
5+
**Add multiple global attributes**
6+
7+
Use `addAttributes` to add or update several attributes at once.
8+
9+
```js
10+
DdSdkReactNative.addAttributes({
11+
profile_mode: 'wall',
12+
chat_enabled: true,
13+
campaign_origin: 'example_ad_network'
14+
});
15+
```
16+
17+
**Add a single global attribute**
18+
19+
Use `addAttribute` when you want to add or update a single attribute.
20+
21+
```js
22+
DdSdkReactNative.addAttribute('profile_mode', 'wall');
23+
DdSdkReactNative.addAttribute('chat_enabled', true);
24+
```
25+
26+
If the attribute already exists, its value is overwritten.
27+
28+
**Remove a single global attribute**
29+
30+
Use `removeAttribute` to remove a specific attribute from the global context.
31+
32+
```js
33+
DdSdkReactNative.removeAttribute('campaign_origin');
34+
```
35+
36+
After removal, the attribute is no longer attached to future Logs, Spans, or RUM events.
37+
38+
**Remove multiple global attributes**
39+
40+
Use `removeAttributes` to remove several attributes at once.
41+
42+
```js
43+
DdSdkReactNative.removeAttributes([
44+
'profile_mode',
45+
'chat_enabled'
46+
]);
47+
```
48+
49+
This is useful when cleaning up session-specific data, such as when a user logs out or exits a feature flow.
50+
51+
[1]: https://app.datadoghq.com/rum/application/create
52+
[2]: /real_user_monitoring/application_monitoring/react_native

‎layouts/shortcodes/mdoc/en/sdk/add_custom_context/roku.mdoc.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### Track custom global attributes
2+
3+
In addition to the default attributes captured by the SDK automatically, you can choose to add additional contextual information, such as custom attributes, to your Logs and RUM events to enrich your observability within Datadog. Custom attributes allow you to filter and group information about observed user behavior (for example by cart value, merchant tier, or ad campaign) with code-level information (such as backend services, session timeline, error logs, and network health).
4+
5+
```text
6+
m.global.setField("datadogContext", { foo: "Some value", bar: 123})
7+
```
8+
9+
[1]: https://app.datadoghq.com/rum/application/create
10+
[2]: /real_user_monitoring/application_monitoring/roku/setup

‎layouts/shortcodes/mdoc/en/sdk/add_custom_context/unity.mdoc.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
### Set a custom global attribute
2+
3+
To set a custom global attribute, use `DdRum.AddAttribute`.
4+
5+
* To add or update an attribute, use `DdRum.AddAttribute`.
6+
* To remove the key, use `DdRum.RemoveAttribute`.
7+
8+
[1]: https://app.datadoghq.com/rum/application/create
9+
[3]: /real_user_monitoring/application_monitoring/unity/data_collected/

‎layouts/shortcodes/mdoc/en/sdk/manage_sessions/android.mdoc.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
## Event and data management
2+
3+
The Android SDK first stores events and only uploads events when the [intake specifications][8] conditions are met.
4+
5+
### Clear all data
6+
7+
You have the option of deleting all unsent data stored by the SDK with the `clearAllData` API.
8+
9+
```kotlin
10+
fun clearAllData(sdkCore: SdkCore = getInstance()) {
11+
sdkCore.clearAllData()
12+
}
13+
```
14+
15+
### Stop data collection
16+
17+
You can use the `StopInstance` API to stop the SDK instance assigned to the given name (or the default instance if the name is null) from collecting and uploading data further.
18+
19+
```kotlin
20+
fun stopInstance(instanceName: String? = null) {
21+
synchronized(registry) {
22+
val instance = registry.unregister(instanceName)
23+
(instance as? DatadogCore)?.stop()
24+
}
25+
}
26+
```
27+
28+
### Control event buildup
29+
30+
Many operations, such as data processing and event I/O, are queued in background threads to handle edge cases where the queue has grown so much that there could be delayed processing, high memory usage, or Application Not Responding (ANR) errors.
31+
32+
You can control the buildup of events on the SDK with the `setBackpressureStrategy` API. This API ignores new tasks if a queue reaches 1024 items.
33+
34+
```kotlin
35+
fun setBackpressureStrategy(backpressureStrategy: BackPressureStrategy): Builder {
36+
coreConfig = coreConfig.copy(backpressureStrategy = backpressureStrategy)
37+
return this
38+
}
39+
```
40+
41+
See an [example of this API][9] being used.
42+
43+
### Set remote log threshold
44+
45+
You can define the minimum log level (priority) to send events to Datadog in a logger instance. If the log priority is below the one you set at this threshold, it does not get sent. The default value is -1 (allow all).
46+
47+
```kotlin
48+
fun setRemoteLogThreshold(minLogThreshold: Int): Builder {
49+
minDatadogLogsPriority = minLogThreshold
50+
return this
51+
}
52+
```
53+
54+
## Retrieve the RUM session ID
55+
56+
Retrieving the RUM session ID can be helpful for troubleshooting. For example, you can attach the session ID to support requests, emails, or bug reports so that your support team can later find the user session in Datadog.
57+
58+
You can access the RUM session ID at runtime without waiting for the `sessionStarted` event:
59+
60+
```kotlin
61+
GlobalRumMonitor.get().getCurrentSessionId { sessionId ->
62+
currentSessionId = sessionId
63+
}
64+
```
65+
66+
[1]: https://app.datadoghq.com/rum/application/create
67+
[2]: /real_user_monitoring/android
68+
[3]: /real_user_monitoring/android/data_collected
69+
[4]: /real_user_monitoring/application_monitoring/android/advanced_configuration/#automatically-track-views
70+
[5]: /real_user_monitoring/application_monitoring/android/advanced_configuration/#initialization-parameters
71+
[6]: /real_user_monitoring/application_monitoring/android/advanced_configuration/#automatically-track-network-requests
72+
[7]: /real_user_monitoring/android/data_collected/#event-specific-attributes
73+
[8]: /real_user_monitoring/application_monitoring/android/setup/#sending-data-when-device-is-offline
74+
[9]: https://github.com/DataDog/dd-sdk-android/blob/eaa15cd344d1723fafaf179fcebf800d6030c6bb/sample/kotlin/src/main/kotlin/com/datadog/android/sample/SampleApplication.kt#L279
75+
[10]: https://github.com/DataDog/dd-sdk-android/tree/master/sample/kotlin/src/main/kotlin/com/datadog/android/sample/widget
76+
[11]: /real_user_monitoring/application_monitoring/android/monitoring_app_performance/#time-to-network-settled
77+
[12]: https://square.github.io/okhttp/features/events/
78+
[13]: /real_user_monitoring/application_monitoring/android/monitoring_app_performance/#interaction-to-next-view
79+
[14]: /real_user_monitoring/application_monitoring/android/setup?tab=kotlin#setup

‎layouts/shortcodes/mdoc/en/sdk/manage_sessions/flutter.mdoc.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
## Tracking from background isolates
2+
3+
Starting with v3, Datadog Flutter SDK is capable of monitoring from multiple isolates, but monitoring must be initialized from the background isolate:
4+
5+
When initializing your background isolate, call `DatadogSdk.instance.attachToBackgroundIsolate`. For example:
6+
7+
```dart
8+
Future<void> _spawnIsolate() async {
9+
final receivePort = ReceivePort();
10+
receivePort.listen((message) {
11+
//
12+
});
13+
await Isolate.spawn(_backgroundWork, receivePort.sendPort);
14+
}
15+
16+
void _backgroundWork(SendPort port) async {
17+
await DatadogSdk.instance.attachToBackgroundIsolate();
18+
19+
// Your background work
20+
}
21+
```
22+
23+
`attachToBackgroundIsolate` must be called **after** Datadog is initialized in your main isolate, otherwise the call silently fails and tracking is not available.
24+
25+
If you are using [Datadog Tracking HTTP Client][10] to automatically track resources, `attachToBackgroundIsolate` automatically starts tracking resources from the calling isolate. However, using `Client` from the `http` package or `Dio` requires you to re-initialize HTTP tracking for those packages from the background isolate.
26+
27+
## Clear all data
28+
29+
Use `clearAllData` to clear all data that has not been sent to Datadog.
30+
31+
```dart
32+
DatadogSdk.instance.clearAllData();
33+
```
34+
35+
## Retrieve the RUM session ID
36+
37+
Retrieving the RUM session ID can be helpful for troubleshooting. For example, you can attach the session ID to support requests, emails, or bug reports so that your support team can later find the user session in Datadog.
38+
39+
You can access the RUM session ID at runtime without waiting for the `sessionStarted` event:
40+
41+
```dart
42+
final sessionId = await DatadogSdk.instance.rum?.getCurrentSessionId()
43+
```
44+
45+
[1]: https://app.datadoghq.com/rum/application/create
46+
[2]: /real_user_monitoring/application_monitoring/flutter/setup/
47+
[3]: /real_user_monitoring/application_monitoring/flutter/integrated_libraries/
48+
[4]: /getting_started/tagging/#defining-tags
49+
[5]: /real_user_monitoring/connect_rum_and_traces/?tab=browserrum#how-are-rum-resources-linked-to-traces
50+
[6]: https://github.com/openzipkin/b3-propagation#single-headers
51+
[7]: https://github.com/openzipkin/b3-propagation#multiple-headers
52+
[8]: https://www.w3.org/TR/trace-context/#tracestate-header
53+
[9]: /real_user_monitoring/application_monitoring/browser/frustration_signals/
54+
[10]: https://pub.dev/packages/datadog_tracking_http_client
55+
[11]: https://api.flutter.dev/flutter/dart-io/HttpOverrides/current.html
56+
[12]: https://pub.dev/documentation/datadog_tracking_http_client/latest/datadog_tracking_http_client/DatadogTrackingHttpOverrides-class.html
57+
[13]: /serverless/aws_lambda/distributed_tracing/
58+
[14]: /real_user_monitoring/application_monitoring/flutter/data_collected
59+
[15]: /real_user_monitoring/explorer/?tab=measures#setup-facets-and-measures
60+
[16]: https://github.com/DataDog/dd-sdk-flutter/tree/main/packages/datadog_tracking_http_client
61+
[17]: https://pub.dev/documentation/datadog_flutter_plugin/latest/datadog_flutter_plugin/
62+
[18]: /real_user_monitoring/application_monitoring/mobile_vitals/?tab=flutter
63+
[19]: https://pub.dev/packages/datadog_grpc_interceptor
64+
[20]: https://pub.dev/packages/datadog_gql_link
65+
[21]: https://pub.dev/packages/datadog_dio
66+
[22]: /real_user_monitoring/application_monitoring/flutter/integrated_libraries

‎layouts/shortcodes/mdoc/en/sdk/manage_sessions/ios.mdoc.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
## Track background events
2+
3+
{% alert level="info" %}
4+
Tracking background events may lead to additional sessions, which can impact billing. For questions, [contact Datadog support](https://docs.datadoghq.com/help/).
5+
{% /alert %}
6+
7+
You can track events such as crashes and network requests when your application is in the background (for example, no active view is available).
8+
9+
To track background events, add the following snippet during initialization in your Datadog configuration:
10+
11+
```swift
12+
import DatadogRUM
13+
14+
RUM.enable(
15+
with: RUM.Configuration(
16+
...
17+
trackBackgroundEvents: true
18+
)
19+
)
20+
```
21+
22+
## Retrieve the RUM session ID
23+
24+
Retrieving the RUM session ID can be helpful for troubleshooting. For example, you can attach the session ID to support requests, emails, or bug reports so that your support team can later find the user session in Datadog.
25+
26+
You can access the RUM session ID at runtime without waiting for the `sessionStarted` event:
27+
28+
```swift
29+
RumMonitor.shared().currentSessionID(completion: { sessionId in
30+
currentSessionId = sessionId
31+
})
32+
```
33+
34+
## Set tracking consent (GDPR compliance)
35+
36+
To be compliant with the GDPR regulation, the RUM iOS SDK requires the tracking consent value at initialization.
37+
38+
The `trackingConsent` setting can be one of the following values:
39+
40+
1. `.pending`: The RUM iOS SDK starts collecting and batching the data but does not send it to Datadog. The RUM iOS SDK waits for the new tracking consent value to decide what to do with the batched data.
41+
2. `.granted`: The RUM iOS SDK starts collecting the data and sends it to Datadog.
42+
3. `.notGranted`: The RUM iOS SDK does not collect any data. No logs, traces, or RUM events are sent to Datadog.
43+
44+
To change the tracking consent value after the RUM iOS SDK is initialized, use the `Datadog.set(trackingConsent:)` API call. The RUM iOS SDK changes its behavior according to the new value.
45+
46+
For example, if the current tracking consent is `.pending`:
47+
48+
- If you change the value to `.granted`, the RUM iOS SDK sends all current and future data to Datadog.
49+
- If you change the value to `.notGranted`, the RUM iOS SDK wipes all current data and does not collect future data.
50+
51+
## Data management
52+
53+
The iOS SDK first stores events locally and only uploads events when the [intake specifications][9] conditions are met.
54+
55+
### Clear all data
56+
57+
You have the option of deleting all unsent data stored by the SDK with the `Datadog.clearAllData()` API.
58+
59+
```swift
60+
import DatadogCore
61+
62+
Datadog.clearAllData()
63+
```
64+
65+
### Stop data collection
66+
67+
You can use the `Datadog.stopInstance()` API to stop a named SDK instance (or the default instance if the name is `nil`) from collecting and uploading data further.
68+
69+
```swift
70+
import DatadogCore
71+
72+
Datadog.stopInstance()
73+
```
74+
75+
Calling this method disables the SDK and all active features, such as RUM. To resume data collection, you must reinitialize the SDK. You can use this API if you want to change configurations dynamically.
76+
77+
[1]: https://app.datadoghq.com/rum/application/create
78+
[2]: /real_user_monitoring/application_monitoring/ios
79+
[3]: /real_user_monitoring/application_monitoring/ios/data_collected/
80+
[4]: https://github.com/DataDog/dd-sdk-ios/blob/master/DatadogRUM/Sources/RUMMonitorProtocol.swift
81+
[5]: /real_user_monitoring/application_monitoring/ios/data_collected/?tab=error#error-attributes
82+
[6]: /real_user_monitoring/application_monitoring/ios/data_collected/?tab=session#default-attributes
83+
[7]: https://www.ntppool.org/en/
84+
[8]: /real_user_monitoring/error_tracking/mobile/ios/#add-app-hang-reporting
85+
[9]: /real_user_monitoring/application_monitoring/ios/setup

0 commit comments

Comments
 (0)