diff --git a/packages/apm/README.md b/packages/apm/README.md
index 280b08f9b569..c0674956a713 100644
--- a/packages/apm/README.md
+++ b/packages/apm/README.md
@@ -1,24 +1,140 @@
-<p align="center">
-  <a href="https://sentry.io" target="_blank" align="center">
-    <img src="https://sentry-brand.storage.googleapis.com/sentry-logo-black.png" width="280">
-  </a>
-  <br />
-</p>
+# Deprecated
 
-# Sentry APM Extensions
+The tracing integration for JavaScript SDKs has moved from
+[`@sentry/apm`](https://www.npmjs.com/package/@sentry/apm) to
+[`@sentry/tracing`](https://www.npmjs.com/package/@sentry/tracing). While the
+two packages are similar, some imports and APIs have changed slightly.
 
-[![npm version](https://img.shields.io/npm/v/@sentry/apm.svg)](https://www.npmjs.com/package/@sentry/apm)
-[![npm dm](https://img.shields.io/npm/dm/@sentry/apm.svg)](https://www.npmjs.com/package/@sentry/apm)
-[![npm dt](https://img.shields.io/npm/dt/@sentry/apm.svg)](https://www.npmjs.com/package/@sentry/apm)
-[![typedoc](https://img.shields.io/badge/docs-typedoc-blue.svg)](http://getsentry.github.io/sentry-javascript/)
+The old package `@sentry/apm` is deprecated in favor of `@sentry/tracing`.
+Future support for `@sentry/apm` is limited to bug fixes only.
 
-## Links
+## Migrating from @sentry/apm to @sentry/tracing
 
-- [Official SDK Docs](https://docs.sentry.io/quickstart/)
-- [TypeDoc](http://getsentry.github.io/sentry-javascript/)
+### Browser (CDN bundle)
 
-## General
+If you were using the Browser CDN bundle, switch from the old
+`bundle.apm.min.js` to the new tracing bundle:
 
-This package is deprecated and will be removed in the next major release. We recommend switching to using the `@sentry/tracing` package for the time being.
+```html
+<script
+  src="https://browser.sentry-cdn.com/xxx/bundle.tracing.min.js"
+  integrity="sha384-sha"
+  crossorigin="anonymous"
+></script>
+```
 
-This package contains extensions to the `@sentry/hub` to enable APM related functionality. It also provides integrations for Browser and Node that provide a good experience out of the box.
+And then update `Sentry.init`:
+
+```diff
+ Sentry.init({
+-  integrations: [new Sentry.Integrations.Tracing()]
++  integrations: [new Sentry.Integrations.BrowserTracing()]
+ });
+```
+
+### Browser (npm package)
+
+If you were using automatic instrumentation, update the import statement and
+update `Sentry.init` to use the new `BrowserTracing` integration:
+
+```diff
+ import * as Sentry from "@sentry/browser";
+-import { Integrations } from "@sentry/apm";
++import { Integrations } from "@sentry/tracing";
+
+ Sentry.init({
+   integrations: [
+-    new Integrations.Tracing(),
++    new Integrations.BrowserTracing(),
+   ]
+ });
+```
+
+If you were using the `beforeNavigate` option from the `Tracing` integration,
+the API in `BrowserTracing` has changed slightly. Instead of passing in a
+location and returning a string representing transaction name, `beforeNavigate`
+now accepts a transaction context and is expected to return a transaction
+context. You can now add extra tags or change the `op` based on different
+parameters. If you want to access the location like before, you can get it from
+`window.location`.
+
+For example, if you had a function like so that computed a custom transaction
+name:
+
+```javascript
+import * as Sentry from "@sentry/browser";
+import { Integrations } from "@sentry/apm";
+
+Sentry.init({
+  integrations: [
+    new Integrations.Tracing({
+      beforeNavigate: location => {
+        return getTransactionName(location);
+      },
+    }),
+  ],
+});
+```
+
+You would now leverage the context to do the same thing:
+
+```javascript
+import * as Sentry from "@sentry/browser";
+import { Integrations } from "@sentry/tracing";
+
+Sentry.init({
+  integrations: [
+    new Integrations.BrowserTracing({
+      beforeNavigate: context => {
+        return {
+          ...context,
+          // Can even look at context tags or other data to adjust
+          // transaction name
+          name: getTransactionName(window.location),
+        };
+      },
+    }),
+  ],
+});
+```
+
+For the full diff:
+
+```diff
+ import * as Sentry from "@sentry/browser";
+-import { Integrations } from "@sentry/apm";
++import { Integrations } from "@sentry/tracing";
+
+ Sentry.init({
+   integrations: [
+-    new Integrations.Tracing({
+-      beforeNavigate: (location) => {
+-        return getTransactionName(location)
++    new Integrations.BrowserTracing({
++      beforeNavigate: (ctx) => {
++        return {
++          ...ctx,
++          name: getTransactionName(ctx.name, window.location)
++        }
+       }
+     }),
+   ]
+ });
+```
+
+### Node
+
+If you were using the Express integration for automatic instrumentation, the
+only necessary change is to update the import statement:
+
+```diff
+ import * as Sentry from "@sentry/node";
+-import { Integrations } from "@sentry/apm";
++import { Integrations } from "@sentry/tracing";
+
+ Sentry.init({
+   integrations: [
+     new Integrations.Express(),
+   ]
+ });
+```