|
10 | 10 | [](https://www.npmjs.com/package/@sentry/ember) |
11 | 11 | [](https://www.npmjs.com/package/@sentry/ember) |
12 | 12 |
|
13 | | -This SDK is a v2 Ember addon that provides error tracking and performance monitoring for Ember.js applications. |
| 13 | +The official Sentry SDK for monitoring Ember.js applications. |
14 | 14 |
|
15 | | -## Requirements |
| 15 | +## Documentation |
16 | 16 |
|
17 | | -- Ember.js 4.0+ |
18 | | -- Node.js 20.19.0+ |
| 17 | +- [Getting started](https://docs.sentry.io/platforms/javascript/guides/ember/) |
| 18 | +- [Configuration](https://docs.sentry.io/platforms/javascript/guides/ember/configuration/) |
19 | 19 |
|
20 | | -## Installation |
| 20 | +## Support |
21 | 21 |
|
22 | | -```bash |
23 | | -npm install @sentry/ember |
24 | | -# or |
25 | | -yarn add @sentry/ember |
26 | | -# or |
27 | | -pnpm add @sentry/ember |
28 | | -``` |
29 | | - |
30 | | -## Basic Setup |
31 | | - |
32 | | -Initialize Sentry early in your application, typically in `app/app.ts` or `app/app.js`: |
33 | | - |
34 | | -```typescript |
35 | | -import Application from '@ember/application'; |
36 | | -import Resolver from 'ember-resolver'; |
37 | | -import loadInitializers from 'ember-load-initializers'; |
38 | | -import config from 'my-app/config/environment'; |
39 | | -import * as Sentry from '@sentry/ember'; |
40 | | - |
41 | | -// Initialize Sentry before the application |
42 | | -Sentry.init({ |
43 | | - dsn: '__YOUR_DSN__', |
44 | | - // Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing. |
45 | | - // We recommend adjusting this value in production |
46 | | - tracesSampleRate: 1.0, |
47 | | -}); |
48 | | - |
49 | | -export default class App extends Application { |
50 | | - modulePrefix = config.modulePrefix; |
51 | | - podModulePrefix = config.podModulePrefix; |
52 | | - Resolver = Resolver; |
53 | | -} |
54 | | - |
55 | | -loadInitializers(App, config.modulePrefix); |
56 | | -``` |
57 | | - |
58 | | -## Performance Monitoring |
59 | | - |
60 | | -For automatic performance instrumentation (page loads, navigation, runloop, components), create an instance-initializer: |
61 | | - |
62 | | -```typescript |
63 | | -// app/instance-initializers/sentry-performance.ts |
64 | | -import type ApplicationInstance from '@ember/application/instance'; |
65 | | -import { instrumentAppInstancePerformance } from '@sentry/ember'; |
66 | | - |
67 | | -export function initialize(appInstance: ApplicationInstance): void { |
68 | | - instrumentAppInstancePerformance(appInstance, optionalOptions); |
69 | | -} |
70 | | - |
71 | | -export default { |
72 | | - initialize, |
73 | | -}; |
74 | | -``` |
75 | | - |
76 | | -### Performance Options |
77 | | - |
78 | | -| Option | Type | Default | Description | |
79 | | -| -------------------------------- | --------------------- | ---------- | ----------------------------------------- | |
80 | | -| `appInstance` | `ApplicationInstance` | _required_ | The Ember application instance | |
81 | | -| `disableRunloopPerformance` | `boolean` | `false` | Disable runloop queue tracking | |
82 | | -| `disableInstrumentComponents` | `boolean` | `false` | Disable component render tracking | |
83 | | -| `enableComponentDefinitions` | `boolean` | `false` | Enable component definition tracking | |
84 | | -| `minimumRunloopQueueDuration` | `number` | `5` | Minimum duration (ms) for runloop spans | |
85 | | -| `minimumComponentRenderDuration` | `number` | `2` | Minimum duration (ms) for component spans | |
86 | | -| `instrumentPageLoad` | `boolean` | `true` | Instrument page load spans | |
87 | | -| `instrumentNavigation` | `boolean` | `true` | Instrument navigation spans | |
88 | | -| `idleTimeout` | `number` | `1000` | Idle timeout (ms) for tracing | |
89 | | - |
90 | | -### Route Performance Instrumentation |
91 | | - |
92 | | -To instrument individual routes with detailed lifecycle tracking, use the `instrumentRoutePerformance` decorator: |
93 | | - |
94 | | -```typescript |
95 | | -// app/routes/application.ts |
96 | | -import Route from '@ember/routing/route'; |
97 | | -import { instrumentRoutePerformance } from '@sentry/ember'; |
98 | | - |
99 | | -class ApplicationRoute extends Route { |
100 | | - async model() { |
101 | | - return this.store.findAll('post'); |
102 | | - } |
103 | | -} |
104 | | - |
105 | | -export default instrumentRoutePerformance(ApplicationRoute); |
106 | | -``` |
107 | | - |
108 | | -This wraps the route's `beforeModel`, `model`, `afterModel`, and `setupController` hooks with Sentry spans. |
109 | | - |
110 | | -## API |
111 | | - |
112 | | -This package re-exports everything from `@sentry/browser`, so you have access to the full Sentry Browser SDK API: |
113 | | - |
114 | | -```typescript |
115 | | -import * as Sentry from '@sentry/ember'; |
116 | | - |
117 | | -// Capture an error |
118 | | -Sentry.captureException(new Error('Something went wrong')); |
119 | | - |
120 | | -// Capture a message |
121 | | -Sentry.captureMessage('Something happened'); |
122 | | - |
123 | | -// Set user context |
124 | | -Sentry.setUser({ id: '123', email: 'user@example.com' }); |
125 | | - |
126 | | -// Add breadcrumb |
127 | | -Sentry.addBreadcrumb({ |
128 | | - category: 'ui.click', |
129 | | - message: 'User clicked button', |
130 | | - level: 'info', |
131 | | -}); |
132 | | - |
133 | | -// Create a span |
134 | | -Sentry.startSpan({ name: 'my-operation', op: 'task' }, () => { |
135 | | - // ... do work |
136 | | -}); |
137 | | -``` |
138 | | - |
139 | | -## Migration from v1 Addon |
140 | | - |
141 | | -If you're upgrading from an older version of `@sentry/ember` (v1 addon format), here are the key changes: |
142 | | - |
143 | | -### What Changed |
144 | | - |
145 | | -1. **No automatic instance initializer**: You must now explicitly set up performance instrumentation by creating an instance-initializer that calls `instrumentAppInstancePerformance(appInstance)`. |
146 | | - |
147 | | -2. **No `contentFor` hooks**: The addon no longer injects scripts via `contentFor`. |
148 | | - |
149 | | -3. **No environment config via `ENV['@sentry/ember']`**: Configure Sentry directly via `Sentry.init()` in your app.ts. |
150 | | - |
151 | | -4. **Simpler dependency tree**: The v2 addon format has fewer dependencies and works better with modern build tools like Vite and Embroider. |
152 | | - |
153 | | -### Migration Steps |
154 | | - |
155 | | -1. Update your `app/app.ts` to call `Sentry.init()` directly with your configuration. |
156 | | - |
157 | | -2. Create `app/instance-initializers/sentry-performance.ts` to set up performance monitoring using `instrumentAppInstancePerformance`. |
158 | | - |
159 | | -3. Remove any `@sentry/ember` configuration from `config/environment.js`. |
160 | | - |
161 | | -## Links |
162 | | - |
163 | | -- [Official SDK Docs](https://docs.sentry.io/platforms/javascript/guides/ember/) |
164 | | -- [TypeDoc](http://getsentry.github.io/sentry-javascript/) |
165 | | - |
166 | | -## License |
167 | | - |
168 | | -MIT |
| 22 | +- [Report a bug](https://github.com/getsentry/sentry-javascript/issues/new/choose) |
| 23 | +- [Contributing](https://github.com/getsentry/sentry-javascript/blob/develop/CONTRIBUTING.md) |
0 commit comments