Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/embrace-io/embrace-android-sdk
Embrace's Android SDK built on OpenTelemetry
https://github.com/embrace-io/embrace-android-sdk
android crash crash-reporting embrace exception-reporting java java-android kotlin kotlin-android network-monitoring sdk
Last synced: 5 days ago
JSON representation
Embrace's Android SDK built on OpenTelemetry
- Host: GitHub
- URL: https://github.com/embrace-io/embrace-android-sdk
- Owner: embrace-io
- License: apache-2.0
- Created: 2023-10-13T13:23:51.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-29T14:42:33.000Z (3 months ago)
- Last Synced: 2024-10-29T14:46:29.636Z (3 months ago)
- Topics: android, crash, crash-reporting, embrace, exception-reporting, java, java-android, kotlin, kotlin-android, network-monitoring, sdk
- Language: Kotlin
- Homepage: https://embrace.io/docs/android/
- Size: 11.7 MB
- Stars: 134
- Watchers: 12
- Forks: 11
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[](https://codecov.io/gh/embrace-io/embrace-android-sdk)
[](https://dash.embrace.io/signup/)
[](https://github.com/embrace-io/embrace-android-sdk/actions)
[](https://shields.io/github/v/release/embrace-io/embrace-android-sdk)
# About
The Embrace Android SDK builds on top of [OpenTelemetry](https://opentelemetry.io) to capture performance data for
Android apps, enabling full-stack observability of your system by connecting mobile and backend telemetry in a seamless way.
Telemetry recorded through this SDK can be consumed on the Embrace platform for Embrace customers, but it can also be used by those who are
not Embrace customers to export collected data directly to any OTel Collector, either one that they host or is hosted by other vendors.
In effect, this SDK is an alternative to [opentelemetry-android](https://github.com/open-telemetry/opentelemetry-android) or using the [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java) directly for Android apps that want to leverage the
OpenTelemetry ecosystem for observability, but also want all the advanced telemetry capture that Embrace is known for like ANR thread sampling, native crash
capture, and so forth.
Currently, only Spans and Logs are supported, but other signals will be added in the future.
# Getting Started
### Android Project Setup
1. In your app's Gradle file, add a dependency to the latest version of the Embrace Swazzler Gradle plugin: `io.embrace:embrace-swazzler:`.
- This plugin is responsible for configuring your app at build time to auto-capture telemetry. This includes:
- Updating dependencies to include optional modules that are needed for certain features.
- Setting up configuration files to be read at runtime.
- Doing bytecode instrumentation to enable the capture of certain telemetry.
2. For multi-module projects, in the Gradle files of modules you want to invoke Embrace SDK API methods, add a dependency to the main Embrace SDK module: `'io.embrace:embrace-android-sdk:`.
3. In the `main` directory of your app's root source folder (i.e. `app/src/main/`), add in a file called `embrace-config.json` that contains `{}` as its only line.
- To further configure the SDK, additional attributes can be added to this configuration file.
- See our [configuration documentation page](https://embrace.io/docs/android/features/configuration-file/) for further details.
4. In your app's Gradle properties file, add in the entry `embrace.disableMappingFileUpload=true`
- This allows the SDK to function without sending data to Embrace.
5. In Android Studio, do a Gradle Sync. Barring any errors, you should be able to configure and start the SDK to begin recording and exporting data.
### Configure Exporters and Start SDK
Using the Embrace SDK without being an Embrace customer requires you to set up OTel Exporters to work with the SDK so that recorded telemetry can be sent somewhere.
To do that, create and configure instances of your chosen exporters and register them with the Embrace SDK before you start it.
```kotlin
val grafanaCloudExporter = OtlpHttpSpanExporter.builder()
.setEndpoint("https://myinstance.grafana.net/otlp/v1/traces")
.addHeader("Authorization", "YourToken")
.build()
Embrace.getInstance().addSpanExporter(grafanaCloudExporter)
Embrace.getInstance().addLogRecordExporter(SystemOutLogRecordExporter.create())
```
It is recommended that you start the Embrace SDK in the your `Application` object's `onCreate()` function (or even earlier) to minimize
the amount of time when telemetry isn't being recorded. This allows performance problems such as crashes and ANRs to be captured as soon
as possible.
```kotlin
internal class MyApplication : Application() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Do your exporter setup before starting the SDK
Embrace.getInstance().start(this)
}
}
```
For details about the features the Embrace Android SDK supports, refer to our [features page](https://embrace.io/docs/android/features/).
## Prospective Embrace Customers
- If you want to try out the Embrace product along with using this SDK, [go to our website](https://dash.embrace.io/signup/) and begin the sign up process.
- After you've obtained an `appId` and `API token`, checkout our [integration guide](https://embrace.io/docs/android/integration/) for further instructions.
## Existing Embrace Customers Upgrading from 5.x
- For existing customers on older versions of the Embrace SDK, follow the instructions in our [upgrade guide](https://github.com/embrace-io/embrace-android-sdk/blob/main/UPGRADING.md).
## Support
We appreciate any feedback you have on the SDK and the APIs that is provides. To contribute to this project please see our [Contribution Guidelines](https://github.com/embrace-io/embrace-android-sdk/blob/master/CONTRIBUTING.md) there you'll be able to submit a feature request, create a bug report, or submit a pull request.
For urgent matters (such as outages) or issues concerning the Embrace service or UI reach out in our [Community Slack](https://join.slack.com/t/embraceio-community/shared_invite/zt-ywr4jhzp-DLROX0ndN9a0soHMf6Ksow) for direct, faster assistance.
Embrace Android SDK is published under the Apache-2.0 license.
[](./LICENSE.txt)