Skip to content

Commit 6c9e06c

Browse files
jennmuengjennmueng
committed
wip: Just write out what needs to be mentioned for RN auto perf
1 parent 614b944 commit 6c9e06c

File tree

1 file changed

+226
-12
lines changed

1 file changed

+226
-12
lines changed

‎src/platforms/common/performance/capturing/automatic.mdx

Lines changed: 226 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ title: Automatic Instrumentation
33
sidebar_order: 10
44
supported:
55
- javascript
6+
- react-native
67
description: "Learn how to add automatic instrumentation to captured transactions."
78
---
89

@@ -12,38 +13,251 @@ To _automatically_ capture transactions, you must first <PlatformLink to="/perfo
1213

1314
</Note>
1415

15-
The `@sentry/tracing` package provides a `BrowserTracing` integration to add _automatic_ instrumentation for monitoring the performance of browser applications.
16+
The `@sentry/react-native` provides a `ReactNativeTracing` integration to add _automatic_ instrumentation for monitoring the performance of React Native applications.
1617

1718
## What Automatic Instrumentation Provides
1819

19-
The `BrowserTracing` integration creates a new transaction for each page load and navigation event, and creates a child span for every `XMLHttpRequest` or `fetch` request that occurs while those transactions are open. Learn more about [traces, transactions, and spans](/product/performance/distributed-tracing/).
20+
The `ReactNativeTracing` creates a child span for every `XMLHttpRequest` or `fetch` request on the Javascript layer that occurs while those transactions are open. Learn more about [traces, transactions, and spans](/product/performance/distributed-tracing/).
2021

2122
## Enable Automatic Instrumentation
2223

23-
To enable this automatic tracing, include the `BrowserTracing` integration in your SDK configuration options. (Note that when using ESM modules, the main `@sentry/*` import must come before the `@sentry/tracing` import.)
24+
To enable this automatic tracing, include the `ReactNativeTracing` integration in your SDK configuration options.
2425

25-
<PlatformContent includePath="performance/enable-automatic-instrumentation" />
26+
```javascript
27+
import * as Sentry from "@sentry/react-native";
28+
29+
Sentry.init({
30+
dsn: "___PUBLIC_DSN___",
31+
32+
integrations: [
33+
new Sentry.Tracing.ReactNativeTracing({
34+
tracingOrigins: ["localhost", "my-site-url.com", /^\//],
35+
// ... other options
36+
}),
37+
],
38+
39+
// We recommend adjusting this value in production, or using tracesSampler
40+
// for finer control
41+
tracesSampleRate: 1.0,
42+
});
43+
```
2644

2745
## Configuration Options
2846

