Skip to content

Commit 0fead30

Browse files
arielvalentinarielvalentin
committed
squash: some refactoring
1 parent 36b7dcd commit 0fead30

File tree

2 files changed

+72
-43
lines changed
  • helpers/semconv

2 files changed

+72
-43
lines changed

‎helpers/semconv/lib/opentelemetry/helpers/semconv/http.rb‎

Lines changed: 64 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -28,45 +28,48 @@ module Semconv
2828
# ## Semantic Convention Support
2929
#
3030
# Supports both current and legacy OpenTelemetry semantic conventions:
31-
# - **Current**: `http.request.method`, `url.template`
31+
# - **Current**: `http.request.method`, `url.template` (client spans only)
3232
# - **Legacy**: `http.method` (deprecated but supported for compatibility)
3333
#
34+
# **Note**: The `url.template` attribute is only applicable to HTTP client spans.
35+
# Server spans should use `http.route` or other appropriate attributes for naming.
36+
#
3437
# When both current and legacy attributes are present, current conventions take
3538
# precedence.
3639
#
37-
# @example Basic usage with method and URL template
40+
# @example Basic HTTP client span naming
3841
# attrs = {
3942
# 'http.request.method' => 'GET',
4043
# 'url.template' => '/users/:id'
4144
# }
42-
# HTTP.name_from(attrs) # => "GET /users/:id"
45+
# HTTP::Client.name_from(attrs) # => "GET /users/:id"
4346
#
4447
# @example Method normalization
4548
# attrs = { 'http.request.method' => 'get' }
46-
# HTTP.name_from(attrs) # => "GET"
49+
# HTTP::Client.name_from(attrs) # => "GET"
4750
#
4851
# @example Legacy attribute support
4952
# attrs = { 'http.method' => 'POST' }
50-
# HTTP.name_from(attrs) # => "POST"
53+
# HTTP::Client.name_from(attrs) # => "POST"
5154
#
5255
# @example Preference for current conventions
5356
# attrs = {
5457
# 'http.request.method' => 'PUT',
5558
# 'http.method' => 'GET' # ignored in favor of current convention
5659
# }
57-
# HTTP.name_from(attrs) # => "PUT"
60+
# HTTP::Client.name_from(attrs) # => "PUT"
5861
#
5962
# @example Fallback behavior
6063
# # Unknown method falls back to HTTP
6164
# attrs = { 'http.request.method' => 'UNKNOWN' }
62-
# HTTP.name_from(attrs) # => "HTTP"
65+
# HTTP::Client.name_from(attrs) # => "HTTP"
6366
#
6467
# # URL template without method
6568
# attrs = { 'url.template' => '/health' }
66-
# HTTP.name_from(attrs) # => "HTTP /health"
69+
# HTTP::Client.name_from(attrs) # => "HTTP /health"
6770
#
6871
# # Empty attributes
69-
# HTTP.name_from({}) # => "HTTP"
72+
# HTTP::Client.name_from({}) # => "HTTP"
7073
module HTTP
7174
# Mapping of HTTP methods (in various cases) to their uppercase equivalents.
7275
# Only includes standard HTTP methods as defined by RFC specifications.
@@ -79,37 +82,63 @@ module HTTP
7982
hash[uppercase_method] = uppercase_method
8083
end.freeze
8184

82-
module_function
83-
84-
# Generates a span name from HTTP semantic convention attributes.
85+
# Provides span naming utilities for HTTP client spans.
8586
#
86-
# Creates consistent span names for HTTP operations by combining the HTTP method
87-
# and URL template when available. Handles method normalization, attribute
88-
# precedence, and provides appropriate fallbacks.
87+
# This module contains methods specifically designed for naming HTTP client spans
88+
# according to OpenTelemetry semantic conventions. Client spans typically include
89+
# `url.template` attributes that describe the URL pattern being requested.
8990
#
90-
# ## Attribute Processing
91+
# @example Basic usage
92+
# attrs = {
93+
# 'http.request.method' => 'GET',
94+
# 'url.template' => '/users/:id'
95+
# }
96+
# HTTP::Client.name_from(attrs) # => "GET /users/:id"
9197
#
92-
# 1. **Method Resolution**: Looks for `http.request.method` first, then falls back
93-
# to `http.method` for legacy compatibility
94-
# 2. **Method Normalization**: Standard HTTP methods are converted to uppercase
95-
# 3. **Unknown Methods**: Non-standard methods default to "HTTP"
96-
# 4. **URL Template**: Uses `url.template` when available
97-
# 5. **Whitespace Handling**: Strips whitespace from all attribute values
98-
#
99-
# @param attrs [Hash] Hash of span attributes following OpenTelemetry semantic conventions
100-
# @return [String] The generated span name
101-
# - With method and template: `"GET /users/:id"`
102-
# - Method only: `"GET"`
103-
# - Template only: `"HTTP /health"`
104-
# - No attributes: `"HTTP"`
105-
def name_from(attrs)
106-
http_method = HTTP_METHODS_TO_UPPERCASE[attrs['http.request.method']&.strip || attrs['http.method']&.strip]
107-
http_method ||= 'HTTP'
108-
url_template = attrs['url.template']&.strip
98+
# @since 0.1.0
99+
module Client
100+
module_function
101+
102+
# Generates a span name for HTTP client spans from semantic convention attributes.
103+
#
104+
# Creates consistent span names for HTTP client operations by combining the HTTP method
105+
# and URL template when available. This method is specifically designed for HTTP client
106+
# spans that use `url.template` attributes. For server spans, consider using `http.route`
107+
# or other appropriate naming strategies.
108+
#
109+
# ## Attribute Processing
110+
#
111+
# 1. **Method Resolution**: Looks for `http.request.method` first, then falls back
112+
# to `http.method` for legacy compatibility
113+
# 2. **Method Normalization**: Standard HTTP methods are converted to uppercase
114+
# 3. **Unknown Methods**: Non-standard methods default to "HTTP"
115+
# 4. **URL Template**: Uses `url.template` when available (client spans only)
116+
# 5. **Whitespace Handling**: Strips whitespace from all attribute values
117+
#
118+
# ## Client vs Server Spans
119+
#
120+
# This method is designed for **HTTP client spans** that include:
121+
# - `http.request.method` or `http.method` - The HTTP method being used
122+
# - `url.template` - The URL template being requested (e.g., "/users/:id")
123+
#
124+
# For **HTTP server spans**, use `http.route` or other server-specific attributes
125+
# instead of `url.template`.
126+
#
127+
# @param attrs [Hash] Hash of span attributes following OpenTelemetry semantic conventions
128+
# @return [String] The generated span name for HTTP client operations
129+
# - With method and template: `"GET /users/:id"`
130+
# - Method only: `"GET"`
131+
# - Template only: `"HTTP /health"`
132+
# - No attributes: `"HTTP"`
133+
def name_from(attrs)
134+
http_method = HTTP_METHODS_TO_UPPERCASE[attrs['http.request.method']&.strip || attrs['http.method']&.strip]
135+
http_method ||= 'HTTP'
136+
url_template = attrs['url.template']&.strip
109137

