Database query comments with Marginalia

The Marginalia gem is used to add query comments containing application related context information to PostgreSQL queries generated by ActiveRecord.

It is very useful for tracing problematic queries back to the application source.

An engineer during an on-call incident will have the full context of a query and its application source from the comments.

Metadata information in comments

Queries generated from Rails include the following metadata in comments:

  • application
  • controller
  • action
  • correlation_id
  • line

Queries generated from Sidekiq workers will include the following metadata in comments:

  • application
  • jid
  • job_class
  • correlation_id
  • line

Examples of queries with comments as observed in development.log:

  1. Rails:

    SELECT "project_features".* FROM "project_features" WHERE "project_features"."project_id" = $1 LIMIT $2 [["project_id", 5], ["LIMIT", 1]] /*application:web,controller:jobs,action:trace,correlation_id:rYF4mey9CH3,line:/app/policies/project_policy.rb:504:in `feature_available?'*/
    
  2. Sidekiq:

    SELECT "ci_pipelines".* FROM "ci_pipelines" WHERE "ci_pipelines"."id" = $1 LIMIT $2 [["id", 64], ["LIMIT", 1]] /*application:sidekiq,jid:e7d6668a39a991e323009833,job_class:ExpireJobCacheWorker,correlation_id:rYF4mey9CH3,line:/app/workers/expire_job_cache_worker.rb:14:in `perform'*/
    

Enable/Disable the feature

Enabling or disabling the feature requires a restart/SIGHUP of the Web and Sidekiq workers, as the feature flag’s state is memoized upon starting up.

The feature_flag for this feature is disabled by default. You can enable or disable it with:

Feature.enable(:marginalia)
Feature.disable(:marginalia)