# BunyanSourceRemoteReader

<!-- bunyan_header -->

The RemoteReader is a component of the [Bunyan logging system][bunyan].
Use it in conjunction with one or more remote writers to provide
distributed logging.

Any Bunyan node can be a remote reader, a remote writer, both, or
neither.

If a node runs one or more remote readers, then it can accept log
messages from other nodes. These messages are integrated into the
regular stream of messages processed on that node, and so are made
available to that nodes writers just as if they had originated locally.
The remote messages will contain information on their origin noce, which
you can include in the messages generated by `Bunyan.Writer.Device`
using the `$node` formatting keyword.

If a node runs one or more remote writers, then messages generated on
that node will be forwarded to another node's remote reader. Each writer
is configured to forward to a single reader.

If a node runs both remote readers and remote writers then it can both
receive messages and also forward them to other nodes. This might
conceivably be useful in a situation where you wanted (for example)
regional logging at the `warn` level and rolled-up logging at the
`error` level. To achieve this, each region would run a logger with a
reader, collecting that regions messages. Each reader would also run a
writer, sending only `error` level messages on the the top-level logger.

If a node runs neither a remote reader nor a remote writer, then it
doesn't communicate with other nodes using Bunyan. (It can, however, use
other writers to send messages to cloud-based SaaS logging systems.)

### Installation

~~~ elixir
{ :bunyan_source_remote_reader, "~>0.0.0" }
~~~

### Configuration

This plugin is configured as part of the sources section of the overall
Bunyan configuration.

For context, the main Bunyan config looks like this:

~~~ elixir
config :bunyan,
       [
        read_from: [
          { source, [ source-specific config ] },
          { source, [ source-specific config ] },
          . . .
        ],

        write_to: [
          { writer, [ writer-specific config ] },
          { writer, [ writer-specific config ] },
        ]
      ]
~~~

The configuration described here becomes an entry in the `read_from:`
section. It looks like this:

~~~ elixir
{
  Bunyan.Source.RemoteReader,
  global_name:  «name»,
}
~~~

where «name» is the globally unique name of this reader. This is the
name that you give as the `target_logger_name` option for the remote
writers that forward to this logger.

[bunyan]: (https://github.com/bunyan-logger/bunyan)