diff --git a/README.md b/README.md index 0833de985..133ba241d 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,13 @@ * [Features](#contributing) * [Contributing](#contributing) -# About +## About The repository contains the OpenTelemetry Android SDK for generating mobile client telemetry for real user monitoring (RUM). It is built on top of the [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java). -# Getting Started +## Getting Started > If your project's minSdk is lower than 26, then you must enable > [corelib desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring). @@ -52,7 +52,7 @@ dependencies { } ``` -# Features +## Features This android library builds on top of the [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java). @@ -69,6 +69,8 @@ Some of the additional features provided include: * [Slow / frozen render detection](./instrumentation/slowrendering) * Offline buffering of telemetry via storage +For a bundled “everything on” experience during evaluation/development, see the optional [`instrumentation-all` module](./instrumentation/all/README.md). + Note: Use of these features is not yet well documented. ## Exporter Chain @@ -77,21 +79,21 @@ The SDK performs asynchronous exporter initialization with an in-memory bufferin disk buffering for offline scenarios. See [Exporter Chain documentation](./docs/EXPORTER_CHAIN.md) for details, customization hooks, and ordering semantics. -# Contributing +## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). -### Maintainers +## Maintainers -- [Cesar Munoz](https://github.com/likethesalad), Elastic -- [Jason Plumb](https://github.com/breedx-splk), Splunk +* [Cesar Munoz](https://github.com/likethesalad), Elastic +* [Jason Plumb](https://github.com/breedx-splk), Splunk For more information about the maintainer role, see the [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#maintainer). -### Approvers +## Approvers -- [Hanson Ho](https://github.com/bidetofevil), Embrace -- [Manoel Aranda Neto](https://github.com/marandaneto), PostHog +* [Hanson Ho](https://github.com/bidetofevil), Embrace +* [Manoel Aranda Neto](https://github.com/marandaneto), PostHog For more information about the approver role, see the [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#approver). diff --git a/instrumentation/all/README.md b/instrumentation/all/README.md new file mode 100644 index 000000000..56e122c18 --- /dev/null +++ b/instrumentation/all/README.md @@ -0,0 +1,73 @@ +# instrumentation-all (aggregate) + +Status: development + +The `instrumentation-all` module aggregates all currently available end‑user Android instrumentation libraries in this repository +behind a single dependency coordinate. It is intended for quick evaluation, prototyping, demo apps, or exploratory +testing—NOT for long‑term production builds (where you should declare only what you use to minimize size, method count, +and initialization overhead). + +## When to use + +Use this module when you want to see “everything working” without hunting down each instrumentation artifact. Once you +decide which signals you actually want, replace this aggregate with the individual modules. + +## Installation + +Add the BOM and the aggregate artifact: + +```kotlin +dependencies { + api(platform("io.opentelemetry.android:opentelemetry-android-bom:")) + implementation("io.opentelemetry.android:instrumentation-all:") +} +``` + +Replace `` with the desired release (the aggregate will follow the repository's published versioning). If you +already use `android-agent`, you typically do NOT also need `instrumentation-all`; `instrumentation-all` is mostly for +manual / modular setups or experimentation. + +## Included (at time of writing) + +Feature / library instrumentation modules bundled: + +* activity +* anr +* crash +* fragment +* network +* slowrendering +* sessions +* startup +* view-click +* compose:click +* okhttp3 (library) +* okhttp3-websocket (library) +* httpurlconnection (library) +* android-log (library) + +Supporting foundational modules: + +* common-api +* android-instrumentation + +Excluded by design: + +* `*:agent` variants (bytecode / agent specific, not needed in normal Android app packaging) +* `*:testing` helpers + +## Telemetry + +This module does not produce telemetry on its own—it simply re-exports other instrumentation modules. See the +individual instrumentation READMEs for emitted spans/logs/metrics. + +## Maintenance / Updating + +When a new instrumentation module is added to the repository, append an `api(project("..."))` entry inside +`instrumentation/all/build.gradle.kts` and update the lists above. PRs that add new instrumentation should include that +change. + +## Production Guidance + +Avoid depending on this aggregate in production apps: it can increase APK size, method count, memory, and startup work +by pulling in features you may not enable. Prefer explicit, minimal dependencies. diff --git a/instrumentation/all/api/all.api b/instrumentation/all/api/all.api new file mode 100644 index 000000000..e69de29bb diff --git a/instrumentation/all/build.gradle.kts b/instrumentation/all/build.gradle.kts new file mode 100644 index 000000000..4cbc2f17d --- /dev/null +++ b/instrumentation/all/build.gradle.kts @@ -0,0 +1,48 @@ +plugins { + id("otel.android-library-conventions") + id("otel.publish-conventions") +} + +description = "OpenTelemetry Android aggregate: all available instrumentation features" + +android { + namespace = "io.opentelemetry.android.instrumentation.all" + + defaultConfig { + // No consumer rules; this module just aggregates others. + } +} + +dependencies { + api(platform(libs.opentelemetry.platform.alpha)) + api(libs.opentelemetry.api) + // Core/common building blocks some instrumentations rely on transitively + api(project(":instrumentation:common-api")) + api(project(":instrumentation:android-instrumentation")) + + // Feature instrumentations (add new ones here as they are added to the repo) + api(project(":instrumentation:activity")) + api(project(":instrumentation:anr")) + api(project(":instrumentation:crash")) + api(project(":instrumentation:fragment")) + api(project(":instrumentation:network")) + api(project(":instrumentation:slowrendering")) + api(project(":instrumentation:sessions")) + api(project(":instrumentation:startup")) + api(project(":instrumentation:view-click")) + // Compose specific (click tracking) + api(project(":instrumentation:compose:click")) + // HTTP client / networking related (OkHttp3, WebSocket, HttpURLConnection) + api(project(":instrumentation:okhttp3:library")) + api(project(":instrumentation:okhttp3-websocket:library")) + api(project(":instrumentation:httpurlconnection:library")) + // Android log instrumentation (library flavor) + api(project(":instrumentation:android-log:library")) + + // SDK / internal dependencies required by some features + implementation(project(":services")) + implementation(project(":session")) + implementation(project(":common")) + implementation(libs.opentelemetry.sdk) + implementation(libs.opentelemetry.instrumentation.api) +}