• Stars
    star
    1,676
  • Rank 27,865 (Top 0.6 %)
  • Language
    Ruby
  • License
    MIT License
  • Created over 12 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Attach comments to ActiveRecord's SQL queries

marginalia Build Status

Attach comments to your ActiveRecord queries. By default, it adds the application, controller, and action names as a comment at the end of each query.

This helps when searching log files for queries, and seeing where slow queries came from.

For example, once enabled, your logs will look like:

Account Load (0.3ms)  SELECT `accounts`.* FROM `accounts` 
WHERE `accounts`.`queenbee_id` = 1234567890 
LIMIT 1 
/*application:BCX,controller:project_imports,action:show*/

You can also use these query comments along with a tool like pt-query-digest to automate identification of controllers and actions that are hotspots for slow queries.

This gem was created at 37signals. You can read more about how we use it on our blog.

This has been tested and used in production with the mysql2 and pg gems, and is tested on Rails 5.2 through 6.1, and Ruby 2.6 through 3.0. It is also tested for sqlite3. As of Rails 7, Marginalia is a part of Rails itself and does not need to be separately included.

Rails version support will follow supported versions in the Ruby on Rails maintenance policy and Ruby support will follow maintained versions in the Ruby maintenance policy.

Patches are welcome for other database adapters.

Installation

# Gemfile
gem 'marginalia'

Customization

Optionally, you can set the application name shown in the log like so in an initializer (e.g. config/initializers/marginalia.rb):

Marginalia.application_name = "BCX"

The name will default to your Rails application name.

Components

You can also configure the components of the comment that will be appended, by setting Marginalia::Comment.components. By default, this is set to:

Marginalia::Comment.components = [:application, :controller, :action]

Which results in a comment of application:#{application_name},controller:#{controller.name},action:#{action_name}.

You can re-order or remove these components. You can also add additional comment components of your desire by defining new module methods for Marginalia::Comment which return a string. For example:

module Marginalia
  module Comment
    def self.mycommentcomponent
      "TEST"
    end
  end
end

Marginalia::Comment.components = [:application, :mycommentcomponent]

Which will result in a comment like application:#{application_name},mycommentcomponent:TEST The calling controller is available to these methods via @controller.

Marginalia ships with :application, :controller, and :action enabled by default. In addition, implementation is provided for:

  • :line (for file and line number calling query). :line supports a configuration by setting a regexp in Marginalia::Comment.lines_to_ignore to exclude parts of the stacktrace from inclusion in the line comment.
  • :controller_with_namespace to include the full classname (including namespace) of the controller.
  • :job to include the classname of the ActiveJob being performed.
  • :hostname to include Socket.gethostname.
  • :pid to include current process id.
  • :db_host to include the configured database hostname.
  • :socket to include the configured database socket.
  • :database to include the configured database name.

Pull requests for other included comment components are welcome.

Prepend comments

By default marginalia appends the comments at the end of the query. Certain databases, such as MySQL will truncate the query text. This is the case for slow query logs and the results of querying some InnoDB internal tables where the length of the query is more than 1024 bytes.

In order to not lose the marginalia comments from your logs, you can prepend the comments using this option:

Marginalia::Comment.prepend_comment = true

Inline query annotations

In addition to the request or job-level component-based annotations, Marginalia may be used to add inline annotations to specific queries using a block-based API.

For example, the following code:

Marginalia.with_annotation("foo") do
  Account.where(queenbee_id: 1234567890).first
end

will issue this query:

Account Load (0.3ms)  SELECT `accounts`.* FROM `accounts`
WHERE `accounts`.`queenbee_id` = 1234567890
LIMIT 1
/*application:BCX,controller:project_imports,action:show*/ /*foo*/

Nesting with_annotation blocks will concatenate the comment strings.

Caveats

Prepared statements

Be careful when using Marginalia with prepared statements. If you use a component like request_id then every query will be unique and so ActiveRecord will create a new prepared statement for each potentially exhausting system resources. Disable prepared statements if you wish to use components with high cardinality values.

Contributing

Start by bundling and creating the test database:

bundle
rake db:mysql:create
rake db:postgresql:create

Then, running rake will run the tests on all the database adapters (mysql, mysql2, postgresql and sqlite):

rake

More Repositories

1

trix

A rich text editor for everyday writing
JavaScript
17,847
star
2

kamal

Deploy web apps anywhere.
Ruby
9,584
star
3

handbook

Basecamp Employee Handbook
6,165
star
4

omakub

Opinionated Ubuntu Setup
Shell
4,152
star
5

pow

Zero-configuration Rack server for Mac OS X
CoffeeScript
3,423
star
6

policies

