1 | # node-loggly-bulk
|
2 |
|
3 | [![Version npm](https://img.shields.io/npm/v/node-loggly-bulk.svg?style=flat-square)](https://www.npmjs.com/package/node-loggly-bulk)[![npm Downloads](https://img.shields.io/npm/dm/node-loggly-bulk.svg?style=flat-square)](https://www.npmjs.com/package/node-loggly-bulk)
|
4 |
|
5 | [![NPM](https://nodei.co/npm/node-loggly-bulk.png?downloads=true&downloadRank=true)](https://nodei.co/npm/node-loggly-bulk/)
|
6 |
|
7 | A client implementation for Loggly in node.js. Check out Loggly's [Node logging documentation](https://www.loggly.com/docs/nodejs-logs/) for more.
|
8 |
|
9 | ## Usage
|
10 |
|
11 | The `node-loggly-bulk` library is compliant with the [Loggly API][api]. Using `node-loggly-bulk` is easy for a variety of scenarios: logging, working with devices and inputs, searching, and facet searching.
|
12 |
|
13 | ### Getting Started
|
14 | Before we can do anything with Loggly, we have to create a client with valid credentials. We will authenticate for you automatically:
|
15 |
|
16 | ``` js
|
17 | var loggly = require('loggly');
|
18 |
|
19 | var client = loggly.createClient({
|
20 | token: "your-really-long-input-token",
|
21 | subdomain: "your-subdomain",
|
22 | auth: {
|
23 | username: "your-username",
|
24 | password: "your-password"
|
25 | },
|
26 | //
|
27 | // Optional: Tag to send with EVERY log message
|
28 | //
|
29 | tags: ['global-tag']
|
30 | });
|
31 | ```
|
32 |
|
33 | ### Logging
|
34 | There are two ways to send log information to Loggly via node-loggly-bulk. The first is to simply call client.log with an appropriate input token:
|
35 |
|
36 | ``` js
|
37 | client.log('127.0.0.1 - Theres no place like home', function (err, result) {
|
38 | // Do something once you've logged
|
39 | });
|
40 | ```
|
41 |
|
42 | Note that the callback in the above example is optional, if you prefer the 'fire and forget' method of logging:
|
43 |
|
44 | ``` js
|
45 | client.log('127.0.0.1 - Theres no place like home');
|
46 | ```
|
47 |
|
48 | ### Logging with Tags
|
49 |
|
50 | If you're using Loggly's [tags](https://www.loggly.com/docs/tags/) functionality, simply include an array of tags as the second argument to the `log` method:
|
51 |
|
52 | ``` js
|
53 | client.log('127.0.0.1 - Theres no place like home', [ 'dorothy' ], function (err, result) {
|
54 | // Do something once you've logged
|
55 | });
|
56 | ```
|
57 |
|
58 | *note* Tags passed into the log function will be merged with any global tags you may have defined.
|
59 |
|
60 |
|
61 | ### Logging Shallow JSON Objects as a String
|
62 | In addition to logging pure strings it is also possible to pass shallow JSON object literals (i.e. no nested objects) to client.log(..) or input.log(..) methods, which will get converted into the [Loggly recommended string representation][sending-data]. So
|
63 |
|
64 | ``` js
|
65 | var source = {
|
66 | foo: 1,
|
67 | bar: 2,
|
68 | buzz: 3
|
69 | };
|
70 |
|
71 | input.log(source);
|
72 | ```
|
73 |
|
74 | will be logged as:
|
75 |
|
76 | ```
|
77 | foo=1,bar=2,buzz=3
|
78 | ```
|
79 |
|
80 | ### Logging JSON Objects
|
81 | It is also possible to log complex objects using the new JSON capabilities of Loggly. To enable JSON functionality in the client simply add 'json: true' to the configuration:
|
82 |
|
83 | ``` js
|
84 | var config = {
|
85 | subdomain: "your-subdomain",
|
86 | auth: {
|
87 | username: "your-username",
|
88 | password: "your-password"
|
89 | },
|
90 | json: true
|
91 | };
|
92 | ```
|
93 |
|
94 | When the json flag is enabled, objects will be converted to JSON using JSON.stringify before being transmitted to Loggly. So
|
95 |
|
96 | ``` js
|
97 | var source = {
|
98 | foo: 1,
|
99 | bar: 2,
|
100 | buzz: {
|
101 | sheep: 'jumped',
|
102 | times: 10
|
103 | }
|
104 | };
|
105 |
|
106 | input.log(source);
|
107 | ```
|
108 |
|
109 | will be logged as:
|
110 |
|
111 | ``` json
|
112 | { "foo": 1, "bar": 2, "buzz": {"sheep": "jumped", "times": 10 }}
|
113 | ```
|
114 |
|
115 | ### Logging arrays
|
116 | It is possible to send arrays, which will result in one single request to Loggly.
|
117 |
|
118 | ``` js
|
119 | input.log([ {iam:'number 1'}, {iam:'number 2'} ])
|
120 | ```
|
121 |
|
122 | ### Searching
|
123 | [Searching][search-api] with node-loggly-bulk is easy. All you have to do is use the search() method defined on each Loggly client:
|
124 |
|
125 | ``` js
|
126 | var util = require('util');
|
127 |
|
128 | client.search('404', function (err, results) {
|
129 | // Inspect the result set
|
130 | console.dir(results.events);
|
131 | });
|
132 | ```
|
133 |
|
134 | The search() method can also take an Object parameter that allows you to set additional search parameters such as: rows, from, until, etc.
|
135 |
|
136 | ``` js
|
137 | var util = require('util');
|
138 |
|
139 | client.search({ query: '404', rows: 10 })
|
140 | .run(function (err, results) {
|
141 | // Inspect the result set
|
142 | console.dir(results.events);
|
143 | });
|
144 | ```
|
145 |
|
146 | See the [Loggly search guide][search] for more details on how to effectively search through your Loggly logs.
|
147 |
|
148 | ## Installation
|
149 |
|
150 | ### Installing npm (node package manager)
|
151 | ``` bash
|
152 | $ curl http://npmjs.org/install.sh | sh
|
153 | ```
|
154 |
|
155 | ### Installing node-loggly-bulk
|
156 | ``` bash
|
157 | $ npm install node-loggly-bulk
|
158 | ```
|
159 |
|
160 | ## Run Tests
|
161 |
|
162 | ### Run Tests by sending events to your Loggly Account
|
163 | All of the node-loggly-bulk tests are written in [vows][vows], and cover all of the use cases described above. You will need to add your Loggly username, password, subdomain, and your loggly token to test/config.json before running tests.
|
164 |
|
165 | ``` js
|
166 | {
|
167 | "token": "your-really-long-token-you-got-when-you-created-an-http-input",
|
168 | "subdomain": "your-subdomain",
|
169 | "auth": {
|
170 | "username": "your-username",
|
171 | "password": "your-password"
|
172 | }
|
173 | }
|
174 | ```
|
175 |
|
176 | Once you have valid Loggly credentials you can run tests with [vows][vows]:
|
177 |
|
178 | ``` bash
|
179 | $ npm test
|
180 | ```
|
181 | ### Run Tests with Mock HTTP Request
|
182 | To mock the HTTP requests and run test cases in your local machine you can run the following command
|
183 | ```bash
|
184 | $ npm run test-as-mock
|
185 | ```
|
186 |
|
187 | #### Author: [Charlie Robbins](http://www.github.com/indexzero)
|
188 | #### Contributors: [Marak Squires](http://github.com/marak), [hij1nx](http://github.com/hij1nx), [Kord Campbell](http://loggly.com), [Erik Hedenström](http://github.com/ehedenst),
|
189 |
|
190 | [api]: http://www.loggly.com/docs/api-overview/
|
191 | [sending-data]: http://www.loggly.com/docs/api-sending-data/
|
192 | [search-api]: http://www.loggly.com/docs/api-retrieving-data/
|
193 | [search]: http://www.loggly.com/docs/search-overview/
|
194 | [vows]: http://vowsjs.org
|