Better Stack Ruby & Rails

Where do you want to collect your Ruby logs from?

• Rails application
• Rack application
• Ruby code

Logging from Rails

Collect logs from your Rails application, including your Sidekiq jobs. This integration also supports Structured Events in Rails 8.1 or higher for rich, queryable event logging.

1. Install

Install Better Stack Rails Gem:

bundle add logtail-rails

2. Setup

Set up Better Stack Rails Gem in config/application.rb:

module YourProject
  class Application < Rails::Application
    # ...
    # configuration of your project
    # ...

    config.logger = Logtail::Logger.create_default_logger(
      "$SOURCE_TOKEN",
      ingesting_host: "$INGESTING_HOST",
    )
  end
end

3. Start logging 🎉

Use Rails logger as usual:

Rails.logger.error("Something bad happened.")
Rails.logger.warn("Log message with structured logging.", {
    item: "Orange Soda",
    price: 100.00
})

# Send a structured event (in Rails 8.1 or higher)
Rails.event.notify("user.signed_up", email: "user@example.com")

You should see your logs in Better Stack Logs → Live tail.

Check out the Ruby on Rails dashboard.

Logging from Rack

Collect logs from any Rack-based framework such as Sinatra, Hanami, Padrino, or Roda.

1. Install

Install Better Stack Rack Gem:

bundle add logtail-rack

2. Setup

Set up Better Stack Rack Gem in your config.ru:

require 'logtail-rack'

# Initialization of logging middlewares (you don't have to use all)
use Logtail::Integrations::Rack::HTTPContext
use Logtail::Integrations::Rack::HTTPEvents
use Logtail::Integrations::Rack::ErrorEvent
use Logtail::Integrations::Rack::UserContext
use Logtail::Integrations::Rack::SessionContext

# Logger instance initialization
http_io_device = Logtail::LogDevices::HTTP.new(
  "$SOURCE_TOKEN",
  ingesting_host: "$INGESTING_HOST",
)
logger = Logtail::Logger.new(http_io_device)
Logtail::Config.instance.logger = logger

# Here is your application initialization
run ...

3. Start logging 🎉

Use the instantiated logger instance to send logs to Better Stack:

logger = Logtail::Config.instance.logger

logger.info("I am using Better Stack! 🚀")

# You can also provide additional information when logging
logger.debug("Logging structured data...",
  name: {
    first: "John",
    last: "Smith"
  },
  id: 123456
)

You should see your logs in Better Stack Logs → Live tail.

Logging from Ruby

Collect logs from your Ruby code.

1. Install

Install Better Stack Gem:

bundle add logtail

2. Setup

Set up Better Stack Ruby client:

require "logtail"

http_io_device = Logtail::LogDevices::HTTP.new(
  "$SOURCE_TOKEN",
  ingesting_host: "$INGESTING_HOST",
)
logger = Logtail::Logger.new(http_io_device)

3. Start logging 🎉

Use Ruby logger as usual:

logger.error("Something bad happened.")
logger.warn("Log message with structured logging.", {
    item: "Orange Soda",
    price: 100.00
})

# Close logger to ensure that all logs are sent to Better Stack
logger.close

You should see your logs in Better Stack → Live tail.

N+1 queries

Bullet detects N+1 queries, unused eager loading, and missing counter caches in your Rails app. We'll log each detection as a structured event, tagged with the file and line that triggered it.

1. Install

Add the Bullet gem:

bundle add bullet

2. Configure

Enable Bullet in config/environments/production.rb and register a notifier that emits one structured event per detection through Rails.logger:

config.after_initialize do
  Bullet.enable = true

  class BetterStackBulletNotifier < UniformNotifier::Base
    OPTIMIZATION_TYPES = {
      /\AUSE eager loading/   => "use_eager_loading",
      /\AAVOID eager loading/ => "avoid_eager_loading",
      /\ANeed Counter Cache/  => "need_counter_cache"
    }.freeze

    def self.active? = true

    def self._out_of_channel_notify(data)
      _, type = OPTIMIZATION_TYPES.find { |p, _| data[:title] =~ p }
      Rails.logger.warn(data[:title], bullet: {
        optimization_type: type,
        location: data[:body].to_s[type == "need_counter_cache" ? /\A\s*(\S.*?=>\s*\[[^\]]+\])/ : /Call stack\n  ([^\n]+)/, 1]
      })
    end
  end

  UniformNotifier.singleton_class.prepend(Module.new do
    def active_notifiers
      super + [BetterStackBulletNotifier]
    end
  end)
end

BetterStackBulletNotifier is a regular UniformNotifier — the same library Bullet uses for its other output channels. It runs alongside any Bullet notifiers you already have enabled (alert, console, the in-browser footer) without affecting them.

3. Trigger a detection

Trigger an N+1 in your app. Open Live tail and you'll see one structured event per detection:

{
  "level": "warn",
  "message": "N+1 query detected",
  "bullet": {
    "optimization_type": "use_eager_loading",
    "location": "app/views/posts/index.html.erb:8:in `each'"
  }
}

Sidekiq job metrics

We turn OpenTelemetry traces from Sidekiq into metrics automatically.

1. Install

Add the OpenTelemetry gems:

bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-sidekiq

2. Setup

Set up tracing in config/initializers/opentelemetry.rb. This initializer covers both enqueueing and processing jobs.

require "opentelemetry/sdk"
require "opentelemetry/exporter/otlp"
require "opentelemetry/instrumentation/sidekiq"

OpenTelemetry::SDK.configure do |config|
  config.resource = OpenTelemetry::SDK::Resources::Resource.create(
    "service.name" => "your-app",
  )

  config.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: "https://$INGESTING_HOST/v1/traces",
        headers: { "Authorization" => "Bearer $SOURCE_TOKEN" },
        compression: "gzip",
      )
    )
  )

  config.use "OpenTelemetry::Instrumentation::Sidekiq", {
    # Name spans after the job class instead of the queue
    span_naming: :job_class,
    # Keep each job in its own trace, linked to the trace that enqueued it
    propagation_style: :link,
  }
end

3. Start tracing 🎉

Run any job. Within a couple of minutes, the data will become visible in the Sidekiq section of the Ruby on Rails dashboard.

Need help?

Please let us know at hello@betterstack.com.
We're happy to help! 🙏

Example projects

You can take a look at example projects on Github:

• Rails
• Rack
• Ruby

Additional information

Interested in learning more about log levels in Rails?
Check out our Intro guide to Ruby on Rails logging.

Enrich log context

Add custom data to multiple log lines using with block:

Logtail.with_context(user: { id: 123 }) do
    Rails.logger.info('User logged in.')
    Rails.logger.info('User bought a gem.')
end

logger = Logtail::Config.instance.logger
Logtail.with_context(user: { id: 123 }) do
    logger.info('User logged in.')
    logger.info('User bought a gem.')
end

Logtail.with_context(user: { id: 123 }) do
    logger.info('User logged in.')
    logger.info('User bought a gem.')
end

Add the user to every line of a request

In Rails, Devise, any other Warden-based authentication, and Clearance users are added automatically. With other authentication, return the user from the Rack environment:

Logtail::Integrations::Rack::UserContext.custom_user_hash = lambda do |rack_env|
  user_id = rack_env["rack.session"]["user_id"]
  user_id && { id: user_id }
end

The hash is logged as context.user on every line of the request, including the Started and Completed lines, which a with_context block in a controller can't reach. For other per-request context, use a Rack middleware inserted before Logtail::Integrations::Rack::HTTPEvents. See the example project.

Filter sensitive information

The Authorization, Proxy-Authorization, Cookie and Set-Cookie headers are logged as [FILTERED] out of the box, starting with logtail-rack 0.2.7.

Starting with logtail-rack 0.2.9, secrets in query strings and in Referer and Location URLs are logged as [FILTERED] too. This covers every query parameter whose name contains passw, secret, token, _key, crypt, salt, certificate, otp, ssn, cvv or cvc. In Rails, logtail-rails 0.3.0 and newer filter these URLs with your app's filter_parameters instead.

In Rails or Rack, you can filter more headers and sensitive parameters:

# config/initializers/filter_logging.rb
# Be sure to restart your server when you create this file.

# Configure parameters to be filtered from the log file.
# Use this to limit dissemination of sensitive information.
# See the ActiveSupport::ParameterFilter documentation for supported notations and behaviors.
Rails.application.config.filter_parameters += [
  :passw, :secret, :token, :_key, :crypt, :salt, :certificate, :otp, :ssn
]

# Configure HTTP headers to be filtered from the log.
# Setting this replaces the default list, so add to it to keep the defaults.
Logtail::Integrations::Rack::HTTPEvents.http_header_filters =
  Logtail::Integrations::Rack::HTTPEvents::DEFAULT_HTTP_HEADER_FILTERS + [:x_api_key]

# config.ru
# Be sure to restart your server when you modify this file.

# Configure HTTP headers to be filtered from the log.
# Setting this replaces the default list, so add to it to keep the defaults.
Logtail::Integrations::Rack::HTTPEvents.http_header_filters =
  Logtail::Integrations::Rack::HTTPEvents::DEFAULT_HTTP_HEADER_FILTERS + [:x_api_key]

# Configure query parameters to be filtered from logged URLs.
# Setting this replaces the default list, so add to it to keep the defaults.
Logtail::Integrations::Rack::HTTPEvents.query_string_filters =
  Logtail::Integrations::Rack::HTTPEvents::DEFAULT_QUERY_STRING_FILTERS + [:email]

To log every header or query parameter unfiltered, set http_header_filters or query_string_filters to an empty array.

Filter logs sent to Better Stack

You can prevent logger from sending certain logs to Better Stack:

# in your config/application.rb
config.logtail.filter_sent_to_better_stack do |log_entry|
    log_entry.context_snapshot[:http][:path].start_with?('/_')
end

# in your config.ru
Logtail.config.filter_sent_to_better_stack do |log_entry|
    log_entry.message.include?("IGNORE")
end

# anywhere before sending the logs
Logtail.config.filter_sent_to_better_stack do |log_entry|
    log_entry.message.include?("IGNORE")
end

See Logtail::LogEntry for available attributes of the block parameter.

Structured Events

Starting with Rails 8.1, you can use the new Structured Events system to send structured data to Better Stack. The logtail-rails gem automatically subscribes to these events and logs them as structured log entries in case you've used Logtail::Logger.create_default_logger to initialize.

This is particularly useful for tracking key business events or application-specific actions with rich, queryable data, without having to format them into a log message.

# Notify about a simple event with a payload
Rails.event.notify("user.signed_up",  email: "user@example.com")

# You can add context that will be included in all subsequent events
Rails.event.set_context(request_id: "abc-123", shop_id: 456)

# Tag specific events for easier filtering
Rails.event.tagged("api", "billing") do
    Rails.event.notify("payment.processed", amount: 9.99, currency: "USD")
end

# If you haven't used Logtail::Logger.create_default_logger
# the logger needs to be subscribed manually to the events
Rails.event.subscribe(
  Logtail::Integrations::Rails::EventLogSubscriber.new(logger)
)

# The event subscriber can have the log level changed
Logtail::Integrations::Rails::EventLogSubscriber.log_level = :debug

# The event subscriber can be disabled
Logtail::Integrations::Rails::EventLogSubscriber.enabled = false

When you use Rails.event.notify, the logtail-rails gem captures the event name, payload, context, tags, and source location, and sends it all as a structured log to Better Stack.

Including raw SQL in OpenTelemetry traces

If you're using OpenTelemetry instrumentation for PostgreSQL (pg gem), by default it sanitizes SQL queries in traces, replacing values with ?. This is done to prevent leaking sensitive data.

However, seeing the full query with values can be very helpful for debugging. You can configure the instrumentation to include the raw SQL statement.

This allows you to see the exact queries being run in your application traces, providing more context for performance analysis and troubleshooting.

To disable query sanitization for the pg instrumentation, set the db_statement option to :include in your OpenTelemetry initializer. This is typically done in config/initializers/opentelemetry.rb for a Rails application.

OpenTelemetry::SDK.configure do |c|
  # ...

  c.use 'OpenTelemetry::Instrumentation::PG', {
    db_statement: :include
    # no obfuscation_limit configuration
  }

  # ...
end