@@ -23,52 +23,141 @@ This package contains extensions to the `@sentry/hub` to enable Sentry AM relate
2323
2424## Migrating from @sentry/apm to @sentry/tracing
2525
26- The ` @sentry/tracing ` package is the replacement to the ` @sentry/apm ` package. No functionality has changed between
27- the packages, but there are some steps required for upgrade.
26+ The tracing integration for JavaScript SDKs has moved from
27+ [ ` @sentry/apm ` ] ( https://www.npmjs.com/package/@sentry/apm ) to
28+ [ ` @sentry/tracing ` ] ( https://www.npmjs.com/package/@sentry/tracing ) . While the
29+ two packages are similar, some imports and APIs have changed slightly.
2830
29- First, you must update your imports from the ` Tracing ` integration to the ` BrowserTracing ` integration.
31+ The old package ` @sentry/apm ` is deprecated in favor of ` @sentry/tracing ` .
32+ Future support for ` @sentry/apm ` is limited to bug fixes only.
3033
31- ``` ts
32- import * as Sentry from " @sentry/browser"
33- import { Integrations } from " @sentry/tracing"
34+ ## Migrating from @sentry/apm to @sentry/tracing
3435
35- Sentry .init ({
36- integrations: [
37- new Integrations .BrowserTracing ({}),
38- ]
39- })
36+ ### Browser (CDN bundle)
37+
38+ If you were using the Browser CDN bundle, switch from the old
39+ ` bundle.apm.min.js ` to the new tracing bundle:
40+
41+ ``` html
42+ <script
43+ src =" https://browser.sentry-cdn.com/{{ packages.version('sentry.javascript.browser') }}/bundle.tracing.min.js"
44+ integrity =" sha384-{{ packages.checksum('sentry.javascript.browser', 'bundle.tracing.min.js', 'sha384-base64') }}"
45+ crossorigin =" anonymous"
46+ ></script >
47+ ```
48+
49+ And then update ` Sentry.init ` :
50+
51+ ``` diff
52+ Sentry.init({
53+ - integrations: [new Sentry.Integrations.Tracing()]
54+ + integrations: [new Sentry.Integrations.BrowserTracing()]
55+ });
56+ ```
57+
58+ ### Browser (npm package)
59+
60+ If you were using automatic instrumentation, update the import statement and
61+ update ` Sentry.init ` to use the new ` BrowserTracing ` integration:
62+
63+ ``` diff
64+ import * as Sentry from "@sentry/browser";
65+ - import { Integrations } from "@sentry/apm";
66+ + import { Integrations } from "@sentry/tracing";
67+
68+ Sentry.init({
69+ integrations: [
70+ - new Integrations.Tracing(),
71+ + new Integrations.BrowserTracing(),
72+ ]
73+ });
4074```
4175
42- Next, if you were using the ` beforeNavigate ` option, the API has changed to this type:
76+ If you were using the ` beforeNavigate ` option from the ` Tracing ` integration,
77+ the API in ` BrowserTracing ` has changed slightly. Instead of passing in a
78+ location and returning a string representing transaction name, ` beforeNavigate `
79+ now accepts a transaction context and is expected to return a transaction
80+ context. You can now add extra tags or change the ` op ` based on different
81+ parameters. If you want to access the location like before, you can get it from
82+ ` window.location ` .
83+
84+ For example, if you had a function like so that computed a custom transaction
85+ name:
86+
87+ ``` javascript
88+ import * as Sentry from " @sentry/browser"
89+ import { Integrations } from " @sentry/apm"
4390
44- ``` ts
45- /**
46- * beforeNavigate is called before a pageload/navigation transaction is created and allows for users
47- * to set a custom transaction context.
48- *
49- * If undefined is returned, a pageload/navigation transaction will not be created.
50- */
51- beforeNavigate (context : TransactionContext ): TransactionContext | undefined ;
91+ Sentry .init ({
92+ integrations: [
93+ new Integrations.Tracing ({
94+ beforeNavigate : location => {
95+ return getTransactionName (location);
96+ },
97+ }),
98+ ],
99+ });
52100```
53101
54- We removed the location argument, in favour of being able to see what the transaction context is on creation. You will
55- have to access ` window.location ` yourself if you want to replicate that. In addition, if you return undefined in
56- ` beforeNavigate ` , the transaction will not be created.
102+ You would now leverage the context to do the same thing:
57103
58- ``` ts
104+ ``` javascript
59105import * as Sentry from " @sentry/browser"
60106import { Integrations } from " @sentry/tracing"
61107
62108Sentry .init ({
63109 integrations: [
64110 new Integrations.BrowserTracing ({
65- beforeNavigate : ( ctx ) => {
111+ beforeNavigate : context => {
66112 return {
67- ... ctx ,
68- name: getTransactionName (ctx .name , window .location )
69- }
70- }
113+ ... context,
114+ // Can even look at context tags or other data to adjust
115+ // transaction name
116+ name: getTransactionName (window .location ),
117+ };
118+ },
71119 }),
72- ]
73- })
120+ ],
121+ });
122+ ```
123+
124+ For the full diff:
125+
126+ ``` diff
127+ import * as Sentry from "@sentry/browser";
128+ - import { Integrations } from "@sentry/apm";
129+ + import { Integrations } from "@sentry/tracing";
130+
131+ Sentry.init({
132+ integrations: [
133+ - new Integrations.Tracing({
134+ - beforeNavigate: (location) => {
135+ - return getTransactionName(location)
136+ + new Integrations.BrowserTracing({
137+ + beforeNavigate: (ctx) => {
138+ + return {
139+ + ...ctx,
140+ + name: getTransactionName(ctx.name, window.location)
141+ + }
142+ }
143+ }),
144+ ]
145+ });
146+ ```
147+
148+ ### Node
149+
150+ If you were using the Express integration for automatic instrumentation, the
151+ only necessary change is to update the import statement:
152+
153+ ``` diff
154+ import * as Sentry from "@sentry/node";
155+ - import { Integrations } from "@sentry/apm";
156+ + import { Integrations } from "@sentry/tracing";
157+
158+ Sentry.init({
159+ integrations: [
160+ new Integrations.Express(),
161+ ]
162+ });
74163```
0 commit comments