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 = 
:'labkit-service'
GRPCInterceptor =

GRPCInterceptor is the deprecated name for GRPCClientInterceptor

GRPC::ClientInterceptor

Class Method Summary collapse

Class Method Details

.connection_string ⇒ Object 



44
45
46
 
# File 'lib/labkit/tracing.rb', line 44

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)



154
155
156
157
158
159
 
# File 'lib/labkit/tracing.rb', line 154

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) 


40
41
42
 
# File 'lib/labkit/tracing.rb', line 40

def self.enabled?
  connection_string.present?
end

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

Returns:

  • (Boolean) 


52
53
54
 
# File 'lib/labkit/tracing.rb', line 52

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) 


48
49
50
 
# File 'lib/labkit/tracing.rb', line 48

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) 


68
69
70
71
 
# File 'lib/labkit/tracing.rb', line 68

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

.stacktrace_operations ⇒ Object 



73
74
75
 
# File 'lib/labkit/tracing.rb', line 73

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



132
133
134
 
# File 'lib/labkit/tracing.rb', line 132

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



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

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:



85
86
87
 
# File 'lib/labkit/tracing.rb', line 85

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 }



63
64
65
 
# File 'lib/labkit/tracing.rb', line 63

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.



167
168
169
 
# File 'lib/labkit/tracing.rb', line 167

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