diff --git a/docs/ruby/ruby-on-rails/README.md b/docs/ruby/ruby-on-rails/README.md index e22d376..c0fc022 100644 --- 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: @@ -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 | | | 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 index 26380a4..7ee4b55 100644 --- a/ruby/sqlcommenter-ruby/README.md +++ b/ruby/sqlcommenter-ruby/README.md @@ -1 +1,18 @@ -# sqlcommenter-ruby \ No newline at end of file +# 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 index b506187..25b1b41 100644 --- 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 index f46fdd9..8beaff1 100644 --- 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 ```