@barrysolomon/mobile-react-native 0.2.0-alpha → 0.2.1-alpha

package/README.md

@@ -1,23 +1,52 @@
-# @dash0/mobile-react-native
+# @barrysolomon/mobile-react-native
 
 Dash0 Mobile Observability SDK for React Native. Bridges JS/TS into the
 existing native Android (`otel-android-mobile`) and iOS (`otel-ios-mobile`)
 SDKs — native owns buffering, policy evaluation, OTLP export, and crash
 recovery. JS stays thin.
 
-**Status:** Complete and validated end-to-end in Dash0. Both Android and iOS
-builds produce real binaries (140 MB APK, 239 MB .app) and telemetry lands in
-Dash0 within ~3 s. All 4 platforms (Android native, iOS native, RN Android,
-RN iOS) have a UAT matrix of 12/12 cells green. 83 Jest tests pass.
+**Version:** `0.2.1-alpha`, published under the `alpha` dist-tag.
+
+**Status:** Validated end-to-end in Dash0. All 4 platforms (Android native,
+iOS native, RN Android, RN iOS) have a UAT matrix of 12/12 cells green.
+
+## Install
+
+```bash
+# Install the alpha (a bare `npm install @barrysolomon/mobile-react-native`
+# resolves the OLD 0.1.0-alpha — always pin the dist-tag or version):
+npm install @barrysolomon/mobile-react-native@alpha
+# or pin the exact version:
+# npm install @barrysolomon/mobile-react-native@0.2.1-alpha
+
+cd ios && pod install
+```
+
+This JS package wraps the native SDKs; install those too:
+
+- **iOS** — add the Swift Package `https://github.com/barrysolomon/mobile-otel`
+  at tag `v0.2.1-alpha` to your app target, then copy
+  `OTelMobileCallSink.swift` (+ `BoundedLiveSpanStore.swift`) from this package
+  into your app target and call
+  `Dash0MobileModule.installSink { OTelMobileCallSink() }`. The pod intentionally
+  excludes the sink because it depends on the SwiftPM SDK delivered on the app
+  side.
+- **Android** — `io.opentelemetry.android:mobile:0.2.1-alpha` from GitHub
+  Packages (`https://maven.pkg.github.com/barrysolomon/mobile-otel`). As of
+  0.2.0-alpha the full module set (`mobile-core` + all
+  `mobile-instrumentation-*` modules) publishes there, so the dependency tree
+  resolves.
 
 ## Quickstart
 
 ```ts
-import { Dash0Mobile } from '@dash0/mobile-react-native';
+import { Dash0Mobile } from '@barrysolomon/mobile-react-native';
 
 await Dash0Mobile.start({
   serviceName: 'my-rn-app',
-  endpoint: 'https://ingress.us-west-2.aws.dash0.com/v1/logs',
+  // Base ingress host — per-signal URLs are built as
+  // `<endpoint>/v1/{logs,traces,metrics}`; do NOT append `/v1/...` yourself.
+  endpoint: 'https://ingress.us-west-2.aws.dash0.com',
   authToken: process.env.DASH0_AUTH_TOKEN,
   dataset: 'otel-mobile',
 });
@@ -35,7 +64,7 @@ await Dash0Mobile.span('checkout', async () => {
 # Install dependencies (first time)
 npm install
 
-# Jest — bridge contract + auto-instrumentation (83 tests)
+# Jest — bridge contract + auto-instrumentation
 npm test
 
 # Type-check
@@ -53,34 +82,56 @@ src/
     types.ts           # cross-repo seam — DO NOT change without coordinating
     NativeBridge.ts    # debounced batching marshaller (50 ms batch window)
   instrumentation/
-    fetch.ts           # fetch/XHR span auto-capture
-    xhr.ts             # XHR span auto-capture
+    fetch.ts           # fetch span shim (non-RN/web; off on RN — fetch is XHR-backed)
+    xhr.ts             # XHR span shim (authoritative JS layer; gated off on Android)
     errors.ts          # JS error log auto-capture
     unhandledRejection.ts  # unhandled promise rejection capture
-    navigation.ts      # React Navigation screen-view auto-capture
-    touch.ts           # tap event auto-capture
+    navigation.ts      # React Navigation screen-view auto-capture (opt-in)
+    touch.ts           # tap event auto-capture (opt-in via withTapTelemetry)
   otel-compat.ts       # OTel-API shim (third-party JS libs flow through bridge)
   index.ts             # public API
-android/               # Kotlin ReactContextBaseJavaModule + BridgeCallSink
-ios/                   # Swift RCTDash0MobileModule + BridgeCallSink
-__tests__/             # Jest — 83 tests across bridge + instrumentation
+android/               # Kotlin ReactContextBaseJavaModule + OkHttp net interceptor
+ios/                   # Swift RCTDash0MobileModule + OTelMobileCallSink
+__tests__/             # Jest — bridge contract + instrumentation suites
 ```
 
 ## Auto-instrumentation
 
