Module: Labkit::Tracing Private

Defined in:
lib/labkit/tracing.rb,
lib/labkit/tracing/grpc.rb,
lib/labkit/tracing/rails.rb,
lib/labkit/tracing/redis.rb,
lib/labkit/tracing/factory.rb,
lib/labkit/tracing/railtie.rb,
lib/labkit/tracing/external_http.rb,
lib/labkit/tracing/tracing_utils.rb,
lib/labkit/tracing/jaeger_factory.rb,
lib/labkit/tracing/tracing_common.rb,
lib/labkit/tracing/auto_initialize.rb,
lib/labkit/tracing/rack_middleware.rb,
lib/labkit/tracing/grpc_interceptor.rb,
lib/labkit/tracing/rails/action_view.rb,
lib/labkit/tracing/adapters/base_span.rb,
lib/labkit/tracing/rails/active_record.rb,
lib/labkit/tracing/adapters/base_tracer.rb,
lib/labkit/tracing/open_tracing_factory.rb,
lib/labkit/tracing/rails/active_support.rb,
lib/labkit/tracing/abstract_instrumenter.rb,
lib/labkit/tracing/open_telemetry_factory.rb,
lib/labkit/tracing/grpc/client_interceptor.rb,
lib/labkit/tracing/grpc/server_interceptor.rb,
lib/labkit/tracing/redis/redis_interceptor.rb,
lib/labkit/tracing/adapters/opentracing_span.rb,
lib/labkit/tracing/adapters/opentelemetry_span.rb,
lib/labkit/tracing/adapters/opentracing_tracer.rb,
lib/labkit/tracing/rails/action_view/subscriber.rb,
lib/labkit/tracing/adapters/opentelemetry_tracer.rb,
lib/labkit/tracing/rails/active_record/subscriber.rb,
lib/labkit/tracing/redis/redis_interceptor_helper.rb,
lib/labkit/tracing/rails/active_support/subscriber.rb,
lib/labkit/tracing/external_http/request_instrumenter.rb,
lib/labkit/tracing/rails/active_record/sql_instrumenter.rb,
lib/labkit/tracing/rails/active_support/cache_read_instrumenter.rb,
lib/labkit/tracing/rails/action_view/render_partial_instrumenter.rb,
lib/labkit/tracing/rails/active_support/cache_write_instrumenter.rb,
lib/labkit/tracing/rails/action_view/render_template_instrumenter.rb,
lib/labkit/tracing/rails/active_support/cache_delete_instrumenter.rb,
lib/labkit/tracing/rails/action_view/render_collection_instrumenter.rb,
lib/labkit/tracing/rails/active_support/cache_generate_instrumenter.rb,
lib/labkit/tracing/rails/active_support/cache_fetch_hit_instrumenter.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Tracing provides distributed tracing functionality

Defined Under Namespace

Modules: Adapters, AutoInitialize, ExternalHttp, GRPC, Rails, Redis, TracingCommon Classes: AbstractInstrumenter, Factory, JaegerFactory, OpenTelemetryFactory, OpenTracingFactory, RackMiddleware, Railtie, TracingUtils

Constant Summary collapse

DEFAULT_SERVICE_NAME =

Must be a String, not Symbol, as OpenTelemetry requires resource attribute values to be strings, integers, floats, or booleans

"labkit-service"
GRPCInterceptor =

GRPCInterceptor is the deprecated name for GRPCClientInterceptor

GRPC::ClientInterceptor

Class Method Summary collapse

Class Method Details

.connection_string ⇒ Object 



46
47
48
 
# File 'lib/labkit/tracing.rb', line 46

def self.connection_string
  ENV["GITLAB_TRACING"]
end

.current_span ⇒ OpenTelemetry::Trace::Span?

Returns the currently active span from OpenTelemetry. This provides direct access to the OpenTelemetry span API.

Examples:

Adding attributes to the current span

span = Labkit::Tracing.current_span
span.set_attribute("user.id", user.id) if span.recording?

Adding events

span = Labkit::Tracing.current_span
span.add_event("cache_miss", attributes: { "key" => cache_key })

Conditional expensive operations

span = Labkit::Tracing.current_span
if span.recording?
  span.set_attribute("expensive_data", compute_expensive_data)
end

Returns:

  • (OpenTelemetry::Trace::Span, nil) —

    The current span (may be a no-op span when tracing is disabled, or nil when using OpenTracing)



156
157
158
159
160
161
 
# File 'lib/labkit/tracing.rb', line 156

def self.current_span
  return nil if opentracing_connection?

  require "opentelemetry/sdk"
  OpenTelemetry::Trace.current_span
end

.enabled? ⇒ Boolean

