From 54d09d7e473c118a3ea13a537397ba719a5b3cd7 Mon Sep 17 00:00:00 2001 From: Pierre Guceski Date: Thu, 2 Jan 2020 11:59:10 +0100 Subject: [PATCH] group doc in docs folder --- README.md | 69 +------ .../Migrating_To_1.0.0.md | 12 +- docs/README.md | 6 + screenshot.png => docs/images/screenshot.png | Bin docs/log_collection.md | 184 ++++++++++++++++++ 5 files changed, 203 insertions(+), 68 deletions(-) rename Migrating_To_1.0.0.md => docs/Migrating_To_1.0.0.md (87%) create mode 100644 docs/README.md rename screenshot.png => docs/images/screenshot.png (100%) create mode 100644 docs/log_collection.md diff --git a/README.md b/README.md index fbd7e4bc29..6cae6741ac 100644 --- a/README.md +++ b/README.md @@ -2,82 +2,27 @@ > A client-side Android library to interact with Datadog. -## Getting Started +## Getting Started -### Gradle Dependency - -To include the Datadog SDK for Android in your project, simply add the following -to your application's `build.gradle` file. - -``` -repositories { - maven { url "https://dl.bintray.com/datadog/datadog-maven" } -} - -dependencies { - implementation "com.datadoghq:dd-sdk-android:" -} -``` +See the dedicated [Datadog Android log collection documentation](http://docs.datadoghq.com/logs/log_collection/android) to learn how to forward logs from your Androind application to Datadog. ### Migrating from earlier versions -If you were a user of the SDK version `0.2.5` or lower, take a look at our -[Migration Guide](Migrating_To_1.0.0.md). - -### 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`.** - -```kotlin -class SampleApplication : Application() { - - override fun onCreate() { - super.onCreate() - Datadog.initialize(this, BuildConfig.DD_CLIENT_TOKEN) - } -} -``` - -You can create a `Logger` instance using the dedicated builder, as follow: - -```kotlin - logger = Logger.Builder().build(); -``` - -You can then send logs with the following methods, mimicking the ones available -in the Android Framework: - -```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!") -``` - -For more information on the SDK capabilities, you can read a more complete [Documentation](dd-sdk-android/README.md). - +If you were a user of the SDK version `0.2.5` or lower, take a look at our [Migration Guide](docs/Migrating_To_1.0.0.md). ### Integrating with Timber -If you're existing codebase is already using Timber, you can migrate to Datadog -easily by using our [dedicated library](dd-sdk-android-timber/README.md). +If you're existing codebase is already using Timber, you can migrate to Datadog easily by using our [dedicated library](dd-sdk-android-timber/README.md). ## Looking up your logs -When you open your console in Datadog, navigate to the Logs section, and in the search bar, type -`source:mobile`. This will filter your logs to only show the ones coming from mobile applications -(Android and iOS). +When you open your console in Datadog, navigate to the Logs section, and in the search bar, type `source:mobile`. This will filter your logs to only show the ones coming from mobile applications (Android and iOS). -![Datadog Mobile Logs](screenshot.png) +![Datadog Mobile Logs](docs/images/screenshot.png) ## Contributing -Pull requests are welcome, but please open an issue first to discuss what you -would like to change. For more information, read the -[Contributing Guide](CONTRIBUTING.md). +Pull requests are welcome, but please open an issue first to discuss what you would like to change. For more information, read the [Contributing Guide](CONTRIBUTING.md). ## License diff --git a/Migrating_To_1.0.0.md b/docs/Migrating_To_1.0.0.md similarity index 87% rename from Migrating_To_1.0.0.md rename to docs/Migrating_To_1.0.0.md index b26ae7c4d2..6a84c01bbc 100644 --- a/Migrating_To_1.0.0.md +++ b/docs/Migrating_To_1.0.0.md @@ -1,6 +1,6 @@ # Migrating to 1.0.0 -If you've been using the former SDK (version `0.1.x` or `0.2.x`), there are some breaking changes +If you've been using the former SDK (version `0.1.x` or `0.2.x`), there are some breaking changes introduced in version `1.0.0`, namely: ### Logger.Builder @@ -14,7 +14,7 @@ introduced in version `1.0.0`, namely: .build("my-api-key"); ``` -#### After +#### After ```java Datadog.initialize(context, "my-api-key"); @@ -28,9 +28,9 @@ introduced in version `1.0.0`, namely: .setLogcatLogsEnabled(true) .build(); ``` - + #### Attributes -The attributes were created or removed with the `Logger.addField()` or `Logger.removeField()` -methods. These methods were rename for consistency purposes, and are now `Logger.addAttribute()` - and`Logger.removeAttribute()`, but they will behave the same way as the old ones. \ No newline at end of file +The attributes were created or removed with the `Logger.addField()` or `Logger.removeField()` +methods. These methods were rename for consistency purposes, and are now `Logger.addAttribute()` + and`Logger.removeAttribute()`, but they will behave the same way as the old ones. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..22c36c7ef7 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,6 @@ +# Datadog Android SDK documentation + +Find in this folder dedicated documentation to: + +* [Collect and send logs from your Android application to Datadog](docs/log_collection.md) +* [Migrating from earlier versions to the v1.0 of the dd-sdk-android](docs/Migrating_To_1.0.0). diff --git a/screenshot.png b/docs/images/screenshot.png similarity index 100% rename from screenshot.png rename to docs/images/screenshot.png diff --git a/docs/log_collection.md b/docs/log_collection.md new file mode 100644 index 0000000000..5b956bcc17 --- /dev/null +++ b/docs/log_collection.md @@ -0,0 +1,184 @@ +# Android Log Collection + +Send logs to Datadog from your Android applications with [Datadog's `dd-sdk-android` client-side Kotlin logging library][1] and leverage the following features: + +* Log to Datadog in JSON format natively. +* Add `context` and extra custom attributes to each log sent. +* Forward Java/Kotlin caught exceptions automatically. +* Record real client IP addresses and User Agent. +* Optimized network usage with automatic bulk posts. + +**Note**: The `dd-sdk-android` library supports all Android versions from API level 21 (Lollipop). + +## Setup + +1. Add the Gradle dependency by declaring the libbrary as a dependency in your `build.gradle` file: + + ```conf + repositories { + maven { url "https://dl.bintray.com/datadog/datadog-maven" } + } + + dependencies { + implementation "com.datadoghq:dd-sdk-android:x.x.x" + } + ``` + +2. Initialize the library with your application context and your Datadog Client token. A [Datadog client token][2] is used here for security reasons, [Datadog API keys][3] cannot be used to configure the `dd-sdk-android` library as they would be exposed client-side in the Android application APK bytecode. For more information about setting up a client token, see the [Client token documentation][2]: + + {{< tabs >}} + {{% tab "US" %}} + +```kotlin +class SampleApplication : Application() { + override fun onCreate() { + super.onCreate() + Datadog.initialize(this, BuildConfig.DD_CLIENT_TOKEN) + } +} +``` + + {{% /tab %}} + {{% tab "EU" %}} + +```kotlin +class SampleApplication : Application() { + override fun onCreate() { + super.onCreate() + Datadog.initialize(this, BuildConfig.DD_CLIENT_TOKEN, Datadog.DATADOG_EU) + } +} +``` + + {{% /tab %}} + {{< /tabs >}} + +3. Send a custom log entry directly to Datadog with one of the following functions: + + ```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!") + ``` + + Exceptions caught can be sent with a message as follow: + + ```kotlin + try { + doSomething() + } catch (e : IOException) { + logger.e("Error while doing something", e) + } + ``` + + **Note**: All logging methods can have a throwable attached to them. + +4. (Optional) - Provide a map alongside your log message to add attributes to the emitted log. Each entry of the map is added as an attribute. + + ```kotlin + logger.i("onPageStarted", attributes = mapOf("http.url", url)) + ``` + + In java you would have: + + ```java + Logger.d( + "onPageStarted", + null, + new HashMap() {{ + put("http.url", url); + }} + ); + ``` + +## Advanced logging + +### Initialization + +The following parameters can be used when initializing the logger to send logs to Datadog: + +| Method | Description | +|----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `setNetworkInfoEnabled(true)` | Add `network.client.connectivity` attribute to all log. The data logged by default is `connectivity` (`Wifi`, `3G`, `4G`...) and `carrier_name` (`AT&T - US`). `Carrier_name` is only available for Android API level 28 and above. | +| `setServiceName()` | Set `` as value for the `service` [standard attribute][4] attached to all log sent to Datadog. | +| `setLogcatLogsEnabled(true)` | Set to `true` to use Logcat as logger. | +| `setDatadogLogsEnabled(true)` | Set to `true` to send logs to Datadog. | +| `setLoggerName()` | Set `` as value for the `logger.name` attribute attached to all log sent to Datadog. | +| `setVerbosity(Log.INFO)` | Set the verbosity of the logger. All internal messages in the library with a priority equal or higher than the provided level will be logged to Android's LogCat. | +| `build()` | Build a new logger instance with all options set. | + +### Global configuration + +Find below functions to add/remove tags and attributes to all logs sent by a given logger. + +#### Global Tags + +##### Add Tags + +Use the `addTag("","")` function to add tags to all logs sent by a specific logger: + +```kotlin +// This adds a tag "build_type:debug" or "build_type:release" accordingly +logger.addTag("build_type", BuildConfig.BUILD_TYPE) + +// This adds a tag "device:android" +logger.addTag("device", "android") +``` + +**Note**: `` must be a String. + +##### Remove Tags + +Use the `removeTagsWithKey("")` function to remove tags from all logs sent by a specific logger: + +```kotlin +// This removes any tag starting with "build_type" +logger.removeTagsWithKey("build_type") +``` + +[Learn more about Datadog tags][5]. + +#### Global Attributes + +##### Add attributes + +By default, the following attributes are added to all logs send by a logger: + +* `http.useragent` and its extracted `device` and `OS` properties +* `network.client.ip` and its extracted geographical properties (`country`, `city`) + +Use the `addAttribute("", "")` function to add a custom attribute to all logs sent by a specific logger: + +```kotlin +// This adds an attribute "version_code" with an integer value +logger.addAttribute("version_code", BuildConfig.VERSION_CODE) + +// This adds an attribute "version_name" with a String value +logger.addAttribute("version_name", BuildConfig.VERSION_NAME) +``` + +**Note**: `` can be any primitive, String, or Date. + +##### Remove attributes + +Use the `removeAttribute("", "")` function to remove a custom attribute from all logs sent by a specific logger: + +```kotlin +// This removes the attribute "version_code" from all further log send. +logger.removeAttribute("version_code") + +// This removes the attribute "version_name" from all further log send. +logger.removeAttribute("version_name") +``` + +## Further Reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://github.com/DataDog/dd-sdk-android +[2]: https://docs.datadoghq.com/account_management/api-app-keys/#client-tokens +[3]: https://docs.datadoghq.com/account_management/api-app-keys/#api-keys +[4]: https://docs.datadoghq.com/logs/processing/attributes_naming_convention/ +[5]: https://docs.datadoghq.com/tagging/