opentelemetry-helpers-sql-processor 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ed5ecc010586814ebc74f60f2d590eac9d0ab75aaa66aa130ba76f992973d5c
-  data.tar.gz: 8d3c91ecb6254424c6e0a9866e34d18edf27dd56981931facc93aef77ef37531
+  metadata.gz: 93190bba5f90cc331db3cb1bf1ca6f881aa84c2ca372fe36fef411406536e91f
+  data.tar.gz: 6d9223214f3c3d2976a98ac38728f09a877beba95ab1e048fead10c41747eb67
 SHA512:
-  metadata.gz: 244d84fdf356d629f2680cb3c3ece397e7b79b151c7b464fb1415b37ebeaf70421193119b5e7d4584cfc500c2ca392a2c495ba8ee52610c6aaf8310e1d26d3fa
-  data.tar.gz: c545cdf4006fdb88281fcf0bfa0d83a46af6e078fbb291a05f343db1aba01e90fa20a6151ad8ffc2d2d080f9d9ee97d88e97bf0ffe84a92cf4fe66029e23731c
+  metadata.gz: 11ba72f0edb34309d4d7302b57f18461857e140b8a8060e76cdfceaf3a002864f801747728f7e7207ec4362a94a17d58bf45db70bec604bc4f20a9f6c00994a2
+  data.tar.gz: 2f82c82e9a1eed0e4aa3be7a7d3d9d34ea53fe048a87c66d6d315c093788012f3d0f26e3fe84d22f14711df4e4367657c088e32a66c8f4d38b7213c80d4af249

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Release History: opentelemetry-helpers-sql-processor
 
+### v0.4.0 / 2026-01-13
+
+* ADDED: Add SQL Comment Propagator
+
+### v0.3.1 / 2025-11-11
+
+* DOCS: Update example to match new gem namespace (sql-processor)
+
 ### v0.3.0 / 2025-11-04
 
 * ADDED: Refactor SQL processor file structure for clarity

data/README.md

@@ -22,6 +22,7 @@ group :test do
   gem 'opentelemetry-helpers-sql-processor', path: '../../helpers/sql-processor'
 end
 ```
+
 ## Obfuscation
 
 Make sure the `Instrumentation` class for your gem contains configuration options for:
@@ -43,7 +44,7 @@ Check [New Relic's SQL Obfuscation Helpers module][new-relic-obfuscation-helpers
 To obfuscate sql in your library:
 
 ```ruby
