From 63d22a459aa3d94e4ee69035447fe4dd6c0cd327 Mon Sep 17 00:00:00 2001 From: Nikita Ogorodnikov Date: Tue, 18 Jul 2023 13:50:00 +0200 Subject: [PATCH] RUMM-3465: Update documentation for SDK v2 --- CONTRIBUTING.md | 39 +++-- README.md | 35 ++-- dd-sdk-android-core/README.md | 138 ++++----------- docs/advanced_troubleshooting.md | 30 +++- docs/kotlin_extensions.md | 62 ------- docs/native_crash_collection.md | 71 -------- docs/sdk_benchmarks.md | 61 ------- docs/sdk_performance.md | 158 +++++++++++++++--- features/dd-sdk-android-logs/README.md | 6 +- features/dd-sdk-android-ndk/README.md | 48 ++++++ features/dd-sdk-android-rum/README.md | 6 +- features/dd-sdk-android-trace/README.md | 6 +- features/dd-sdk-android-webview/README.md | 6 +- integrations/dd-sdk-android-coil/README.md | 53 ++---- integrations/dd-sdk-android-compose/README.md | 44 +---- integrations/dd-sdk-android-fresco/README.md | 40 +---- integrations/dd-sdk-android-glide/README.md | 42 ++--- integrations/dd-sdk-android-ktx/README.md | 55 +++--- integrations/dd-sdk-android-okhttp/README.md | 6 +- integrations/dd-sdk-android-rx/README.md | 39 +---- .../dd-sdk-android-sqldelight/README.md | 44 ++--- integrations/dd-sdk-android-timber/README.md | 47 +----- integrations/dd-sdk-android-tv/README.md | 61 ++----- 23 files changed, 407 insertions(+), 690 deletions(-) delete mode 100644 docs/kotlin_extensions.md delete mode 100644 docs/native_crash_collection.md delete mode 100644 docs/sdk_benchmarks.md create mode 100644 features/dd-sdk-android-ndk/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f8b0f33f69..7b7b452e90 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,16 +21,25 @@ In addition, to be able to run the static analysis tools locally, you should run This project hosts the following modules: - - `dd-sdk-android`: the main library implementing all Datadog features (Logs, Traces, RUM, Crash reports); - - `dd-sdk-android-ktx`: a set of Kotlin extensions to make the `dd-sdk-android` library more Kotlin friendly; - - `dd-sdk-android-ndk`: a Plugin to allow tracking NDK information; - - `dd-sdk-android-glide`: a lightweight library providing a bridge integration between `dd-sdk-android` and [Glide](https://bumptech.github.io/glide/); - - `dd-sdk-android-timber`: a lightweight library providing a bridge integration between `dd-sdk-android` and [Timber](https://github.com/JakeWharton/timber); + - `dd-sdk-android-core`: the main library implementing the core functionality of SDK (storage and upload of data, core APIs); + - `features/***`: a set of libraries implementing Datadog products: Logs, RUM, Traces, etc. + - `integrations/dd-sdk-android-coil`: a lightweight library providing a bridge integration between Datadog SDK and [Coil](https://coil-kt.github.io/coil/); + - `integrations/dd-sdk-android-compose`: a lightweight library providing a bridge integration between Datadog SDK and [Jetpack Compose](https://developer.android.com/jetpack/compose); + - `integrations/dd-sdk-android-fresco`: a lightweight library providing a bridge integration between Datadog SDK and [Fresco](https://frescolib.org/); + - `integrations/dd-sdk-android-okhttp`: a lightweight library providing an instrumentation for [OkHttp](https://square.github.io/okhttp/); + - `integrations/dd-sdk-android-rx`: a lightweight library providing a bridge integration between Datadog SDK and [RxJava](https://github.com/ReactiveX/RxJava); + - `integrations/dd-sdk-android-sqldelight`: a lightweight library providing a bridge integration between Datadog SDK and [SQLDelight](https://cashapp.github.io/sqldelight/); + - `integrations/dd-sdk-android-tv`: a lightweight library providing extensions for [Android TV](https://www.android.com/tv/) + - `integrations/dd-sdk-android-ktx`: a set of Kotlin extensions to make the Datadog SDK more Kotlin friendly; + - `integrations/dd-sdk-android-glide`: a lightweight library providing a bridge integration between Datadog SDK and [Glide](https://bumptech.github.io/glide/); + - `integrations/dd-sdk-android-timber`: a lightweight library providing a bridge integration between Datadog SDK and [Timber](https://github.com/JakeWharton/timber); - `instrumented/integration`: a test module with integration tests using Espresso; + - `instrumented/nightly-tests`: a test module with E2E tests using Espresso; - `tools/detekt`: a few custom [Detekt](https://github.com/arturbosch/detekt) static analysis rules; + - `tools/lint`: a custom [Lint](https://developer.android.com/studio/write/lint) static analysis rule; - `tools/noopfactory`: an annotation processor generating no-op implementation of interfaces; - `tools/unit`: a utility library with code to help writing unit tests; - - `sample/***`: a few sample application showcasing how to use the library features in production code; + - `sample/***`: a few sample applications showcasing how to use the library features in production code; ### Building the SDK @@ -106,7 +115,7 @@ the bug are best. ## Have a patch? We welcome code contributions to the library, which you can -[submit as a pull request](https://github.com/DataDog/dd-sdk-android/pull/new/master). +[submit as a pull request](https://github.com/DataDog/dd-sdk-android/pull/new/develop). Before you submit a PR, make sure that you first create an Issue to explain the bug or the feature your patch covers, and make sure another Issue or PR doesn't already exist. @@ -116,10 +125,8 @@ To create a pull request: 1. **Fork the repository** from https://github.com/DataDog/dd-sdk-android ; 2. **Make any changes** for your patch; 3. **Write tests** that demonstrate how the feature works or how the bug is fixed; -4. **Update any documentation** such as `docs/GettingStarted.md`, especially for - new features; -5. **Submit the pull request** from your fork back to this - [repository](https://github.com/DataDog/dd-sdk-android) . +4. **Update any documentation**, especially for new features. It can be found either in the `docs` folder of this repository, or in [documentation repository](https://github.com/DataDog/documentation); +5. **Submit the pull request** from your fork back to this [repository](https://github.com/DataDog/dd-sdk-android). The pull request will be run through our CI pipeline, and a project member will @@ -143,7 +150,7 @@ any change you introduce are still compatible with Java. If you want to add Kotlin specific features (DSL, lambdas, …), make sure there is a way to get the same feature from a Java source code. -### Code qualituy +### Code quality Our code uses [Detekt](https://detekt.dev/) static analysis with a shared configuration, slightly stricter than the default one. A Detekt check is ran on every on every PR to ensure that all new code @@ -191,7 +198,7 @@ class Foo : Observable(), Runnable { ``` There is also a command that you can use to automatically format the code following the -required styling rules (require ktlint installed on your machine): +required styling rules (require `ktlint` installed on your machine): ```console ktlint -F "**/*.kt" "**/*.kts" '!**/build/generated/**' '!**/build/kspCaches/**' @@ -299,7 +306,7 @@ output is measured by 2 Datadog Monitors (one for performance and one for functi 4. `additionalInfo` is some context to distinguish multiple test on the same method (could be related to the argument, the context, a state) -- We need to add an identifier in the method documentation following the method signature in the [apiSurface](dd-sdk-android/apiSurface). +- We need to add an identifier in the method documentation following the method signature in the [apiSurface](dd-sdk-android-core/api/apiSurface). This will be used by our test coverage tool. @@ -309,9 +316,9 @@ We have created a Live Template that you can add in your development environment * apiMethodSignature: THE API METHOD SIGNATURE HERE */ @org.junit.Test -fun $EXP$(){ +fun $EXP$() { val testMethodName = "$EXP$" - measure(testMethodName){ + measure(testMethodName) { // API call here } } diff --git a/README.md b/README.md index 4033e1fa8c..67210f5081 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,11 @@ ### Log Collection -See the dedicated [Datadog Android Log Collection documentation](http://docs.datadoghq.com/logs/log_collection/android) to learn how to forward logs from your Android or Android TV application to Datadog. +See the dedicated [Datadog Android Log Collection documentation][1] to learn how to forward logs from your Android or Android TV application to Datadog. ### Real User Monitoring -See the dedicated [Datadog Android RUM Collection documentation](https://docs.datadoghq.com/real_user_monitoring/android/) to learn how to send RUM data from your Android or Android TV application to Datadog. +See the dedicated [Datadog Android RUM Collection documentation][2] to learn how to send RUM data from your Android or Android TV application to Datadog. ## Log Integrations @@ -36,9 +36,17 @@ If you use Glide to load images in your application, take a look at Datadog's [d If you use Jetpack Compose in your application, take a look at Datadog's [dedicated library](integrations/dd-sdk-android-compose/README.md). +### SQLDelight + +If you use SQLDelight in your application, take a look at Datadog's [dedicated library](integrations/dd-sdk-android-sqldelight/README.md). + +### RxJava + +If you use RxJava in your application, take a look at Datadog's [dedicated library](integrations/dd-sdk-android-rx/README.md). + ### Picasso -If you use Picasso, let it use your `OkHttpClient`, and you can get RUM and APM information about network requests made by Picasso. +If you use Picasso, let it use your `OkHttpClient` instrumented with Datadog SDK, and you can get RUM and APM information about network requests made by Picasso. ```kotlin val picasso = Picasso.Builder(context) @@ -50,7 +58,7 @@ If you use Picasso, let it use your `OkHttpClient`, and you can get RUM and APM ### Retrofit -If you use Retrofit, let it use your `OkHttpClient`, and you can get RUM and APM information about network requests made with Retrofit. +If you use Retrofit, let it use your `OkHttpClient` instrumented with Datadog SDK, and you can get RUM and APM information about network requests made with Retrofit. ```kotlin val retrofitClient = Retrofit.Builder() @@ -61,7 +69,7 @@ If you use Retrofit, let it use your `OkHttpClient`, and you can get RUM and APM ### Apollo (GraphQL) -If you use Apollo, let it use your `OkHttpClient`, and you can get RUM and APM information about all the queries performed through the Apollo client. +If you use Apollo, let it use your `OkHttpClient` instrumented with Datadog SDK, and you can get RUM and APM information about all the queries performed through the Apollo client. ```kotlin val apolloClient = ApolloClient.builder() @@ -72,26 +80,26 @@ If you use Apollo, let it use your `OkHttpClient`, and you can get RUM and APM i ## Looking up your logs -When you open your console in Datadog, navigate to the [Log Explorer][1]. In the search bar, type `source:android`. This filters your logs to only show the ones coming from Android or Android TV applications. +When you open your console in Datadog, navigate to the [Log Explorer][3]. In the search bar, type `source:android`. This filters your logs to only show the ones coming from Android or Android TV applications. ![Datadog Mobile Logs](docs/images/screenshot_logs.png) ## Looking up your spans -When you open your console in Datadog, navigate to [**APM** > **Services**][2]. In the list of services, you can see all your Android and Android TV applications (by default, the service name matches your application's package name, for example: `com.example.android`). You can access all the traces started from your application. +When you open your console in Datadog, navigate to [**APM** > **Services**][4]. In the list of services, you can see all your Android and Android TV applications (by default, the service name matches your application's package name, for example: `com.example.android`). You can access all the traces started from your application. ![Datadog Mobile Logs](docs/images/screenshot_apm.png) ## Looking up your RUM events -When you open your console in Datadog, navigate to the [RUM Explorer][3]. In the side bar, you can select your application and explore Sessions, Views, Actions, Errors, Resources, and Long Tasks. +When you open your console in Datadog, navigate to the [RUM Explorer][5]. In the side bar, you can select your application and explore Sessions, Views, Actions, Errors, Resources, and Long Tasks. ![Datadog Mobile Logs](docs/images/screenshot_rum.png) ## Troubleshooting If you encounter any issue when using the Datadog SDK for Android and Android TV, please take a look at -the [troubleshooting checklist](docs/troubleshooting_android.md), [common problems](docs/advanced_troubleshooting.md), or at +the [troubleshooting checklist][6], [common problems](docs/advanced_troubleshooting.md), or at the existing [issues](https://github.com/DataDog/dd-sdk-android/issues?q=is%3Aissue).
@@ -106,6 +114,9 @@ Pull requests are welcome. First, open an issue to discuss what you would like t [Apache License, v2.0](LICENSE) -[1]: https://app.datadoghq.com/logs -[2]: https://app.datadoghq.com/apm/services -[3]: https://app.datadoghq.com/rum/explorer \ No newline at end of file +[1]: https://docs.datadoghq.com/logs/log_collection/android/?tab=kotlin +[2]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=kotlin +[3]: https://app.datadoghq.com/logs +[4]: https://app.datadoghq.com/apm/services +[5]: https://app.datadoghq.com/rum/explorer +[6]: https://docs.datadoghq.com/real_user_monitoring/android/troubleshooting/ \ No newline at end of file diff --git a/dd-sdk-android-core/README.md b/dd-sdk-android-core/README.md index a7bda008f9..dc0f15b389 100644 --- a/dd-sdk-android-core/README.md +++ b/dd-sdk-android-core/README.md @@ -1,13 +1,14 @@ -# Datadog SDK for Android +# Datadog SDK for Android - core library -## Getting Started +## Getting Started -To include the Datadog SDK for Android in your project, simply add the following -to your application's `build.gradle` file. +To include the Datadog SDK for Android in your project, simply add any product you want to use to your application's `build.gradle` file. -``` +For example, in case of RUM: + +```groovy dependencies { - implementation "com.datadoghq:dd-sdk-android:" + implementation "com.datadoghq:dd-sdk-android-rum:" } ``` @@ -22,129 +23,46 @@ class SampleApplication : Application() { override fun onCreate() { super.onCreate() val configuration = Configuration.Builder( - logsEnabled = true, - tracesEnabled = true, - crashReportsEnabled = true, - rumEnabled = true + clientToken = CLIENT_TOKEN, + env = ENV_NAME, + variant = APP_VARIANT_NAME ) .useSite(DatadogSite.US1) // replace with the site you're targeting (e.g.: US3, EU1, …) - .trackInteractions() - .trackLongTasks(durationThreshold) - .useViewTrackingStrategy(strategy) .build() - val credentials = Credentials(CLIENT_TOKEN, ENV_NAME, APP_VARIANT_NAME, APPLICATION_ID) - Datadog.initialize(this, credentials, configuration, trackingConsent) + Datadog.initialize(this, configuration, trackingConsent) } } ``` -### Logger Initialization - -You can create a `Logger` instance using the dedicated builder, as follows: - -```kotlin - logger = Logger.Builder() - .setNetworkInfoEnabled(true) - .setServiceName("com.example.app.android") - .setLogcatLogsEnabled(true) - .setDatadogLogsEnabled(true) - .setLoggerName("name") - .build() -``` - -### Logging +### Using a Secondary Instance of the SDK -You can then send logs with the following methods, mimicking the ones available -in the Android Framework: +It is possible to initialize multiple instances of the SDK by associating them with a name. Many methods of the SDK can optionally take an SDK instance as an argument. If not provided, the call is associated with the default (nameless) SDK instance. -```kotlin - logger.d("A debug message.") - logger.i("Some relevant information ?") - logger.w("An important warning…") - logger.e("An error was met!") - logger.wtf("What a Terrible Failure!") -``` - -### Logging Errors - -If you caught an exception and want to log it with a message, you can do so as -follow: +Here is an example illustrating how to initialize a secondary core instance and use it: ```kotlin - try { - doSomething() - } catch (e : IOException) { - logger.e("Error while doing something", e) - } +val namedSdkInstance = Datadog.initialize("myInstance", context, configuration, trackingConsent) +val userInfo = UserInfo(...) +Datadog.setUserInfo(userInfo, sdkCore = namedSdkInstance) ``` -> Note: All logging methods can have a throwable attached to them. +**Note**: The SDK instance name should have the same value between application runs. Storage paths for SDK events are associated with it. -### Adding context +You can retrieve the named SDK instance by calling `Datadog.getInstance()` and use the `Datadog.isInitialized()` method to check if the particular SDK instance is initialized. -#### Tags +## Setting up Datadog RUM SDK -Tags take the form of a single String, but can also represent key-value pairs when using a colon, and are -You can add tags to a specific logger as follows: +See the dedicated [Datadog Android RUM Collection documentation][1] to learn how to send RUM data from your Android or Android TV application to Datadog. -```kotlin - // This will add a tag "build_type:debug" or "build_type:release" accordingly - logger.addTag("build_type", BuildConfig.BUILD_TYPE) - - // This will add a tag "android" - logger.addTag("android") -``` +## Setting up Datadog Logs SDK -You can remove tags from a specific logger as follows: +See the dedicated [Datadog Android Log Collection documentation][2] to learn how to forward logs from your Android or Android TV application to Datadog. -```kotlin - // This will remove any tag starting with "build_type:" - logger.removeTagsWithKey("build_type") - - // This will remove the tag "android" - logger.removeTag("android") -``` +## Setting up Datadog Trace SDK -#### Attributes +See the dedicated [Datadog Android Trace Collection documentation][3] to learn how to send traces from your Android or Android TV application to Datadog. -Attributes are always in the form of a key-value pair. The value can be any primitive, String or Date. -You can add attributes to a specific logger as follows: - -```kotlin - // This will add an attribute "version_code" with an integer value - logger.addAttribute("version_code", BuildConfig.VERSION_CODE) - // This will add an attribute "version_name" with a String value - logger.addAttribute("version_name", BuildConfig.VERSION_NAME) -``` - -You can remove attributes from a specific logger as follows: - -```kotlin - logger.removeAttribute("version_code") - logger.removeAttribute("version_name") -``` - -#### Local Attributes - -Sometimes, you might want to log a message with attributes only for that specific message. You can -do so by providing a map alongside the message, each entry being added as an attribute. - -```kotlin - logger.i("onPageStarted", attributes = mapOf("http.url", url)) -``` - -In Java you can do so as follows: -```java - Map attributes = new HashMap<>(); - attributes.put("http.url", url); - logger.d( - "onPageStarted", - null, - attributes - ); -``` - -### Setting the Library's verbosity +## Setting the Library's verbosity If you need to get information about the Library, you can set the verbosity level as follows: @@ -165,3 +83,7 @@ would like to change. For more information, read the ## License [Apache License, v2.0](../LICENSE) + +[1]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=kotlin +[2]: https://docs.datadoghq.com/logs/log_collection/android/?tab=kotlin +[3]: https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/android/?tab=kotlin diff --git a/docs/advanced_troubleshooting.md b/docs/advanced_troubleshooting.md index ff8b180130..6b6f41878b 100644 --- a/docs/advanced_troubleshooting.md +++ b/docs/advanced_troubleshooting.md @@ -13,7 +13,6 @@ You also need to set the `android.useAndroidX` and `android.enableJetifier` prop ### Duplicate class com.google.common.util.concurrent.ListenableFuture - > Duplicate class com.google.common.util.concurrent.ListenableFuture found in modules jetified-guava-jdk5-17.0.jar (com.google.guava:guava-jdk5:17.0) and jetified-listenablefuture-1.0.jar (com.google.guava:listenablefuture:1.0) This issue can occur if your dependencies rely on different Guava artifacts as the Datadog SDK for Android. The SDK uses AndroidX's WorkManager, which depends on a specific Guava dependency. @@ -26,6 +25,25 @@ implementation ("com.datadoghq:dd-sdk-android:1.3.0") { } ``` +### Duplicate class kotlin.collections.jdk8.CollectionsJDK8Kt found + +> Duplicate class kotlin.collections.jdk8.CollectionsJDK8Kt found in modules kotlin-stdlib-1.8.10 (org.jetbrains.kotlin:kotlin-stdlib:1.8.10) and kotlin-stdlib-jdk8-1.7.20 (org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.7.20) + +You need to add the following rules to your buildscript (more details [here](https://stackoverflow.com/a/75298544)): + +```kotlin +dependencies { + constraints { + implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.8.10") { + because("kotlin-stdlib-jdk7 is now a part of kotlin-stdlib") + } + implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.8.10") { + because("kotlin-stdlib-jdk8 is now a part of kotlin-stdlib") + } + } +} +``` + ### Other If you encounter another issue when building your application with the Datadog SDK for Android, open an issue on the [DataDog/dd-sdk-android Github repository](https://github.com/DataDog/dd-sdk-android/issues/new?assignees=&labels=bug&template=bug_report.md&title=) with as many details as you can. @@ -74,12 +92,12 @@ If you think the SDK does not behave as it should, make sure you set the library ### Logs/Traces are not appearing in your dashboard. -Make sure that you initialized the SDK using a valid [Client Token](https://docs.datadoghq.com/account_management/api-app-keys/#client-tokens). +Make sure that you initialized the SDK using a valid [Client Token](https://docs.datadoghq.com/account_management/api-app-keys/#client-tokens) and you are targeting the correct Datadog site. Otherwise, if the library's logs are enabled, you should see the following message in the Logcat : -> Unable to send batch because your token is invalid. Make sure that the provided token still exists. +> "$batchInfo failed because your token is invalid; the batch was dropped. Make sure that the provided token still exists and you're targeting the relevant Datadog site." -### RUM FragmentViewTrackingStrategy is not working correctly with the ViewPager +### RUM `FragmentViewTrackingStrategy` is not working correctly with the `ViewPager` If you have a `FragmentViewPager` somewhere in your activities this can produce wrong View events if you are using the RUM `FragmentViewTrackingStrategy`. The reason for this is the way the `FragmentPagerAdapter` used to work by resuming **current** and **next** fragment to be able to resolve the @@ -88,3 +106,7 @@ makes sure you switch to the new way of instantiating your `FragmentPagerAdapter ```kotlin FragmentPagerAdapter(fragmentManager, BEHAVIOR_RESUME_ONLY_CURRENT_FRAGMENT) ``` + +### RUM view debugging + +You can use `RumMonitor#debug` property, which once enable will show you the overlay in the application with the actual RUM view name. diff --git a/docs/kotlin_extensions.md b/docs/kotlin_extensions.md deleted file mode 100644 index 55705a7a8f..0000000000 --- a/docs/kotlin_extensions.md +++ /dev/null @@ -1,62 +0,0 @@ -# Kotlin Extensions - -Take advantage of the Kotlin syntax to improve your usage of the dd-sdk-android library. - -**Note**: This package is an extension of the main package, so add both dependencies into your gradle file. - -## Setup -```conf -dependencies { - implementation "com.datadoghq:dd-sdk-android:x.x.x" - implementation "com.datadoghq:dd-sdk-android-ktx:x.x.x" -} -``` - -### Extensions - -1. Span extension methods: - -```kotlin - -// Attaches the throwable as a special attribute to the Span and in the same time sends also a Log message -// with all the needed information. -span.setError(throwable) - -// Attaches the error message as a special attribute to the Span and in the same time sends also a Log message -// with all the needed information. -span.setError(message) - -``` - -```kotlin - -// Automatically creates a span around the provided lambda -withinSpan(spanName, parentSpan) { - // Your code here -} - -``` - -2. Closeable extension methods: - -```kotlin - -// Executes the given [block] function on the [Closeable] instance, intercepts any Exception and sends it in -// a RUM error event closing the [Closeable] instance afterwards. - -val closeable: Closeable = ... -closeable.useMonitored { - // Your code here -} - -``` - -3. Extensions for OkHttp request builder: - -```kotlin - - // If you are using the Datadog TracingInterceptor for OkHttp request, this adds the provided parentSpan as the parent - // of the span created around the request. - val okHttpRequest = Request.Builder().parentSpan(span).build() - -``` diff --git a/docs/native_crash_collection.md b/docs/native_crash_collection.md deleted file mode 100644 index e43228f4bd..0000000000 --- a/docs/native_crash_collection.md +++ /dev/null @@ -1,71 +0,0 @@ -# Android Native Crash Collection - -
The Android NDK module is in public alpha and not supported by Datadog.
- -Send crash report for issues rising from the C/C++ code in your application. - -**Note**: This package is an extension of the main package, so add both dependencies into your gradle file. - -## Setup - -```conf -dependencies { - implementation "com.datadoghq:dd-sdk-android:x.x.x" - implementation "com.datadoghq:dd-sdk-android-ndk:x.x.x" -} -``` - -Initialize the library with your application context, tracking consent, and the [Datadog client token][1] and Application ID generated when you create a new RUM application in the Datadog UI (see [Getting Started with Android RUM Collection][3] for more information). For security reasons, you must use a client token: you cannot use [Datadog API keys][2] to configure the `dd-sdk-android` library as they would be exposed client-side in the Android application APK byte code. For more information about setting up a client token, see the [client token documentation][1]: - -Kotlin - -```kotlin -class SampleApplication : Application() { - override fun onCreate() { - super.onCreate() - - val configuration = Configuration.Builder(crashReportsEnabled = true, ...) - .addPlugin(NDKCrashReporterPlugin(), Feature.CRASH) - .build() - val credentials = Credentials(, , , ) - Datadog.initialize(this, credentials, configuration, trackingConsent) - } -} -``` - -Java - -```java -public class SampleApplication extends Application { - @Override - public void onCreate() { - super.onCreate(); - Configuration configuration = new Configuration.Builder(true, true, true, true) - .addPlugin(NDKCrashReporterPlugin(), Feature.CRASH) - .build(); - Credentials credentials = new Credentials(, , , ); - Datadog.initialize(this, credentials, configuration, trackingConsent); - } -} -``` - -To be compliant with the GDPR regulation, the SDK requires the tracking consent value at initialization. -The tracking consent can be one of the following values: - -* `TrackingConsent.PENDING`: The SDK starts collecting and batching the data but does not send it to the data - collection endpoint. The SDK waits for the new tracking consent value to decide what to do with the batched data. -* `TrackingConsent.GRANTED`: The SDK starts collecting the data and sends it to the data collection endpoint. -* `TrackingConsent.NOT_GRANTED`: The SDK does not collect any data. You will not be able to manually send any logs, traces, or - RUM events. - -To update the tracking consent after the SDK is initialized, call: `Datadog.setTrackingConsent()`. -The SDK changes its behavior according to the new consent. For example, if the current tracking consent is `TrackingConsent.PENDING` and you update it to: - -* `TrackingConsent.GRANTED`: The SDK sends all current batched data and future data directly to the data collection endpoint. -* `TrackingConsent.NOT_GRANTED`: The SDK wipes all batched data and does not collect any future data. - -Note that in the credentials required for initialization, your application variant name is also required. This is important because it enables the right proguard `mapping.txt` file to be automatically uploaded at build time. This allows a Datadog dashboard to de-obfuscate the stack traces. - -[1]: https://docs.datadoghq.com/account_management/api-app-keys/#client-tokens -[2]: https://docs.datadoghq.com/account_management/api-app-keys/#api-keys -[3]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=us diff --git a/docs/sdk_benchmarks.md b/docs/sdk_benchmarks.md deleted file mode 100644 index 9d0d497d3c..0000000000 --- a/docs/sdk_benchmarks.md +++ /dev/null @@ -1,61 +0,0 @@ -# SDK Usage Benchmarks - -## Concept - -The way we procured the data for our benchmarks was by profiling several popular open source Android applications -([GoogleIO](https://github.com/google/iosched), [RedReader](https://github.com/QuantumBadger/RedReader)). -All profiling sessions were performed on a SAMSUNG GALAXY S9(SM-G960F) device running Android version 10. - -## Benchmarks - -For measuring the SDK performance and Network activity we played with each tested application main functionality for about 2 minutes. -We tried to stay consistent in the use cases performed for both sessions (with Datadog SDK enabled and without). - -#### Performance profiling - -##### GoogleIO - -| Datadog SDK enabled | Max RAM | Max CPU | ENERGY consumption at peak | -|:-------------------:|:-------:|:-------:|:--------------------------:| -| true | 267 MB | 35% | < LIGHT | -| false | 262 MB | 34% | < LIGHT | - -##### RedReader - -| Datadog SDK enabled | Max RAM | Max CPU | ENERGY consumption at peak | -|:-------------------:|:-------:|:-------:|:--------------------------:| -| true | 297 MB | 41% | < LIGHT | -| false | 288 MB | 41% | < LIGHT | - - -#### Network profiling - -##### GoogleIO - -| Endpoint | Network requests | Data sent | Data received | Time interval | -|--------------------------|------------------|-----------|---------------|---------------| -| Datadog RUM | 1 | 14.48 Kb | 31.96 Kb | 2 minutes | -| Datadog Tracing | 1 | 3.96 Kb | 35.40 Kb | 2 minutes | -| Datadog Log | 1 | 13.33 Kb | 31.76 Kb | 2 minutes | -| Application private requests | 6 | 530 Kb | 136.17 Kb | 2 minutes | - - -##### RedReader - -For RedReader we could not auto - instrument the Logs sent inside the application hence the missing data for the **Datadog Logs** endpoint. - -| Endpoint | Network requests | Data sent | Data received | Time interval | -|--------------------------|------------------|-----------|---------------|---------------| -| Datadog RUM | 1 | 102.39 Kb | 32.76 Kb | 2 minutes | -| Datadog Tracing | 1 | 21 Kb | 32.26 Kb | 2 minutes | -| Datadog Logs | | | | | -| Application private requests | 28 | 104 Kb | 252 Kb | 2 minutes | - - -**Notes** - -1. You can observe in our Network profiling data that the max number of requests per each Datadog endpoint in a 2 minutes interval is 1. -That is because we are using the keep alive capability in our OkHttp client to reuse the opened connections during a specific time interval. -2. To display the energy consumption data we are using as measurement unit: LIGHT, MEDIUM, HEAVY. Those are the energy consumption levels - proposed by the Android Profiler tool. - diff --git a/docs/sdk_performance.md b/docs/sdk_performance.md index fa1f84e163..882cc32a09 100644 --- a/docs/sdk_performance.md +++ b/docs/sdk_performance.md @@ -1,30 +1,141 @@ -# SDK Performance +# SDK Performance and impact on the host application -## SDK Size +## Methodology -**The SDK is 723 KB**, measured as the `.aar` package size -without the transitive dependencies. The SDK uses the following transitive dependencies: +To simulate the typical usage of Datadog SDK it was added to the [Docile-Alligator/Infinity-For-Reddit][1] application and typical user behavior (scrolling the feed, browsing reddits) was simulated for 2 minutes 30 seconds. - - androidx.core:core - - androidx.navigation:navigation-fragment-ktx - - androidx.navigation:navigation-ui-ktx - - androidx.navigation:navigation-runtime-ktx - - androidx.recyclerview:recyclerview - - androidx.work:work-runtime - - com.google.code.gson:gson - - com.lyft.kronos:kronos-android - - com.squareup.okhttp3:okhttp - - org.jetbrains.kotlin:kotlin-stdlib +Application used: [Docile-Alligator/Infinity-For-Reddit][1] (revision [e8c9915a](https://github.com/Docile-Alligator/Infinity-For-Reddit/tree/e8c9915a)) +Device used: Google Pixel 6 +Android OS: Android 13 (Build Number TQ2A.230505.002) +Datadog SDK: revision [7f842d343](https://github.com/DataDog/dd-sdk-android/tree/7f842d343) -## Background behavior +Network profiling was done using Charles Proxy 4.6.4. +CPU, Memory, Energy profiling was done using Android Studio Flamingo | 2022.2.1 Patch 1. +Device had 1.6 GB memory free on average (out of 7.6 GB), 115 apps installed and 25 GB of storage was free. +Device was connected to the 4G network, WiFi interface was disabled. + +CPU and Memory profiling was done for the minified `release` build type with `profileable` attribute. CPU profiling was done using the `System Traces` option. + +SDK modules which were added to the application: + +* `dd-sdk-android-logs` +* `dd-sdk-android-trace` +* `dd-sdk-android-rum` +* `dd-sdk-android-okhttp` +* `dd-sdk-android-glide` + +SDK was set up with default settings. + +## Performance profiling + +### Network traffic + +| Measurement | Traffic | +|-------------|----------------------------------------------------------------------| +| #1 | 23 requests: 62.2 KB sent, 22.2 KB received. | +| #2 | 29 requests: 72.5 KB sent, 23.2 KB received. | +| #3 | 28 requests: 86.1 KB sent, 23.2 KB received. | +| #4 | 27 requests: 71.9 KB sent, 23.1 KB received. | +| #5 | 25 requests: 69.8 KB sent, 22.7 KB received. | +| average | 26 requests: 72.5 KB (σ=7.73 KB) sent, 22.9 KB (σ=0.39 KB) received. | + +All requests were sent using `gzip` encoding, compression was around 90%. + +For each measurement round the first request had an initial TLS handshake with certificate chain download, which had a size of 17.5 KB. Removing this single server certificate chain download from calculation leads to the following results. + +| Measurement | Traffic | +|-------------|---------------------------------------------------------------------| +| #1 | 23 requests: 62.2 KB sent, 4.7 KB received. | +| #2 | 29 requests: 72.5 KB sent, 5.7 KB received. | +| #3 | 28 requests: 86.1 KB sent, 5.7 KB received. | +| #4 | 27 requests: 71.9 KB sent, 5.6 KB received. | +| #5 | 25 requests: 69.8 KB sent, 5.2 KB received. | +| average | 26 requests: 72.5 KB sent (σ=7.73 KB), 5.4 KB (σ=0.39 KB) received. | + +### Peak CPU and Memory usage + +**Note**: Measurement without SDK means the measurement of the original application without Datadog SDK added as a dependency. + +| Measurement | CPU with SDK | CPU w/o SDK | Memory with SDK | Memory w/o SDK | +|-------------|-----------------|-----------------|-----------------------|--------------------| +| #1 | 19% | 23% | 432 MB | 413 MB | +| #2 | 32% | 23% | 441 MB | 470 MB | +| #3 | 25% | 27% | 400 MB | 430 MB | +| #4 | 32% | 29% | 453 MB | 432 MB | +| #5 | 26% | 24% | 437 MB | 440 MB | +| average | 26.8% (σ=4.87%) | 25.2% (σ=2.4%) | 432.6 MB (σ=17.72 MB) | 437 MB (σ=18.7 MB) | + +CPU usage pattern was the same, with the majority of the CPU usage below 10% during user interactions with the app and around 1-2% when application was in idle (no interactions performed). +Memory allocation/de-allocation pattern stays the same with and without SDK. + +### Janky frames + +Janky frames are described in the [official Android documentation][2] + +| Measurement | With SDK | Without SDK | +|-------------|-----------------|-----------------| +| #1 | 57/5883 (0.9%) | 69/7781 (0.9%) | +| #2 | 73/6580 (1.1%) | 43/6247 (0.7%) | +| #3 | 57/6323 (0.9%) | 81/6607 (1.2%) | +| #4 | 59/5628 (1.0%) | 81/7688 (1.0%) | +| #5 | 62/6256 (0.9%) | 62/6577 (0.9%) | +| average | 0.96% (σ=0.08%) | 0.94% (σ=0.16%) | + +Datadog SDK doesn't have any meaningful impact on the amount of janky frames in the app. + +### Energy consumption + +Documentation about this metric can be found [here][3]. + +| Measurement | With SDK | Without SDK | +|-------------|----------|-------------| +| #1 | LIGHT | LIGHT | +| #2 | LIGHT | LIGHT | +| #3 | LIGHT | LIGHT | +| #4 | LIGHT | LIGHT | +| #5 | LIGHT | LIGHT | + +### Application Startup Time + +As a reference we measured [Time To Initial Display][4]. + +Cold start was simulated by running the following command (application was killed before run): + +```shell +adb shell am start -S -W ml.docilealligator.infinityforreddit/.activities.MainActivity -c android.intent.category.LAUNCHER -a android.intent.action.MAIN +``` + +| Measurement | With SDK | Without SDK | +|-------------|-------------------|---------------------| +| #1 | 246 ms | 228 ms | +| #2 | 239 ms | 222 ms | +| #3 | 242 ms | 233 ms | +| #4 | 241 ms | 233 ms | +| #5 | 247 ms | 228 ms | +| average | 243 ms (σ=3.4 ms) | 228.8 ms (σ=4.5 ms) | + +SDK and its initialization has no significant impact on the `Time To Initial Display` metric. + +### Application size impact + +The measurement was done for the `2.0.0-beta2` version of Datadog SDK for the `minifiedRelease` application variant. + +`apk` size without Datadog SDK: 11044045 bytes +`apk` size with Datadog SDK: 11566506 bytes + +Datadog SDK added 552 KB to the `apk` size. + +## SDK behavior in the host application + +### Background behavior When the application goes in background: - the auto-instrumentation stops and detaches itself from any UI callbacks (lifecycle events, gesture detection). No RUM event will be automatically tracked but you can still manually send them with the `RumMonitor`. - - The endpoint accepts logs and traces as usual. + - The endpoints accept RUM events, logs and traces as usual. - The endpoints collect and send new batches of data. -## How batches are created and sent +### How batches are created and sent When a new event is ready to be serialized and batched, the persistence layer asks for the last known batch file to store the serialized event. A batch file is valid for appending new data when all the following conditions are met: @@ -38,16 +149,21 @@ valid for appending new data when all the following conditions are met: linearly with every batch sent. The maximum frequency is one batch per second. If there's no batch or network available or the battery level is too low, the upload frequency is linearly decreased to the minimum default value of one batch every 20 seconds. -## Battery consumption +### Battery consumption The SDK does not perform network activity if the device battery level is less than 10% or if the device is in power saving mode. -## Lifespan of the persisted data +### Lifespan of the persisted data The SDK stores data in batches and tries to send those whenever the network is available. A batch will not be stored more than 18 hours in an application. Every time the SDK reads a new batch for sending, will first remove batches that are older than 18 hours. -## Low available storage +### Low available storage The SDK checks the storage space used every time it creates a new batch. If this value is greater than 512 MB (the maximum amount of storage space that the SDK will use), it first tries to make more space available -by removing the older files. +by removing the older files. + +[1]: https://github.com/Docile-Alligator/Infinity-For-Reddit +[2]: https://developer.android.com/studio/profile/jank-detection +[3]: https://developer.android.com/studio/profile/energy-profiler +[4]: https://developer.android.com/topic/performance/vitals/launch-time#time-initial \ No newline at end of file diff --git a/features/dd-sdk-android-logs/README.md b/features/dd-sdk-android-logs/README.md index e3ab5b1ace..fe5370ffe0 100644 --- a/features/dd-sdk-android-logs/README.md +++ b/features/dd-sdk-android-logs/README.md @@ -1,3 +1,5 @@ -# Datadog Library for Logs +# Datadog Logs SDK for Android -## Getting Started +See the dedicated [Datadog Android Log Collection documentation][1] to learn how to forward logs from your Android or Android TV application to Datadog. + +[1]: https://docs.datadoghq.com/logs/log_collection/android/?tab=kotlin \ No newline at end of file diff --git a/features/dd-sdk-android-ndk/README.md b/features/dd-sdk-android-ndk/README.md new file mode 100644 index 0000000000..27f8526d45 --- /dev/null +++ b/features/dd-sdk-android-ndk/README.md @@ -0,0 +1,48 @@ +# Datadog Android Native Crash Collection + +Send crash report for issues rising from the C/C++ code in your application. + +**Note**: Native crash reports can be sent to both RUM and Logs, so you need to add these modules as well. + +## Setup + +```groovy +dependencies { + // if you want to send native crash reports to RUM product + implementation "com.datadoghq:dd-sdk-android-rum:x.x.x" + // if you want to send native crash reports to Logs product + implementation "com.datadoghq:dd-sdk-android-logs:x.x.x" + + implementation "com.datadoghq:dd-sdk-android-ndk:x.x.x" +} +``` + +1. If you want to send native crash reports to RUM, [add and initialize RUM product in your application][1]. +2. If you want to sent native crash reports to Logs, [add and initialize Logs product in your application][2]. +3. Initialize NDK Crash Reporting feature in your application: + +```kotlin +class SampleApplication : Application() { + override fun onCreate() { + super.onCreate() + + // RUM and/or Logs were initialized before + NdkCrashReports.enable() + } +} +``` + +```java +public class SampleApplication extends Application { + @Override + public void onCreate() { + super.onCreate(); + + // RUM and/or Logs were initialized before + NdkCrashReports.enable(); + } +} +``` + +[1]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=kotlin +[2]: https://docs.datadoghq.com/logs/log_collection/android/?tab=kotlin diff --git a/features/dd-sdk-android-rum/README.md b/features/dd-sdk-android-rum/README.md index 4a9f536f97..5a00f30935 100644 --- a/features/dd-sdk-android-rum/README.md +++ b/features/dd-sdk-android-rum/README.md @@ -1,3 +1,5 @@ -# Datadog Library for RUM +# Datadog RUM SDK for Android -## Getting Started +See the dedicated [Datadog Android RUM Collection documentation][1] to learn how to send RUM data from your Android or Android TV application to Datadog. + +[1]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=kotlin \ No newline at end of file diff --git a/features/dd-sdk-android-trace/README.md b/features/dd-sdk-android-trace/README.md index 1e55032666..04ec30ba66 100644 --- a/features/dd-sdk-android-trace/README.md +++ b/features/dd-sdk-android-trace/README.md @@ -1,3 +1,5 @@ -# Datadog Library for Tracing +# Datadog Trace SDK for Android -## Getting Started +See the dedicated [Datadog Android Trace Collection documentation][1] to learn how to send traces from your Android or Android TV application to Datadog. + +[1]: https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/android/?tab=kotlin diff --git a/features/dd-sdk-android-webview/README.md b/features/dd-sdk-android-webview/README.md index a521bc1a09..1929cf19c7 100644 --- a/features/dd-sdk-android-webview/README.md +++ b/features/dd-sdk-android-webview/README.md @@ -1,3 +1,5 @@ -# Datadog Library for WebView integration +# Datadog Web View Integration SDK for Android -## Getting Started +See the dedicated [Datadog Web View Tracking documentation][1] to learn how to monitor and send web views in your Android or Android TV application to Datadog. + +[1]: https://docs.datadoghq.com/real_user_monitoring/android/web_view_tracking diff --git a/integrations/dd-sdk-android-coil/README.md b/integrations/dd-sdk-android-coil/README.md index a1fb109232..ce3a3cd95f 100644 --- a/integrations/dd-sdk-android-coil/README.md +++ b/integrations/dd-sdk-android-coil/README.md @@ -5,45 +5,22 @@ To include the Datadog integration for [Coil][1] in your project, add the following to your application's `build.gradle` file. -``` +```groovy dependencies { - implementation "com.datadoghq:dd-sdk-android:" + implementation "com.datadoghq:dd-sdk-android-rum:" + implementation "com.datadoghq:dd-sdk-android-okhttp:" implementation "com.datadoghq:dd-sdk-android-coil:" } ``` -### Initial setup - -Before using the SDK, set up the library with your application -context, client token, and application ID. -To generate a client token and an application ID, check **UX Monitoring > RUM Applications > New Application** -in the Datadog dashboard. +### Initial Setup -```kotlin -class SampleApplication : Application() { - override fun onCreate() { - super.onCreate() +1. Setup RUM monitoring, see the dedicated [Datadog Android RUM Collection documentation][2] to learn how. +2. Setup OkHttp instrumentation with Datadog RUM SDK, see the [dedicated documentation][3] to learn how. - val configuration = Configuration.Builder( - rumEnabled = true, - ... - ) - .trackInteractions() - .useViewTrackingStrategy(strategy) - ... - .build() - val credentials = Credentials(, , , ) - Datadog.initialize(this, credentials, configuration, trackingConsent) - - val monitor = RumMonitor.Builder().build() - GlobalRum.registerIfAbsent(monitor) - } -} -``` - -Follow Coil's [API documentation][2] to: +Follow Coil's [API documentation][4] to: - - Create your own `ImageLoader` by providing your own OkHttpClient (configured with `DatadogInterceptor`). + - Create your own `ImageLoader` by providing your own `OkHttpClient` (configured with `DatadogInterceptor`). ```kotlin val imageLoader = ImageLoader.Builder(context).okHttpClient(okHttpClient).build() @@ -52,11 +29,11 @@ Follow Coil's [API documentation][2] to: - Decorate the `ImageRequest.Builder` with the `DatadogCoilRequestListener` whenever you perform an image loading request. - ```kotlin - imageView.load(uri){ - listener(DatadogCoilRequestListener()) - } - ``` +```kotlin + imageView.load(uri) { + listener(DatadogCoilRequestListener()) + } +``` This automatically tracks Coil's network requests (creating both APM Traces and RUM Resource events), and listens for disk cache errors (creating RUM Error events). @@ -70,4 +47,6 @@ For details on contributing, read the [Apache License, v2.0](../../LICENSE) [1]: https://github.com/coil-kt/coil -[2]: https://coil-kt.github.io/coil/getting_started/ +[2]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=kotlin +[3]: https://docs.datadoghq.com/real_user_monitoring/android/advanced_configuration/?tab=kotlin#automatically-track-network-requests +[4]: https://coil-kt.github.io/coil/getting_started/ diff --git a/integrations/dd-sdk-android-compose/README.md b/integrations/dd-sdk-android-compose/README.md index 8518b67c13..9a7ad093f9 100644 --- a/integrations/dd-sdk-android-compose/README.md +++ b/integrations/dd-sdk-android-compose/README.md @@ -5,47 +5,19 @@ To include the Datadog integration for [Jetpack Compose][1] in your project, add the following to your application's `build.gradle` file. -``` +```groovy dependencies { - implementation "com.datadoghq:dd-sdk-android:" + implementation "com.datadoghq:dd-sdk-android-rum:" implementation "com.datadoghq:dd-sdk-android-compose:" } ``` -### Initial setup - -Before using the SDK, set up the library with your application -context, client token, and application ID. -To generate a client token and an application ID, check **UX Monitoring > RUM Applications > New Application** -in the Datadog dashboard. - -```kotlin -class SampleApplication : Application() { - override fun onCreate() { - super.onCreate() +### Initial Setup - val configuration = Configuration.Builder( - rumEnabled = true, - ... - ) - .trackInteractions() - .useViewTrackingStrategy(strategy) - ... - .build() - - val credentials = Credentials(, , , ) - Datadog.initialize(this, credentials, configuration, trackingConsent) - - val monitor = RumMonitor.Builder().build() - GlobalRum.registerIfAbsent(monitor) - } -} -``` +1. Setup RUM monitoring, see the dedicated [Datadog Android RUM Collection documentation][2] to learn how. #### Navigation for Compose support -**Support of Navigation for Compose is experimental, because `androidx.navigation:navigation-compose` is still in alpha, so overall API may be a subject to change.** - If you are migrating your existing app to Jetpack Compose, and use fragment-based Navigation as it is recommended in the [guide][2], continue to use `useViewTrackingStrategy` with the strategy which suits you best. If you have an app with only Compose elements, you can add support of view tracking for Navigation for Compose in the following way when `NavController` is created: @@ -60,10 +32,7 @@ You also must reject Activities or Fragments, which are hosts of Compose views d Here is an example in case of `ActivityViewTrackingStrategy` usage: ```kotlin -val configuration = Configuration.Builder( - rumEnabled = true, - ... -) +val configuration = RumConfiguration.Builder(applicationId = applicationId) .useViewTrackingStrategy( ActivityViewTrackingStrategy( trackExtras = ..., @@ -137,4 +106,5 @@ For details on contributing, read the [Apache License, v2.0](../../LICENSE) [1]: https://developer.android.com/jetpack/compose -[2]: https://developer.android.com/jetpack/compose/navigation#interoperability +[2]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=kotlin +[3]: https://developer.android.com/jetpack/compose/navigation#interoperability diff --git a/integrations/dd-sdk-android-fresco/README.md b/integrations/dd-sdk-android-fresco/README.md index b1536dcbbf..9c9ca9e8d9 100644 --- a/integrations/dd-sdk-android-fresco/README.md +++ b/integrations/dd-sdk-android-fresco/README.md @@ -5,43 +5,19 @@ To include the Datadog integration for [Fresco][1] in your project, simply add the following to your application's `build.gradle` file. -``` +```groovy dependencies { - implementation "com.datadoghq:dd-sdk-android:" + implementation "com.datadoghq:dd-sdk-android-rum:" + implementation "com.datadoghq:dd-sdk-android-okhttp:" implementation "com.datadoghq:dd-sdk-android-fresco:" } ``` ### Initial Setup -Before you can use the SDK, you need to setup the library with your application -context, your Client token and your Application ID. -To generate a Client token and an Application ID please check **UX Monitoring > RUM Applications > New Application** -in the Datadog dashboard. - -```kotlin -class SampleApplication : Application() { - override fun onCreate() { - super.onCreate() - - val configuration = Configuration.Builder( - rumEnabled = true, - ... - ) - .trackInteractions() - .useViewTrackingStrategy(strategy) - ... - .build() - val credentials = Credentials(, , , ) - Datadog.initialize(this, credentials, configuration, trackingConsent) - - val monitor = RumMonitor.Builder().build() - GlobalRum.registerIfAbsent(monitor) - } -} -``` - -Following Fresco's [Generated API documentation][2], you need to create your own `OkHttpImagePipelineConfigFactory` by providing your own `OkHttpClient` (configured with `DatadogInterceptor`). You can also add an instance of `DatadogFrescoCacheListener` in your `DiskCacheConfig`. +1. Setup RUM monitoring, see the dedicated [Datadog Android RUM Collection documentation][2] to learn how. +2. Setup OkHttp instrumentation with Datadog RUM SDK, see the [dedicated documentation][3] to learn how. +3. Following Fresco's [Generated API documentation][4], you need to create your own `OkHttpImagePipelineConfigFactory` by providing your own `OkHttpClient` (configured with `DatadogInterceptor`). You can also add an instance of `DatadogFrescoCacheListener` in your `DiskCacheConfig`. Doing so will automatically track Fresco's network requests (creating both APM Traces and RUM Resource events), and will also listen for disk cache errors (creating RUM Error events). @@ -68,4 +44,6 @@ would like to change. For more information, read the [Apache License, v2.0](../../LICENSE) [1]: https://github.com/facebook/fresco -[2]: https://frescolib.org/docs/index.html +[2]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=kotlin +[3]: https://docs.datadoghq.com/real_user_monitoring/android/advanced_configuration/?tab=kotlin#automatically-track-network-requests +[4]: https://frescolib.org/docs/index.html diff --git a/integrations/dd-sdk-android-glide/README.md b/integrations/dd-sdk-android-glide/README.md index cdc9d685c3..90c88ddcfe 100644 --- a/integrations/dd-sdk-android-glide/README.md +++ b/integrations/dd-sdk-android-glide/README.md @@ -5,42 +5,19 @@ To include the Datadog integration for [Glide][1] in your project, simply add the following to your application's `build.gradle` file. -``` +```groovy dependencies { - implementation "com.datadoghq:dd-sdk-android:" + implementation "com.datadoghq:dd-sdk-android-rum:" + implementation "com.datadoghq:dd-sdk-android-trace:" implementation "com.datadoghq:dd-sdk-android-glide:" } ``` ### Initial Setup -Before you can use the SDK, you need to setup the library with your application -context, your Client token and your Application ID. -To generate a Client token and an Application ID please check **UX Monitoring > RUM Applications > New Application** -in the Datadog dashboard. - -```kotlin -class SampleApplication : Application() { - - override fun onCreate() { - super.onCreate() - - val configuration = Configuration.Builder().build() - val credentials = Credentials( - , - , - , - - ) - Datadog.initialize(this, credentials, configuration, trackingConsent) - - val monitor = RumMonitor.Builder().build() - GlobalRum.registerIfAbsent(monitor) - } -} -``` - -Following Glide's [Generated API documentation][2], you then need to create your own `GlideAppModule` with Datadog integrations by extending the `DatadogGlideModule`, as follow. +1. Setup RUM monitoring, see the dedicated [Datadog Android RUM Collection documentation][2] to learn how. +2. Setup Trace monitoring, see the dedicated [Datadog Android Trace Collection documentation][3] to learn how. +3. Following Glide's [Generated API documentation][4], you then need to create your own `GlideAppModule` with Datadog integrations by extending the `DatadogGlideModule`, as follow. Doing so will automatically track Glide's network requests (creating both APM Traces and RUM Resource events), and will also listen for disk cache and image transformation errors (creating RUM Error events). @@ -48,13 +25,12 @@ Doing so will automatically track Glide's network requests (creating both APM Tr @GlideModule class CustomGlideModule : DatadogGlideModule( - listOf("example.com", "example.eu"), traceSamplingRate = 20f + firstPartyHosts = listOf("example.com", "example.eu"), sampleRate = 20f ) ``` Network requests are sampled with an adjustable sampling rate. A sampling of 20% is applied by default. - ## Contributing Pull requests are welcome, but please open an issue first to discuss what you @@ -66,4 +42,6 @@ would like to change. For more information, read the [Apache License, v2.0](../../LICENSE) [1]: https://bumptech.github.io/glide/ -[2]: https://bumptech.github.io/glide/doc/generatedapi.html \ No newline at end of file +[2]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=kotlin +[3]: https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/android/?tab=kotlin +[4]: https://bumptech.github.io/glide/doc/generatedapi.html \ No newline at end of file diff --git a/integrations/dd-sdk-android-ktx/README.md b/integrations/dd-sdk-android-ktx/README.md index 8f12df1943..9b6d5f288b 100644 --- a/integrations/dd-sdk-android-ktx/README.md +++ b/integrations/dd-sdk-android-ktx/README.md @@ -5,42 +5,12 @@ To include the Datadog extensions for Kotlin in your project, simply add the following to your application's `build.gradle` file. -``` +```groovy dependencies { - implementation "com.datadoghq:dd-sdk-android:" implementation "com.datadoghq:dd-sdk-android-ktx:" } ``` -### Initial Setup - -Before you can use the SDK, you need to setup the library with your application -context, your Client token and your Application ID. -To generate a Client token and an Application ID please check **UX Monitoring > RUM Applications > New Application** -in the Datadog dashboard. - -```kotlin -class SampleApplication : Application() { - override fun onCreate() { - super.onCreate() - - val configuration = Configuration.Builder( - rumEnabled = true, - ... - ) - .trackInteractions() - .useViewTrackingStrategy(strategy) - ... - .build() - val credentials = Credentials(, , , ) - Datadog.initialize(this, credentials, configuration, trackingConsent) - - val monitor = RumMonitor.Builder().build() - GlobalRum.registerIfAbsent(monitor) - } -} -``` - ### Extension #### Running a lambda within a Span @@ -62,7 +32,7 @@ You can mark a span as having an error using one of the following `error()` meth try { // … } catch (e: IOException) { - span.error(e) + span.setError(e) } span.finish() ``` @@ -70,11 +40,25 @@ You can mark a span as having an error using one of the following `error()` meth ```kotlin val span = tracer.buildSpan("").start() if (invalidState) { - span.error("Something unexpected happened") + span.setError("Something unexpected happened") } span.finish() ``` +#### `Closeable` extension methods: + +```kotlin + +// Executes the given [block] function on the [Closeable] instance, intercepts any Exception and sends it in +// a RUM error event closing the [Closeable] instance afterwards. + +val closeable: Closeable = ... +closeable.useMonitored { + // Your code here +} + +``` + #### OkHttp Request extension method If you are using the `DatadogInterceptor` to trace your OkHttp requests, you can add a parent span using the `parentSpan()` method. @@ -90,7 +74,7 @@ If you are using the `DatadogInterceptor` to trace your OkHttp requests, you can If you're using coroutines, you can trace the coroutine blocks using one of the following method. They behave like the usual coroutine methods, and simply require a span operation name. ```kotlin - fun doSomething(){ + fun doSomething() { GlobalScope.launchTraced("", Dispatchers.IO) { // … } @@ -113,7 +97,6 @@ If you're using coroutines, you can trace the coroutine blocks using one of the } ``` - #### Reporting Coroutine Flow errors If you're using Kotlin Coroutine Flow, you can propagate Flow errors to your RUM dashboard using the `sendErrorToDatadog()` method. @@ -133,7 +116,7 @@ If you're using Kotlin Coroutine Flow, you can propagate Flow errors to your RUM If you are using SQLiteDatabase to persist data locally, you can trace the database transaction using the following method: ```kotlin - sqliteDatabase.transactionTraced("",isExclusive){ database -> + sqliteDatabase.transactionTraced("",isExclusive) { database -> // Your queries here database.insert("", null, contentValues) diff --git a/integrations/dd-sdk-android-okhttp/README.md b/integrations/dd-sdk-android-okhttp/README.md index 85c6f19d9a..1bf1507565 100644 --- a/integrations/dd-sdk-android-okhttp/README.md +++ b/integrations/dd-sdk-android-okhttp/README.md @@ -1,3 +1,5 @@ -# Datadog instrumentation for OkHttp +# Datadog SDK instrumentation for OkHttp -## Getting Started +See the dedicated [Datadog SDK instrumentation for OkHttp documentation][1] to learn how track network requests made by `OkHttp` library automatically. + +[1]: https://docs.datadoghq.com/real_user_monitoring/android/advanced_configuration/?tab=kotlin#automatically-track-network-requests \ No newline at end of file diff --git a/integrations/dd-sdk-android-rx/README.md b/integrations/dd-sdk-android-rx/README.md index 94cb6ab2cd..a63caa9252 100644 --- a/integrations/dd-sdk-android-rx/README.md +++ b/integrations/dd-sdk-android-rx/README.md @@ -5,43 +5,17 @@ To include the Datadog integration for [RxJava][1] in your project, simply add the following to your application's `build.gradle` file. -``` +```groovy dependencies { - implementation "com.datadoghq:dd-sdk-android:" + implementation "com.datadoghq:dd-sdk-android-rum:" implementation "com.datadoghq:dd-sdk-android-rx:" } ``` ### Initial Setup -Before you can use the SDK, you need to setup the library with your application -context, your Client token and your Application ID. -To generate a Client token and an Application ID please check **UX Monitoring > RUM Applications > New Application** -in the Datadog dashboard. - -```kotlin -class SampleApplication : Application() { - override fun onCreate() { - super.onCreate() - - val configuration = Configuration.Builder( - rumEnabled = true, - ... - ) - .trackInteractions() - .useViewTrackingStrategy(strategy) - ... - .build() - val credentials = Credentials(, , , ) - Datadog.initialize(this, credentials, configuration, trackingConsent) - - val monitor = RumMonitor.Builder().build() - GlobalRum.registerIfAbsent(monitor) - } -} -``` - -Following RxJava's [Generated API documentation][2], you just have to apply the `doOnError` operator on your `Observable`, +1. Setup RUM monitoring, see the dedicated [Datadog Android RUM Collection documentation][2] to learn how. +2. Following RxJava's [Generated API documentation][3], you just have to apply the `doOnError` operator on your `Observable`, `Flowable`, `Single`, `Maybe` or `Completable` and pass an instance of `DatadogErrorConsumer`. Doing so will automatically intercept any Exception thrown in the upper stream by creating RUM Error events. @@ -58,7 +32,7 @@ Java: Kotlin: -```java +```kotlin Observable.create{...} .publishErrorsToRum() ... @@ -75,4 +49,5 @@ would like to change. For more information, read the [Apache License, v2.0](../../LICENSE) [1]: https://github.com/ReactiveX/RxJava -[2]: https://github.com/ReactiveX/RxJava/wiki \ No newline at end of file +[2]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=kotlin +[3]: https://github.com/ReactiveX/RxJava/wiki \ No newline at end of file diff --git a/integrations/dd-sdk-android-sqldelight/README.md b/integrations/dd-sdk-android-sqldelight/README.md index ff6f91a8c3..53f452eda8 100644 --- a/integrations/dd-sdk-android-sqldelight/README.md +++ b/integrations/dd-sdk-android-sqldelight/README.md @@ -5,43 +5,19 @@ To include the Datadog integration for [SQLDelight][1] in your project, simply add the following to your application's `build.gradle` file. -``` +```groovy dependencies { - implementation "com.datadoghq:dd-sdk-android:" + implementation "com.datadoghq:dd-sdk-android-rum:" + implementation "com.datadoghq:dd-sdk-android-trace:" implementation "com.datadoghq:dd-sdk-android-sqldelight:" } ``` ### Initial Setup -Before you can use the SDK, you need to setup the library with your application -context, your Client token and your Application ID. -To generate a Client token and an Application ID please check **UX Monitoring > RUM Applications > New Application** -in the Datadog dashboard. - -```kotlin -class SampleApplication : Application() { - override fun onCreate() { - super.onCreate() - - val configuration = Configuration.Builder( - rumEnabled = true, - ... - ) - .trackInteractions() - .useViewTrackingStrategy(strategy) - ... - .build() - val credentials = Credentials(, , , ) - Datadog.initialize(this, credentials, configuration, trackingConsent) - - val monitor = RumMonitor.Builder().build() - GlobalRum.registerIfAbsent(monitor) - } -} -``` - -Following SQLDelight's [Generated API documentation][1], you just have to provide the `DatadogSqliteCallback` in the +1. Setup RUM monitoring, see the dedicated [Datadog Android RUM Collection documentation][2] to learn how. +2. Setup Trace monitoring, see the dedicated [Datadog Android Trace Collection documentation][3] to learn how. +3. Following SQLDelight's [Generated API documentation][1], you just have to provide the `DatadogSqliteCallback` in the `AndroidSqliteDriver` constructor. Doing this detects whenever a database is corrupted and sends a relevant @@ -61,18 +37,18 @@ RUM error event for it. If you are using SQLDelight transactions, you can trace the transaction block using the following 2 methods: ```kotlin - database.yourQuery.transactionTraced("", noEnclosing){ + database.yourQuery.transactionTraced("", noEnclosing) { // … } ``` ```kotlin - val result = database.yourQuery.transactionTracedWithResult("", noEnclosing){ + val result = database.yourQuery.transactionTracedWithResult("", noEnclosing) { // … } ``` -They behave as the default methods (`transaction(noEnclosing,block)`, `transactionWithResult(noEnclosing,block`) and they simply require a span name as an +They behave as the default methods (`transaction(noEnclosing,block)`, `transactionWithResult(noEnclosing,block)`) and they simply require a span name as an extra argument. ## Contributing @@ -86,3 +62,5 @@ would like to change. For more information, read the [Apache License, v2.0](../../LICENSE) [1]: https://cashapp.github.io/sqldelight/android_sqlite/ +[2]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=kotlin +[3]: https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/android/?tab=kotlin diff --git a/integrations/dd-sdk-android-timber/README.md b/integrations/dd-sdk-android-timber/README.md index ee112b04ca..099e1157dc 100644 --- a/integrations/dd-sdk-android-timber/README.md +++ b/integrations/dd-sdk-android-timber/README.md @@ -5,54 +5,19 @@ To include the Datadog integration for Timber in your project, simply add the following to your application's `build.gradle` file. -``` +```groovy dependencies { - implementation "com.datadoghq:dd-sdk-android:" + implementation "com.datadoghq:dd-sdk-android-logs:" implementation "com.datadoghq:dd-sdk-android-timber:" } ``` ### Initial Setup -Before you can use the SDK, you need to setup the library with your application -context and your API token. You can create a token from the Integrations > API -in Datadog. **Make sure you create a key of type `Client Token`.** - -Once Datadog is initialized, you can then create a `Logger` instance using the -dedicated builder, and integrate it in Timber, as follows: - -```kotlin -class SampleApplication : Application() { - override fun onCreate() { - super.onCreate() - - val configuration = Configuration.Builder( - rumEnabled = true, - ... - ) - .trackInteractions() - .useViewTrackingStrategy(strategy) - ... - .build() - val credentials = Credentials(, , , ) - Datadog.initialize(this, credentials, configuration, trackingConsent) - - val monitor = RumMonitor.Builder().build() - GlobalRum.registerIfAbsent(monitor) +1. Setup RUM monitoring, see the dedicated [Datadog Android Log Collection documentation][1] to learn how. +2. That's it, now all your Timber logs will be sent to Datadog automatically. - val logger = Logger.Builder() - .setNetworkInfoEnabled(true) - .setLogcatLogsEnabled(true) - .setDatadogLogsEnabled(true) - .build(); - Timber.plant(DatadogTree(logger)) - } -} -``` - -That's it, now all your Timber logs will be sent to Datadog automatically. - -You can configure the logger's tags and attributes, as explained in the [Datadog Android log collection documentation](http://docs.datadoghq.com/logs/log_collection/android) +You can configure the logger's tags and attributes, as explained in the [Datadog Android Log Collection documentation][1] ## Contributing @@ -63,3 +28,5 @@ would like to change. For more information, read the ## License [Apache License, v2.0](../../LICENSE) + +[1]: https://docs.datadoghq.com/logs/log_collection/android/?tab=kotlin diff --git a/integrations/dd-sdk-android-tv/README.md b/integrations/dd-sdk-android-tv/README.md index 624e256460..827125cdd8 100644 --- a/integrations/dd-sdk-android-tv/README.md +++ b/integrations/dd-sdk-android-tv/README.md @@ -6,73 +6,40 @@ To include the Datadog integration for Android TV in your project, add the follo ```groovy dependencies { - implementation "com.datadoghq:dd-sdk-android:" + implementation "com.datadoghq:dd-sdk-android-rum:" implementation "com.datadoghq:dd-sdk-android-tv:" } ``` ### Initial Setup -Before using the SDK, you need to setup the library with your application context, client token, and application ID. - -To generate a client token and an application ID, navigate to **UX Monitoring** > **RUM Applications** and click [**New Application**][2]. - -To receive more information about RUM action events for Android TV applications, provide the [`LeanbackViewAttributesProvider`][1] when initializing the SDK. +1. Setup RUM monitoring, see the dedicated [Datadog Android RUM Collection documentation][1] to learn how. +2. To receive more information about RUM action events for Android TV applications, provide the `LeanbackViewAttributesProvider` when configuring RUM. #### Kotlin Example ```kotlin - class SampleApplication : Application() { - override fun onCreate() { - super.onCreate() - val configuration = Configuration.Builder( - logsEnabled = true, - tracesEnabled = true, - crashReportsEnabled = true, - rumEnabled = true - ) - .useSite(DatadogSite.US1) - .trackInteractions(touchTargetExtraAttributesProviders = arrayOf(LeanbackViewAttributesProvider())) - .trackLongTasks(durationThreshold) - .useViewTrackingStrategy(strategy) - .build() - val credentials = Credentials(, , , ) - Datadog.initialize(this, credentials, configuration, trackingConsent) - } - } + val rumConfiguration = RumConfiguration.Builder(applicationId) + ... + .trackInteractions(touchTargetExtraAttributesProviders = arrayOf(LeanbackViewAttributesProvider())) + .build() ``` #### Java Example ```java -public class SampleApplication extends Application { - @Override - public void onCreate() { - super.onCreate(); - final Configuration configuration = - new Configuration.Builder(true, true, true, true) - .trackInteractions(new ViewAttributesProvider[]{new LeanbackViewAttributesProvider()}) - .trackLongTasks(durationThreshold) - .useViewTrackingStrategy(strategy) - .useSite(DatadogSite.US1) - .build(); - final Credentials credentials = new Credentials( < CLIENT_TOKEN >, , < - APP_VARIANT_NAME >, ); - Datadog.initialize(this, credentials, configuration, trackingConsent); - } -} + RumConfiguration rumConfiguration = new RumConfiguration.Builder(applicationId) + ... + .trackInteractions(new ViewAttributesProvider[]{new LeanbackViewAttributesProvider()}) + .build(); ``` ## Contributing -Pull requests are welcome. Open an issue first to discuss what you would like to change. For more information, see our [Contributing Guide][4]. +Pull requests are welcome. Open an issue first to discuss what you would like to change. For more information, see our [Contributing Guide](../../CONTRIBUTING.md). ## License -[Apache License, v2.0][5] +[Apache License, v2.0](../../LICENSE) -[1]: https://github.com/DataDog/dd-sdk-android/blob/master/dd-sdk-android-tv/src/main/kotlin/com/datadog/android/tv/LeanbackViewAttributesProvider.kt -[2]: https://app.datadoghq.com/rum/application/create -[3]: https://github.com/DataDog/dd-sdk-android/blob/master/dd-sdk-android-tv/README.md -[4]: https://github.com/DataDog/dd-sdk-android/blob/master/CONTRIBUTING.md -[5]: https://github.com/DataDog/dd-sdk-android/blob/master/LICENSE +[1]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=kotlin