Verified Commit 1d2d8c5c authored by Hercules Merscher's avatar Hercules Merscher 🌴
Browse files

deprecated: mark tracing URL methods as OpenTracing/Jaeger only 

Add YARD documentation to tracing_url, tracing_url_enabled?, and
tracing_url_template explaining they only work with OpenTracing/Jaeger.

These methods use correlation_id for trace lookups, which only works
with Jaeger's legacy OpenTracing integration. Modern OTel backends
(Jaeger with OTLP, Grafana Tempo, etc.) require trace_id instead.

Also removed "Getting Trace URLs" section from tracing README to keep
OTel-focused documentation accurate. Methods remain functional for
backward compatibility.
parent 4fa7c12d

lib/labkit/tracing.rb

+33 −2
Original line number Diff line number Diff line
@@ -45,6 +45,13 @@ module Labkit 
      connection_string.to_s.start_with?("#{OpenTracingFactory::OPENTRACING_SCHEME}://")

    end



    # Returns the tracing URL template from the GITLAB_TRACING_URL environment variable.

    #

    # @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.

    #

    # @return [String, nil] The URL template with placeholders for {{ correlation_id }} and {{ service }}

    def self.tracing_url_template

      ENV["GITLAB_TRACING_URL"]

    end
@@ -59,12 +66,36 @@ module Labkit 
      @stacktrace_operations ||= Set.new(ENV["GITLAB_TRACING_INCLUDE_STACKTRACE"].to_s.split(",").map(&:strip))

    end



    # Checks if tracing URL generation is enabled.

    #

    # @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.

    #

    # @return [Boolean] true if both tracing and URL template are configured

    # @see tracing_url

    def self.tracing_url_enabled?

      enabled? && tracing_url_template.present?

    end



    # This will provide a link into the distributed tracing for the current trace,

    # if it has been captured.

    # 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.

    #

    # @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

    #

    # @param service_name [String] The name of the service to include in the URL

    # @return [String, nil] The generated URL, or nil if tracing URL is not enabled

    #

    # @example 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"

    def self.tracing_url(service_name)

      return unless tracing_url_enabled?

lib/labkit/tracing/README.md

+1 −23
Original line number Diff line number Diff line
@@ -13,7 +13,7 @@ Distributed tracing allows you to track requests as they flow through your appli 


## Configuration



Tracing is controlled via environment variables:

Tracing is controlled via an environment variable:



### Required Configuration
@@ -49,17 +49,6 @@ Auto-initialization provides: 


### Optional Configuration



**`GITLAB_TRACING_URL`** - Template URL for linking to trace views



Supports placeholders:

- `{{ correlation_id }}` - Current correlation ID

- `{{ service }}` - Service name



Example:

```bash

export GITLAB_TRACING_URL="https://tracing.example.com/trace/{{ correlation_id }}?service={{ service }}"

```



**`GITLAB_TRACING_INCLUDE_STACKTRACE`** - Comma-separated list of operation name prefixes to include stack traces



Example:
@@ -262,17 +251,6 @@ end 


**Important:** Calling `Factory.create_tracer` multiple times will reconfigure the global OpenTelemetry tracer provider each time. Initialize tracing once during application startup.



### Getting Trace URLs



Generate a URL to view the current trace in your tracing UI:



```ruby

if Labkit::Tracing.tracing_url_enabled?

  url = Labkit::Tracing.tracing_url("my-service")

  # Returns: https://tracing.example.com/trace/abc123?service=my-service

end

```



### Checking if Current Request is Sampled



```ruby