Tracing is only enabled when the ‘GITLAB_TRACING` env var is configured.

Returns:

  • (Boolean) 


42
43
44
 
# File 'lib/labkit/tracing.rb', line 42

def self.enabled?
  connection_string.present?
end

.opentracing_connection?(connection_string = ENV["GITLAB_TRACING"]) ⇒ Boolean

Returns:

  • (Boolean) 


54
55
56
 
# File 'lib/labkit/tracing.rb', line 54

def self.opentracing_connection?(connection_string = ENV["GITLAB_TRACING"])
  connection_string.to_s.start_with?("#{OpenTracingFactory::OPENTRACING_SCHEME}://")
end

.otlp_connection?(connection_string = ENV["GITLAB_TRACING"]) ⇒ Boolean

Returns:

  • (Boolean) 


50
51
52
 
# File 'lib/labkit/tracing.rb', line 50

def self.otlp_connection?(connection_string = ENV["GITLAB_TRACING"])
  connection_string.to_s.start_with?("#{OpenTelemetryFactory::OTLP_SCHEME}://")
end

.sampled? ⇒ Boolean

Check if the current request is being traced.

Returns:

  • (Boolean) 


70
71
72
73
 
# File 'lib/labkit/tracing.rb', line 70

def self.sampled?
  context = TracingUtils.tracer.active_span&.context
  context&.respond_to?(:sampled?) && context&.sampled?
end

.stacktrace_operations ⇒ Object 



75
76
77
 
# File 'lib/labkit/tracing.rb', line 75

def self.stacktrace_operations
  @stacktrace_operations ||= Set.new(ENV["GITLAB_TRACING_INCLUDE_STACKTRACE"].to_s.split(",").map(&:strip))
end

.tracer ⇒ Object

Returns the underlying tracer implementation from the tracing library in use. This provides direct access to the native tracer API when LabKit’s abstraction is insufficient for advanced use cases.

Examples:

Using OpenTelemetry-specific APIs

tracer = Labkit::Tracing.tracer
tracer.in_span("custom-span") do |span|
  span.add_event("custom-event", attributes: { "key" => "value" })
end

Returns:

  • (Object) —

    The tracer implementation:

    • OpenTelemetry::SDK::Trace::Tracer when using OTLP connection

    • No-op tracer when tracing is not configured



134
135
136
 
# File 'lib/labkit/tracing.rb', line 134

def self.tracer
  TracingUtils.tracer.tracer
end

.tracing_url(service_name) ⇒ String?

Note:

This method is only useful with OpenTracing and Jaeger. It does not work with OpenTelemetry backends because:

  • Uses correlation_id (GitLab-specific request ID) instead of trace_id (W3C standard)

  • Modern tracing UIs (Jaeger with OTLP, Grafana Tempo, etc.) expect trace_id for lookups

  • Only Jaeger’s legacy OpenTracing integration supports correlation_id-based URLs

Generates a URL to view the current trace in a tracing UI.

This method substitutes correlation_id } and service } placeholders in the GITLAB_TRACING_URL template with the current correlation ID and provided service name.

Examples:

With OpenTracing/Jaeger (supported)

ENV["GITLAB_TRACING_URL"] = "https://jaeger.example.com/trace?correlationId={{ correlation_id }}"
Labkit::Tracing.tracing_url("my-service")
# => "https://jaeger.example.com/trace?correlationId=abc123"

Parameters:

  • service_name (String) —

    The name of the service to include in the URL

Returns:

  • (String, nil) —

    The generated URL, or nil if tracing URL is not enabled



109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/labkit/tracing.rb', line 109

def self.tracing_url(service_name)
  return unless tracing_url_enabled?

  correlation_id = Labkit::Correlation::CorrelationId.current_id.to_s

  # Avoid using `format` since it can throw TypeErrors
  # which we want to avoid on unsanitised env var input
  tracing_url_template.to_s
    .gsub("{{ correlation_id }}", correlation_id)
    .gsub("{{ service }}", service_name)
end

.tracing_url_enabled? ⇒ Boolean

Note:

This method is only useful with OpenTracing and Jaeger. It does not work with OpenTelemetry backends, as they expect trace_id (W3C standard) rather than correlation_id (GitLab-specific) for trace lookups.

Checks if tracing URL generation is enabled.

Returns:

  • (Boolean) —

    true if both tracing and URL template are configured

See Also:



87
88
89
 
# File 'lib/labkit/tracing.rb', line 87

def self.tracing_url_enabled?
  enabled? && tracing_url_template.present?
end

.tracing_url_template ⇒ String?

Note:

This method is only useful with OpenTracing and Jaeger. It does not work with OpenTelemetry backends, as they expect trace_id (W3C standard) rather than correlation_id (GitLab-specific) for trace lookups.

Returns the tracing URL template from the GITLAB_TRACING_URL environment variable.

Returns:

  • (String, nil) —

    The URL template with placeholders for correlation_id } and service }



65
66
67
 
# File 'lib/labkit/tracing.rb', line 65

def self.tracing_url_template
  ENV["GITLAB_TRACING_URL"]
end

.with_tracing(**kwargs, &block) ⇒ Object

This will run a block with a span

Parameters:

  • operation_name (String) —

    The operation name for the span

  • tags (Hash) —

    Tags to assign to the span

  • child_of (SpanContext, Span) —

    SpanContext that acts as a parent to the newly-started span. If a span instance is provided, its context is automatically substituted.



169
170
171
 
# File 'lib/labkit/tracing.rb', line 169

def self.with_tracing(**kwargs, &block)
  TracingUtils.with_tracing(**kwargs, &block)
end