Add repo level documentation with GitDocs

.gitdocs.json

@@ -0,0 +1,4 @@
+{
+  "name": "Timber Node",
+  "root": "docs/"
+}

.gitignore

@@ -7,4 +7,4 @@ logs
 coverage
 dist
 notes.md
-docs
+.gitdocs_output

docs/api/index.md

@@ -0,0 +1 @@
+Describe the logger API here

docs/best-practices/errors.md

@@ -0,0 +1 @@
+Talk about catching errors, dealing with 500s, 404s, etc.

docs/best-practices/log-files.md

@@ -0,0 +1,3 @@
+Logging to a file
+Logrotate
+etc...

docs/best-practices/profiling.md

@@ -0,0 +1 @@
+Talk about logging as a profiling tool https://www.npmjs.com/package/winston#profiling.

docs/best-practices/security.md

@@ -0,0 +1 @@
+best practices regarding security

docs/best-practices/shipping.md

@@ -0,0 +1 @@
+Agent vs Package

docs/best-practices/stdout-vs-stderr.md

@@ -0,0 +1 @@
+Explain the difference.

docs/best-practices/transports.md

@@ -0,0 +1 @@
+HTTP vs Syslog

docs/browser/index.md

@@ -0,0 +1 @@
+Browser...

docs/configuration/augmentation.md

@@ -0,0 +1,21 @@
+# Automatic Log Augmentation
+
+Timber for Node will automatically augment all log lines with rich structured data. This will turn ordinary log lines like:
+
+```
+Sent 200 in 45.ms
+```
+
+into this:
+
+```
+Sent 200 in 45.2ms @metadata {"dt": "2017-02-02T01:33:21.154345Z", "level": "info", "context": {"http": {"method": "GET", "host": "timber.io", "path": "/path", "request_id": "abcd1234"}}, "event": {"http_response": {"status": 200, "time_ms": 45.2}}}
+```
+
+But when using Timber for Node in a development environment, having all that extra noise in your console can make it difficult to read your logs. For this reason, Timber only appends metadata when the `NODE_ENV` is set to `production`. If you want to override this setting, you can use the `append_metadata` configuration option.
+
+## How to use it
+
+```js
+timber.config.append_metadata = true
+```

docs/configuration/index.md