110-
return "#{http_method} #{url_template}".strip if url_template && http_method
138+
return "#{http_method} #{url_template}".strip if url_template && http_method
111139

112-
http_method
140+
http_method
141+
end
113142
end
114143
end
115144
end

‎helpers/semconv/test/opentelemetry/helpers/semconv/http/http_test.rb‎ renamed to ‎helpers/semconv/test/opentelemetry/helpers/semconv/http/client_test.rb‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
require_relative '../../../../../lib/opentelemetry/helpers/semconv/http'
1010

11-
describe OpenTelemetry::Helpers::Semconv::HTTP do
11+
describe OpenTelemetry::Helpers::Semconv::HTTP::Client do
1212
describe 'span naming' do
1313
test_cases = [
1414
# [description, attributes, expected_result]
@@ -28,33 +28,33 @@
2828

2929
test_cases.each do |description, attributes, expected|
3030
it description do
31-
_(OpenTelemetry::Helpers::Semconv::HTTP.name_from(attributes)).must_equal expected
31+
_(OpenTelemetry::Helpers::Semconv::HTTP::Client.name_from(attributes)).must_equal expected
3232
end
3333
end
3434

3535
it 'normalizes HTTP methods to uppercase' do
3636
%w[GET POST PUT PATCH DELETE HEAD OPTIONS TRACE CONNECT].each do |method|
3737
attrs = { 'http.request.method' => method }
38-
_(OpenTelemetry::Helpers::Semconv::HTTP.name_from(attrs)).must_equal method
38+
_(OpenTelemetry::Helpers::Semconv::HTTP::Client.name_from(attrs)).must_equal method
3939

4040
attrs = { 'http.request.method' => method.downcase }
41-
_(OpenTelemetry::Helpers::Semconv::HTTP.name_from(attrs)).must_equal method
41+
_(OpenTelemetry::Helpers::Semconv::HTTP::Client.name_from(attrs)).must_equal method
4242

4343
attrs = { 'http.method' => method }
44-
_(OpenTelemetry::Helpers::Semconv::HTTP.name_from(attrs)).must_equal method
44+
_(OpenTelemetry::Helpers::Semconv::HTTP::Client.name_from(attrs)).must_equal method
4545

4646
attrs = { 'http.method' => method.downcase }
47-
_(OpenTelemetry::Helpers::Semconv::HTTP.name_from(attrs)).must_equal method
47+
_(OpenTelemetry::Helpers::Semconv::HTTP::Client.name_from(attrs)).must_equal method
4848
end
4949
end
5050

5151
it 'defaults to HTTP for unknown methods' do
5252
%w[PURGE FAKE PHONY].each do |method|
5353
attrs = { 'http.request.method' => method }
54-
_(OpenTelemetry::Helpers::Semconv::HTTP.name_from(attrs)).must_equal 'HTTP'
54+
_(OpenTelemetry::Helpers::Semconv::HTTP::Client.name_from(attrs)).must_equal 'HTTP'
5555
end
5656

57-
_(OpenTelemetry::Helpers::Semconv::HTTP.name_from({})).must_equal 'HTTP'
57+
_(OpenTelemetry::Helpers::Semconv::HTTP::Client.name_from({})).must_equal 'HTTP'
5858
end
5959
end
6060
end

0 commit comments

Comments
 (0)