gitlab-labkit 1.5.0 → 1.12.0

data/lib/labkit/fields.rb

@@ -1,54 +1,122 @@
 # frozen_string_literal: true
 
+# Code generated by labkit-spec. DO NOT EDIT.
+#
+# Source: https://gitlab.com/gitlab-org/quality/tooling/labkit-spec/-/blob/main/schema/fields.yaml (version 1.0)
+
 module Labkit
-  ##
-  # Fields is intended to be a SSOT for all of the common field names that
-  # we emit via any observability we add to our systems.
-  #
-  # These fields should span multiple services.
-  #
-  # The goal of this package is to reduce the likelihood for typos or
-  # subtly different naming conventions. This will help to ensure we
-  # are able to marry up logs between different systems as a request
-  # is being processed.
-  #
-  # Usage:
-  #   require 'labkit/fields'
-  #   ...
-  #   data[Labkit::Fields::GL_USER_ID] = user.id
-  #   ...
-  #
-  # Labkit (Go): https://gitlab.com/gitlab-org/labkit/-/tree/master/fields?ref_type=heads
-  #
-  # For Engineers Looking to add fields:
-  #
-  # These fields are derived from the Go Labkit variant. Please ensure that you've made the
-  # respective changes in that repository prior to including the fields in this package.
-  #
-  # Please see the handbook page for more information
-  # https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_field_standardisation/
   module Fields
-    # correlation_id - string
-    #
-    # This field is used to correlate
-    # the logs emitted by all of our systems.
-    # This should be present in all log line
-    # emissions.
+    # Unique identifier for correlating requests across services. Should be
+    # present in all log line emissions.
     CORRELATION_ID = "correlation_id"
 
-    # GitLabUserID - an integer field that
-    # captures the user's numeric ID for logging purposes.
+    # GitLab user numeric ID.
     GL_USER_ID = "gl_user_id"
 
-    # GitLabUserName - a string field that
-    # captures the user's username for logging purposes.
+    # GitLab username.
     GL_USER_NAME = "gl_user_name"
 