-OpenTelemetry::Helpers::SqlObfuscation.obfuscate_sql(sql, obfuscation_limit: config[:obfuscation_limit], adapter: :postgres)
+OpenTelemetry::Helpers::SqlProcessor.obfuscate_sql(sql, obfuscation_limit: config[:obfuscation_limit], adapter: :postgres)
 ```
 
 ## How can I get involved?

data/lib/opentelemetry/helpers/sql_processor/commenter.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'cgi'
+
+module OpenTelemetry
+  module Helpers
+    module SqlProcessor
+      # SqlCommenter provides SQL comment-based trace context propagation
+      # according to the SQL Commenter specification.
+      #
+      # This module implements a propagator interface compatible with Vitess,
+      # allowing it to be used as a drop-in replacement.
+      #
+      # @api public
+      module SqlCommenter
+        extend self
+
+        # SqlQuerySetter is responsible for formatting trace context as SQL comments
+        # and appending them to SQL queries according to the SQL Commenter specification.
+        #
+        # Format: /*key='value',key2='value2'*/
+        # Values are URL-encoded per the SQL Commenter spec
+        module SqlQuerySetter
+          extend self
+
+          # Appends trace context as a SQL comment to the carrier (SQL query string)
+          #
+          # @param carrier [String] The SQL query string to modify
+          # @param headers [Hash] Hash of trace context headers (e.g., {'traceparent' => '00-...'})
+          def set(carrier, headers)
+            return if headers.empty?
+            return if carrier.frozen?
+
+            # Convert headers hash to SQL commenter format
+            # Format: /*key1='value1',key2='value2'*/
+            comment_parts = headers.map do |key, value|
+              # URL encode values as per SQL Commenter spec (using URI component encoding)
+              encoded_value = CGI.escapeURIComponent(value.to_s)
+              "#{key}='#{encoded_value}'"
+            end
+
+            # Append to end of query (spec recommendation)
+            carrier << " /*#{comment_parts.join(',')}*/"
+          end
+        end
+
+        # SqlQueryPropagator propagates trace context using SQL comments
+        # according to the SQL Commenter specification.
+        #
+        # This propagator implements the same interface as the Vitess propagator
+        # and can be used as a drop-in replacement.
+        #
+        # @example
+        #   propagator = OpenTelemetry::Helpers::SqlProcessor::SqlCommenter.sql_query_propagator
+        #   sql = "SELECT * FROM users"
+        #   propagator.inject(sql, context: current_context)
+        #   # => "SELECT * FROM users /*traceparent='00-...',tracestate='...'*/"
+        module SqlQueryPropagator
+          extend self
+
+          # Injects trace context into a SQL query as a comment
+          #
+          # @param carrier [String] The SQL query string to inject context into
+          # @param context [optional, Context] The context to inject. Defaults to current context.
+          # @param setter [optional, #set] The setter to use for appending the comment.
+          #   Defaults to SqlQuerySetter.
+          # @return [nil]
+          def inject(carrier, context: OpenTelemetry::Context.current, setter: SqlQuerySetter)
+            # Use the global propagator to extract headers into a hash
+            headers = {}
+            OpenTelemetry.propagation.inject(headers, context: context)
+
+            # Pass the headers to our SQL comment setter
+            setter.set(carrier, headers)
+            nil
+          end
+        end
+
+        # Returns the SqlQueryPropagator module for stateless propagation
+        #
+        # @return [Module] The SqlQueryPropagator module
+        def sql_query_propagator
+          SqlQueryPropagator
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/helpers/sql_processor/version.rb

@@ -7,7 +7,7 @@
 module OpenTelemetry
   module Helpers
     module SqlProcessor
-      VERSION = '0.3.0'
+      VERSION = '0.4.0'
     end
   end
 end

data/lib/opentelemetry/helpers/sql_processor.rb

@@ -6,13 +6,15 @@
 
 require 'opentelemetry-common'
 require_relative 'sql_processor/obfuscator'
+require_relative 'sql_processor/commenter'
 
 module OpenTelemetry
   module Helpers
     # SQL processing utilities for OpenTelemetry instrumentation.
     #
     # This module provides a unified interface for SQL processing operations
-    # commonly needed in database adapter instrumentation, including SQL obfuscation.
+    # commonly needed in database adapter instrumentation, including SQL obfuscation
+    # and SQL comment-based trace context propagation.
     #
     # @api public
     module SqlProcessor

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-helpers-sql-processor
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-04 00:00:00.000000000 Z
+date: 2026-01-13 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: opentelemetry-common
   requirement: !ruby/object:Gem::Requirement
@@ -38,16 +52,17 @@ files:
 - lib/opentelemetry-helpers-sql-processor.rb
 - lib/opentelemetry/helpers.rb
 - lib/opentelemetry/helpers/sql_processor.rb
+- lib/opentelemetry/helpers/sql_processor/commenter.rb
 - lib/opentelemetry/helpers/sql_processor/obfuscator.rb
 - lib/opentelemetry/helpers/sql_processor/version.rb
 homepage: https://github.com/open-telemetry/opentelemetry-ruby-contrib
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://rubydoc.info/gems/opentelemetry-helpers-sql-processor/0.3.0/file/CHANGELOG.md
+  changelog_uri: https://rubydoc.info/gems/opentelemetry-helpers-sql-processor/0.4.0/file/CHANGELOG.md
   source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/helpers/sql-processor
   bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby-contrib/issues
-  documentation_uri: https://rubydoc.info/gems/opentelemetry-helpers-sql-processor/0.3.0
+  documentation_uri: https://rubydoc.info/gems/opentelemetry-helpers-sql-processor/0.4.0
 post_install_message: ''
 rdoc_options: []
 require_paths: