Ruby and Ruby on Rails

The Ruby library lets you send logs from your Ruby and Ruby on Rails applications to LogDNA.

These libraries are open source. Check out the Ruby library repository and the Ruby on Rails library repository on GitHub.

Requirements

Installing the library requires RubyGems and Bundler.

Installation

You can install the library in one of two ways:

Add the library to your application's Gemfile and execute Bundler
Install the library using gem install

Ruby

Add logdna to your application’s Gemfile:

gem 'logdna'

And then execute Bundler:

$ bundle

Alternatively, use:

$ gem install logdna

Ruby on Rails

Add logdna-rails your application’s Gemfile:

gem 'logdna-rails'

And then execute Bundler:

$ bundle

Alternatively, use:

$ gem install logdna-rails

Configuration

To add the library to your application, simply initialize the logger with your LogDNA API key and an optional Hash of options.

For the plain Ruby library, add the following to initialize the logger:

logger = Logdna::Ruby.new(api_key, options)

api_key

Required
Type: String

The LogDNA Ingestion Key associated with your account.

options

Optional
Type: Hash
Default: nil

A Hash of optional arguments used to configure the logger.

app

Type: String
Default: ''
Example: YourCustomApp
Max Length: 80

The name of the application.

endpoint

Type: String
Default: ''
Example: https://logs.logdna.com/logs/ingest

The URL to send logs to. Defaults to LogDNA’s cloud ingestion servers.

env

Type: String
Default: ''
Example: Development, Staging, Production

The environment that the application is running in.

flushbyte

Type: FixNum
Default: 500000

The maximum size (in bytes) of the log buffer before it is flushed.

flushtime

Type: Float
Default: 0.25

The amount of time to wait (in seconds) before flushing the log buffer.

hostname

Type: String
Default: ''
Example: YourCustomHostname
Max Length: 80

The name of the host.

Type: String
Default: ''
Example: 10.0.0.1

The IP address of the host.

level

Type: String
Default: INFO
Examples: TRACE, DEBUG, INFO, WARN, ERROR, FATAL, YourCustomLevel

The default level of each log message.

mac

Type: String
Default ''
Example: C0:FF:EE:C0:FF:EE

The network MAC address of the host.

meta

Type: Hash
Default: nil
Example: {:once => {:first => "nested1", :another => "nested2"}}

Extra fields to send with each log message. These fields can store any data type, including nested Hashes.

Ruby on Rails Configuration

To configure the library for Ruby on Rails, initialize a new logger using RailsLogger.new():

logger = Logdna::RailsLogger.new(api_key, options)

The arguments are the same as the Ruby logger.

Usage

log(line, [options])

This method generates a new log message and sends it to LogDNA.

line

Required
Type: String
Default: ''

The text that makes up the log message.

options

Optional
Type: Hash
Default: nil

A hash of optional arguments applied to this specific log message. This supports all of the arguments shown in the Configuration section.

Examples

To send a log, use the log method:

logger.log('This is my first log')

Send logs with a particular level using the log.<level> methods:

logger.warn('This is a warning message')
logger.fatal('This is a fatal message')
logger.debug('This is a debug message' )

You can modify the logger’s options after initialization. For example, let's change the default log level to FATAL:

logger.level = 'FATAL'

Or:

logger.level = Logger::FATAL

Here, we set a custom level, app name, environment, and metadata for a specific log message:

logger.log('This is warn message', {:meta => {:meta => "data"}, :level => "WARN", :app => "MyApp", :env => "DEVELOPMENT"})

clear()

Resets the current level, app, environment, and metadata for all log events.

?

Checks whether the default log level is set to the specified level. Returns true if the levels match, or false if they don't.

For example, this checks to see if the default log level is set to INFO:

# Current log level is set to INFO
logger.info? => true
logger.warn? => false

FAQ

Logger Limitations

Avoid creating multiple instances of the logger. Although it is not strictly enforced, the logger is a singleton and should only be initialized once.

The logger also expects you to pass in JSON-formatted data for the log message. Otherwise, your logs may not be properly parsed

Log Colors in the LogDNA Web App

The LogDNA web app displays logs in different colors depending on their level:

Trace, Debug, Info
Warn
Error, Fatal