Table of Contents

• Features
• Requirements
• Setup
• Rails
• Usage
• Development
• Tests
• License
• Credits

Features

Lokilogger is a gem to push logs to Grafana Loki. Some features:

• Push logs to Grafana Loki (either your own or Grafana Cloud)

• Push logs asynchronously

Requirements

1. Ruby

2. Grafana Loki

Setup

To install, run:

gem install lokilogger

You can also add the gem directly to your project:

bundle add lokilogger

Once the gem is installed, you only need to require it:

require "lokilogger"

Rails

First off, regarding Ruby on Rails:

You can use Lokilogger within a Rails application. It has basic no-op implementations to make it compatible. However, you are strongly adviced not use Lokilogger as your default logger in Rails.

Rails does not implement calls to Logger within Async do blocks and therefor calls to e.g. Lokilogger.info() will be executed synchronously. That call will wait for the Loki Backend to respond. If you are using Grafana Cloud this means that any request that would produce some kind of log message will wait for Grafana Cloud to respond. If you really want to use Lokilogger as Rails default logger please make sure to have a Loki instance on the same network with low latency.

Usage

Start by creating a new logger instance:

# required: url, log_level, version and tags
# optional: username and password (if one of them is nil, no auth will be used)
logger = Lokilogger::Logger.new({url:, log_level: 0, version: "v1", username:, password:, tags: {foo: "bar"}})

If you need proxy or custom TLS settings, you can optionally pass as well:

• ssl_options (Faraday docs on ssl options)

• proxy_options (Faraday docs on proxy options)

then it’s straight forward:

Async do
  logger.debug("some debug", {useless: "tag"})
  logger.info("an info", {useless: "tag"})
  logger.warn("a warning", {useless: "tag"})
  logger.error("an error", {useless: "tag"})
  logger.fatal("a fatal", {useless: "tag"})
  logger.unknown("into the unknown", {useless: "tag"})
end

The second argument is extra_tags. This way you can pass custom tags per message. Be aware, that those cannot be nested.

To set the default log level:

logger.level = 1

Please see example/log.rb for an example implementation.

Development

To contribute, run:

git clone
cd LokiLogger
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

License

Credits

• Built with Gemsmith.

• Really useful help by Stefan Piep.