Skip to content

Commit 1108ae3

Browse files
niemyjskiniemyjski
committed
Updated read me documentation
1 parent a4a59a8 commit 1108ae3

File tree

7 files changed

+453
-199
lines changed

7 files changed

+453
-199
lines changed

‎README.md

Lines changed: 136 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -5,200 +5,209 @@
55
[![NPM version](https://img.shields.io/npm/v/exceptionless.svg)](https://www.npmjs.org/package/exceptionless)
66
[![Donate](https://img.shields.io/badge/donorbox-donate-blue.svg)](https://donorbox.org/exceptionless?recurring=true)
77

8-
The definition of the word exceptionless is: to be without exception. Exceptionless.js provides real-time error reporting for your JavaScript applications in the browser or in Node.js. It organizes the gathered information into simple actionable data that will help your app become exceptionless!
8+
The definition of the word exceptionless is: to be without exception. Exceptionless provides real-time error reporting for your JavaScript applications in the browser or in Node.js. It organizes the gathered information into simple actionable data that will help your app become exceptionless!
99

10-
## Show me the code!
10+
## Browser
1111

12-
```html
13-
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/exceptionless.min.js"></script>
14-
<script>
15-
var client = exceptionless.ExceptionlessClient.default;
16-
client.config.apiKey = "API_KEY_HERE";
12+
You can install the npm package via `npm install @exceptionless/browser --save`
13+
or via cdn [`https://unpkg.com/@exceptionless/browser](https://unpkg.com/@exceptionless/browser).
14+
Next, you just need to call startup during your apps startup to automatically
15+
capture unhandled errors.
1716

18-
try {
19-
throw new Error("test");
20-
} catch (error) {
21-
client.submitException(error);
22-
}
23-
</script>
24-
```
17+
```js
18+
import { Exceptionless } from "https://unpkg.com/@exceptionless/browser";
19+
20+
await Exceptionless.startup((c) => {
21+
c.apiKey = "API_KEY_HERE";
22+
c.usePersistedQueueStorage = true;
23+
c.setUserIdentity("12345678", "Blake");
24+
c.useSessions();
2525

26-
```javascript
27-
var client = require("exceptionless").ExceptionlessClient.default;
28-
client.config.apiKey = "API_KEY_HERE";
26+
// set some default data
27+
c.defaultData["cart"] = {
28+
sku: "abc",
29+
quantity: 1
30+
};
31+
32+
c.defaultTags.push("Example", "JavaScript", "Browser");
33+
});
2934

3035
try {
3136
throw new Error("test");
3237
} catch (error) {
33-
client.submitException(error);
38+
await Exceptionless.submitException(error);
3439
}
35-
3640
```
3741

38-
## Using Exceptionless
42+
## Node
3943

40-
### Installation
44+
You can install the npm package via `npm install @exceptionless/node --save`.
45+
Next, you just need to call startup during your apps startup to automatically
46+
capture unhandled errors.
4147

42-
You can install Exceptionless.js either in your browser application using Bower or a `script` tag, or you can use the Node Package Manager (npm) to install the Node.js package.
48+
```js
49+
import { Exceptionless } from "@exceptionless/node";
4350

44-
#### Browser application
51+
await Exceptionless.startup((c) => {
52+
c.apiKey = "API_KEY_HERE";
53+
c.usePersistedQueueStorage = true;
54+
c.setUserIdentity("12345678", "Blake");
55+
c.useSessions();
4556

46-
Use one of the following methods to install Exceptionless.js into your browser application:
57+
// set some default data
58+
c.defaultData["cart"] = {
59+
sku: "abc",
60+
quantity: 1
61+
};
4762

48-
- **CDN:**
63+
c.defaultTags.push("Example", "JavaScript", "Node");
64+
});
4965

50-
Add the following script to your page:
66+
try {
67+
throw new Error("test");
68+
} catch (error) {
69+
await Exceptionless.submitException(error);
70+
}
71+
```
5172

52-
```html
53-
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/exceptionless.min.js"></script>
54-
```
73+
## Using Exceptionless
5574

56-
- **Bower:**
75+
### Installation
5776

58-
1. Install the package by running `bower install exceptionless`.
59-
2. Add the script to your HTML page:
77+
You can install Exceptionless either in your browser application using a `script`
78+
tag, or you can use the Node Package Manager (npm) to install the package.
6079

61-
```html
62-
<script src="bower_components/exceptionless/dist/exceptionless.min.js"></script>
63-
```
80+
#### Browser application
6481

65-
In either case, we recommend placing the `script` tag at the very beginning of your page.
82+
Use one of the following methods to install Exceptionless into your browser application:
6683

67-
#### Node.js
84+
##### CDN
6885

69-
Use this method to install Exceptionless.js into your Node application:
86+
Add the following script tag at the very beginning of your page:
7087

71-
1. Install the package by running `npm install exceptionless --save`.
72-
2. Require the Exceptionless.js module in your application:
88+
```html
89+
<script type="module">
90+
import { Exceptionless } from "https://unpkg.com/@exceptionless/browser";
7391
74-
```javascript
75-
var client = require("exceptionless").ExceptionlessClient.default;
92+
await Exceptionless.startup((c) => {
93+
c.apiKey = "API_KEY_HERE";
94+
c.usePersistedQueueStorage = true;
95+
});
96+
</script>
7697
```
7798

78-
### Configuring the client
79-
80-
In order to use Exceptionless.js, the `apiKey` setting has to be configured first.
81-
You can configure the `ExceptionlessClient` class using one of the following ways:
82-
83-
#### Browser application
84-
85-
- You can configure the `apiKey` as part of the script tag. This will be applied to all new instances of the `ExceptionlessClient` class:
86-
87-
```html
88-
<script src="bower_components/exceptionless/dist/exceptionless.min.js?apiKey=API_KEY_HERE"></script>
89-
```
99+
##### npm
90100

91-
- You can set the `apiKey` on the default `ExceptionlessClient` instance:
101+
1. Install the package by running `npm install @exceptionless/browser --save`.
102+
2. Import Exceptionless and call startup during app startup.
92103

93-
```javascript
94-
exceptionless.ExceptionlessClient.default.config.apiKey = "API_KEY_HERE";
95-
```
104+
```js
105+
import { Exceptionless } from "@exceptionless/browser";
96106

97-
- You can create a new instance of the `ExceptionlessClient` class and specify the `apiKey`, `serverUrl` or [configuration object](https://github.com/exceptionless/Exceptionless.JavaScript/blob/master/packages/core/src/configuration/IConfigurationSettings.ts):
98-
99-
```javascript
100-
var client = new exceptionless.ExceptionlessClient("API_KEY_HERE");
101-
// or with an api key and server url
102-
var client = new exceptionless.ExceptionlessClient("API_KEY_HERE", "http://localhost:5000");
103-
// or with a configuration object
104-
var client = new exceptionless.ExceptionlessClient({
105-
apiKey: "API_KEY_HERE",
106-
serverUrl: "http://localhost:5000",
107-
submissionBatchSize: 100
107+
await Exceptionless.startup((c) => {
108+
c.apiKey = "API_KEY_HERE";
109+
c.usePersistedQueueStorage = true;
108110
});
109111
```
110112

111113
#### Node.js
112114

113-
- You can set the `apiKey` on the default `ExceptionlessClient` instance:
114-
115-
```javascript
116-
var client = require("exceptionless").ExceptionlessClient.default;
117-
client.config.apiKey = "API_KEY_HERE";
118-
```
115+
Use this method to install Exceptionless into your Node application:
119116

120-
- You can create a new instance of the `ExceptionlessClient` class and specify the `apiKey`, `serverUrl` or [configuration object](https://github.com/exceptionless/Exceptionless.JavaScript/blob/master/packages/core/src/configuration/IConfigurationSettings.ts):
117+
1. Install the package by running `npm install @exceptionless/node --save`.
118+
2. Import the Exceptionless module in your application:
121119

122-
```javascript
123-
var exceptionless = require("exceptionless");
120+
```js
121+
import { Exceptionless } from "@exceptionless/node";
124122

125-
var client = new exceptionless.ExceptionlessClient("API_KEY_HERE");
126-
// or with an api key and server url
127-
var client = new exceptionless.ExceptionlessClient("API_KEY_HERE", "http://localhost:5000");
128-
// or with a configuration object
129-
var client = new exceptionless.ExceptionlessClient({
130-
apiKey: "API_KEY_HERE",
131-
serverUrl: "http://localhost:5000",
132-
submissionBatchSize: 100
123+
await Exceptionless.startup((c) => {
124+
c.apiKey = "API_KEY_HERE";
125+
c.usePersistedQueueStorage = true;
133126
});
134127
```
135128

129+
### Configuring the client
130+
131+
In order to use Exceptionless, the `apiKey` setting has to be configured first.
132+
You can configure the `ExceptionlessClient` class by calling
133+
`await Exceptionless.startup("API_KEY_HERE");`. If you want to configure
134+
additional client settings you'll want to call the `startup` overload that takes
135+
a callback as shown below:
136+
137+
```js
138+
await Exceptionless.startup((c) => {
139+
c.apiKey = "API_KEY_HERE";
140+
c.usePersistedQueueStorage = true;
141+
c.useReferenceIds();
142+
});
143+
```
144+
145+
Please see the [docs](https://exceptionless.com/docs/clients/javascript/) for
146+
more information on configuring the client.
147+
136148
### Submitting Events and Errors
137149

138-
Once configured, Exceptionless.js will automatically submit any unhandled exceptions that happen in your application to the Exceptionless server. The following sections will show you how to manually submit different event types as well as customize the data that is sent:
150+
Once configured, Exceptionless will automatically submit any unhandled exceptions
151+
that happen in your application to the Exceptionless server. The following
152+
sections will show you how to manually submit different event types as well as
153+
customize the data that is sent:
139154

140155
#### Submitting Events
141156

142157
You may also want to submit log messages, feature usage data or other kinds of events. You can do this very easily with the fluent API:
143158

144-
```javascript
145-
// Browser
146-
var client = exceptionless.ExceptionlessClient.default;
147-
// Node.js
148-
// var client = require("exceptionless").ExceptionlessClient.default;
159+
```js
160+
import { Exceptionless } from "@exceptionless/browser";
149161

150-
client.submitLog("Logging made easy");
162+
await Exceptionless.submitLog("Logging made easy");
151163

152164
// You can also specify the log source and log level.
153165
// We recommend specifying one of the following log levels: Trace, Debug, Info, Warn, Error
154-
client.submitLog("app.logger", "This is so easy", "Info");
155-
client.createLog("app.logger", "This is so easy", "Info").addTags("Exceptionless").submit();
166+
await Exceptionless.submitLog("app.logger", "This is so easy", "Info");
167+
await Exceptionless.createLog("app.logger", "This is so easy", "Info").addTags("Exceptionless").submit();
156168

157169
// Submit feature usages
158-
client.submitFeatureUsage("MyFeature");
159-
client.createFeatureUsage("MyFeature").addTags("Exceptionless").submit();
170+
await Exceptionless.submitFeatureUsage("MyFeature");
171+
await Exceptionless.createFeatureUsage("MyFeature").addTags("Exceptionless").submit();
160172

161173
// Submit a 404
162-
client.submitNotFound("/somepage");
163-
client.createNotFound("/somepage").addTags("Exceptionless").submit();
174+
await Exceptionless.submitNotFound("/somepage");
175+
await Exceptionless.createNotFound("/somepage").addTags("Exceptionless").submit();
164176

165177
// Submit a custom event type
166-
client.submitEvent({ message = "Low Fuel", type = "racecar", source = "Fuel System" });
178+
await Exceptionless.submitEvent({ message = "Low Fuel", type = "racecar", source = "Fuel System" });
167179
```
168180

169181
#### Manually submitting Errors
170182

171-
In addition to automatically sending all unhandled exceptions, you may want to manually send exceptions to the service. You can do so by using code like this:
183+
In addition to automatically sending all unhandled exceptions, you may want to
184+
manually send exceptions to the service. You can do so by using code like this:
172185

173-
```javascript
174-
// Browser
175-
var client = exceptionless.ExceptionlessClient.default;
176-
// Node.js
177-
// var client = require("exceptionless").ExceptionlessClient.default;
186+
```js
187+
import { Exceptionless } from "@exceptionless/node";
188+
await Exceptionless.startup("API_KEY_HERE");
178189

179190
try {
180191
throw new Error("test");
181192
} catch (error) {
182-
client.submitException(error);
193+
await Exceptionless.submitException(error);
183194
}
184195
```
185196

186197
#### Sending Additional Information
187198

188199
You can easily include additional information in your error reports using the fluent [event builder API](https://github.com/exceptionless/Exceptionless.JavaScript/blob/master/packages/core/src/EventBuilder.ts).
189200

190-
```javascript
191-
// Browser
192-
var client = exceptionless.ExceptionlessClient.default;
193-
// Node.js
194-
// var client = require("exceptionless").ExceptionlessClient.default;
201+
```js
202+
import { Exceptionless } from "@exceptionless/node";
203+
await Exceptionless.startup("API_KEY_HERE");
195204

196205
try {
197206
throw new Error("Unable to create order from quote.");
198207
} catch (error) {
199-
client.createException(error)
208+
await Exceptionless.createException(error)
200209
// Set the reference id of the event so we can search for it later (reference:id).
201-
// This will automatically be populated if you call client.config.useReferenceIds();
210+
// This will automatically be populated if you call Exceptionless.config.useReferenceIds();
202211
.setReferenceId("random guid")
203212
// Add the order object (the ability to exclude specific fields will be coming in a future version).
204213
.setProperty("Order", order)
@@ -219,23 +228,15 @@ try {
219228

220229
## Self hosted options
221230

222-
The Exceptionless client can also be configured to send data to your self hosted instance. This is configured by setting the `serverUrl` setting to point to your Exceptionless instance:
231+
The Exceptionless client can also be configured to send data to your self hosted
232+
instance. This is configured by setting the `serverUrl` on the default
233+
`ExceptionlessClient` when calling `startup`:
223234

224-
#### Browser
225-
226-
You can set the `serverUrl` on the default `ExceptionlessClient` instance:
227-
228-
```javascript
229-
exceptionless.ExceptionlessClient.default.config.serverUrl = "http://localhost:5000";
230-
```
231-
232-
#### Node.js
233-
234-
You can set the `serverUrl` on the default `ExceptionlessClient` instance:
235-
236-
```javascript
237-
var client = require("exceptionless.node").ExceptionlessClient.default;
238-
client.config.serverUrl = "http://localhost:5000";
235+
```js
236+
await Exceptionless.startup((c) => {
237+
c.apiKey = "API_KEY_HERE";
238+
c.serverUrl = "http://localhost:5000";
239+
});
239240
```
240241

241242
### General Data Protection Regulation
@@ -248,7 +249,10 @@ for detailed information on how to configure the client to meet your requirement
248249

249250
## Support
250251

251-
If you need help, please contact us via in-app support, [open an issue](https://github.com/exceptionless/Exceptionless.JavaScript/issues/new) or [join our chat on Discord](https://discord.gg/6HxgFCx). We’re always here to help if you have any questions!
252+
If you need help, please contact us via in-app support,
253+
[open an issue](https://github.com/exceptionless/Exceptionless.JavaScript/issues/new)
254+
or [join our chat on Discord](https://discord.gg/6HxgFCx). We’re always here to
255+
help if you have any questions!
252256

253257
## Contributing
254258

@@ -261,7 +265,7 @@ If you find a bug or want to contribute a feature, feel free to create a pull re
261265
```
262266

263267
2. Install [Node.js](https://nodejs.org). Node is used for building and testing purposes.
264-
3. Install [gulp](http://gulpjs.com) and the development dependencies using [npm](https://www.npmjs.com).
268+
3. Install the development dependencies using [npm](https://www.npmjs.com).
265269

266270
```sh
267271
npm install
@@ -279,8 +283,6 @@ If you find a bug or want to contribute a feature, feel free to create a pull re
279283
npm run test
280284
```
281285

282-
During development, you can use relative paths to require Exceptionless, e.g. `require("./dist/exceptionless.node.js")` when you are running Node.js from the git root directory.
283-
284286
## Thanks
285287

286288
Thanks to all the people who have contributed!

0 commit comments

Comments
 (0)