libs/js/jquery-mobile-1.2.0/node_modules/grunt/node_modules/prompt/node_modules/winston/node_modules/loggly/README.md

   1 # node-loggly
   2
   3 A client implementation for Loggly in node.js
   4
   5 ## Installation
   6
   7 ### Installing npm (node package manager)
   8 ``` bash
   9   $ curl http://npmjs.org/install.sh | sh
  10 ```
  11
  12 ### Installing node-loggly
  13 ``` bash
  14   $ [sudo] npm install loggly
  15 ```
  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
  24 ``` js
  25   var loggly = require('loggly');
  26   var config = {
  27     subdomain: "your-subdomain",
  28     auth: {
  29       username: "your-username",
  30       password: "your-password"
  31     }
  32   };
  33   var client = loggly.createClient(config);
  34 ```
  35
  36 ### Logging
  37 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:
  38
  39 ``` js
  40   client.log('your-really-long-input-token', '127.0.0.1 - Theres no place like home', function (err, result) {
  41     // Do something once you've logged
  42   });
  43 ```
  44
  45 Note that the callback in the above example is optional, if you prefer the 'fire and forget' method of logging:
  46
  47 ``` js
  48   client.log('your-really-long-input-token', '127.0.0.1 - Theres no place like home');
  49 ```
  50
  51 The second way to send log information to Loggly is to do so once you've retrieved an input directly from Loggly:
  52
  53 ``` js
  54   client.getInput('your-input-name', function (err, input) {
  55     input.log('127.0.0.1 - Theres no place like home');
  56   });
  57 ```
  58
  59 Again the callback in the above example is optional and you can pass it if you'd like to.
  60
  61 ### Logging Shallow JSON Object Literals 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][1]. 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 Objects to JSON Enabled Loggly Inputs
  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 ### Searching
 116 [Searching][3] with node-loggly is easy. All you have to do is use the search() method defined on each Loggly client:
 117
 118 ``` js
 119   var util = require('util');
 120
 121   client.search('404', function (err, results) {
 122     // Inspect the result set
 123     util.inspect(results.data);
 124   });
 125 ```
 126
 127 The search() exposes a chainable interface that allows you to set additional search parameters such as: ip, input name, rows, start, end, etc.
 128
 129 ``` js
 130   var util = require('util');
 131
 132   client.search('404')
 133         .meta({ ip: '127.0.0.1', inputname: test })
 134         .context({ rows: 10 })
 135         .run(function (err, results) {
 136           // Inspect the result set
 137           util.inspect(results.data);
 138         });
 139 ```
 140
 141 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.
 142
 143 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].
 144
 145 ### Facet Searching
 146 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:
 147
 148 ``` js
 149   var util = require('util');
 150
 151   client.facet('ip', '404')
 152         .context({ buckets: 10 })
 153         .run(function (err, results) {
 154           // Inspect the result set
 155           util.inspect(results.data);
 156         });
 157 ```
 158
 159 The chaining and options for the facet method(s) are the same as the search method above.
 160
 161 ### Working with Devices and Inputs
 162 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:
 163
 164 ``` js
 165   //
 166   // Returns all inputs associated with your account
 167   //
 168   client.getInputs(function (err, inputs) { /* ... */ });
 169
 170   //
 171   // Returns an input with the specified name
 172   //
 173   client.getInput('input-name', function (err, input) { /* ... */ });
 174
 175   //
 176   // Returns all devices associated with your account
 177   //
 178   client.getDevices(function (err, devices) { /* ... */ });
 179 ```
 180
 181 ## Run Tests
 182 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 two test inputs to test/data/test-config.json before running tests. When configuring the test inputs on Loggly, the first test input should be named 'test' using the HTTP service. The second input should be name 'test_json' using the HTTP service with the JSON logging option enabled:
 183
 184 ``` js
 185   {
 186     "subdomain": "your-subdomain",
 187     "auth": {
 188       "username": "your-username",
 189       "password": "your-password"
 190     },
 191     "inputs": {
 192       "test": {
 193         //
 194         // Token and ID of your plain-text input.
 195         //
 196         "token": "your-really-long-token-you-got-when-you-created-an-http-input",
 197         "id": 000
 198       },
 199       "test_json": {
 200         //
 201         // Token and ID of your JSON input.
 202         //
 203         "token": "your-really-long-token-you-got-when-you-created-an-http-input",
 204         "id": 001
 205       },
 206     }
 207   }
 208 ```
 209
 210 Once you have valid Loggly credentials you can run tests with [vows][8]:
 211
 212 ``` bash
 213   $ npm test
 214 ```
 215
 216 #### Author: [Charlie Robbins](http://www.github.com/indexzero)
 217 #### Contributors: [Marak Squires](http://github.com/marak), [hij1nx](http://github.com/hij1nx), [Kord Campbell](http://loggly.com), [Erik Hedenström](http://github.com/ehedenst),
 218
 219 [0]: http://wiki.loggly.com/apidocumentation
 220 [1]: http://wiki.loggly.com/loggingfromcode
 221 [3]: http://wiki.loggly.com/retrieve_events#search_uri
 222 [4]: http://wiki.loggly.com/searchguide
 223 [5]: http://wiki.loggly.com/
 224 [6]: http://wiki.loggly.com/retrieve_events#facet_uris
 225 [7]: http://wiki.loggly.com/loggingjargon
 226 [8]: http://vowsjs.org
 227 [9]: http://wiki.loggly.com/retrieve_events#optional