Ruby on Rails documentation

open-telemetry · Oct 23, 2022 · e61efa8 · e61efa8
1 parent 2f8841a
commit e61efa8
Show file tree

Hide file tree

Showing 4 changed files with 70 additions and 26 deletions.
diff --git a/docs/ruby/ruby-on-rails/README.md b/docs/ruby/ruby-on-rails/README.md
@@ -2,17 +2,31 @@
 ![](../../images/activerecord_marginalia-logo.png)
 
 - [Ruby on Rails](#ruby-on-rails)
-  - [Introduction](#introduction)
-  - [Installation](#installation)
-  - [Usage](#usage)
-  - [Fields](#fields)
-  - [End to end example](#end-to-end-example)
-    - [Results](#results)
-      - [GET /posts](#get-posts)
-      - [POST /posts](#post-posts)
-  - [References](#references)
-
-## Introduction
+  - [Rails 7.1 and up](#rails-7.1-and-up)
+  - [Rails 7.0](#rails-7.0)
+  - [Rails 6.1 and under](#rails-6.1-and-under)
+    - [Introduction](#introduction)
+    - [Installation](#installation)
+    - [Usage](#usage)
+    - [Fields](#fields)
+    - [End to end example](#end-to-end-example)
+      - [Results](#results)
+        - [GET /posts](#get-posts)
+        - [POST /posts](#post-posts)
+    - [References](#references)
+  - [Tracing support in Rails](#tracing-support-in-rails)
+
+Support for SQLCommenter in Ruby on Rails varies, depending on the version. Select your version of Rails below to enable SQLCommenter.
+
+## Rails 7.1 and up
+
+SQLCommenter is supported by default. Enable [query_log_tags](https://guides.rubyonrails.org/configuring.html#config-active-record-query-log-tags-enabled), and SQLCommenter formatting will be [enabled by default](https://edgeguides.rubyonrails.org/configuring.html#config-active-record-query-log-tags-format).
+
+## Rails 7.0
+Enable [query_log_tags](https://guides.rubyonrails.org/configuring.html#config-active-record-query-log-tags-enabled) and install the [PlanetScale SQLCommenter gem](https://github.com/planetscale/activerecord-sql_commenter#installation) for SQLCommenter support.
+
+
+## Rails 6.1 and under
 
 [sqlcommenter_rails](https://github.com/open-telemetry/opentelemetry-sqlcommenter/tree/main/ruby/sqlcommenter-ruby/sqlcommenter_rails) adds comments to your SQL statements.
 
@@ -22,14 +36,16 @@ comments if you use the [opencensus gem].
 [sqlcommenter_rails](https://github.com/open-telemetry/opentelemetry-sqlcommenter/tree/main/ruby/sqlcommenter-ruby/sqlcommenter_rails) configures [marginalia](https://github.com/basecamp/marginalia) and [marginalia-opencensus](https://github.com/open-telemetry/opentelemetry-sqlcommenter/tree/main/ruby/sqlcommenter-ruby/marginalia-opencensus) to
 match the SQLCommenter format.
 
-## Installation
+Compared to newer versions of Rails, this method requires additional work because you will have to install a fork of the [marginalia](https://github.com/basecamp/marginalia/) gem, which has since been consolidated into newer versions of Rails (7.0 and up).
+
+### Installation
 
 Currently, this gem is not released on rubygems. But can be installed from source.
 
-The gem requires functionality provided by an [open PR](https://github.com/basecamp/marginalia/pull/89) to [marginalia](https://github.com/basecamp/marginalia). Install the PR by cloning [glebm's fork of marginalia](https://github.com/glebm/marginalia) one directory above this folder.
+The gem requires functionality provided by an [open PR](https://github.com/basecamp/marginalia/pull/130) to [marginalia](https://github.com/basecamp/marginalia). Install the PR by cloning [modulitos' fork of marginalia](https://github.com/modulitos/marginalia) one directory above this folder.
 
 ```shell
-git clone https://github.com/glebm/marginalia.git ../marginalia
+git clone https://github.com/modulitos/marginalia.git ../marginalia
 ```
 Add the following lines to your application's Gemfile:
 
@@ -49,11 +65,11 @@ To enable [OpenCensus](https://opencensus.io) support, add the [`opencensus`](ht
 require 'opencensus/trace/integrations/rails'
 ```
 
-## Usage
+### Usage
 
 All of the SQL queries initiated by the application will now come with comments!
 
-## Fields
+### Fields
 
 The following fields will be added to your SQL statements as comments:
 
@@ -79,7 +95,7 @@ To include the `traceparent` field, install the [marginalia-opencensus](https://
 
 To change which fields are included, set `Marginalia::Comment.components = [ :field1, :field2, ... ]` in `config/initializers/marginalia.rb` as described in the [marginalia documentation](https://github.com/basecamp/marginalia#components).
 
-## End to end example
+### End to end example
 
 A Rails 6 [sqlcommenter_rails](https://github.com/open-telemetry/opentelemetry-sqlcommenter/tree/main/ruby/sqlcommenter-ruby/sqlcommenter_rails) demo is available at:
 <https://github.com/open-telemetry/opentelemetry-sqlcommenter/tree/main/ruby/sqlcommenter-ruby/sqlcommenter_rails>
@@ -162,11 +178,11 @@ log with the following command:
 tail -f log/development.log | grep 'Post '
 ```
 
-### Results
+#### Results
 
 The demo application has 2 endpoints: `GET /posts` and `POST /posts`.
 
-#### GET /posts
+##### GET /posts
 
 ```shell
 curl localhost:3000/posts
@@ -180,7 +196,7 @@ framework='rails_v6.0.0.rc1',route='/posts',
 traceparent='00-ff19308b1f17fedc5864e929bed1f44e-6ddace73a9debf63-01'*/
 ```
 
-#### POST /posts
+##### POST /posts
 
 ```shell
 curl -X POST localhost:3000/posts -d 'title=my-post'
@@ -194,7 +210,7 @@ framework='rails_v6.0.0.rc1',route='/posts',
 traceparent='00-ff19308b1f17fedc5864e929bed1f44e-6ddace73a9debf63-01'*/
 ```
 
-## References
+### References
 
 | Resource                | URL                                                                                             |
 |-------------------------|-------------------------------------------------------------------------------------------------|
@@ -204,3 +220,8 @@ traceparent='00-ff19308b1f17fedc5864e929bed1f44e-6ddace73a9debf63-01'*/
 | The opencensus gem    | <https://github.com/census-instrumentation/opencensus-ruby >                                      |
 | marginalia-opencensus | <https://github.com/google/sqlcommenter/tree/master/ruby/sqlcommenter-ruby/marginalia-opencensus> |
 
+## Tracing support in Rails
+
+Tracing support has been implemented in the [marginalia-opencensus gem]: https://github.com/open-telemetry/opentelemetry-sqlcommenter/tree/main/ruby/sqlcommenter-ruby/marginalia-opencensus. Note that this only works for Rails versions below 7.0, before the [marginalia](https://github.com/basecamp/marginalia/) gem was consolidated into Rails.
+
+Re-purposing that gem for Rails versions >=7.0 should only require minor modifications (contributions are welcome!).
diff --git a/ruby/sqlcommenter-ruby/README.md b/ruby/sqlcommenter-ruby/README.md
@@ -1 +1,18 @@
-# sqlcommenter-ruby
+# sqlcommenter-ruby
+
+## SQLCommenter support in Rails
+
+Support for [SQLCommenter](https://open-telemetry.github.io/opentelemetry-sqlcommenter) in [Ruby on Rails](https://rubyonrails.org/) varies, depending on your versions of Rails.
+
+If you are on Rails version:
+
+ - **7.1 and above:** SQLCommenter is supported by default. Enable [query_log_tags](https://guides.rubyonrails.org/configuring.html#config-active-record-query-log-tags-enabled), and SQLCommenter formatting will be [enabled by default](https://edgeguides.rubyonrails.org/configuring.html#config-active-record-query-log-tags-format).
+ - **7.0:** Enable [query_log_tags](https://guides.rubyonrails.org/configuring.html#config-active-record-query-log-tags-enabled) and install the [PlanetScale SQLCommenter gem](https://github.com/planetscale/activerecord-sql_commenter#installation) for SQLCommenter support.
+ - **Below 7.0:** Refer to the [sqlcommenter_rails gem](https://github.com/open-telemetry/opentelemetry-sqlcommenter/tree/main/ruby/sqlcommenter-ruby/sqlcommenter_rails) in this directory for adding SQLCommenter support. Note that this requires additional work because you will have to install a fork of the [marginalia](https://github.com/basecamp/marginalia/) gem, which has since been consolidated into Rails 7.0 and up.
+
+## Tracing support in Rails
+
+Tracing support has been implemented in the [marginalia-opencensus gem]: https://github.com/open-telemetry/opentelemetry-sqlcommenter/tree/main/ruby/sqlcommenter-ruby/marginalia-opencensus. Note that this only works for Rails versions below 7.0, before the [marginalia](https://github.com/basecamp/marginalia/) gem was consolidated into Rails.
+
+Re-purposing that gem for Rails versions >=7.0 should only require minor modifications (contributions are welcome!).
+
diff --git a/ruby/sqlcommenter-ruby/sqlcommenter_rails/README.md b/ruby/sqlcommenter-ruby/sqlcommenter_rails/README.md
@@ -1,5 +1,7 @@
 # sqlcommenter_rails
 
+**If you are on Rails version 7.0 and up, refer to the [sqlcommenter-ruby README] instead**
+
 [sqlcommenter] for [Ruby on Rails].
 
 Powered by [marginalia] and [marginalia-opencensus].
@@ -8,16 +10,17 @@ Powered by [marginalia] and [marginalia-opencensus].
 [Ruby on Rails]: https://rubyonrails.org/
 [marginalia]: https://github.com/basecamp/marginalia/
 [marginalia-opencensus]: https://github.com/open-telemetry/opentelemetry-sqlcommenter/tree/master/ruby/sqlcommenter-ruby/marginalia-opencensus
+[sqlcommenter-ruby README]: https://github.com/open-telemetry/opentelemetry-sqlcommenter/blob/main/ruby/sqlcommenter-ruby/README.md
 
 ## Installation
 
 Currently, this gem is not released on rubygems.
 But can be installed from source.
 
-The gem requires functionality provided by an [open PR](https://github.com/basecamp/marginalia/pull/89) to [marginalia](https://github.com/basecamp/marginalia). Install the PR by cloning [glebm's fork of marginalia](https://github.com/glebm/marginalia) one directory above this folder.
+The gem requires functionality provided by an [open PR](https://github.com/basecamp/marginalia/pull/130) to [marginalia](https://github.com/basecamp/marginalia). Install the PR by cloning [modulitos' fork of marginalia](https://github.com/modulitos/marginalia) one directory above this folder.
 
 ```bash
-git clone https://github.com/glebm/marginalia.git ../marginalia
+git clone https://github.com/modulitos/marginalia.git ../marginalia
 ```
 
 Add the following lines to your application's Gemfile:

diff --git a/ruby/sqlcommenter-ruby/sqlcommenter_rails_demo/README.md b/ruby/sqlcommenter-ruby/sqlcommenter_rails_demo/README.md
@@ -1,18 +1,21 @@
 # sqlcommenter_rails demo
 
+**If you are on Rails version 7.0 and up, refer to the [sqlcommenter-ruby README] instead**
+
 This is a demo [Rails API] application to demonstrate [sqlcommenter_rails] integration.
 
 [Rails API]: https://guides.rubyonrails.org/api_app.html
 [sqlcommenter_rails]: https://github.com/open-telemetry/opentelemetry-sqlcommenter/ruby/sqlcommenter-ruby/sqlcommenter_rails
+[sqlcommenter-ruby README]: https://github.com/open-telemetry/opentelemetry-sqlcommenter/blob/main/ruby/sqlcommenter-ruby/README.md
 
 ## Setup
 
 Install [Ruby v2.6.3](https://www.ruby-lang.org/en/news/2019/04/17/ruby-2-6-3-released/) if you don't already have it installed.
 
-This demo requires functionality provided by an [open PR](https://github.com/basecamp/marginalia/pull/89) to [marginalia](https://github.com/basecamp/marginalia). Install the PR by cloning [glebm's fork of marginalia](https://github.com/glebm/marginalia) one directory above this demo. Starting from the root directory of this demo:
+This demo requires functionality provided by an [open PR](https://github.com/basecamp/marginalia/pull/130) to [marginalia](https://github.com/basecamp/marginalia). Install the PR by cloning [modulitos' fork of marginalia](https://github.com/modulitos/marginalia) one directory above this demo. Starting from the root directory of this demo:
 
 ```bash
-git clone https://github.com/glebm/marginalia.git ../marginalia
+git clone https://github.com/modulitos/marginalia.git ../marginalia
 git -C ../marginalia checkout formatting
 ```