diff --git a/.github/resources/expo-observe.svg b/.github/resources/expo-observe.svg
new file mode 100644
index 00000000000000..37864ef44fb0fc
--- /dev/null
+++ b/.github/resources/expo-observe.svg
@@ -0,0 +1,19 @@
+
diff --git a/docs/pages/eas/observe/get-started.mdx b/docs/pages/eas/observe/get-started.mdx
index 24947317f7afaa..aa5fe9e743a2bb 100644
--- a/docs/pages/eas/observe/get-started.mdx
+++ b/docs/pages/eas/observe/get-started.mdx
@@ -231,7 +231,7 @@ For details on filtering, release comparison, and session investigation, see the
You can also query metrics from the terminal using the EAS CLI:
- `eas observe:versions`: Lists app versions along with their build IDs, update group IDs, and release dates. Useful for finding the version identifiers needed to filter the other commands.
-- `eas observe:metrics-summary`: Shows aggregated performance metric statistics (such as median, p75, and p95 values) grouped by app version. Use this to compare overall startup performance across releases.
+- `eas observe:metrics-summary`: Shows aggregated performance metric statistics (such as median, p90, and p99 values) grouped by app version. Use this to compare overall startup performance across releases.
- `eas observe:metrics`: Shows individual performance metric events ordered by value, including session and device metadata. Use this to investigate specific slow sessions or outliers.
- `eas observe:routes`: Shows navigation metrics (cold and warm time to first render, and time to interactive) grouped by route name. Requires the [Expo Router](/eas/observe/integrations/expo-router/) or [React Navigation](/eas/observe/integrations/react-navigation/) integration.
- `eas observe:session`: Shows the full event timeline for a single session.
diff --git a/docs/pages/versions/unversioned/sdk/observe.mdx b/docs/pages/versions/unversioned/sdk/observe.mdx
index b6fb9e40e698f6..5e95c77d3c2e8d 100644
--- a/docs/pages/versions/unversioned/sdk/observe.mdx
+++ b/docs/pages/versions/unversioned/sdk/observe.mdx
@@ -3,6 +3,7 @@ title: Observe
description: A library that collects app performance metrics and user-defined events and dispatches them to EAS Observe.
sourceCodeUrl: 'https://github.com/expo/expo/tree/main/packages/expo-observe'
packageName: 'expo-observe'
+iconUrl: '/static/images/packages/expo-observe.png'
platforms: ['android', 'ios', 'tvos']
---
diff --git a/docs/pages/versions/v55.0.0/sdk/observe.mdx b/docs/pages/versions/v55.0.0/sdk/observe.mdx
index fcb1f6e8b12894..8a959c0296eb18 100644
--- a/docs/pages/versions/v55.0.0/sdk/observe.mdx
+++ b/docs/pages/versions/v55.0.0/sdk/observe.mdx
@@ -3,6 +3,7 @@ title: Observe
description: A library that collects app performance metrics and dispatches them to EAS Observe.
sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-55/packages/expo-observe'
packageName: 'expo-observe'
+iconUrl: '/static/images/packages/expo-observe.png'
platforms: ['android', 'ios', 'tvos']
---
diff --git a/docs/pages/versions/v56.0.0/sdk/observe.mdx b/docs/pages/versions/v56.0.0/sdk/observe.mdx
index d8a70452289d72..66158f1f53d2ac 100644
--- a/docs/pages/versions/v56.0.0/sdk/observe.mdx
+++ b/docs/pages/versions/v56.0.0/sdk/observe.mdx
@@ -3,6 +3,7 @@ title: Observe
description: A library that collects app performance metrics and user-defined events and dispatches them to EAS Observe.
sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-56/packages/expo-observe'
packageName: 'expo-observe'
+iconUrl: '/static/images/packages/expo-observe.png'
platforms: ['android', 'ios', 'tvos']
---
diff --git a/docs/pages/versions/v57.0.0/sdk/observe.mdx b/docs/pages/versions/v57.0.0/sdk/observe.mdx
index 1bb6b2f4b15972..c5ea56ed618970 100644
--- a/docs/pages/versions/v57.0.0/sdk/observe.mdx
+++ b/docs/pages/versions/v57.0.0/sdk/observe.mdx
@@ -3,6 +3,7 @@ title: Observe
description: A library that collects app performance metrics and user-defined events and dispatches them to EAS Observe.
sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-57/packages/expo-observe'
packageName: 'expo-observe'
+iconUrl: '/static/images/packages/expo-observe.png'
platforms: ['android', 'ios', 'tvos']
---
diff --git a/docs/public/static/images/packages/expo-observe.png b/docs/public/static/images/packages/expo-observe.png
new file mode 100644
index 00000000000000..ab691fd73f90ce
Binary files /dev/null and b/docs/public/static/images/packages/expo-observe.png differ
diff --git a/packages/expo-observe/README.md b/packages/expo-observe/README.md
index a154491f5e74d3..708c70a741b463 100644
--- a/packages/expo-observe/README.md
+++ b/packages/expo-observe/README.md
@@ -1,32 +1,138 @@
-# expo-observe
+
-Expo module that dispatches collected app metrics to EAS Observe
+**React Native performance monitoring, from the team that builds Expo.**
-# API documentation
+`expo-observe` measures how fast your app starts and how fast each screen becomes usable, on real user devices and real networks. It is open source, it speaks OpenTelemetry, and the endpoint is replaceable.
-- [Documentation for the latest stable release](https://docs.expo.dev/versions/latest/sdk/docs.expo.dev/)
-- [Documentation for the main branch](https://docs.expo.dev/versions/unversioned/sdk/docs.expo.dev/)
+The app you are building is not the app your users are using. They run several versions of it at once, on hundreds of device models, on connections nothing like yours. `expo-observe` measures what each of them actually experiences.
-# Installation in managed Expo projects
+There are two parts, and they are separable:
-For [managed](https://docs.expo.dev/archive/managed-vs-bare/) Expo projects, please follow the installation instructions in the [API documentation for the latest stable release](#api-documentation). If you follow the link and there is no documentation available then this library is not yet usable within managed projects — it is likely to be included in an upcoming Expo SDK release.
+- **`expo-observe`** (this package) is the open source instrumentation. It collects metrics, events and logs from production apps and transmits them over the OpenTelemetry Protocol.
+- **EAS Observe** is the service that stores and analyzes that data. It is also the only destination that can join a metric to the EAS build, the OTA update and the commit behind it, because it is the same system that produced them.
-# Installation in bare React Native projects
+You can use the library without the service. The default endpoint is EAS Observe.
-For bare React Native projects, you must ensure that you have [installed and configured the `expo` package](https://docs.expo.dev/bare/installing-expo-modules/) before continuing.
+## Platforms supported
-### Add the package to your npm dependencies
+Android, iOS, and tvOS.
+## Requirements
+
+- Expo SDK 55 or later
+- An EAS project (`extra.eas.projectId` in your app config, or run `eas init`)
+- A development or production build. `expo-observe` does not run in Expo Go.
+
+## Setup
+
+Three steps.
+
+**1. Install**
+
+```bash
+npx expo install expo-observe
```
-npm install expo-observe
+
+**2. Wrap your root layout**
+
+```tsx
+import { ObserveRoot } from 'expo-observe';
+
+function RootLayout() {
+ // your app
+}
+
+export default ObserveRoot.wrap(RootLayout);
+```
+
+On SDK 55, the export is `AppMetricsRoot.wrap`.
+
+**3. Mark the moment your app is usable**
+
+```tsx
+import { useObserve } from 'expo-observe';
+import { useEffect } from 'react';
+
+function HomeScreen() {
+ const { markInteractive } = useObserve();
+
+ useEffect(() => {
+ // after your initialization work finishes
+ markInteractive();
+ }, [markInteractive]);
+
+ return ;
+}
```
-### Configure for Android
+Call it on every entry screen. Only the first call in a session records the measurement. On SDK 55, use `AppMetrics.markInteractive()`.
+
+Then run `eas build`. Instrumentation ships with the binary, and metrics appear in the Observe tab of your EAS dashboard.
+
+Launch, bundle load and render metrics are automatic. The one explicit call exists because only your code knows when your app is genuinely ready for input. Automatic where it can be, explicit where accuracy matters.
+
+## Startup metrics
+
+Cold launch, warm launch, bundle load and time to first render are collected automatically. Time to interactive comes from your `markInteractive()` call. Every TTI event also carries frame, thermal, battery and network params, and a summary of the requests made during launch, so you can tell a slow device from a slow network. Tools built for browsers do not collect these fields, because on the web they do not exist.
+
+Every event carries app, release, device and route context, so you can group the results by version, model or screen.
+
+See [Metrics reference](https://docs.expo.dev/eas/observe/reference/metrics/).
+
+## Per-screen metrics
+
+On SDK 56 and later, the Expo Router and React Navigation integrations record per-route render and interactive timings. Both are opt-in.
+
+See [Expo Router integration](https://docs.expo.dev/eas/observe/integrations/expo-router/) and [React Navigation integration](https://docs.expo.dev/eas/observe/integrations/react-navigation/).
+
+## Update downloads
+
+Apps that use EAS Update report how long each update bundle takes to download. This needs no instrumentation.
+
+See [EAS Update download performance](https://docs.expo.dev/eas/observe/eas-update/).
+
+## User-defined events
+
+Log your own named events with `Observe.logEvent`. They land on the same timeline as the startup metrics, so a business event sits next to the frame drop that happened around it.
+
+See [User-defined events](https://docs.expo.dev/eas/observe/events/).
+
+## Errors
+
+On SDK 57 and later, unhandled JavaScript errors are recorded automatically. Wrap a subtree in `ObserveErrorBoundary` to catch render errors, and call `Observe.reportError` for the errors you handle yourself. This feature is in preview.
+
+See [Error reporting](https://docs.expo.dev/eas/observe/errors/).
+
+## Custom endpoint
+
+`expo-observe` transmits over the OpenTelemetry Protocol (OTLP) over HTTP with a JSON payload. Set `endpointUrl` in your app config to send the data to your own collector instead. The endpoint exists so that there is no lock-in. The reason to keep the default is attribution: EAS is the only collector that already knows which build and which update a session was running.
+
+See [Custom endpoint](https://docs.expo.dev/eas/observe/configuration/#custom-endpoint).
+
+## Configuration
+
+`Observe.configure()` sets the environment label, the sampling rate, dispatching behavior and integrations at runtime. `Observe.dispatchEvents()` flushes pending events manually.
+
+See [Configuration](https://docs.expo.dev/eas/observe/configuration/).
+
+## Command line and agents
+
+Everything the dashboard shows is also available from the terminal through the `eas observe:` commands. They all accept `--json --non-interactive`, so you can pipe them into a script or hand them to a coding agent. The `eas-observe` [Expo Skill](https://docs.expo.dev/skills/) teaches an agent to set the library up and query the results.
+
+See [Querying with EAS CLI](https://docs.expo.dev/eas/observe/eas-cli/).
-### Configure for iOS
+## Documentation
-Run `npx pod-install` after installing the npm package.
+- [EAS Observe guides](https://docs.expo.dev/eas/observe/): setup, dashboard, configuration, integrations and the metrics reference
+- [API reference](https://docs.expo.dev/versions/latest/sdk/observe/): every method, option and type in this package
-# Contributing
+## Contributing
-Contributions are very welcome! Please refer to guidelines described in the [contributing guide](https://github.com/expo/expo#contributing).
+Contributions are very welcome. Please refer to the guidelines in the [contributing guide](https://github.com/expo/expo#contributing).
+
+