-Enabled by default when `Dash0Mobile.start()` is called. Opt out per signal:
+`network` and `errors` are enabled by default when `Dash0Mobile.start()` is
+called. Opt out per signal:
 
 ```ts
 await Dash0Mobile.start({
   // ...
   autoCapture: {
-    network: false,   // disable fetch/XHR spans
-    errors: false,    // disable JS error + rejection logs
-    lifecycle: false, // disable AppState fg/bg
+    network: false,   // disable HTTP capture (JS fetch/XHR shims + native net)
+    errors: false,    // disable JS error + unhandled-rejection logs
   },
 });
 ```
 
+App lifecycle (`app.foreground` / `app.background` / `app.start`) is **always
+on via native instrumentation** (Android `ProcessLifecycleOwner`, iOS
+`NotificationCenter`) — there is no JS or per-flag knob for it. The other
+`autoCapture` flags (`tap`, `scroll`, `textInput`, `screen`, `freeze`,
+`vitals`, `deviceStats`, `screenshot`, `wireframe`) toggle native-only capture
+suites and default **off** on RN.
+
+### HTTP capture on Android is native (Expo SDK 52+)
+
+On Android, network capture is owned by a native OkHttp interceptor
+(`OTelNetworkInterceptor`) installed before JS runs. It records native CLIENT
+spans and injects a W3C `traceparent` from the real native span context, so
+Android mobile→backend traces stitch. The JS `XMLHttpRequest` shim is
+auto-gated **off** on Android to avoid double-counting.
+
+This matters because **Expo SDK 52+ replaced the global `fetch` with
+`expo/fetch`, a non-XHR-backed client.** The JS `fetch`/XHR shims wrap the JS
+globals and see nothing there — only the native interceptor (which sits under
+OkHttp) captures `expo/fetch` traffic. On iOS the JS XHR shim is kept (RN iOS
+`fetch` is XHR-backed and the native `URLProtocol` swizzle is opt-in/off by
+default for RN).
+
 ## Sampling
 
 **The RN bridge defaults to `always_on` (100% of spans)** — unlike the native
@@ -117,15 +168,18 @@ native SDK on each platform:
 ```text
 JS (fetch/XHR/errors/nav/tap)
   ↓  50 ms batch window
-NativeBridge.ts  →  NativeDash0Mobile  →  Android: OTelMobile (gRPC :4317)
-                                      →  iOS:     OTelMobile (HTTP :4318)
+NativeBridge.ts  →  NativeDash0Mobile  →  Android: OTelMobile (OTLP/HTTP)
+                                      →  iOS:     OTelMobile (OTLP/HTTP)
                                                 ↓
                                           OTLP Collector → Dash0
 ```
 
-**Transport note:** Android uses OTLP/gRPC on port 4317; iOS uses OTLP/HTTP on
-port 4318. The shared `otel-config.json` uses a per-platform port rewrite at
-startup — do not assume a single endpoint works for both.
+**Transport note:** As of 0.2.0-alpha both platforms default to OTLP/HTTP
+(protobuf) against a single endpoint, with per-signal URLs built as
+`<endpoint>/v1/{logs,traces,metrics}`. Android changed from gRPC to HTTP so
+exports traverse HTTPS-terminating proxies / managed ingress that can't forward
+HTTP/2 gRPC. gRPC-only collector? Restore it on Android with
+`MobileConfig.protocol = OtlpProtocol.GRPC`.
 
 ## Test strategy
 
