Ruby on Rails

Introduction

sqlcommenter_rails adds comments to your SQL statements.

It is powered by marginalia and also adds OpenCensus information to the comments if you use the opencensus gem.

sqlcommenter_rails configures marginalia and marginalia-opencensus to match the SQLCommenter format.

Installation

Currently, this gem is not released on rubygems. But can be installed from source.

The gem requires functionality provided by an open PR to marginalia. Install the PR by cloning glebm's fork of marginalia one directory above this folder.

git clone https://github.com/glebm/marginalia.git ../marginalia

Add the following lines to your application's Gemfile:

gem 'sqlcommenter_rails', path: '../sqlcommenter_rails'
gem 'marginalia', path: '../marginalia'
gem 'marginalia-opencensus', path: '../marginalia-opencensus'

Install dependencies:

bin/setup

To enable OpenCensus support, add the opencensus gem to your Gemfile, and add the following line in the beginning of config/application.rb:

require 'opencensus/trace/integrations/rails'

Usage

All of the SQL queries initiated by the application will now come with comments!

Fields

The following fields will be added to your SQL statements as comments:

Field Included
by default?
Description Provided by
action
Controller action name marginalia
application
Application name marginalia
controller
Controller name marginalia
controller_with_namespace
Full classname (including namespace) of the controller marginalia
database
Database name marginalia
db_driver
Database adapter class name sqlcommenter_rails
db_host
Database hostname marginalia
framework
rails_v followed by Rails::VERSION sqlcommenter_rails
hostname
Socket.gethostname marginalia
job
Classname of the ActiveJob being performed marginalia
line
File and line number calling query marginalia
pid
Current process id marginalia
route
Request’s full path sqlcommenter_rails
socket
Database socket marginalia
traceparent
The W3C TraceContext.Traceparent field of the OpenCensus trace marginalia-opencensus

To include the traceparent field, install the marginalia-opencensus gem and it will be automatically included by default.

To change which fields are included, set Marginalia::Comment.components = [ :field1, :field2, ... ] in config/initializers/marginalia.rb as described in the marginalia documentation.

End to end example

A Rails 6 sqlcommenter_rails demo is available at: https://github.com/google/sqlcommenter/tree/master/ruby/sqlcommenter-ruby/sqlcommenter_rails_demo

The demo is a vanilla Rails API application with sqlcommenter_rails and OpenCensus enabled.

First, we create a vanilla Rails application with the following command:

gem install rails -v 6.0.0.rc1
rails _6.0.0.rc1_ new sqlcommenter_rails_demo --api

Then, we add and implement a basic Post model and controller:

bin/rails g model Post title:text
bin/rails g controller Posts index create

Implement the controller:

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def index
    render json: Post.all
  end

  def create
    title = params[:title].to_s.strip
    head :bad_request if title.empty?
    render json: Post.create!(title: title)
  end
end

Configure the routes:

# config/routes.rb
Rails.application.routes.draw do
 resources :posts, only: %i[index create]
end

Then, we add sqlcommenter_rails and OpenCensus:

# Gemfile
gem 'opencensus'
gem 'sqlcommenter_rails'
# config/application.rb
require "opencensus/trace/integrations/rails"

Finally, we run bundle to install the newly added gems:

bundle

Now, we can start the server:

bin/rails s

In a separate terminal, you can monitor the relevant SQL statements in the server log with the following command:

tail -f log/development.log | grep 'Post '

Results

The demo application has 2 endpoints: GET /posts and POST /posts.

GET /posts
curl localhost:3000/posts
Post Load (0.1ms)  SELECT "posts".* FROM "posts" /*
action='index',application='SqlcommenterRailsDemo',controller='posts',
db_driver='ActiveRecord::ConnectionAdapters::SQLite3Adapter',
framework='rails_v6.0.0.rc1',route='/posts',
traceparent='00-ff19308b1f17fedc5864e929bed1f44e-6ddace73a9debf63-01'*/
POST /posts
curl -X POST localhost:3000/posts -d 'title=my-post'
Post Create (0.2ms)  INSERT INTO "posts" ("title", "created_at", "updated_at")
VALUES (?, ?, ?) /*action='create',application='SqlcommenterRailsDemo',
controller='posts',db_driver='ActiveRecord::ConnectionAdapters::SQLite3Adapter',
framework='rails_v6.0.0.rc1',route='/posts',
traceparent='00-ff19308b1f17fedc5864e929bed1f44e-6ddace73a9debf63-01'*/

References

Resource URL
sqlcommenter_rails https://github.com/google/sqlcommenter/tree/master/ruby/sqlcommenter-ruby/sqlcommenter_rails
marginalia https://github.com/basecamp/marginalia
OpenCensus https://opencensus.io/
The opencensus gem https://github.com/census-instrumentation/opencensus-ruby
marginalia-opencensus https://github.com/google/sqlcommenter/tree/master/ruby/sqlcommenter-ruby/marginalia-opencensus