37signals policies, terms, and legal. Share them; reuse them; contribute to them.
1,863
star
7

local_time

Rails engine for cache-friendly, client-side local time
CoffeeScript
1,791
star
8

mail_view

Visual email testing
Ruby
1,341
star
9

xip-pdns

PowerDNS pipe backend adapter powering xip.io
Shell
1,159
star
10

geared_pagination

Paginate Active Record sets at variable speeds
Ruby
758
star
11

wysihat

A WYSIWYG JavaScript framework
JavaScript
681
star
12

bcx-api

API documentation and wrappers for Basecamp 2
672
star
13

name_of_person

Presenting names of people in full, familiar, abbreviated, and initialized forms (but without titulation etc)
Ruby
647
star
14

console1984

The Rails console you love, 1984 style
Ruby
609
star
15

google_sign_in

Sign in (or up) with Google for Rails applications
Ruby
494
star
16

bc3-api

API documentation for Basecamp 4
472
star
17

intermission

intermission helps you perform zero down time application maintenance
Lua
364
star
18

audits1984

Auditing tool for Rails console sessions
Ruby
336
star
19

snapback_cache

A client side page cache for jquery.
JavaScript
316
star
20

full_request_logger

Make full request logs accessible via web UI
Ruby
305
star
21

mysql_role_swap

(Nearly) Zero interruption mysql maintenance script.
Ruby
282
star
22

concerning

Bite-sized separation of concerns
Ruby
201
star
23

api

API integration and more for Basecamp products (Basecamp, Highrise, Campfire, Backpack)
192
star
24

easymon

Easy Monitoring
Ruby
191
star
25

trashed

Tell StatsD about request time, GC, objects and more. Latest Rails 4 and Ruby 2.1 support, and ancient Rails 2 and Ruby 1.8 support.
Ruby
189
star
26

highrise-api

Official API documentation for Highrise
130
star
27

fast_remote_cache

A faster version of Capistrano's remote_cache deployment strategy
Ruby
125
star
28

mass_encryption

Ruby
106
star
29

platform_agent

Parse user agent to deduce the platform
Ruby
103
star
30

cached_externals

Symlink to external dependencies, rather than bloating your repositories with them
Ruby
100
star
31

homographic_spoofing

Toolkit to both detect and sanitize homographic spoofing attacks in URLs and Email addresses
Ruby
98
star
32

campfire-api

Official API documentation for Campfire
97
star
33

basecamp-classic-api

Official API documentation for Basecamp Classic
87
star
34

lufo

Tracks the most recent options chosen on a `<select>` element and displays them at the top of the list
JavaScript
87
star
35

powprox

Pow .dev sites, meet SSL and HTTP/2
Shell
83
star
36

libmemcached_store

ActiveSupport::Cache wrapper for libmemcached
Ruby
81
star
37

action_profiler

Profile Rails requests on a live app
Ruby
75
star
38

bc3-integrations

Ruby
73
star
39

project_search

Rails plugin that adds a script/find command for searching your project
Ruby
71
star
40

activestorage-office-previewer

Active Storage previewer for Microsoft Office files based on LibreOffice
Ruby
67
star
41

turbo-8-morphing-demo

Ruby
58
star
42

dumpsterfire-2020

Code that runs the dumpster
HTML
47
star
43

cognition

Match text; run commands. Works great for building a chatbot!
Ruby
37
star
44

snapshot

A rails plugin that provides tasks for creating and restoring snapshots of development data.
Ruby
34
star
45

backpack-api

Official API documentation for Backpack
Ruby
20
star
46

ruby-dev

Old Rubies on new Macs
15
star
47

orc

Orc(hestrator) - A really bad pow.cx clone for linux
Shell
10
star
48

cleversafe

Ruby
7
star
49

accessibility

Guidelines and tools we use at 37signals to make sure our apps are accessible
7
star
50

memcached_bench

Ruby
6
star
51

duo-api

Ruby Gem for communicating with the Duo Api
Ruby
6
star
52

Xamarin.iOS.OnePasswordExtension

1Password bindings for Xamarin.iOS
C#
5
star
53

mail

Ruby
4
star
54

composed_of_ipaddr

Compact IPv4 attributes for Active Record. Presents an unsigned int (4 bytes) as an IPAddr.
Ruby
4
star
55

house-style

37signals house style
Ruby
3
star
56

deep_hash_transform

Re-key a nested Hash to all-Symbol or -String keys. Rails 4+ backport.
Ruby
3
star
57

assets-redirect

Ruby
2
star
58

github-issues

Github Issue query CLI
Go
2
star
59

homebrew-dev

Old software to build old stuff on new Macs
Ruby
1
star
60

nsone

A stupid simple API client for NS1
Ruby
1
star