1 | # node-loggly
|
2 |
|
3 | A client implementation for Loggly in node.js
|
4 |
|
5 | ## Installation
|
6 |
|
7 | ### Installing npm (node package manager)
|
8 | <pre>
|
9 | curl http://npmjs.org/install.sh | sh
|
10 | </pre>
|
11 |
|
12 | ### Installing node-loggly
|
13 | <pre>
|
14 | [sudo] npm install loggly
|
15 | </pre>
|
16 |
|
17 | ## Usage
|
18 |
|
19 | The node-loggly library is compliant with the [Loggly API][0]. Using node-loggly is easy for a variety of scenarios: logging, working with devices and inputs, searching, and facet searching.
|
20 |
|
21 | ### Getting Started
|
22 | Before we can do anything with loggly, we have to create a client with valid credentials. We will authenticate for you automatically:
|
23 | <pre>
|
24 | var loggly = require('loggly');
|
25 | var config = {
|
26 | subdomain: "your-subdomain",
|
27 | auth: {
|
28 | username: "your-username",
|
29 | password: "your-password"
|
30 | }
|
31 | };
|
32 | var client = loggly.createClient(config);
|
33 | </pre>
|
34 |
|
35 | ### Logging
|
36 | There are two ways to send log information to loggly via node-loggly. The first is to simply call client.log with an appropriate input token:
|
37 |
|
38 | <pre>
|
39 | client.log('your-really-long-input-token', '127.0.0.1 - Theres no place like home', function (err, result) {
|
40 | // Do something once you've logged
|
41 | });
|
42 | </pre>
|
43 |
|
44 | Note that the callback in the above example is optional, if you prefer the 'fire and forget' method of logging:
|
45 | <pre>
|
46 | client.log('your-really-long-input-token', '127.0.0.1 - Theres no place like home');
|
47 | </pre>
|
48 |
|
49 | The second way to send log information to loggly is to do so once you've retrieved an input directly from loggly:
|
50 | <pre>
|
51 | client.getInput('your-input-name', function (err, input) {
|
52 | input.log('127.0.0.1 - Theres no place like home');
|
53 | });
|
54 | </pre>
|
55 |
|
56 | Again the callback in the above example is optional and you can pass it if you'd like to.
|
57 |
|
58 | ### Logging Shallow JSON Object Literals
|
59 | 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][1]. So
|
60 |
|
61 | <pre>
|
62 | var source = {
|
63 | foo: 1,
|
64 | bar: 2,
|
65 | buzz: 3
|
66 | };
|
67 |
|
68 | input.log(source);
|
69 | </pre>
|
70 |
|
71 | will be logged as:
|
72 |
|
73 | <pre>
|
74 | foo=1,bar=2,buzz=3
|
75 | </pre>
|
76 |
|
77 | ### Searching
|
78 | [Searching][3] with node-loggly is easy. All you have to do is use the search() method defined on each loggly client:
|
79 | <pre>
|
80 | var util = require('util');
|
81 |
|
82 | client.search('404', function (err, results) {
|
83 | // Inspect the result set
|
84 | util.inspect(results.data);
|
85 | });
|
86 | </pre>
|
87 |
|
88 | The search() exposes a chainable interface that allows you to set additional search parameters such as: ip, input name, rows, start, end, etc.
|
89 | <pre>
|
90 | var util = require('util');
|
91 |
|
92 | client.search('404')
|
93 | .meta({ ip: '127.0.0.1', inputname: test })
|
94 | .context({ rows: 10 })
|
95 | .run(function (err, results) {
|
96 | // Inspect the result set
|
97 | util.inspect(results.data);
|
98 | });
|
99 | </pre>
|
100 |
|
101 | The context of the search (set using the `.context()` method) represents additional parameters in the Loggly API besides the search query itself. See the [Search API documentation][9] for a list of all options.
|
102 |
|
103 | Metadata set using the `.meta()` method is data that is set in the query parameter of your Loggly search, but `:` delimited. For more information about search queries in Loggly, check out the [Search Language Guide][4] on the [Loggly Wiki][5].
|
104 |
|
105 | ### Facet Searching
|
106 | Loggly also exposes searches that can return counts of events over a time range. These are called [facets][6]. The valid facets are 'ip', 'date', and 'input'. Performing a facet search is very similar to a normal search:
|
107 | <pre>
|
108 | var util = require('util');
|
109 |
|
110 | client.facet('ip', '404')
|
111 | .context({ buckets: 10 })
|
112 | .run(function (err, results) {
|
113 | // Inspect the result set
|
114 | util.inspect(results.data);
|
115 | });
|
116 | </pre>
|
117 |
|
118 | The chaining and options for the facet method(s) are the same as the search method above.
|
119 |
|
120 | ### Working with Devices and Inputs
|
121 | Loggly exposes several entities that are available through node-loggly: inputs and devices. For more information about these terms, checkout the [Loggly Jargon][7] on the wiki. There are several methods available in node-loggly to work with these entities:
|
122 |
|
123 | <pre>
|
124 | //
|
125 | // Returns all inputs associated with your account
|
126 | //
|
127 | client.getInputs(function (err, inputs) { /* ... */ });
|
128 |
|
129 | //
|
130 | // Returns an input with the specified name
|
131 | //
|
132 | client.getInput('input-name', function (err, input) { /* ... */ });
|
133 |
|
134 | //
|
135 | // Returns all devices associated with your account
|
136 | //
|
137 | client.getDevices(function (err, devices) { /* ... */ });
|
138 | </pre>
|
139 |
|
140 | ## Run Tests
|
141 | All of the node-loggly tests are written in [vows][8], and cover all of the use cases described above. You will need to add your Loggly username, password, subdomain, and a test input to test/data/test-config.json before running tests:
|
142 | <pre>
|
143 | {
|
144 | "subdomain": "your-subdomain",
|
145 | "auth": {
|
146 | "username": "your-username",
|
147 | "password": "your-password"
|
148 | },
|
149 | "inputs": [{
|
150 | "token": "your-really-long-token-you-got-when-you-created-an-http-input",
|
151 | "id": 000 // ID of this input
|
152 | }]
|
153 | }
|
154 | </pre>
|
155 |
|
156 | Once you have valid Rackspace credentials you can run tests with [vows][8]:
|
157 | <pre>
|
158 | vows test/*-test.js --spec
|
159 | </pre>
|
160 |
|
161 | #### Author: [Charlie Robbins](http://www.github.com/indexzero)
|
162 | #### Contributors: [Marak Squires](http://github.com/marak), [hij1nx](http://github.com/hij1nx), [Kord Campbell](http://loggly.com)
|
163 |
|
164 | [0]: http://wiki.loggly.com/apidocumentation
|
165 | [1]: http://wiki.loggly.com/loggingfromcode
|
166 | [3]: http://wiki.loggly.com/retrieve_events#search_uri
|
167 | [4]: http://wiki.loggly.com/searchguide
|
168 | [5]: http://wiki.loggly.com/
|
169 | [6]: http://wiki.loggly.com/retrieve_events#facet_uris
|
170 | [7]: http://wiki.loggly.com/loggingjargon
|
171 | [8]: http://vowsjs.org
|
172 | [9]: http://wiki.loggly.com/retrieve_events#optional |
\ | No newline at end of file |