@@ -133,12 +187,16 @@ Three layers, all must pass on every PR:
 
 1. **Jest** — `npm test` in this directory; contract + bridge + instrumentation
 2. **Native unit** — `./gradlew :android:test` (Android) + `swift test` (iOS)
-3. **Real-app E2E** — `scripts/test/validate-rn-end-to-end.sh` boots
-   AstronomyShopRN on iOS Simulator + Android emulator, queries Dash0 after 75 s
+3. **Real-app E2E** — `scripts/test/validate-rn-end-to-end.sh` (use `--mode=jest`
+   for the package + AstronomyShopRN demo tests; `--mode=device` boots
+   AstronomyShopRN on iOS Simulator + Android emulator and queries Dash0)
 
 ## Known limitations
 
-- **Expo** — not supported without eject (bare workflow only). An Expo config
-  plugin is planned as a follow-up.
+- **Expo** — works in the bare/dev-client workflow (native modules required).
+  0.2.0-alpha was hardened against a real Expo SDK 56 / RN 0.85 integration,
+  including the Expo SDK 52+ `expo/fetch` capture via native Android
+  instrumentation (see above). A managed-workflow config plugin (no prebuild)
+  is tracked as a follow-up (EXPO-001).
 - **Realm / Amplify DataStore** — scoped in a separate epic.
 - **Web / desktop RN targets** — not supported.

package/android/build.gradle

@@ -97,7 +97,7 @@ ext.reactAndroidVersion = project.findProperty('Dash0Mobile_reactAndroidVersion'
 // dependency strings (which silently drifted to 0.1.0-alpha vs the published
 // 0.2.0-alpha and broke clean-.m2 CI while passing on caches that still had the
 // old artifact).
-ext.dash0SdkVersion = project.findProperty('Dash0Mobile_sdkVersion') ?: '0.2.0-alpha'
+ext.dash0SdkVersion = project.findProperty('Dash0Mobile_sdkVersion') ?: '0.2.1-alpha'
 
 dependencies {
     implementation "com.facebook.react:react-android:$reactAndroidVersion"

package/android/gradle.properties

@@ -11,9 +11,9 @@ org.gradle.jvmargs=-Xmx2g -Dfile.encoding=UTF-8
 Dash0Mobile_standaloneTestBuild=true
 
 # Version of the native Android SDK (io.opentelemetry.android:mobile) this module
-# depends on. MUST match the version the repo publishes (currently 0.2.0-alpha).
+# depends on. MUST match the version the repo publishes (currently 0.2.1-alpha).
 # Single source of truth, read by build.gradle's dash0SdkVersion.
-Dash0Mobile_sdkVersion=0.2.0-alpha
+Dash0Mobile_sdkVersion=0.2.1-alpha
 
 # Pin the Kotlin version the module's build.gradle reads (it defaults to
 # 2.1.20 and honors this property) so stdlib matches the compiler the

package/lib/index.js

@@ -105,7 +105,7 @@ function resolveNative() {
 // callers and correlate issues to a specific bridge release. Keep this in
 // sync with package.json on each release.
 const DISTRO_NAME = 'dash0-react-native';
-const DISTRO_VERSION = '0.1.0-alpha';
+const DISTRO_VERSION = '0.2.1-alpha';
 function resolveReactNativeVersion() {
     try {
         // eslint-disable-next-line @typescript-eslint/no-var-requires

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barrysolomon/mobile-react-native",
-  "version": "0.2.0-alpha",
+  "version": "0.2.1-alpha",
   "description": "Dash0 Mobile Observability SDK for React Native (JS/TS bridge). For native iOS use the Swift Package at https://github.com/barrysolomon/mobile-otel. For native Android use io.opentelemetry.android:mobile on GitHub Packages.",
   "main": "lib/index.js",
   "module": "lib/index.js",

package/src/index.ts

@@ -142,7 +142,7 @@ function resolveNative(): NativeDash0MobileModule | null {
 // callers and correlate issues to a specific bridge release. Keep this in
 // sync with package.json on each release.
 const DISTRO_NAME = 'dash0-react-native';
-const DISTRO_VERSION = '0.1.0-alpha';
+const DISTRO_VERSION = '0.2.1-alpha';
 
 function resolveReactNativeVersion(): string | undefined {
   try {