@newrelic/browser-agent 0.0.7 → 0.0.8-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +111 -37
  2. package/dist/bundled/es5/index.js +1 -1
  3. package/dist/bundled/es5/index.js.map +1 -1
  4. package/dist/bundled/es6/index.js +1 -1
  5. package/dist/bundled/es6/index.js.map +1 -1
  6. package/dist/webpack-analysis.html +2 -2
  7. package/package.json +11 -3
package/README.md CHANGED
@@ -24,31 +24,26 @@ yarn add @newrelic/browser-agent
24
24
 
25
25
  Using [unpkg](https://unpkg.com/)
26
26
 
27
- Default (defaults to ES6)
27
+ See [Using Unpkg](#using-unpkg) for implementation details
28
28
 
29
- ```html
30
- <script src="https://unpkg.com/@newrelic/browser-agent/bundled"></script>
31
- ```
32
-
33
- ES6 compatible (same resolve as default)
29
+ ES6 compatible bundle
34
30
 
35
31
  ```html
36
- <script src="https://unpkg.com/@newrelic/browser-agent/bundled/es6/index.js"></script>
32
+ <script src="https://unpkg.com/@newrelic/browser-agent/dist/bundled/es6/index.js"></script>
37
33
  ```
38
34
 
39
- ES5 compatible
35
+ ES5 compatible bundle
40
36
 
41
37
  ```html
42
- <script src="https://unpkg.com/@newrelic/browser-agent/bundled/es5/index.js"></script>
38
+ <script src="https://unpkg.com/@newrelic/browser-agent/dist/bundled/es5/index.js"></script>
43
39
  ```
44
40
 
45
-
46
41
  ## Usage Examples
47
42
 
48
43
  ### Basic Setup
49
44
 
50
45
  ```javascript
51
- << App.js >>
46
+ // << App.js >>
52
47
  // initialize the agent as close to
53
48
  // the top level of the application as possible
54
49
  import NR from '@newrelic/browser-agent'
@@ -63,10 +58,24 @@ nr.start(options).then(() => {
63
58
  })
64
59
  ```
65
60
 
66
- #### Using unpkg
61
+ ### Notice Errors After Setup
62
+ ```javascript
63
+ // << SomeComponent.js >>
64
+ // notice handled errors
65
+ try {
66
+ ...
67
+ } catch (err){
68
+ nr.noticeError(err)
69
+ }
70
+
71
+ // thrown errors *anywhere* on the page will be captured if `auto` is enabled
72
+ ```
73
+
74
+ ### Setup Using unpkg
67
75
 
68
76
  ```html
69
77
  <head>
78
+ <!-- Download and initialize as soon as possible to avoid missing early events -->
70
79
  <script src="https://unpkg.com/@newrelic/browser-agent/bundled"></script>
71
80
  <script>
72
81
  const { BrowserAgent } = NRBA;
@@ -81,30 +90,75 @@ nr.start(options).then(() => {
81
90
  </head>
82
91
  ```
83
92
 
84
- ### Instrumenting a Micro Front End
93
+ ### Notice Errors after Setup
94
+ ```javascript
95
+ // << somewhere in your app >>
96
+
97
+ // notice handled errors
98
+ try {
99
+ ...
100
+ } catch (err){
101
+ nr.noticeError(err)
102
+ }
103
+
104
+ // thrown errors *anywhere* on the page will be captured if `auto` is enabled
105
+ ```
85
106
 
86
- The New Relic Browser Agent can maintain separate configuration scopes by creating new instances. Micro front end patterns can rely on separate NR instances and can thus each report their own scoped data to separate New Relic applications.
107
+ ### Instrumenting a Micro Front Ends or Multiple Targets
108
+
109
+ The New Relic Browser Agent can maintain separate configuration scopes by creating new instances. Separate NR instances can each report their own scoped data to separate New Relic applications.
87
110
 
88
111
  ```javascript
89
- // <<< MICRO FRONT END APP 1 >>>
90
112
  // ---- App.js ----
113
+ // Initialize as close to top of page as possible
91
114
  import { BrowserAgent } from '@newrelic/browser-agent'
92
- const options = {
115
+ const options1 = {
93
116
  // see 'Configuring your application'
117
+ licenseKey: 'abc',
118
+ applicationID: '123',
119
+ beacon: 'bam.nr-data.net'
94
120
  }
95
- const nr = new BrowserAgent()
96
- nr.features.JSERRORS.enabled = true
97
- nr.start(options).then(() => {
98
- console.log("Browser Agent Initialized!")
121
+ const agent1 = new BrowserAgent()
122
+ agent1.features.errors.enabled = true // this is enabled by default, but just for visibility
123
+ agent1.start(options1).then(() => {
124
+ console.log("Browser Agent (options1) Initialized!")
99
125
  })
100
126
 
101
- // ---- MyComponent.js ----
127
+ const options2 = {
128
+ // see 'Configuring your application'
129
+ licenseKey: 'xyz',
130
+ applicationID: '987',
131
+ beacon: 'bam.nr-data.net'
132
+ }
133
+ const agent2 = new BrowserAgent()
134
+ agent2.features.errors.auto = false // do not capture global errors on this instance
135
+ agent2.start(options2).then(() => {
136
+ console.log("Browser Agent (options2) Initialized!")
137
+ })
138
+
139
+ // --- NOTE ---
140
+ // thrown errors *anywhere* on the page will be captured if `auto` is enabled in your instance
141
+ // agent2 has disabled `auto`, and will not capture globally thrown errors
142
+
143
+ // ---- NavBarComponent.js ----
102
144
  class MyComponent() {
103
145
  try {
104
146
  ...
105
147
  } catch(err) {
106
- nr.noticeError(err)
107
- // reports to applicationID 1
148
+ agent1.noticeError(err)
149
+ // agent1 instance
150
+ // reports the error to applicationID '123', licenseKey 'abc'
151
+ }
152
+ }
153
+
154
+ // ---- SearchComponent.js ----
155
+ class MyComponent() {
156
+ try {
157
+ ...
158
+ } catch(err) {
159
+ agent2.noticeError(err)
160
+ // agent2 instance
161
+ // reports to applicationID '987', licenseKey 'xyz'
108
162
  }
109
163
  }
110
164
  ```
@@ -115,9 +169,10 @@ The NR interface's `start` method accepts an `options` object to configure the a
115
169
 
116
170
  ```js
117
171
  const options = {
118
- licenseKey: String
119
- applicationID: String
120
- beacon: String
172
+ licenseKey: String // (required)
173
+ applicationID: String // (required)
174
+ beacon: String // (required)
175
+ // ... other configurations
121
176
  }
122
177
  nr.start(options)
123
178
  ```
@@ -132,8 +187,8 @@ You can find `licenseKey`, `applicationID` and `beacon` values in the New Relic
132
187
 
133
188
  |Feature|Subfeature|Default|Description|
134
189
  |-|-|-|-|
135
- |JSERRORS|enabled |true|Enable's `noticeError` method|
136
- |JSERRORS|auto |false|Reports all global errors |
190
+ |errors |enabled |true|Enable's `noticeError` method|
191
+ |errors |auto |false|Reports all global errors |
137
192
 
138
193
  > Features must be set before calling the .start() method.
139
194
 
@@ -145,32 +200,51 @@ This NPM package can currently capture JavaScript Error reporting in two ways. T
145
200
  import { BrowserAgent } from '@newrelic/browser-agent'
146
201
  const browserAgent = new BrowserAgent()
147
202
 
148
- // enable API scoped to applicationID
149
- browserAgent.features.JSERRORS.enabled = true
203
+ // enable noticeError() API scoped to applicationID (enabled by default)
204
+ browserAgent.features.errors.enabled = true
150
205
 
151
- // report global errors to applicationID
152
- browserAgent.features.JSERRORS.auto = true
206
+ // report global errors to applicationID (enabled by default)
207
+ browserAgent.features.errors.auto = true
153
208
 
154
- // enable features before starting the agent
209
+ // configure features before starting the agent
155
210
  browserAgent.start(options)
156
211
  ```
157
212
 
158
213
  ### Capture JavaScript errors via API
159
214
 
160
215
  ```javascript
161
- browserAgent.features.jserrors.enabled = true
216
+ // if browserAgent.features.errors.enabled === true (enabled by default)
162
217
  browserAgent.noticeError(new Error())
163
218
  ```
164
219
 
165
- Set `browserAgent.jserrors.enabled` to `true` to report specific errors via the noticeError API.
220
+ Set `browserAgent.errors.enabled` to `true` to report specific errors via the noticeError API.
166
221
 
167
222
  ### Automatically capture global JavaScript errors
168
223
 
169
224
  ```javascript
170
- browserAgent.features.jserrors.auto = true
225
+ browserAgent.features.errors.auto = true
171
226
  ```
172
227
 
173
- Set `browserAgent.jserrors.auto` to `true` to report all errors on the page.
228
+ Set `browserAgent.errors.auto` to `true` to report all errors on the page.
229
+
230
+
231
+ ## Differences
232
+
233
+ The Browser Agent delivered through NPM will eventually offer parity to its copy/paste and APM counterparts, but during this initial development phase, **it should not yet be treated as equivalent**. Please see the following table describing the capabilities of each. The availability of these features will change over time.
234
+
235
+ | Feature | APM Injected | Copy/Paste | NPM |
236
+ | ------- | ------------ | ---------- | --- |
237
+ | JavaScript Errors | Auto, API | Auto, API | `Auto, API` |
238
+ | Page View | Auto | Auto | `None` |
239
+ | Page View Timings | Auto | Auto | `None` |
240
+ | Ajax Tracking | Auto | Auto | `None` |
241
+ | Page Actions | API | API | `None` |
242
+ | Session Traces | Auto | Auto | `None` |
243
+ | Browser Interactions (SPA) | Auto, API | Auto, API | `None` |
244
+ | Multiple Configurable Instances of Browser Agent on One Page | No | No | `Yes` |
245
+ | Configurable Code Splitting | No | No | `Yes` |
246
+ | IDE Code Completion and Typings | No | No | `Yes` |
247
+
174
248
 
175
249
  ## Contributing
176
250