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
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
Credits
-
Built with Gemsmith.
-
Really useful help by Stefan Piep.