sqlcommenter is a project donated to OpenTelemetry that provides various language-specific implementations to inject metadata into SQL comments. This allows for better observability by linking database queries back to the application code that generated them.

Available implementations include support for:

• Python: Django, psycopg2, and SQLAlchemy
• Java: Hibernate and Spring+Hibernate
• Ruby: Rails
• Node.js: Knex.js and Sequelize.js
• PHP: Laravel

This gem works by registering an opencensus component and appending it to the list of default Marginalia components.

In the default configuration, the OpenCensus trace is automatically appended to the end of the Marginalia comments. The trace consists of OpenCensus Span names from the current span up to the root, joined by the ~ character.

For detailed configuration options regarding the trace format, refer to the Marginalia::OpenCensus documentation.

To achieve full correlation when using Spring with Hibernate, you must apply both integrations:

1. Add the Spring interceptor (SpringSQLCommenterInterceptor) to your Spring MVC configuration to capture web context.
2. Add the Hibernate StatementInspector (com.google.cloud.sqlcommenter.schibernate.SCHibernate) to your Hibernate configuration to inject that context into SQL comments.

The sqlcommentermux package provides a middleware that extracts SQLCommenter HTTP request tags from a request handled by gorilla/mux and attaches them to the request's context.

To ensure these tags and trace information (like traceparent) are passed into SQL comments, you must use the context returned by the middleware when executing queries via sqlcommenter/go/database/sql.

import (
    "net/http"
    sqlcommentermux "github.com/google/sqlcommenter/go/gorrila/mux"
    "github.com/gorilla/mux"
)

func runApp() {
    r := mux.NewRouter()
    r.Use(sqlcommentermux.SQLCommenterMiddleware)

    r.HandleFunc("/", ActionHome).Methods("GET")

    http.ListenAndServe(":8081", r)
}

To use SQLcommenter, use the gosql.Open method provided by the github.com/google/sqlcommenter/go/database/sql package.

Because of how Go handles information passing, it is highly recommended to use context-aware methods from the DB interface (such as QueryContext, ExecContext, and PrepareContext) to ensure application-related information is correctly passed from your framework to the database driver.

import (
    gosql "github.com/google/sqlcommenter/go/database/sql"
    sqlcommentercore "github.com/google/sqlcommenter/go/core"
    _ "github.com/lib/pq" // or any other database driver
)

db, err := gosql.Open("<driver>", "<connectionString>", sqlcommentercore.CommenterOptions{
    Config: sqlcommentercore.CommenterConfig{<flag>:bool}
    Tags  : sqlcommentercore.StaticTags{<tag>: string} // optional
})

Note: If you are using Rails 7.0 or higher, use the sqlcommenter-ruby gem instead of this one.

sqlcommenter_rails is not currently available on RubyGems and must be installed from source. It requires a specific fork of marginalia that includes functionality from an open PR.

Follow these steps to install:

1. Clone the required marginalia fork into the directory above your project:

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

2. Add the gems to your Gemfile using local paths:

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

3. Run the setup command to install dependencies:

   bin/setup

You can add the SpringSQLCommenterInterceptor as a bean in your Spring XML configuration. You can apply it globally to all interceptors or restrict it to specific URL mappings.

<!-- Global configuration -->
<mvc:interceptors>
    <bean class="com.google.cloud.sqlcommenter.interceptors.SpringSQLCommenterInterceptor"></bean>
</mvc:interceptors>

<!-- Specific path configuration -->
<mvc:interceptors>
    <mvc:interceptor>
        <mvc:mapping path="/flights"></mvc:mapping>
        <bean class="com.google.cloud.sqlcommenter.interceptors.SpringSQLCommenterInterceptor"></bean>
    </mvc:interceptor>
</mvc:interceptors>

Install the SQLcommenter Go database driver using go get:

go get -u github.com/google/sqlcommenter/go/database/sql

Install the SQLCommenter Sequelize plugin using npm to enable SQL statement augmentation in your Sequelize.js application.

npm install @google-cloud/sqlcommenter-sequelize

To use marginalia-opencensus in your Ruby application, add it to your Gemfile and run bundle install, or install it directly via the gem command.

This gem adds OpenCensus support to Marginalia, allowing OpenCensus trace information to be appended to SQL comments.

# Add to your Gemfile
gem 'marginalia-opencensus'

Then execute in your terminal

$ bundle

Or install manually

$ gem install marginalia-opencensus