-    # New fields being added to this section should have
-    # the appropriate doc comments added above. These
-    # should clearly indicate what the intended use of the
-    # field is and should be replicated across the labkit
-    # variations.
+    # Duo Workflow definition identifier (e.g. "analytics_agent/v1"). Identifies
+    # which Duo Workflow agent originated a request, enabling per-agent
+    # filtering in Kibana and Grafana.
+    DUO_WORKFLOW_DEFINITION = "duo_workflow_definition"
+
+    # Error type or classification (e.g. "NoMethodError", "ValidationError").
+    ERROR_TYPE = "error_type"
+
+    # Detailed error message (e.g. "undefined method 'boom!' for nil").
+    ERROR_MESSAGE = "error_message"
+
+    # HTTP response status code.
+    HTTP_STATUS_CODE = "status"
+
+    # HTTP method (e.g. "GET", "POST").
+    HTTP_METHOD = "method"
+
+    # URL of an HTTP request containing only scheme, host, and path. Query
+    # strings and fragments must be omitted to avoid logging sensitive
+    # information.
+    HTTP_URL = "url"
+
+    # Duration of any operation in seconds. Not limited to HTTP requests; can be
+    # used for database queries, background jobs, external API calls. Uses
+    # float64 for sub-second precision (e.g. 0.032 for 32ms).
+    DURATION_S = "duration_s"
+
+    # Remote IP address of a request.
+    REMOTE_IP = "remote_ip"
+
+    # TCP address a service is listening on, in "host:port" format (e.g.
+    # "0.0.0.0:8080").
+    TCP_ADDRESS = "tcp_address"
+
+    # Request URI including path and query string with sensitive parameters
+    # masked (e.g. "?password=FILTERED").
+    HTTP_URI = "uri"
+
+    # HTTP Host header of a request (e.g. "api.gitlab.com").
+    HTTP_HOST = "host"
+
+    # HTTP protocol version (e.g. "HTTP/1.1", "HTTP/2.0").
+    HTTP_PROTO = "proto"
+
+    # Raw remote socket address in "host:port" format (e.g. "10.0.0.1:54321").
+    # Use remote_ip when only the IP is needed.
+    REMOTE_ADDR = "remote_addr"
+
+    # HTTP Referer header with sensitive query parameters masked.
+    HTTP_REFERRER = "referrer"
+
+    # HTTP User-Agent header.
+    HTTP_USER_AGENT = "user_agent"
+
+    # Number of bytes written to the HTTP response body.
+    WRITTEN_BYTES = "written_bytes"
+
+    # Content-Type of an HTTP response (e.g. "application/json").
+    CONTENT_TYPE = "content_type"
+
+    # Time to first byte of an HTTP response in seconds. Measures duration from
+    # request receipt to first response byte written.
+    TTFB_S = "ttfb_s"
+
+    # GitLab project numeric ID.
+    GL_PROJECT_ID = "gl_project_id"
+
+    # GitLab pipeline numeric ID.
+    GL_PIPELINE_ID = "gl_pipeline_id"
+
+    # Log event timestamp in ISO 8601 format (e.g. "2026-04-02T12:00:00.000Z").
+    TIMESTAMP = "timestamp"
+
+    # Log severity level (e.g. "info", "warn", "error").
+    SEVERITY = "severity"
+
+    # Human-readable log message describing the event.
+    LOG_MESSAGE = "message"
+
+    # Class name associated with a log event (e.g. exception class or worker
+    # class).
+    CLASS_NAME = "class_name"
+
+    # Name of the service or component emitting the log event.
+    SERVICE_NAME = "service_name"
+
+    # GitLab organization numeric ID.
+    GL_ORGANIZATION_ID = "gl_organization_id"
+
+    # GitLab project path.
+    GL_PROJECT_PATH = "gl_project_path"
+
+    # The endpoint_id of the current endpoint to be passed as caller_id when
+    # calling another service.
+    ENDPOINT_ID = "endpoint_id"
+
+    # The ID of the caller of the current service.
+    CALLER_ID = "caller_id"
+
+    # The endpoint_id of the original caller at the root of the call chain.
+    ROOT_CALLER_ID = "root_caller_id"
 
     # Get the constant name for a field value
     # @param field_value [String] The field value (e.g., "gl_user_id")
@@ -67,7 +135,24 @@ module Labkit
       # to identify and track usage of deprecated fields in the codebase.
 
       MAPPINGS = {
-        Fields::GL_USER_ID => %w[user_id userid],
+        Fields::CORRELATION_ID => %w[tags.correlation_id],
+        Fields::GL_USER_ID => %w[user_id userid extra.user_id extra.current_user_id meta.user_id],
+        Fields::GL_USER_NAME => %w[username extra.user meta.user],
+        Fields::ERROR_MESSAGE => %w[error err error.message exception.message graphql_errors],
+        Fields::HTTP_STATUS_CODE => %w[status_code extra.status status_text http_status],
+        Fields::HTTP_URL => %w[req_url],
+        Fields::DURATION_S => %w[duration duration_ms elapsed_time actual_duration time_ms total_time gitaly.duration],
+        Fields::REMOTE_IP => %w[ip source_ip ip_address meta.remote_ip],
+        Fields::HTTP_HOST => %w[hostname request_host gitlab_host kubernetes.host],
+        Fields::GL_PROJECT_ID => %w[extra.project_id meta.project_id meta.search.project_id job_project_id target_project_id],
+        Fields::GL_PIPELINE_ID => %w[extra.pipeline_id meta.pipeline_id root_pipeline_id],
+        Fields::TIMESTAMP => %w[start_time],
+        Fields::SEVERITY => %w[level],
+        Fields::LOG_MESSAGE => %w[msg custom_message extra.message fields.message graphql.message reason color_message exception.gitaly],
+        Fields::CLASS_NAME => %w[class author_class exception.class extra.class extra.class_name],
+        Fields::SERVICE_NAME => %w[service grpc.service_name auth_service type component subcomponent],
+        Fields::GL_ORGANIZATION_ID => %w[organization_id],
+        Fields::GL_PROJECT_PATH => %w[project_path full_path root_pipeline_project_path requested_project_path auth_project_path extra.gl_project_path],
       }.freeze
 
       class << self

data/lib/labkit/logging/field_validator/config.rb

@@ -88,26 +88,13 @@ module Labkit
               # This file tracks deprecated logging fields that need to be migrated to standard fields.
               # Each offense represents a file using a deprecated field that should be replaced.
               #
-              # === HOW TO FIX ===
+              # How to fix: https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/blob/master/doc/FIELD_STANDARDIZATION.md#how-to-fix-an-offense
               #
-              # 1. Replace the deprecated field with the standard field constant
-              # 2. Remove the deprecated field entirely (adding the new field is not enough)
-              # 3. Run your tests - the offense will be automatically removed
+              # Adding offenses (if fixing is not immediately possible):
+              #   LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec <spec_file>
               #
-              # Example:
-              #   # Before
-              #   logger.info(user_id: 123)
-              #
-              #   # After
-              #   logger.info(Labkit::Fields::GL_USER_ID => 123)
-              #
-              # === ADDING OFFENSES (if fixing is not immediately possible) ===
-              #
-              # Run: LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec <spec_file>
-              #
-              # === REGENERATE ENTIRE TODO ===
-              #
-              # Delete this file and run: LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec
+              # Regenerate entire TODO:
+              #   Delete this file and run: LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec
 
             HEADER
           end

data/lib/labkit/logging/field_validator.rb

@@ -158,7 +158,7 @@ module Labkit
           lines << ("=" * 80)
           lines << "Total: #{new_offenses.size} new offense(s) in #{new_offenses.map { |o| o['callsite'] }.uniq.size} file(s)" # rubocop:disable Rails/Pluck
           lines << ""
-          lines << "See https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/blob/master/doc/FIELD_STANDARDIZATION.md"
+          lines << "See https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/blob/master/doc/FIELD_STANDARDIZATION.md#new-offenses-detected"
           lines << ("=" * 80)
           lines << ""
 

data/lib/labkit/net_http_publisher.rb

@@ -41,6 +41,8 @@ module Labkit
 
       start_time = ::Labkit::System.monotonic_time
 
+      inject_trace_context(request)
+
       ActiveSupport::Notifications.instrument ::Labkit::EXTERNAL_HTTP_NOTIFICATION_TOPIC, create_request_payload(request) do |payload|
         response =
           begin
@@ -57,7 +59,7 @@ module Labkit
 
     def create_request_payload(request)
       payload = {
-        method: request.method,
+        method: request.method
       }
 
       if request.uri.nil?
@@ -84,5 +86,22 @@ module Labkit
 
       payload
     end
+
+    def inject_trace_context(request)
+      return unless Labkit::Tracing.enabled?
+
+      tracer = Labkit::Tracing::TracingUtils.tracer
+      span = tracer.active_span
+      return if span.nil?
+
+      carrier = {}
+      tracer.inject_context(span, carrier)
+
+      carrier.each do |key, value|
+        request[key] = value
+      end
+    rescue StandardError
+      warn "Labkit::NetHttpPublisher: trace context propagation failed"
+    end
   end
 end

data/lib/labkit/rspec/README.md

