{"id":39032641,"url":"https://github.com/aws-observability/aws-otel-android","last_synced_at":"2026-01-17T17:41:43.001Z","repository":{"id":325196859,"uuid":"962892875","full_name":"aws-observability/aws-otel-android","owner":"aws-observability","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-09T10:04:07.000Z","size":2561,"stargazers_count":2,"open_issues_count":10,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-11T19:37:43.076Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-observability.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-08T20:49:15.000Z","updated_at":"2025-12-10T21:17:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aws-observability/aws-otel-android","commit_stats":null,"previous_names":["aws-observability/aws-otel-android"],"tags_count":1,"template":false,"template_full_name":"amazon-archives/__template_Apache-2.0","purl":"pkg:github/aws-observability/aws-otel-android","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-observability","download_url":"https://codeload.github.com/aws-observability/aws-otel-android/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-android/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28513972,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T17:41:42.841Z","updated_at":"2026-01-17T17:41:42.954Z","avatar_url":"https://github.com/aws-observability.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Distro for OpenTelemetry - Android\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n## Overview\n\nThis repo contains the AWS Distro for OpenTelemetry (ADOT) on Android. It is a bundle that ships a few things out of the box:\n1. OpenTelemetry Java SDK (https://github.com/open-telemetry/opentelemetry-java)\n2. OpenTelemetry Android automated instrumentation (https://github.com/open-telemetry/opentelemetry-android)\n   - This includes instrumentation for telemetry like ANRs, Crashes, Activity lifecycle, etc\n4. Additional automated instrumentation not currently part of upstream OpenTelemetry Android, like the \"Time to first draw\" telemetry\n5. AWS-specific exporter and auth configuration that works out of the box when exporting telemetry to AWS CloudWatch Real User Monitoring (RUM)\n\nThe distro is preconfigured for seamless integration with [AWS CloudWatch RUM](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-RUM.html).\n\n**Key Benefits:**\n- **Zero-code instrumentation** for most common Android telemetry\n- **AWS-native integration** with CloudWatch RUM and Application Signals\n- **Production-ready** with minimal performance overhead\n- **Comprehensive monitoring** including crashes, ANRs, UI performance, and network requests\n- **Flexible configuration** supporting both programmatic and configuration file setup\n\n## Quick Start\n\n### 1. Add Dependencies\n\nAdd to your app's `build.gradle`. For a Kotlin DSL example:\n\n```kotlin\ndependencies {\n    // For automatic instrumentation (recommended; see below for programmatic configuration)\n    implementation(\"software.amazon.opentelemetry.android:agent:1.0.0\")\n\n    // For HTTP instrumentation with ByteBuddy\n    byteBuddy(\"io.opentelemetry.android.instrumentation:okhttp3-agent:0.15.0-alpha\")           // if you are using OkHttp-3.0\n    byteBuddy(\"io.opentelemetry.android.instrumentation:httpurlconnection-agent:0.15.0-alpha\") // if you are using URLConnection / HttpURLConnection / HttpsURLConnection\n}\n```\n\n### 2. Configuration\n\n#### Option A: Zero-Code Configuration (Agent)\n\nCreate `res/raw/aws_config.json`:\n\n```jsonc\n{\n  \"aws\": {\n    \"region\": \"\u003cyour region\u003e\",\n    \"rumAppMonitorId\": \"\u003cyour app monitor id\u003e\",\n\n    // optional, if you have a resource-based policy with an alias\n    \"rumAlias\": \"\u003cyour rum alias\"\n  },\n\n  // optional resource attributes, but recommended\n  \"otelResourceAttributes\": {\n    \"service.name\": \"MyApplication\",\n    \"service.namespace\": \"MyTeam\",\n    \"service.version\": \"1.0.0\",\n    \"deployment.environment\": \"production\"\n    // ... plus any additional custom resource attributes you want to define\n  }\n}\n```\n\nThat's it! That's the minimum you need to automatically initialize the Android agent and start collecting telemetry into your RUM app monitor.\n\n#### Option B: Programmatic Configuration\n\nIf you want to configure the client programmatically, you can depend on the lightweight **core** module instead of the **agent**:\n\n```kotlin\ndependencies {\n    implementation(\"software.amazon.opentelemetry.android:core:LATEST_VERSION\")\n}\n```\n\n```kotlin\nimport io.opentelemetry.sdk.resources.Resource\nimport software.amazon.opentelemetry.android.OpenTelemetryRumClient\n\nclass MyApplication : Application() {\n   override fun onCreate() {\n      super.onCreate()\n\n      OpenTelemetryRumClient {\n         androidApplication = this@MyApplication\n         awsRum {\n            region = \"us-east-1\"\n            appMonitorId = \"\u003cyour-app-monitor-id\u003e\"\n         }\n         otelResource = Resource.builder()\n            .put(\"service.name\", \"testAppName\")\n            .put(\"service.version\", \"1.0\")\n            .build()\n      }\n   }\n}\n```\n\n- [Read more about custom instrumentation you can manually enable](docs/custom_instrumentation.md)\n- [Read more about configuring the SDK with authentication](docs/auth.md)\n\n## Feature modules\n\nThe library consists of several modules designed for flexibility and modularity:\n\n| Module                                   | Description                                 | Use Case                           |\n|------------------------------------------|---------------------------------------------|------------------------------------|\n| **[agent](agent/README.md)**             | Zero-code auto-instrumentation              | Easiest setup, automatic telemetry |\n| **[core](core/README.md)**               | Main OpenTelemetry client and configuration | Manual setup, full control         |\n| **[api](api/README.md)**                 | Public API for custom instrumentation       | Adding custom spans and metrics    |\n| **[ui-loading](ui-loading/README.md)**   | UI performance monitoring                   | Time-to-first-draw tracking        |\n| **[aws-runtime](aws-runtime/README.md)** | AWS authentication and exporters            | SigV4 signing                      |\n\n## Supported Instrumentation\n\n| Instrumentation        | Telemetry generated                          | Automatic or Manual                                        |\n|------------------------|----------------------------------------------|------------------------------------------------------------|\n| **Activity Lifecycle** | Activity creation, start, resume tracking    | Automatic                                                  |\n| **Fragment Lifecycle** | Fragment lifecycle and navigation            | Automatic                                                  |\n| **Network Requests**   | HTTP/HTTPS via URLConnection and OkHttp      | Automatic (w/ ByteBuddy)                                   |\n| **Crash Reporting**    | Unhandled exceptions and system crashes      | Automatic                                                  |\n| **ANR Detection**      | Application Not Responding events            | Automatic                                                  |\n| **UI Performance**     | Time-to-first-draw, slow rendering           | Automatic for Activities (manual Fragment instrumentation) |\n| **Custom Spans**       | Application-specific instrumentation         | Manual                                                     |\n| **Slow rendering**     | Reports when app interface is slow or frozen | Automatic                                                  |\n| **Sessions**           | Reports when user sessions start or end      | Automatic                                                  |\n\n## Requirements\n\n- **Android API Level**: 26 (Android 8.0) or higher\n- **Kotlin**: 1.8.0 or higher\n- **Java**: 8 or higher\n- **Gradle**: 7.0 or higher\n\n## Examples\n\nExplore our comprehensive [demo applications](demo-apps/):\n\n- **[Agent Demo](demo-apps/agent-demo/)** - Zero-configuration auto-instrumentation\n- **[Crash Demo](demo-apps/crash-demo/)** - Crash reporting demonstration\n- **[ANR Demo](demo-apps/anr-demo/)** - ANR detection example\n\n## Version Management\n\n### Version Bumping\n\nThe repository includes a script to manage version bumping across relevant files. The script updates versions in:\n- `gradle.properties` (project version)\n- `README.md` (documentation references, if any)\n\n#### Manual Version Bumping\n\nUse the `scripts/bump-version.sh` script for version control:\n\n**Patch Version** (x.y.z → x.y.z+1):\n```bash\n./scripts/bump-version.sh patch\n```\n\n**Minor Version** (x.y.z → x.y+1.0):\n```bash\n./scripts/bump-version.sh minor\n```\n\n**Major Version** (x.y.z → x+1.0.0):\n```bash\n./scripts/bump-version.sh major\n```\n\n**Specific Version**:\n```bash\n./scripts/bump-version.sh 2.1.3\n```\n\n**With Automatic Commit and Tag**:\n```bash\n./scripts/bump-version.sh patch --commit-tag\n```\n\nThe script will prompt for confirmation before making changes and creates backups of modified files.\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:\n\n- Setting up the development environment\n- Running tests and building the project\n- Submitting pull requests\n- Reporting issues\n\n## Support\n\n- **GitHub Issues**: For bug reports and feature requests\n- **AWS Support**: Enterprise customers can create support tickets\n- **Documentation**: Comprehensive guides in the [docs/](docs/) directory\n- **Community**: Join discussions in GitHub Discussions\n\n## License\n\nThis project is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\n## Security issue notifications\n\nIf you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.\n\n## Related Projects\n\n- **[OpenTelemetry Android](https://github.com/open-telemetry/opentelemetry-android)** - Upstream OpenTelemetry Android SDK\n- **[AWS SDK for Android](https://github.com/aws-amplify/aws-sdk-android)** - AWS SDK for Android applications\n- **[AWS CloudWatch RUM](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-RUM.html)** - Real User Monitoring service\n- **[AWS Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals.html)** - Application performance monitoring\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-observability%2Faws-otel-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-observability%2Faws-otel-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-observability%2Faws-otel-android/lists"}