Skip to content

Commit

Permalink
RUMM-3465: Update documentation for SDK v2
Browse files Browse the repository at this point in the history
  • Loading branch information
@0xnm
0xnm committed Jul 24, 2023
1 parent 842da6c commit 63d22a4
Show file tree
Hide file tree
Showing 23 changed files with 407 additions and 690 deletions.
39 changes: 23 additions & 16 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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/**'
Expand Down Expand Up @@ -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.


Expand All @@ -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
}
}
Expand Down
35 changes: 23 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
Expand All @@ -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()
Expand All @@ -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()
Expand All @@ -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).

<div class="alert alert-warning">
Expand All @@ -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
[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/
138 changes: 30 additions & 108 deletions dd-sdk-android-core/README.md
View file
Original file line number Diff line number Diff line change
@@ -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:<latest-version>"
implementation "com.datadoghq:dd-sdk-android-rum:<latest-version>"
}
```

Expand All @@ -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(<name>)` and use the `Datadog.isInitialized(<name>)` 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<String, Object> 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:
Expand All @@ -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
Loading

0 comments on commit 63d22a4

Please sign in to comment.