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:

1. Add the library to your application's Gemfile and execute Bundler
2. 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.

ip

• 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