@@ -74,15 +74,6 @@ expect { subject }.to complete_user_experience('rails_request', error: true, suc
 expect { subject }.not_to complete_user_experience('rails_request')
 ```
 
-### Legacy Matchers (Backward Compatibility)
-
-For backward compatibility, the following legacy matchers are still available but deprecated. Please migrate to the new `*_user_experience` matchers above.
-
-- `start_covered_experience`
-- `checkpoint_covered_experience`
-- `resume_covered_experience`
-- `complete_covered_experience`
-
 ## Example Usage
 
 ### In your spec_helper.rb or rails_helper.rb:

data/lib/labkit/rspec/matchers/user_experience_matchers.rb

@@ -203,6 +203,59 @@ RSpec::Matchers.define :complete_user_experience do |user_experience_id, error:
   end
 end
 
+# Matcher for verifying UserExperience observed metrics instrumentation.
+#
+# Usage:
+#   expect { subject }.to observed_user_experience('rails_request')
+#
+# This matcher verifies that the following metrics are incremented with specific labels:
+# - gitlab_user_experience_checkpoint_total (with checkpoint=start)
+# - gitlab_user_experience_checkpoint_total (with checkpoint=end)
+# - gitlab_user_experience_total (with error=false)
+# - gitlab_user_experience_apdex_total (with success=true)
+#
+# Parameters:
+# - user_experience_id: Required. The ID of the user experience (e.g., 'rails_request')
+# - error: Optional. The expected error flag for gitlab_user_experience_total (false by default)
+# - success: Optional. The expected success flag for gitlab_user_experience_apdex_total (true by default)
+RSpec::Matchers.define :observed_user_experience do |user_experience_id, error: false, success: true|
+  include Labkit::RSpec::Matchers::UserExperience
+
+  description { "observe user experience '#{user_experience_id}'" }
+  supports_block_expectations
+
+  match do |actual|
+    labels = attributes(user_experience_id)
+
+    start_before = checkpoint_counter&.get(labels.merge(checkpoint: "start")).to_i
+    end_before = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
+    total_before = total_counter&.get(labels.merge(error: error)).to_i
+    apdex_before = apdex_counter&.get(labels.merge(success: success)).to_i
+
+    actual.call
+
+    start_after = checkpoint_counter&.get(labels.merge(checkpoint: "start")).to_i
+    end_after = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
+    total_after = total_counter&.get(labels.merge(error: error)).to_i
+    apdex_after = apdex_counter&.get(labels.merge(success: success)).to_i
+
+    @start_change = start_after - start_before
+    @end_change = end_after - end_before
+    @total_change = total_after - total_before
+    @apdex_change = apdex_after - apdex_before
+
+    @start_change == 1 && @end_change == 1 && @total_change == 1 && @apdex_change == (error ? 0 : 1)
+  end
+
+  failure_message do
+    "Failed to observe user experience '#{user_experience_id}':\n" \
+      "expected checkpoint='start' counter to increase by 1, but increased by #{@start_change}\n" \
+      "expected checkpoint='end' counter to increase by 1, but increased by #{@end_change}\n" \
+      "expected total='error: #{error}' counter to increase by 1, but increased by #{@total_change}\n" \
+      "expected apdex='success: #{success}' counter to increase by #{error ? 0 : 1}, but increased by #{@apdex_change}"
+  end
+end
+
 # Backward compatibility matchers for CoveredExperience
 RSpec::Matchers.alias_matcher :start_covered_experience, :start_user_experience
 RSpec::Matchers.alias_matcher :checkpoint_covered_experience, :checkpoint_user_experience

data/lib/labkit/tracing/README.md

@@ -35,13 +35,18 @@ export GITLAB_TRACING="otlp://localhost:4318"
 
 **Automatic Initialization**
 
-When `GITLAB_TRACING` is set, LabKit automatically creates and configures a tracer when the gem is loaded. No manual initialization is required in most cases.
+When `GITLAB_TRACING` is set, LabKit automatically creates and configures a tracer:
+
+- **Rails applications**: Railtie automatically inserts Labkit::Tracing::RackMiddleware into the middleware stack
+- **Non-Rails applications**: Tracer is auto-initialized, but `Labkit::Tracing::RackMiddleware` must be manually added to your middleware stack for HTTP request tracing (see [Rack Middleware](#rack-middleware))
 
 Auto-initialization provides:
-- Automatic tracer creation with connection string settings
+- Automatic tracer creation with connection string settings (sampler, exporter, service name)
 - Service name from `service_name` query parameter (defaults to `"labkit-service"`)
-- All available OpenTelemetry instrumentation enabled by default (`c.use_all()`)
-- LabKit-specific instrumentation enabled automatically:
+- Selective OpenTelemetry instrumentation for components that don't conflict with LabKit:
+  - `ConcurrentRuby`, `Net::HTTP`, `ActionPack`, `ActionMailer`, `ActiveJob`
+- LabKit's own instrumentation for components it handles directly:
+  - HTTP request tracing (RackMiddleware for Rails)
   - Rails components (ActiveRecord, ActionView, ActiveSupport) - if Rails is available
   - Redis instrumentation - if Redis gem is loaded
   - External HTTP instrumentation (Net::HTTP, Excon, HTTPClient)
@@ -73,6 +78,7 @@ The following connection string formats and query parameters are supported:
   - **Behavior**: Outputs spans immediately to stdout with no remote export
   - **Benefits**: No external collector required, instant feedback, simple debugging
 
+
 ### Sampling
 
 **Default Behavior:** When no sampler is specified, probabilistic sampling is used with a **0.1% sample rate** (1 in 1000 traces).
@@ -159,7 +165,7 @@ This seamless integration means you can:
 
 ### Automatic Initialization (Default Behavior)
 
-When `GITLAB_TRACING` is set, LabKit automatically creates and configures a tracer when the gem loads:
+When `GITLAB_TRACING` is set, LabKit automatically creates and configures a tracer:
 
 ```bash
 # Set environment variable with service name
@@ -169,14 +175,23 @@ export GITLAB_TRACING="otlp://localhost:4318?service_name=my-api&sampler=probabi
 export GITLAB_TRACING="otlp://localhost:4318"
 ```
 
+**Rails Applications:**
+- Initialization happens automatically during Rails boot via Railtie
+- Runs after all other gem initializers (including `opentelemetry-instrumentation-rails`)
+- LabKit's TracerProvider is the final configuration used by the application
+- **No application code changes required** - just set the environment variable
+
+**Non-Rails Applications (Sinatra, Grape, standalone Ruby):**
+- Tracer auto-initialization happens automatically when `require 'gitlab-labkit'` is called.
+- However, you must manually add `Labkit::Tracing::RackMiddleware` to your middleware stack for HTTP request tracing. See the [Rack Middleware](#rack-middleware) section for details.
+
 Auto-initialization:
 - Creates tracer with connection string settings (sampler, exporter, endpoints)
 - Uses service name from `service_name` query parameter (defaults to `"labkit-service"`)
-- Enables all available OpenTelemetry instrumentation
+- Enables selective OpenTelemetry instrumentation (non-conflicting with LabKit's own)
+- Enables LabKit instrumentation for ActiveRecord, ActionView, ActiveSupport, Redis, and External HTTP
 - Sets up the global `OpenTelemetry.tracer_provider`
 
-**No application code changes required** - just set the environment variable.
-
 ### Automatic Rails Middleware Insertion
 
 When using Rails, the `Labkit::Tracing::RackMiddleware` is automatically inserted into your middleware stack when `GITLAB_TRACING` is set. No manual configuration needed!
@@ -214,8 +229,8 @@ You can override auto-initialization by calling `Factory.create_tracer` in your
 # config/initializers/tracing.rb
 # Override auto-initialization with custom configuration
 Labkit::Tracing::Factory.create_tracer("my-custom-service", ENV["GITLAB_TRACING"]) do |c|
-  # Selective instrumentation instead of c.use_all()
-  c.use 'OpenTelemetry::Instrumentation::Rails'
+  # Custom OTel instrumentation
+  c.use 'OpenTelemetry::Instrumentation::ConcurrentRuby'
   c.use 'OpenTelemetry::Instrumentation::Sidekiq'
 
   # Add custom span processors
@@ -232,7 +247,7 @@ end
 ```
 
 **When to use manual initialization:**
-- You need selective instrumentation (not `c.use_all()`)
+- You need different OTel instrumentations than the defaults
 - You need custom span processors
 - You need to add resource attributes
 - You want to override the service name from code instead of the connection string
@@ -289,11 +304,16 @@ end
 
 ### Initialization Order and Precedence
 
-**Auto-initialization:**
-1. Runs when the gem is loaded (`require 'gitlab-labkit'`)
+**Auto-initialization (all applications):**
+1. Runs automatically when `require 'gitlab-labkit'` is called
 2. Only runs if `GITLAB_TRACING` environment variable is set
 3. Uses `service_name` query parameter or defaults to `"labkit-service"`
-4. Attempts to enable all instrumentation with `c.use_all()`
+4. Enables selective OpenTelemetry instrumentation (ConcurrentRuby, Net::HTTP, ActionPack, ActionMailer, ActiveJob) to avoid conflicts with LabKit's own instrumentation
+5. Enables LabKit instrumentation for ActiveRecord, ActionView, ActiveSupport, Redis, and External HTTP
+
+**Additional Rails behavior:**
+1. Railtie runs after user config initializers (via `initializer ... after: :load_config_initializers`)
+2. Automatically inserts `Labkit::Tracing::RackMiddleware` into the middleware stack
 
 **Manual initialization:**
 1. Runs in your application initializer (e.g., `config/initializers/tracing.rb`)
@@ -308,7 +328,7 @@ end
    - Span processors with OTLP exporter
 
 2. **Configuration block** runs second and can:
-   - Add automatic instrumentation (`use`, `use_all`)
+   - Add automatic instrumentation (`use`)
    - Add additional span processors
    - Merge additional resource attributes
    - Override service_name if explicitly set in the block
@@ -570,8 +590,13 @@ If you need to add custom metadata (deployment environment, version, etc.), over
 # config/initializers/tracing.rb
 
 Labkit::Tracing::Factory.create_tracer("my-rails-app", ENV["GITLAB_TRACING"]) do |c|
-  # Enable all available OpenTelemetry instrumentation
-  c.use_all()
+  # Selective instrumentation (avoid conflicting with LabKit's own instrumentation
+  # for ActiveRecord, ActionView, ActiveSupport, Redis, Rack, and Sidekiq)
+  c.use("OpenTelemetry::Instrumentation::ConcurrentRuby")
+  c.use("OpenTelemetry::Instrumentation::Net::HTTP")
+  c.use("OpenTelemetry::Instrumentation::ActionPack") if defined?(ActionPack)
+  c.use("OpenTelemetry::Instrumentation::ActionMailer") if defined?(ActionMailer)
+  c.use("OpenTelemetry::Instrumentation::ActiveJob") if defined?(ActiveJob)
 
   # Add deployment metadata
   c.resource = c.resource.merge(
@@ -588,18 +613,18 @@ end
 
 Note: Middleware is still automatically inserted even with custom tracer initialization.
 
-### With Selective Instrumentation (Manual Override)
+### With Custom Instrumentation (Manual Override)
 
-If you want to control exactly which components are instrumented instead of using `c.use_all()`, override tracer initialization:
+If you want to control exactly which OTel components are instrumented, override tracer initialization:
 
 **Important:** When you manually call `Factory.create_tracer`, auto-initialization still runs but is replaced by your manual configuration. The LabKit-specific instrumentation (Rails, Redis, ExternalHttp) is still automatically enabled unless you explicitly disable auto-initialization.
 
 ```ruby
 # config/initializers/tracing.rb
-# Override auto-initialization for selective OpenTelemetry instrumentation
+# Override auto-initialization for custom OpenTelemetry instrumentation
 Labkit::Tracing::Factory.create_tracer("my-rails-app", ENV["GITLAB_TRACING"]) do |c|
-  # Selective OpenTelemetry instrumentation (instead of c.use_all())
-  c.use 'OpenTelemetry::Instrumentation::Rails'
+  # Only enable the OTel instrumentations you need
+  c.use 'OpenTelemetry::Instrumentation::ConcurrentRuby'
   c.use 'OpenTelemetry::Instrumentation::Sidekiq'
 end
 
@@ -642,9 +667,9 @@ If you're not seeing HTTP request traces in Rails:
    ```
 
 2. Check Rails logs for auto-insertion message:
-   ```
-   Labkit::Tracing: Automatically inserted RackMiddleware after Rails::Rack::Logger
-   ```
+    ```
+    Labkit::Tracing::RackMiddleware automatically inserted after Labkit::Middleware::Rack
+    ```
 
 3. If using custom middleware positioning, verify the order is correct:
    ```bash

data/lib/labkit/tracing/abstract_instrumenter.rb

@@ -7,27 +7,26 @@ module Labkit
     # https://edgeapi.rubyonrails.org/classes/ActiveSupport/Notifications/Instrumenter.html#method-c-new
     class AbstractInstrumenter
       def start(_name, _id, payload)
-        scope = Labkit::Tracing::TracingUtils.tracer.start_active_span(span_name(payload))
+        span_wrapper = Labkit::Tracing::TracingUtils.tracer.start_active_span(span_name(payload))
 
-        scope_stack.push scope
+        scope_stack.push span_wrapper
       end
 
       def finish(_name, _id, payload)
-        scope = scope_stack.pop
-        span = scope.span
+        span_wrapper = scope_stack.pop
 
-        Labkit::Tracing::TracingUtils.log_common_fields_on_span(span, span_name(payload))
+        Labkit::Tracing::TracingUtils.log_common_fields_on_span(span_wrapper, span_name(payload))
 
         # exception_object is the standard exception payload from ActiveSupport::Notifications
         # https://github.com/rails/rails/blob/v6.0.3.1/activesupport/lib/active_support/notifications/instrumenter.rb#L26
         exception = payload[:exception_object].presence || payload[:exception].presence
-        Labkit::Tracing::TracingUtils.log_exception_on_span(span, exception)
+        span_wrapper.set_error(exception)
 
         tags(payload).each do |k, v|
-          span.set_tag(k, v)
+          span_wrapper.set_tag(k, v)
         end
 
-        scope.close
+        span_wrapper.close
       end
 
       def scope_stack

data/lib/labkit/tracing/adapters/opentelemetry_span.rb

@@ -40,6 +40,10 @@ module Labkit
           end
         end
 
+        def close(**opts)
+          finish(**opts)
+        end
+
         def context
           span.context
         end

data/lib/labkit/tracing/adapters/opentelemetry_tracer.rb

@@ -91,6 +91,18 @@ module Labkit
             @token = token
           end
 
+          def set_tag(key, value)
+            span.set_tag(key, value)
+          end
+
+          def set_error(exception)
+            span.set_error(exception)
+          end
+
+          def log_event(name, **attributes)
+            span.log_event(name, **attributes)
+          end
+
           def close
             @raw_span.finish
             OpenTelemetry::Context.detach(@token)

data/lib/labkit/tracing/adapters/opentracing_span.rb

@@ -41,6 +41,10 @@ module Labkit
           scope&.close
         end
 
+        def close
+          finish
+        end
+
         def context
           span.context
         end

data/lib/labkit/tracing/adapters/opentracing_tracer.rb

@@ -34,15 +34,18 @@ module Labkit
         end
 
         def active_span
-          OpenTracing.active_span
+          span = OpenTracing.active_span
+          OpentracingSpan.new(span) if span
         end
 
         def start_active_span(operation_name, tags: nil)
-          if tags
-            OpenTracing.start_active_span(operation_name, tags: tags)
-          else
-            OpenTracing.start_active_span(operation_name)
-          end
+          scope = if tags
+                    OpenTracing.start_active_span(operation_name, tags: tags)
+                  else
+                    OpenTracing.start_active_span(operation_name)
+                  end
+
+          OpentracingSpan.new(scope)
         end
       end
     end