feat(apm): Deprecate @sentry/apm package (getsentry#2844)

AbhiPrasad · web-flow · commit ec75ea75128e · 2020-08-24T16:47:25.000-04:00
diff --git a/packages/apm/README.md b/packages/apm/README.md
@@ -19,4 +19,6 @@
 
 ## General
 
+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.
+
 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.
diff --git a/packages/apm/src/hubextensions.ts b/packages/apm/src/hubextensions.ts
@@ -21,6 +21,7 @@ function traceHeaders(this: Hub): { [key: string]: string } {
 
 /**
  * {@see Hub.startTransaction}
+ * @deprecated Please use the @sentry/tracing package instead
  */
 function startTransaction(this: Hub, context: TransactionContext): Transaction {
   const transaction = new Transaction(context, this);
@@ -91,6 +92,7 @@ export function addExtensionMethods(): void {
   if (carrier.__SENTRY__) {
     carrier.__SENTRY__.extensions = carrier.__SENTRY__.extensions || {};
     if (!carrier.__SENTRY__.extensions.startTransaction) {
+      // eslint-disable-next-line deprecation/deprecation
       carrier.__SENTRY__.extensions.startTransaction = startTransaction;
     }
     if (!carrier.__SENTRY__.extensions.startSpan) {
diff --git a/packages/apm/src/index.bundle.ts b/packages/apm/src/index.bundle.ts
@@ -69,6 +69,7 @@ if (_window.Sentry && _window.Sentry.Integrations) {
 const INTEGRATIONS = {
   ...windowIntegrations,
   ...BrowserIntegrations,
+  // eslint-disable-next-line deprecation/deprecation
   Tracing: ApmIntegrations.Tracing,
 };
 
diff --git a/packages/apm/src/integrations/index.ts b/packages/apm/src/integrations/index.ts
@@ -1,2 +1,3 @@
 export { Express } from './express';
+// eslint-disable-next-line deprecation/deprecation
 export { Tracing } from './tracing';
diff --git a/packages/apm/src/integrations/tracing.ts b/packages/apm/src/integrations/tracing.ts
@@ -1,3 +1,4 @@
+/* eslint-disable deprecation/deprecation */
 /* eslint-disable max-lines */
 import { Hub } from '@sentry/hub';
 import { Event, EventProcessor, Integration, Severity, Span, SpanContext, TransactionContext } from '@sentry/types';
@@ -133,6 +134,9 @@ const defaultTracingOrigins = ['localhost', /^\//];
 
 /**
  * Tracing Integration
+ *
+ * @deprecated Please use the `BrowserTracing` integration from
+ * the `@sentry/tracing` package.
  */
 export class Tracing implements Integration {
   /**
diff --git a/packages/node/package.json b/packages/node/package.json
@@ -16,9 +16,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@sentry/apm": "5.21.4",
     "@sentry/core": "5.21.4",
     "@sentry/hub": "5.21.4",
+    "@sentry/tracing": "5.21.4",
     "@sentry/types": "5.21.4",
     "@sentry/utils": "5.21.4",
     "cookie": "^0.4.1",
diff --git a/packages/node/src/handlers.ts b/packages/node/src/handlers.ts
@@ -1,7 +1,7 @@
 /* eslint-disable max-lines */
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { Span } from '@sentry/apm';
 import { captureException, getCurrentHub, startTransaction, withScope } from '@sentry/core';
+import { Span } from '@sentry/tracing';
 import { Event } from '@sentry/types';
 import { forget, isPlainObject, isString, logger, normalize } from '@sentry/utils';
 import * as cookie from 'cookie';
diff --git a/packages/tracing/README.md b/packages/tracing/README.md
@@ -23,52 +23,141 @@ This package contains extensions to the `@sentry/hub` to enable Sentry AM relate
 
 ## Migrating from @sentry/apm to @sentry/tracing
 
-The `@sentry/tracing` package is the replacement to the `@sentry/apm` package. No functionality has changed between
-the packages, but there are some steps required for upgrade.
+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.
 
-First, you must update your imports from the `Tracing` integration to the `BrowserTracing` integration.
+The old package `@sentry/apm` is deprecated in favor of `@sentry/tracing`.
+Future support for `@sentry/apm` is limited to bug fixes only.
 
-```ts
-import * as Sentry from "@sentry/browser";
-import { Integrations } from "@sentry/tracing";
+## Migrating from @sentry/apm to @sentry/tracing
 
-Sentry.init({
-  integrations: [
-    new Integrations.BrowserTracing({}),
-  ]
-})
+### Browser (CDN bundle)
+
+If you were using the Browser CDN bundle, switch from the old
+`bundle.apm.min.js` to the new tracing bundle:
+
+```html
+<script
+  src="https://browser.sentry-cdn.com/{{ packages.version('sentry.javascript.browser') }}/bundle.tracing.min.js"
+  integrity="sha384-{{ packages.checksum('sentry.javascript.browser', 'bundle.tracing.min.js', 'sha384-base64') }}"
+  crossorigin="anonymous"
+></script>
+```
+
+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(),
+   ]
+ });
 ```
 
-Next, if you were using the `beforeNavigate` option, the API has changed to this type:
+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";
 
-```ts
-/**
- * beforeNavigate is called before a pageload/navigation transaction is created and allows for users
- * to set a custom transaction context.
- *
- * If undefined is returned, a pageload/navigation transaction will not be created.
- */
-beforeNavigate(context: TransactionContext): TransactionContext | undefined;
+Sentry.init({
+  integrations: [
+    new Integrations.Tracing({
+      beforeNavigate: location => {
+        return getTransactionName(location);
+      },
+    }),
+  ],
+});
 ```
 
-We removed the location argument, in favour of being able to see what the transaction context is on creation. You will
-have to access `window.location` yourself if you want to replicate that. In addition, if you return undefined in
-`beforeNavigate`, the transaction will not be created.
+You would now leverage the context to do the same thing:
 
-```ts
+```javascript
 import * as Sentry from "@sentry/browser";
 import { Integrations } from "@sentry/tracing";
 
 Sentry.init({
   integrations: [
     new Integrations.BrowserTracing({
-      beforeNavigate: (ctx) => {
+      beforeNavigate: context => {
         return {
-          ...ctx,
-          name: getTransactionName(ctx.name, window.location)
-        }
-      }
+          ...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(),
+   ]
+ });
 ```

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`export { Express } from './express';`
	`2`	`+// eslint-disable-next-line deprecation/deprecation`
`2`	`3`	`export { Tracing } from './tracing';`