Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 336ee20

Browse files
frankebersollfrankebersoll
committedOct 12, 2015
Merge pull request #31 from frankebersoll/docs
Review: README.md
2 parents aa342d7 + 0256e83 commit 336ee20

File tree

1 file changed

+151
-94
lines changed

1 file changed

+151
-94
lines changed
 

‎README.md

Lines changed: 151 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,142 @@
11
# Exceptionless.JavaScript
2-
[![Build status](https://ci.appveyor.com/api/projects/status/ahu7u4tvls56wqqu?svg=true)](https://ci.appveyor.com/project/Exceptionless/exceptionless-javascript) [![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/exceptionless/Discuss)
2+
[![Build status](https://img.shields.io/appveyor/ci/Exceptionless/exceptionless-javascript.svg)](https://ci.appveyor.com/project/Exceptionless/exceptionless-javascript) [![Gitter](https://img.shields.io/badge/gitter-join_chat-brightgreen.svg)](https://gitter.im/exceptionless/Discuss) [![NPM version](https://img.shields.io/npm/v/exceptionless.svg)](https://www.npmjs.org/package/then-request)
33

4-
Exceptionless JavaScript/Node client
54

6-
## Using Exceptionless
7-
8-
### Installing
5+
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!
96

10-
Please follow the instructions below for installing the exceptionless JavaScript client.
11-
12-
#### JavaScript
13-
Use one of the below methods to install exceptionless into your web app.
14-
##### Bower
15-
1. Install the package by running `bower install exceptionless` or skip this step and use the scripts hosted on our CDN.
16-
2. Add the script to your html page. We recommend placing this as the very first script.
17-
```html
18-
<script src="bower_components/exceptionless/dist/exceptionless.min.js"></script>
19-
```
7+
## Show me the code! ##
208

21-
##### CDN
22-
1. Add the following script to your page.
239
```html
2410
<script src="https://cdn.rawgit.com/exceptionless/Exceptionless.JavaScript/v1.0.1/dist/exceptionless.min.js"></script>
11+
<script>
12+
var client = exceptionless.ExceptionlessClient.default;
13+
client.config.apiKey = 'API_KEY_HERE';
14+
15+
try {
16+
throw new Error('test');
17+
} catch (error) {
18+
client.submitException(error);
19+
}
20+
</script>
2521
```
2622

27-
#### Node.js
28-
Use this method to install exceptionless into your node app.
29-
1. Install the package by running `npm install exceptionless --save-dev`.
30-
2. Add the exceptionless client to your app:
3123
```javascript
32-
var client = require('exceptionless.node').ExceptionlessClient.default;
24+
var client = require('exceptionless').ExceptionlessClient.default;
25+
client.config.apiKey = 'API_KEY_HERE';
26+
27+
try {
28+
throw new Error('test');
29+
} catch (error) {
30+
client.submitException(error);
31+
}
32+
3333
```
3434

35-
### Configuring the client.
36-
You can configure the exceptionless client a few different ways. The section below will cover the different ways you can configure the ExceptionlessClient. _NOTE: The only required setting that you need to configure is the clients `apiKey`._
35+
## Using Exceptionless
36+
37+
### Installation
38+
39+
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.
40+
41+
#### Browser application
42+
Use one of the following methods to install Exceptionless.js into your browser application:
3743

38-
#### JavaScript
39-
1. You can configure the `apiKey` as part of the script tag. This will be applied to all new instances of the ExceptionlessClient
44+
- **CDN:**
45+
46+
Add the following script to your page:
4047

4148
```html
42-
<script src="bower_components/exceptionless/dist/exceptionless.min.js?apiKey=API_KEY_HERE"></script>
43-
```
49+
<script src="https://cdn.rawgit.com/exceptionless/Exceptionless.JavaScript/v1.0.1/dist/exceptionless.min.js"></script>
50+
```
51+
52+
- **Bower:**
53+
54+
1. Install the package by running `bower install exceptionless`.
55+
2. Add the script to your HTML page:
4456

45-
2. You can set the `apiKey` on the default ExceptionlessClient instance.
57+
```html
58+
<script src="bower_components/exceptionless/dist/exceptionless.min.js"></script>
59+
```
60+
61+
In either case, we recommend placing the `script` tag at the very beginning of your page.
62+
63+
#### Node.js
64+
Use this method to install Exceptionless.js into your Node application:
65+
66+
1. Install the package by running `npm install exceptionless --save`.
67+
2. Require the Exceptionless.js module in your application:
4668

4769
```javascript
48-
exceptionless.ExceptionlessClient.default.config.apiKey = 'API_KEY_HERE';
49-
```
70+
var client = require('exceptionless').ExceptionlessClient.default;
71+
```
72+
73+
### Configuring the client
74+
In order to use Exceptionless.js, the `apiKey` setting has to be configured first.
75+
You can configure the `ExceptionlessClient` class using one of the following ways:
76+
77+
#### Browser application
78+
- You can configure the `apiKey` as part of the script tag. This will be applied to all new instances of the `ExceptionlessClient` class:
5079

51-
3. You can create a new instance of the ExceptionlessClient and specify the `apiKey`, `serverUrl` or [configuration object](https://github.com/exceptionless/Exceptionless.JavaScript/blob/master/src/configuration/IConfigurationSettings.ts).
80+
```html
81+
<script src="bower_components/exceptionless/dist/exceptionless.min.js?apiKey=API_KEY_HERE"></script>
82+
```
83+
84+
- You can set the `apiKey` on the default `ExceptionlessClient` instance:
5285

5386
```javascript
54-
var client = new exceptionless.ExceptionlessClient('API_KEY_HERE');
55-
// or with a api key and server url.
56-
var client = new exceptionless.ExceptionlessClient('API_KEY_HERE', 'http://localhost:50000');
57-
// or with a configuration object
58-
var client = new exceptionless.ExceptionlessClient({
59-
apiKey: 'API_KEY_HERE',
60-
serverUrl: 'http://localhost:50000',
61-
submissionBatchSize: 100
62-
});
63-
```
87+
exceptionless.ExceptionlessClient.default.config.apiKey = 'API_KEY_HERE';
88+
```
89+
90+
- 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/src/configuration/IConfigurationSettings.ts):
91+
92+
```javascript
93+
var client = new exceptionless.ExceptionlessClient('API_KEY_HERE');
94+
// or with an api key and server url
95+
var client = new exceptionless.ExceptionlessClient('API_KEY_HERE', 'http://localhost:50000');
96+
// or with a configuration object
97+
var client = new exceptionless.ExceptionlessClient({
98+
apiKey: 'API_KEY_HERE',
99+
serverUrl: 'http://localhost:50000',
100+
submissionBatchSize: 100
101+
});
102+
```
64103

65104
#### Node.js
66-
1. You can set the `apiKey` on the default ExceptionlessClient instance.
105+
- You can set the `apiKey` on the default `ExceptionlessClient` instance:
67106

68107
```javascript
69-
var client = require('exceptionless.node').ExceptionlessClient.default;
70-
client.config.apiKey = 'API_KEY_HERE';
71-
```
108+
var client = require('exceptionless').ExceptionlessClient.default;
109+
client.config.apiKey = 'API_KEY_HERE';
110+
```
72111

73-
2. You can create a new instance of the ExceptionlessClient and specify the `apiKey`, `serverUrl` or [configuration object](https://github.com/exceptionless/Exceptionless.JavaScript/blob/master/src/configuration/IConfigurationSettings.ts).
112+
- 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/src/configuration/IConfigurationSettings.ts):
74113

75114
```javascript
76-
var exceptionless = require('exceptionless.node');
77-
78-
var client = new exceptionless.ExceptionlessClient('API_KEY_HERE');
79-
// or with a api key and server url.
80-
var client = new exceptionless.ExceptionlessClient('API_KEY_HERE', 'http://localhost:50000');
81-
// or with a configuration object
82-
var client = new exceptionless.ExceptionlessClient({
83-
apiKey: 'API_KEY_HERE',
84-
serverUrl: 'http://localhost:50000',
85-
submissionBatchSize: 100
86-
});
87-
```
115+
var exceptionless = require('exceptionless');
88116

89-
### Sending Events
90-
Once configured, Exceptionless will automatically send any unhandled exceptions that happen in your application. The sections below will show you how to send us different event types as well as customize the data that is sent in.
117+
var client = new exceptionless.ExceptionlessClient('API_KEY_HERE');
118+
// or with an api key and server url
119+
var client = new exceptionless.ExceptionlessClient('API_KEY_HERE', 'http://localhost:50000');
120+
// or with a configuration object
121+
var client = new exceptionless.ExceptionlessClient({
122+
apiKey: 'API_KEY_HERE',
123+
serverUrl: 'http://localhost:50000',
124+
submissionBatchSize: 100
125+
});
126+
```
91127

92-
####Sending Events
128+
### Submitting Events and Errors
129+
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:
93130

94-
You may also want to send us log messages, feature usages or other kinds of events. You can do this very easily with our fluent api.
131+
####Submitting Events
132+
133+
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:
95134

96135
```javascript
97-
// javascript
136+
// Browser
98137
var client = exceptionless.ExceptionlessClient.default;
99-
// Node.Js
100-
// var client = require('exceptionless.node').ExceptionlessClient.default;
138+
// Node.js
139+
// var client = require('exceptionless').ExceptionlessClient.default;
101140

102141
client.submitLog('Logging made easy');
103142

@@ -117,15 +156,15 @@ client.createNotFound('/somepage').addTags('Exceptionless').submit();
117156
// Submit a custom event type
118157
client.submitEvent({ message = 'Low Fuel', type = 'racecar', source = 'Fuel System' });
119158
```
120-
####Manually Sending Errors
159+
####Manually submitting Errors
121160

122161
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:
123162

124163
```javascript
125-
// javascript
164+
// Browser
126165
var client = exceptionless.ExceptionlessClient.default;
127-
// Node.Js
128-
// var client = require('exceptionless.node').ExceptionlessClient.default;
166+
// Node.js
167+
// var client = require('exceptionless').ExceptionlessClient.default;
129168

130169
try {
131170
throw new Error('test');
@@ -136,12 +175,13 @@ try {
136175

137176
####Sending Additional Information
138177

139-
You can easily include additional information in your error reports using our fluent [event builder API](https://github.com/exceptionless/Exceptionless.JavaScript/blob/master/src/EventBuilder.ts).
178+
You can easily include additional information in your error reports using the fluent [event builder API](https://github.com/exceptionless/Exceptionless.JavaScript/blob/master/src/EventBuilder.ts).
179+
140180
```javascript
141-
// javascript
181+
// Browser
142182
var client = exceptionless.ExceptionlessClient.default;
143-
// Node.Js
144-
// var client = require('exceptionless.node').ExceptionlessClient.default;
183+
// Node.js
184+
// var client = require('exceptionless').ExceptionlessClient.default;
145185

146186
try {
147187
throw new Error('Unable to create order from quote.');
@@ -169,40 +209,57 @@ try {
169209

170210
## Self hosted options
171211

172-
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.
212+
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:
213+
214+
#### Browser
215+
You can set the `serverUrl` on the default `ExceptionlessClient` instance:
173216

174-
#### JavaScript
175-
You can set the `serverUrl` on the default ExceptionlessClient instance.
176217
```javascript
177218
exceptionless.ExceptionlessClient.default.config.serverUrl = 'http://localhost:50000';
178219
```
179220

180221
#### Node.js
181-
You can set the `serverUrl` on the default ExceptionlessClient instance.
222+
You can set the `serverUrl` on the default `ExceptionlessClient` instance:
223+
182224
```javascript
183225
var client = require('exceptionless.node').ExceptionlessClient.default;
184226
client.config.serverUrl = 'http://localhost:50000';
185227
```
186228

187-
## Getting Started (Development)
229+
## Support
230+
231+
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 gitter](https://gitter.im/exceptionless/Discuss). We’re always here to help if you have any questions!
188232

189-
The JavaScript client can be installed via [bower](http://bower.io/search/?q=exceptionless), [npm](https://www.npmjs.com/package/exceptionless) or CDN. If you need help, please contact us via in-app support or [open an issue](https://github.com/exceptionless/Exceptionless.JavaScript/issues/new). We’re always here to help if you have any questions!
233+
## Contributing
190234

191-
**This section is for development purposes only! If you are trying to use the Exceptionless JavaScript libraries, please get them from bower, npm or the CDN.**
235+
If you find a bug or want to contribute a feature, feel free to create a pull request.
236+
237+
1. Clone this repository:
238+
239+
```sh
240+
git clone https://github.com/exceptionless/Exceptionless.JavaScript.git
241+
```
242+
243+
2. Install [Node.js](https://nodejs.org). Node is used for building and testing purposes.
192244

193-
1. You will need to clone this repo.
194-
2. Install [Node.js](https://nodejs.org). _We only use node for our build and test processes._
195245
3. Install [tsd](https://github.com/DefinitelyTyped/tsd) and [gulp](http://gulpjs.com) and the development dependencies using [npm](https://www.npmjs.com).
196-
```javascript
197-
npm install -g tsd
198-
npm install -g gulp
199-
npm install
200-
```
246+
247+
```sh
248+
npm install -g tsd
249+
npm install -g gulp
250+
npm install
251+
```
252+
201253
4. Build the project by running the following gulp command.
202-
```javascript
203-
gulp build
204-
```
254+
255+
```sh
256+
gulp build
257+
```
258+
205259
5. Test the project by running the following gulp command.
206-
```javascript
207-
gulp test
208-
```
260+
261+
```sh
262+
gulp test
263+
```
264+
265+
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.

0 commit comments

Comments
 (0)
Please sign in to comment.