29-
You can pass many different options to the `BrowserTracing` integration (as an object of the form `{optionName: value}`), but it comes with reasonable defaults out of the box. For all possible options, see [TypeDocs](https://getsentry.github.io/sentry-javascript/interfaces/tracing.browsertracingoptions.html).
47+
You can pass many different options to the `ReactNativeTracing` integration (as an object of the form `{optionName: value}`), but it comes with reasonable defaults out of the box. For all possible options, see [TypeDocs](https://getsentry.github.io/sentry-javascript/interfaces/tracing.browsertracingoptions.html).
3048

3149
### tracingOrigins
3250

33-
The default value of `tracingOrigins` is `['localhost', /^\//]`. The JavaScript SDK will attach the `sentry-trace` header to all outgoing XHR/fetch requests whose destination contains a string in the list or matches a regex in the list. If your frontend is making requests to a different domain, you will need to add it there to propagate the `sentry-trace` header to the backend services, which is required to link transactions together as part of a single trace. **The `tracingOrigins` option matches against the whole request URL, not just the domain. Using stricter regex to match certain parts of the URL ensures that requests do not unnecessarily have the `sentry-trace` header attached.**
51+
The default value of `tracingOrigins` is `['localhost', /^\//]`. The React Native SDK will attach the `sentry-trace` header to all outgoing XHR/fetch requests whose destination contains a string in the list or matches a regex in the list. If your frontend is making requests to a different domain, you will need to add it there to propagate the `sentry-trace` header to the backend services, which is required to link transactions together as part of a single trace. **The `tracingOrigins` option matches against the whole request URL, not just the domain. Using stricter regex to match certain parts of the URL ensures that requests do not unnecessarily have the `sentry-trace` header attached.**
3452

3553
<PlatformContent includePath="performance/tracingOrigins-example" />
3654

3755
You will need to configure your web server CORS to allow the `sentry-trace` header. The configuration might look like `"Access-Control-Allow-Headers: sentry-trace"`, but the configuration depends on your set up. If you do not allow the `sentry-trace` header, the request might be blocked.
3856

39-
### beforeNavigate
40-
41-
For `pageload` and `navigation` transactions, the `BrowserTracing` integration uses the browser's `window.location` API to generate a transaction name. To customize the name of the `pageload` and `navigation` transactions, you can supply a `beforeNavigate` option to the `BrowserTracing` integration. This option allows you to modify the transaction name to make it more generic, so that, for example, transactions named `GET /users/12312012` and `GET /users/11212012` can both be renamed `GET /users/:userid`, so that they'll group together.
42-
43-
<PlatformContent includePath="performance/beforeNavigate-example" />
44-
4557
### shouldCreateSpanForRequest
4658

4759
This function can be used to filter out unwanted spans such as XHR's running health checks or something similar. By default `shouldCreateSpanForRequest` already filters out everything but what was defined in `tracingOrigins`.
4860

4961
<PlatformContent includePath="performance/filter-span-example" />
62+
63+
## Enable Routing Instrumentation
64+
65+
In our React Native, we currently provide two routing instrumentations out of the box for React Navigation V5 and V4. Otherwise you can use the bare bones routing instrumentation or create your own.
66+
67+
### React Navigation V5
68+
69+
Note that this routing instrumentation will create a transaction on every route change including `goBack` navigations.
70+
71+
```js
72+
import * as Sentry from "@sentry/react-native";
73+
74+
// Construct a new instrumentation instance. This is needed to communicate between the integration and React
75+
const reactNavigationV5Instrumentation = new Sentry.Tracing.ReactNavigationV5Instrumentation();
76+
77+
Sentry.init({
78+
...
79+
integrations: [
80+
new Sentry.Tracing.ReactNativeTracing({
81+
// Pass instrumentation to be used as `routingInstrumentation`
82+
routingInstrumentation: reactNavigationV5Instrumentation,
83+
// ...
84+
}),
85+
],
86+
})
87+
88+
const App = () => {
89+
// Create a ref for the navigation container
90+
const navigation = React.createRef<NavigationContainerRef>();
91+
92+
// Register the navigation container with the instrumentation
93+
React.useEffect(() => {
94+
reactNavigationV5Instrumentation.registerNavigationContainer(navigation);
95+
}, []);
96+
97+
return (
98+
// Connect the ref to the navigation container
99+
<NavigationContainer ref={navigation}>
100+
...
101+
</NavigationContainer>
102+
);
103+
};
104+
```
105+
106+
#### Configuration Options
107+
108+
You can configure this instrumentation by passing an object as the first argument to `ReactNavigationV5Instrumentation`:
109+
110+
`shouldSendTransaction` (route, previousRoute) => boolean
111+
112+
```js
113+
114+
const reactNavigationV5Instrumentation = new Sentry.Tracing.ReactNavigationV5Instrumentation({
115+
shouldSendTransaction: (route, previousRoute) => {
116+
if (route.name === 'Ignore-Route') {
117+
return false;
118+
}
119+
120+
if (route.params.containsSensitiveInfo) {
121+
return false;
122+
}
123+
124+
if (previousRoute.name === 'ShouldIgnoreAfter') {
125+
return false;
126+
}
127+
128+
return true;
129+
}
130+
});
131+
132+
// ...
133+
```
134+
135+
### React Navigation V4
136+
137+
Note that this routing instrumentation will create a transaction on every route change including `goBack` navigations.
138+
139+
```js
140+
// Construct a new instrumentation instance. This is needed to communicate between the integration and React
141+
const reactNavigationV4Instrumentation = new Sentry.Tracing.ReactNavigationV4Instrumentation();
142+
143+
Sentry.init({
144+
...
145+
integrations: [
146+
new Sentry.Tracing.ReactNativeTracing({
147+
// Pass instrumentation to be used as `routingInstrumentation`
148+
routingInstrumentation: reactNavigationV4Instrumentation,
149+
...
150+
}),
151+
],
152+
})
153+
154+
const App = () => {
155+
// Create a ref for the navigation container
156+
const appContainer = React.createRef();
157+
158+
// Register the navigation container with the instrumentation
159+
React.useEffect(() => {
160+
reactNavigationV4Instrumentation.registerAppContainer(appContainer);
161+
}, []);
162+
163+
return (
164+
// Connect the ref to the navigation container
165+
<AppContainer ref={appContainer} />
166+
);
167+
};
168+
```
169+
170+
#### Configuration Options
171+
172+
You can configure this instrumentation by passing an object as the first argument to `ReactNavigationV4Instrumentation`:
173+
174+
`shouldSendTransaction` (route, previousRoute) => boolean
175+
176+
```js
177+
178+
const reactNavigationV4Instrumentation = new Sentry.Tracing.ReactNavigationV4Instrumentation({
179+
shouldSendTransaction: (route, previousRoute) => {
180+
// Note that it is route.routeName here and NOT route.name like in V5, this is directly from React-Navigation
181+
if (route.routeName === 'Ignore-Route') {
182+
return false;
183+
}
184+
185+
if (route.params.containsSensitiveInfo) {
186+
return false;
187+
}
188+
189+
if (previousRoute.name === 'ShouldIgnoreAfter') {
190+
return false;
191+
}
192+
193+
return true;
194+
}
195+
});
196+
197+
// ...
198+
```
199+
200+
### Other Navigation Libraries or Custom Navigation
201+
202+
If you use another navigation library that we don't support or have a custom navigation solution, you can use our basic `RoutingInstrumentation` or extend it to create your own class.
203+
204+
Every routing instrumentation revoles around one method:
205+
206+
`onRouteWillChange` (context: TransactionContext): Transaction | undefined
207+
208+
You need to ensure that this method is called **before** the route change occurs.
209+
210+
#### Usage
211+
212+
```js
213+
// Construct a new instrumentation instance. This is needed to communicate between the integration and React
214+
const routingInstrumentation = new Sentry.Tracing.RoutingInstrumentation();
215+
216+
Sentry.init({
217+
...
218+
integrations: [
219+
new Sentry.Tracing.ReactNativeTracing({
220+
// Pass instrumentation to be used as `routingInstrumentation`
221+
routingInstrumentation,
222+
...
223+
}),
224+
],
225+
})
226+
227+
const App = () => {
228+
<SomeNavigationLibrary
229+
onRouteWillChange={(newRoute) => {
230+
// Call this before the route changes
231+
routingInstrumentation.onRouteWillChange({
232+
name: newRoute.name,
233+
op: 'navigation'
234+
})
235+
}}
236+
/>
237+
};
238+
```
239+
240+
241+
#### Extending
242+
243+
244+
```js
245+
class CustomInstrumentation extends RoutingInstrumentation {
246+
247+
constructor(navigator) {
248+
super();
249+
250+
this.navigator.registerRouteChangeListener(this.routeListener.bind(this));
251+
}
252+
253+
routeListener(newRoute) {
254+
// Again, ensure this is called BEFORE the route changes and BEFORE the route is mounted.
255+
this.onRouteWillChange({
256+
name: newRoute.name,
257+
op: 'navigation'
258+
});
259+
}
260+
}
261+
```
262+
263+
More extensive extension examples is by looking at our code for the React Navigation instrumentations.

0 commit comments

Comments
 (0)