opentelemetry-sqlcommenter

Ruby on Rails

• Ruby on Rails
  • Introduction
  • Installation
  • Usage
  • Fields
  • End to end example
    • Results
      • GET /posts
      • POST /posts
  • References

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/open-telemetry/opentelemetry-sqlcommenter/tree/main/ruby/sqlcommenter-ruby/sqlcommenter_rails

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/open-telemetry/opentelemetry-sqlcommenter/tree/main/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

This site is open source. Improve this page.