From db06802c13154f30efb4b1d3f7856b896fffc589 Mon Sep 17 00:00:00 2001 From: Hannah Ramadan Date: Mon, 16 Sep 2024 09:58:40 -0700 Subject: [PATCH] Add docs for StabilityMode --- .../semantic_conventions/stability_mode.rb | 82 +++++++++++++++---- 1 file changed, 65 insertions(+), 17 deletions(-) diff --git a/semantic_conventions/lib/opentelemetry/semantic_conventions/stability_mode.rb b/semantic_conventions/lib/opentelemetry/semantic_conventions/stability_mode.rb index 072af8efe..50a6e68d4 100644 --- a/semantic_conventions/lib/opentelemetry/semantic_conventions/stability_mode.rb +++ b/semantic_conventions/lib/opentelemetry/semantic_conventions/stability_mode.rb @@ -6,13 +6,35 @@ module OpenTelemetry module SemanticConventions - # The StabilityMode class provides constants and methods for semantic conventions stability + # The `StabilityMode` class allows controls which semantic conventions are emitted. + # + # For more information on semantic conventions stability, refer to + # {https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#semantic-conventions-stability OpenTelemetry documentation}. + # + # ## Configuration + # The `StabilityMode` class is relies on the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable, a comma-delimited string of stability modes to opt into. + # + # Currently, `OTEL_SEMCONV_STABILITY_OPT_IN` only supports {https://opentelemetry.io/docs/specs/semconv/http/ semantic conventions for HTTP}. + # The values defined for `OTEL_SEMCONV_STABILITY_OPT_IN` are: + # - `http`: Emit stable HTTP and networking conventions ONLY + # - `http/dup`: Emit both old and stable HTTP and networking conventions + # - `default`: Emit old conventions ONLY + # + # If no `OTEL_SEMCONV_STABILITY_OPT_IN` is set, the `default` behavior is used. `http/dup` has higher precedence than `http`` in case both values are present. + # + # Example usage: + # ```ruby + # stability_mode = OpenTelemetry::SemanticConventions::StabilityMode.new + # stability_mode.set_http_method(result, 'GET') + # stability_mode.set_http_status_code(result, 200) + # stability_mode.set_http_url(result, 'https://example.com') + # ``` class StabilityMode OTEL_SEMCONV_STABILITY_OPT_IN = 'OTEL_SEMCONV_STABILITY_OPT_IN' - DEFAULT = 'default' # emit old conventions ONLY - HTTP = 'http' # emit stable HTTP and networking conventions ONLY - HTTP_DUP = 'http/dup' # emit both old and stable HTTP and networking conventions + DEFAULT = 'default' + HTTP = 'http' + HTTP_DUP = 'http/dup' # These constants will be pulled in from elsehwere once semvconv stability PR merged # https://github.com/open-telemetry/opentelemetry-ruby/pull/1651 @@ -26,19 +48,18 @@ class StabilityMode SERVER_PORT = 'server.port' attr_accessor :initialized, :lock, :otel_semconv_stability_signal_mapping - + def initialize @lock = Mutex.new @otel_semconv_stability_signal_mapping = {} - + @lock.synchronize do - # Users can pass in comma delimited string for opt-in options opt_in = ENV.fetch('OTEL_SEMCONV_STABILITY_OPT_IN', nil) opt_in_list = opt_in.split(',').map(&:strip) if opt_in http_set_sability_mode(opt_in_list) if opt_in_list end end - + def http_set_sability_mode(opt_in_list) return unless opt_in_list.include?(HTTP) || opt_in_list.include?(HTTP_DUP) @@ -54,7 +75,7 @@ def http_set_sability_mode(opt_in_list) def report_new?(opt_in_mode) otel_semconv_stability_signal_mapping[opt_in_mode] != DEFAULT end - + def report_old?(opt_in_mode) otel_semconv_stability_signal_mapping[opt_in_mode] != HTTP end @@ -62,43 +83,70 @@ def report_old?(opt_in_mode) def set_string_attribute(result, key, value) result[key] = String(value) if value end - + def set_int_attribute(result, key, value) result[key] = Integer(value) if value end + # Sets the HTTP method attribute in the result hash. + # + # @param result [Hash] The result hash. + # @param request_method [String] The HTTP request method. def set_http_method(result, request_method) set_string_attribute(result, OpenTelemetry::SemanticConventions::Trace::HTTP_METHOD, request_method) if report_old?(HTTP) set_string_attribute(result, HTTP_REQUEST_METHOD, request_method) if report_new?(HTTP) end - + + # Sets the HTTP status code attribute in the result hash. + # + # @param result [Hash] The result hash. + # @param code [Integer] The HTTP status code. def set_http_status_code(result, code) set_int_attribute(result, OpenTelemetry::SemanticConventions::Trace::HTTP_STATUS_CODE, code) if report_old?(HTTP) set_int_attribute(result, HTTP_RESPONSE_STATUS_CODE, code) if report_new?(HTTP) end - + + # Sets the HTTP URL attribute in the result hash. + # + # @param result [Hash] The result hash. + # @param url [String] The HTTP URL. def set_http_url(result, url) set_string_attribute(result, OpenTelemetry::SemanticConventions::Trace::HTTP_URL, url) if report_old?(HTTP) set_string_attribute(result, URL_FULL, url) if report_new?(HTTP) end - + + # Sets the HTTP scheme attribute in the result hash. + # + # @param result [Hash] The result hash. + # @param scheme [String] The HTTP scheme. def set_http_scheme(result, scheme) set_string_attribute(result, OpenTelemetry::SemanticConventions::Trace::HTTP_SCHEME, scheme) if report_old?(HTTP) set_string_attribute(result, URL_SCHEME, scheme) if report_new?(HTTP) end - - # Client - + + # Sets the server address attribute in the result hash for client requests. + # + # @param result [Hash] The result hash. + # @param peer_name [String] The server address. def set_http_net_peer_name_client(result, peer_name) set_string_attribute(result, OpenTelemetry::SemanticConventions::Trace::NET_PEER_NAME, peer_name) if report_old?(HTTP) set_string_attribute(result, SERVER_ADDRESS, peer_name) if report_new?(HTTP) end - + + # Sets the server port attribute in the result hash for client requests. + # + # @param result [Hash] The result hash. + # @param port [Integer] The server port. def set_http_peer_port_client(result, port) set_int_attribute(result, OpenTelemetry::SemanticConventions::Trace::NET_PEER_PORT, port) if report_old?(HTTP) set_int_attribute(result, SERVER_PORT, port) if report_new?(HTTP) end + # Sets the HTTP target attribute in the result hash. + # + # @param result [Hash] The result hash. + # @param path [String] The URL path. + # @param query [String] The URL query. def set_http_target(result, path, query) set_string_attribute(result, OpenTelemetry::SemanticConventions::Trace::HTTP_TARGET, path) if report_old?(HTTP) return unless report_new?(HTTP)