1 | # Lunar Metrics
|
2 |
|
3 | Provides integrated [NewRelic](https://newrelic.com/) and [Sentry](https://sentry.io/welcome/)
|
4 | insights and metrics logging.
|
5 |
|
6 | This will also set the Google Analytics `userId` if `ga` is global and `userID` is passed to
|
7 | `Metrics.initialize`.
|
8 |
|
9 | ```bash static
|
10 | npm install @airbnb/lunar-metrics --save
|
11 | ```
|
12 |
|
13 | ## Setup
|
14 |
|
15 | Initialize the metrics package with your Sentry key/project (optional) and the current user ID.
|
16 |
|
17 | ```js static
|
18 | import Metrics from '@airbnb/lunar-metrics';
|
19 |
|
20 | Metrics.initialize({
|
21 | context: { additionalParams: 'toLog' },
|
22 | ignoreErrors: ['APIError'],
|
23 | sentryKey: 'abcdef',
|
24 | sentryProject: 'project',
|
25 | userID: getUserID(),
|
26 | });
|
27 | ```
|
28 |
|
29 | > This will automatically bootstrap NewRelic (if the global below exists) and Sentry (if the
|
30 | > key/project are defined).
|
31 |
|
32 | ### NewRelic
|
33 |
|
34 | Rather than being configured in your application logic, NewRelic is configured in the DOM with a
|
35 | `script` block, usually within a `index.html` file. The script block can be found in your NewRelic
|
36 | project -> Application settings page, and looks something like the following.
|
37 |
|
38 | ```html static
|
39 | <script type="text/javascript">
|
40 | window.NREUM || (NREUM = {}),
|
41 | (__nr_require = function(t, e, n) {
|
42 | /* CODE */
|
43 | });
|
44 | if (window.location.origin.indexOf('localhost') >= 0) {
|
45 | // development:
|
46 | NREUM.info = {
|
47 | beacon: 'bam.nr-data.net',
|
48 | errorBeacon: 'bam.nr-data.net',
|
49 | licenseKey: 'foobarbaz',
|
50 | applicationID: '12345678',
|
51 | sa: 1,
|
52 | };
|
53 | } else {
|
54 | // production:
|
55 | NREUM.info = {
|
56 | beacon: 'bam.nr-data.net',
|
57 | errorBeacon: 'bam.nr-data.net',
|
58 | licenseKey: 'foobarbaz',
|
59 | applicationID: '12345678',
|
60 | sa: 1,
|
61 | };
|
62 | }
|
63 | </script>
|
64 | ```
|
65 |
|
66 | > If you'd like to support separate development and production projects, a localhost conditional
|
67 | > like the above will work.
|
68 |
|
69 | ## Usage
|
70 |
|
71 | ### Logging Errors
|
72 |
|
73 | To log an error to both NewRelic and Sentry, use `captureError`. This function accepts a string,
|
74 | `Error`, or `Event` instance. It optionally supports additional
|
75 | [params for Sentry](https://docs.sentry.io/clients/javascript/usage/#passing-additional-data) as the
|
76 | 2nd argument.
|
77 |
|
78 | ```js static
|
79 | import captureError from '@airbnb/lunar-metrics/lib/utils/captureError';
|
80 |
|
81 | captureError('Something is broken');
|
82 |
|
83 | captureError(new Error('Something is really really broken!'), {
|
84 | level: 'error',
|
85 | });
|
86 |
|
87 | captureError(someDomEvent);
|
88 | ```
|
89 |
|
90 | ### Capturing Breadcrumbs
|
91 |
|
92 | If you'd like to capture a [Sentry breadcrumb](https://docs.sentry.io/learn/breadcrumbs/) to trail
|
93 | along side errors, use `captureBreadcrumb`.
|
94 |
|
95 | ```js static
|
96 | import captureBreadcrumb from '@airbnb/lunar-metrics/lib/utils/captureBreadcrumb';
|
97 |
|
98 | captureBreadcrumb({
|
99 | message: 'Failed to login',
|
100 | category: 'auth',
|
101 | data: {
|
102 | username: 'foobar',
|
103 | },
|
104 | });
|
105 | ```
|