@@ -0,0 +1,6 @@
+# Configuration
+
+[Timber for Node](https://github.com/timberio/timber-ruby) ships with a variety of configuration options. Below are a few of the popular ones. For a comprehensive list, see the [timber.config documentation](https://timberio.github.io/timber-node/variable/index.html#static-variable-config).
+
+1. [**Disable automatic log augmentation**](augmentation)
+2. [**Logging to multiple streams**](multiple-streams)

docs/configuration/multiple-streams.md

@@ -0,0 +1,21 @@
+# Logging To Multiple Streams
+
+If you followed the [standard install instructions](../installation), your application will send all logs from `stdout` and `stderr` to Timber. If you prefer to send your logs to multiple destinations Timber has built-in support for this. Using the `attach` function, you can attach multiple writable streams to `stout` and `stderr`.
+
+**Note:** The `attach()` function is a replacement for `install()`. When manually attaching streams, you no longer need to use `install()`.
+
+
+## How to use it
+
+### Example: Logging to Timber & a file
+
+```js
+const fs = require('fs')
+const timber = require('timber')
+
+const http_stream = new timber.transports.HTTPS('{{my-timber-api-key}}')
+const file_stream = fs.createWriteStream('./app_logs', { flags: 'a' })
+
+timber.attach([http_stream, file_stream], process.stdout)
+timber.attach([http_stream, file_stream], process.stderr)
+```

docs/examples/express-winston.md

@@ -0,0 +1,3 @@
+Using express + winston
+
+Link to GitHub repo.

docs/examples/index.md

@@ -0,0 +1 @@
+Example repositories for various setups.

docs/index.md

@@ -0,0 +1,8 @@
+---
+items_prepend:
+  - usage
+  - best-practices
+---
+# Timber Node
+
+Everything you need to know about getting started with logging in Node.

docs/installation/http.md

@@ -0,0 +1,42 @@
+# Node HTTP Installation
+
+1. In your `shell`, *run*: <small style="float: right" class="platform-alt"><a href="/platforms/">prefer to integrate with your platform instead?</a></small>
+
+  ```shell
+  npm install --save timber
+  ```
+
+2. In your entry file, *add*:
+
+  ```js
+  const timber = require('timber');
+
+  const transport = new timber.transports.HTTPS('{{my-timber-api-key}}');
+  timber.install(transport);
+  ```
+
+3. Optionally install middleware:
+
+    - Using [Express](https://github.com/expressjs/express)? ([learn more](../integrations/express)):
+
+      ```js
+      app.use(timber.middlewares.express())
+      ```
+
+4. Optionally integrate with your logger:
+
+    - Using [winston](https://github.com/winstonjs/winston)? ([learn more](../integrations/winston))
+
+      ```js
+      winston.remove(winston.transports.Console);
+      winston.add(winston.transports.Console, { formatter: timber.formatters.Winston });
+      ```
+
+    - Using [bunyan](https://github.com/trentm/node-bunyan)? ([learn more](../integrations/bunyan))
+
+      ```js
+      const log = bunyan.createLogger({
+        name: 'Logger',
+        stream: new timber.transports.Bunyan()
+      });
+      ```

docs/installation/index.md

@@ -0,0 +1,8 @@
+# Node Installation
+
+*Note: We highly recommended [following the instructions within the Timber app](https://app.timber.io), it provides an easy step-by-step guide.*
+
+Depending on your platform you'll want write logs to STDOUT, a file, or deliver them over HTTP to the Timber service. If you're unaware which method to use, checkout our [HTTP, STDOUT, or log files doc](/guides/http-stdout-or-log-files/).
+
+1. [**HTTP** - Recommended. Deliver logs directly from your app.](http)
+2. [**STDOUT** - Advanced. Required external delivery.](stdout)

docs/installation/stdout.md

@@ -0,0 +1,41 @@
+# Node STDOUT Installation
+
+1. In your `shell`, *run*: <small style="float: right" class="platform-alt"><a href="/platforms/">prefer to integrate with your platform instead?</a></small>
+
+  ```shell
+  npm install --save timber
+  ```
+
+2. In your entry file, *add*:
+
+  ```js
+  const timber = require('timber');
+
+  timber.config.append_metadata = true
+  ```
+
+3. Optionally install middleware:
+
+    - Using [Express](https://github.com/expressjs/express)? ([learn more](../integrations/express)):
+
+      ```js
+      app.use(timber.middlewares.express())
+      ```
+
+4. Optionally integrate with your logger:
+
+    - Using [winston](https://github.com/winstonjs/winston)? ([learn more](../integrations/winston))
+
+      ```js
+      winston.remove(winston.transports.Console);
+      winston.add(winston.transports.Console, { formatter: timber.formatters.Winston });
+      ```
+
+    - Using [bunyan](https://github.com/trentm/node-bunyan)? ([learn more](../integrations/bunyan))
+
+      ```js
+      const log = bunyan.createLogger({
+        name: 'Logger',
+        stream: timber.transports.Bunyan
+      });
+      ```

docs/integrations/express.md

@@ -0,0 +1,62 @@
+The [Timber for Node](https://github.com/timberio/timber-node) [Express](http://expressjs.com) integration automatically outputs [augmented](/concepts/structuring-through-augmentation/) log lines for all HTTP events.
+
+|You'll Get|
+|:------|
+|<i>+</i>[HTTP request event](/concepts/log-event-json-schema/events/http-request)|
+|<i>+</i>[HTTP response event](/concepts/log-event-json-schema/events/http-response)|
+
+
+## What you can do
+
+1. [**Trace HTTP requests**](/app/console-log-viewer/trace-http-requests)
+2. [**Inspect HTTP requests & their parameters**](/app/console-log-viewer/inspect-http-requests)
+3. [**Inspect Express logs and view their associated metadata**](/app/console-log-viewer/view-a-logs-metadata-context)
+4. [**Search on Express structured data**](/app/console-log-viewer/searching)
+5. [**Alert on Express structured data**](/app/alerts)
+6. [**Graph & visualize Express structured data**](/app/graphs)
+
+
+## Installation
+
+```js
+const express = require('express')
+const timber = require('timber')
+
+const transport = new timber.transports.HTTPS('your-timber-api-key');
+timber.install(transport);
+
+const app = express()
+
+app.use(timber.middlewares.express())
+
+app.get('/', function (req, res) {
+  res.send('hello, world!')
+})
+
+// Output when loading index route:
+// => Started GET "/" @metadata {"level": "error", "context": {...}}
+// => Outgoing HTTP response 200 in 2ms @metadata {"level": "error", ... }
+```
+
+## Configuration
+
+You can pass a configuration object as an argument to the middleware if you want to use a custom configuration. The available options are:
+
+- `capture_request_body` (`boolean`): Enables capturing of the http request body data (`false` by default)
+- `combine_http_events` (`boolean`): If enabled, the HTTPRequest and HTTPResponse events will be combined in a single log message (`false` by defaut)
+- `logger` (`object`): Pass a reference of your logger if you want the express logs sent to multiple destinations (read the below section for more information)
+
+## Using with a custom logger
+
+If you're using winston or bunyan for logging, it's possible to route the express event logs through your preferred logger. This is not required if you're only sending your logs to Timber, but may be desired if you want the express event logs sent to multiple transports streams. To enable this, pass a reference of your logger to the middleware:
+
+```js
+// If you're using winston:
+const winston = require('winston')
+app.use(timber.middlewares.express({ logger: winston }))
+
+// If you're using bunyan:
+const bunyan = require('bunyan')
+const logger = bunyan.createLogger({ name: 'Custom Logger' })
+app.use(timber.middlewares.express({ logger: winston }))
+```

docs/integrations/system.md

@@ -0,0 +1,16 @@
+The System / Server integration captures system level context upon initialization, augmenting your logs with structured data like `hostname`, `ip`, `pid`, and more.
+
+|You'll Get|
+|:------|
+|<i>+</i>[System context](/concepts/log-event-json-schema/context/system)|
+
+
+## What you can do
+
+1. [**Search your logs with this data**](/app/console-log-viewer/searching) - `system.hostname:server123.myhost.com`
+2. [**Access this data by viewing a log's metadata & context**](/app/console-log-viewer/view-a-logs-metadata-context)
+
+
+## Installation
+
+This integration is installed automatically upon initialization. There is nothing you need to do.

docs/loggers/bunyan.md

@@ -0,0 +1,22 @@
+The [Timber for Node](https://github.com/timberio/timber-node) [Bunyan](https://github.com/trentm/node-bunyan) integration works with the Bunyan logger to ensure structured data is properly captured, providing for seamless integration between the bunyan logger and Timber.
+
+## Installation
+
+This integration is setup when you install Timber. Please follow the instructions for [installing Timber](../installation) to use this integration.
+
+## Example
+
+```javascript
+const bunyan = require('bunyan')
+const timber = require('timber')
+
+const transport = new timber.transports.HTTPS('your-api-key')
+timber.install(transport)
+
+const log = bunyan.createLogger({ name: 'Timber Logger' })
+
+log.info('Sample log message')
+
+// Output:
+// => Sample log message @metadata {"level": "info", ... }
+```

docs/loggers/console.md

@@ -0,0 +1,12 @@
+Timber for Node ships with an integration for the standard JavaScript `console` functions. This integration allows you to either output standard logs or append logs with custom metadata or events using the builtin `console.log` functions. See [usage](../usage) for more details.
+
+
+## Warning
+You might be wondering by now that why can't we simply use console.log() for logging, afterall its built in. While console.log() can be good for immediate debugging it shouldn't be used a logger at the application level. Few of the reasons are:
+
+* You can't switch off the logs. Once a log statement is encountered, it will always be printed.
+* You can't assign levels to logging. For example you might want certain kinds of logs only in development and not in production.
+
+## Installation
+
+This integration is automatically setup when you install Timber. Please follow the instructions for [installing Timber](../installation) to use the console integration.

docs/loggers/index.md

@@ -0,0 +1,10 @@
+http://www.jyotman.xyz/post/logging-in-node.js-done-right: Setting up proper logging in Node.js applications can be bit overwhelming at first due to the plethora of modules available through NPM. But its all about diving and testing a few modules and then getting comfortable with the ones you like. Some of the popular modules for logging in Node.js are
+
+Morgan
+Debug
+Winston
+Log
+Bunyan
+Pino
+
+Luckily, you can use timber-node with all of these popular loggers automatically.

docs/loggers/log.md

@@ -0,0 +1 @@
+https://www.npmjs.com/package/log

docs/loggers/winston.md

@@ -0,0 +1,22 @@
+The [Timber for Node](https://github.com/timberio/timber-node) [Winston](https://github.com/winstonjs/winston) integration works with the Winston logger to ensure structured data is properly captured, providing for seamless integration between the Winston logger and Timber.
+
+## Installation
+
+```javascript
+var winston = require('winston');
+var timber = require('timber');
+
+var logger = new (winston.Logger)({
+  transports: [
+  	// you can put any other transports here
+    new timber.transports.Winston('your-api-key', options)
+  ]
+});
+
+```
+
+## Example
+
+For more details examples demonstrating Winston with Timber, you can check out the following repositories:
+
+1. [Winston + Express](https://github.com/timberio/examples/tree/master/node/express-winston)

docs/troubleshooting.md

@@ -0,0 +1,15 @@
+If you ever run into an issue while using Timber for Node, you can use the built-in debug logger to help identify the issue. When enabling the debug logger, Timber will write verbose debug logs to any stream you supply.
+
+
+## How to use it
+
+The most common way to use the debug logger is with a file stream, this can be done like this:
+
+```js
+const timber = require('timber')
+const fs = require('fs')
+
+timber.config.debug_logger = fs.createWriteStream('./debug.log', {flags: 'a'})
+```
+
+You can supply the `debug_logger` to any writeable stream. It's not recommended to set the `debug_logger` to `stdout` or `stderr` since Timber attaches to those streams by default.