---
title: Ruby on Rails Log Collection
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: >-
  Docs > Log Management > Log Collection and Integrations > Ruby on Rails Log
  Collection
---

# Ruby on Rails Log Collection

## Overview{% #overview %}

To send your logs to Datadog, log to a file with [`Lograge`](https://github.com/roidrage/lograge) and [tail](https://docs.datadoghq.com/glossary.md#tail) this file with your Datadog Agent. When setting up logging with Ruby, keep in mind the [reserved attributes](https://docs.datadoghq.com/logs/log_configuration/attributes_naming_convention.md#reserved-attributes).

Using Lograge, you can transform the standard text-based log format, like in this example:

```text
Started GET "/" for 127.0.0.1 at 2012-03-10 14:28:14 +0100
Processing by HomeController#index as HTML
  Rendered text template within layouts/application (0.0ms)
  Rendered layouts/_assets.html.erb (2.0ms)
  Rendered layouts/_top.html.erb (2.6ms)
  Rendered layouts/_about.html.erb (0.3ms)
  Rendered layouts/_google_analytics.html.erb (0.4ms)
Completed 200 OK in 79ms (Views: 78.8ms | ActiveRecord: 0.0ms)
```

To the following JSON format of the log, which provides more structure:

```json
{
  "timestamp": "2016-01-12T19:15:19.118829+01:00",
  "level": "INFO",
  "logger": "Rails",
  "method": "GET",
  "path": "/jobs/833552.json",
  "format": "json",
  "controller": "jobs",
  "action": "show",
  "status": 200,
  "duration": 58.33,
  "view": 40.43,
  "db": 15.26
}
```

## Install and configure your logger{% #install-and-configure-your-logger %}

{% tab title="Lograge" %}

1. Add the `lograge` gem to your project:
   ```ruby
   gem 'lograge'
   ```
1. In your configuration file, set the following to configure Lograge:
   ```ruby
   # Lograge config
   config.lograge.enabled = true
   
   # This specifies to log in JSON format
   config.lograge.formatter = Lograge::Formatters::Json.new
   
   ## Disables log coloration
   config.colorize_logging = false
   
   # Log to a dedicated file
   config.lograge.logger = ActiveSupport::Logger.new(Rails.root.join('log', "#{Rails.env}.log"))
   
   # This is useful if you want to log query parameters
   config.lograge.custom_options = lambda do |event|
       { :ddsource => 'ruby',
         :params => event.payload[:params].reject { |k| %w(controller action).include? k }
       }
   end
   ```
**Note**: Lograge can also add contextual information to your logs. See the [Lograge documentation](https://github.com/roidrage/lograge#installation) for more details.

For a more in-depth example of this setup, see [How to collect, customize, and manage Rails application logs](https://www.datadoghq.com/blog/managing-rails-application-logs).

### RocketPants{% #rocketpants %}

To configure Lograge for `rocket_pants` controllers, in the `config/initializers/lograge_rocketpants.rb` file (the location can vary depending on your project):

```ruby
# Come from here:
#   https://github.com/Sutto/rocket_pants/issues/111
app = Rails.application
if app.config.lograge.enabled
  ActiveSupport::LogSubscriber.log_subscribers.each do |subscriber|
    case subscriber
      when ActionController::LogSubscriber
        Lograge.unsubscribe(:rocket_pants, subscriber)
    end
  end
  Lograge::RequestLogSubscriber.attach_to :rocket_pants
end
```

{% /tab %}

{% tab title="Grape" %}

1. Add the `grape_logging` gem to your project:

   ```ruby
   gem 'grape_logging'
   ```

1. Add the additional configuration to Grape:

   ```ruby
   use GrapeLogging::Middleware::RequestLogger,
         instrumentation_key: 'grape',
         include: [ GrapeLogging::Loggers::Response.new,
                   GrapeLogging::Loggers::FilterParameters.new ]
   ```

1. Create the `config/initializers/instrumentation.rb` file and add the following configuration:

   ```ruby
   # Subscribe to grape request and log with a logger dedicated to Grape
   grape_logger = Logging.logger['Grape']
   ActiveSupport::Notifications.subscribe('grape') do |name, starts, ends, notification_id, payload|
       grape_logger.info payload
   end
   ```

{% /tab %}

## Configure the Datadog Agent{% #configure-the-datadog-agent %}

Once [log collection is enabled](https://docs.datadoghq.com/agent/logs.md?tab=tailfiles#activate-log-collection), do the following to set up [custom log collection](https://docs.datadoghq.com/agent/logs.md?tab=tailfiles#custom-log-collection) to tail your log files and send them to Datadog.

1. Create a `ruby.d/` folder in the `conf.d/` [Agent configuration directory](https://docs.datadoghq.com/agent/configuration/agent-configuration-files.md?tab=agentv6v7#agent-configuration-directory).
1. Create a `conf.yaml` file in `ruby.d/` with the following content:
   ```yaml
     logs:
       - type: file
         path: "<RUBY_LOG_FILE_PATH>.log"
         service: <SERVICE_NAME>
         source: ruby
         sourcecategory: sourcecode
         ## Uncomment the following processing rule for multiline logs if they
         ## start by the date with the format yyyy-mm-dd
         #log_processing_rules:
         #  - type: multi_line
         #    name: new_log_start_with_date
         #    pattern: \d{4}\-(0?[1-9]|1[012])\-(0?[1-9]|[12][0-9]|3[01])
   ```
1. [Restart the Agent](https://docs.datadoghq.com/agent/configuration/agent-commands.md#restart-the-agent).
1. Run the [Agent's status subcommand](https://docs.datadoghq.com/agent/configuration/agent-commands.md?tab=agentv6v7#agent-status-and-information) and look for `ruby` under the `Checks` section to confirm that logs are successfully submitted to Datadog.

If logs are in JSON format, Datadog automatically [parses the log messages](https://docs.datadoghq.com/logs/log_configuration/parsing.md) to extract log attributes. Use the [Log Explorer](https://docs.datadoghq.com/logs/explorer.md) to view and troubleshoot your logs.

## Connect logs and traces{% #connect-logs-and-traces %}

If APM is enabled for this application, you can improve the connection between application logs and traces by following the [APM Ruby logging instructions](https://docs.datadoghq.com/tracing/other_telemetry/connect_logs_and_traces/ruby.md) to automatically add trace and span IDs in your logs.

## Best practices{% #best-practices %}

Add additional context (user, session, action, and metrics) to your logs when possible.

Instead of logging simple string messages, you can use log hashes as shown in the following example:

```ruby
my_hash = {'user' => '1234', 'button_name'=>'save','message' => 'User 1234 clicked on button saved'};
logger.info(my_hash);
```

The hash is converted into JSON and you can carry out analytics for `user` and `button_name`:

```json
{
  "timestamp": "2016-01-12T19:15:18.683575+01:00",
  "level": "INFO",
  "logger": "WelcomeController",
  "message": {
    "user": "1234",
    "button_name": "save",
    "message": "User 1234 clicked on button saved"
  }
}
```

## Further Reading{% #further-reading %}

- [Lograge Documentation](https://github.com/roidrage/lograge)
- [Learn how to process your logs](https://docs.datadoghq.com/logs/log_configuration/processors.md)
- [Log Collection Troubleshooting Guide](https://docs.datadoghq.com/logs/faq/log-collection-troubleshooting-guide.md)
- [How to collect, customize, and manage Rails application logs](https://www.datadoghq.com/blog/managing-rails-application-logs/)
- [How to manage log files using logrotate](https://www.datadoghq.com/blog/log-file-control-with-logrotate/)
- [Glossary entry for "tail"](https://docs.datadoghq.com/glossary.md#tail)