opentelemetry-helpers-sql-processor 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0380c8c77d57d2b262a891b3884c062ba915a6f07d9d0ff92aeb1c861e8936d
-  data.tar.gz: 944100d9a3992b01bd2e094f53d385c25ebbd1d7965a42e23debc7439c8a5ffe
+  metadata.gz: 93190bba5f90cc331db3cb1bf1ca6f881aa84c2ca372fe36fef411406536e91f
+  data.tar.gz: 6d9223214f3c3d2976a98ac38728f09a877beba95ab1e048fead10c41747eb67
 SHA512:
-  metadata.gz: 8a386117eca07e983310afcb18c79e1d3779b63cf52b4f6eff780ab33a50c13a85b813227bd247a75121a07071f54ede0bacb4e4678dfe77300872f173915fcd
-  data.tar.gz: e05f541df0080331651b87304dc60ef715c7ae6ce4b2348270640199ea0528d75ee0c2435284ed11ce2cb1ccfa8a20a59d4287a297ff9283cd1617804636d436
+  metadata.gz: 11ba72f0edb34309d4d7302b57f18461857e140b8a8060e76cdfceaf3a002864f801747728f7e7207ec4362a94a17d58bf45db70bec604bc4f20a9f6c00994a2
+  data.tar.gz: 2f82c82e9a1eed0e4aa3be7a7d3d9d34ea53fe048a87c66d6d315c093788012f3d0f26e3fe84d22f14711df4e4367657c088e32a66c8f4d38b7213c80d4af249

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 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)

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:

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.1'
+      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.1
+  version: 0.4.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-11 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.1/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.1
+  documentation_uri: https://rubydoc.info/gems/opentelemetry-helpers-sql-processor/0.4.0
 post_install_message: ''
 rdoc_options: []
 require_paths: