LogStruct LogoLogStructby DocSpring

Getting Started with LogStruct

LogStruct needs Ruby 3.3 or newer and Rails 7.1 or newer.

Installation

Add this line to your application's Gemfile:

gem "logstruct"

And then run:

bundle install

That's all you need. In production, LogStruct is now on for your web server and job processes (Puma, Unicorn, Thin, Falcon, rails server, Sidekiq and good_job start), and in test for every process except the console. Consoles, production Rake tasks and other processes keep Rails' usual logger. See When LogStruct runs for the details and how to turn it on for other processes.

Try It in Development

LogStruct is off in development, so rails server looks the same as before. To see the lines your app will write in production, start the server with LOGSTRUCT_ENABLED=true:

LOGSTRUCT_ENABLED=true bin/rails server

Each request then writes a line like this:

{"src":"rails","evt":"request","lvl":"info","ts":"2026-10-17T03:09:30.839+00:00","path":"/orders","method":"GET","source_ip":"203.0.113.7","user_agent":"Mozilla/5.0","referer":"https://app.example.com/","format":"html","controller":"OrdersController","action":"index","status":200,"duration_ms":42.1,"view":30.2,"db":8.4,"params":{"page":"2"},"host":"app.example.com","accept":"text/html","prog":"Rails","req_id":"6f1c2b7e-0d4a-4c1e-9a55-3b8e2f7d9c10"}

Basic Configuration

LogStruct works without any configuration. To change its defaults, create config/initializers/logstruct.rb, for example:

config/initializers/logstruct.rb
LogStruct.configure do |config|
  # Filter these keys too, on top of LogStruct's defaults and Rails' filter_parameters
  config.filters.filter_keys += [:date_of_birth]

  # Log SQL queries slower than 100 ms (off by default)
  config.integrations.enable_sql_logging = true
end

The configuration page lists every setting.

Basic Usage

Keep using the Rails logger. Log a message, or a Hash of fields:

# Log a message
Rails.logger.info "User signed in"

# Log a Hash of fields
Rails.logger.info({evt: "user_login", user_id: user.id, email: user.email})

# Tag every line logged in a block
Rails.logger.tagged("Authentication") do
  Rails.logger.info "Checking the password"
end

These lines are written:

{"src":"app","evt":"log","lvl":"info","ts":"2026-10-17T03:14:21.865+00:00","msg":"User signed in","prog":"Rails"}
{"evt":"user_login","user_id":123,"email":{"_filtered":{"_class":"String","_hash":"18a290e45734f1a2"}},"src":"app","ts":"2026-10-17T03:14:21.865+00:00","lvl":"info","prog":"Rails"}
{"src":"app","evt":"log","lvl":"info","ts":"2026-10-17T03:14:21.865+00:00","msg":"Checking the password","prog":"Rails","tags":["Authentication"]}

A Hash's keys become the line's fields. evt names the event (default log), and src says where the line came from (default app). Leave src as app, or use a name of your own: LogStruct's integrations use names like rails and job.

The email value was filtered: LogStruct logs a hash of it, so you can find every line about the same address without logging the address. See Filtering Sensitive Data.

Next Steps

Edit this page on GitHub