ecs-logging-ruby

This set of libraries allows you to transform your application logs to structured logs that comply with the Elastic Common Schema (ECS). In combination with filebeat you can send your logs directly to Elasticsearch and leverage Kibana's Logs UI to inspect all logs in one single place. See ecs-logging for other ECS logging libraries and more resources about ECS & logging.

---

Please note that this library is in a pre-1.0 version and backwards-incompatible changes might be introduced in future releases. While we strive to comply to semver, we can not guarantee to avoid breaking changes in minor releases.

Installation

Add this line to your application's Gemfile:

gem 'ecs-logging'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install ecs-logging

Usage

Ecs::Logger is a subclass of Ruby's own Logger and responds to the same methods.

require 'ecs/logger'

logger = Ecs::Logger.new($stdout)
logger.info('my informative message')
logger.warn { 'be aware that…' }
logger.error('a_progname') { 'oh no!' }

Logs the following JSON to $stdout:

 {"@timestamp":"2020-11-24T13:32:21.329Z","log.level":"INFO","message":"very informative","ecs.version":"1.4.0"}
 {"@timestamp":"2020-11-24T13:32:21.330Z","log.level":"WARN","message":"be aware that…","ecs.version":"1.4.0"}
 {"@timestamp":"2020-11-24T13:32:21.331Z","log.level":"ERROR","message":"oh no!","ecs.version":"1.4.0","process.title":"a_progname"}

Additionally, it allows for adding additional keys to messages, eg:

logger.info('ok', labels: { my_label: 'value' }, 'trace.id': 'abc-xyz')

Logs:

{
  "@timestamp":"2020-11-24T13:32:21.331Z",
  "log.level":"ERROR",
  "message":"oh no!",
  "ecs.version":"1.4.0",
  "labels":{"my_label":"value"},
  "trace.id":"abc-xyz"
}

To include info about where the log was called, call the methods with include_origin: true, like:

logger.warn('Hello!', include_origin: true)

Resulting in

{
  "@timestamp":"2020-11-24T13:32:21.331Z",
  "log.level":"WARN",
  "message":"Hello!",
  "ecs.version":"1.4.0",
  "log.origin": {
    "file.line": 123,
    "file.name": "my_file.rb",
    "function": "call"
  }
}

Usage with Rack

use EcsLogging::Middleware, $stdout

Example output:

{
  "@timestamp":"2020-12-07T13:44:04.568Z",
  "log.level":"INFO",
  "message":"GET /",
  "ecs.version":"1.4.0",
  "client":{
    "address":"127.0.0.1"
  },
  "http":{
    "request":{
      "method":"GET",
      "body.bytes":"0"
    }
  },
  "url":{
    "domain":"example.org",
    "path":"/",
    "port":"80",
    "scheme":"http"
  }
}

License

Apache 2.0