generate separate attrs and metrics files

Each root namespace gets separate attributes and metrics files.

Include examples of possible values for attributes.

Include a usage example of the template attributes as lambdas.

Fix links in doc comments referencing stable constants.

Co-authored-by: Hannah Ramadan <[email protected]>
Co-authored-by: Kayla Reopelle <[email protected]>

Author: 3 people

semantic_conventions/Rakefile

@@ -51,7 +51,7 @@ end
 task generate: %i[update_gem_version check_out_semconv_version] do
   puts "\n+++ Removing previously generated semantic conventions code.\n"
   semconv_output_dir
-    .glob('*.rb')
+    .glob('**/*.rb')
     .then { |files| FileUtils.rm(files) }
 
   puts "\n+++ Generating semantic conventions code.\n"

semantic_conventions/lib/opentelemetry/semconv/aspnetcore.rb renamed to semantic_conventions/lib/opentelemetry/semconv/aspnetcore/attributes.rb

@@ -26,42 +26,72 @@ module ASPNETCORE
       # ASP.NET Core exception middleware handling result
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   handled
+      #   unhandled
+      #
       ASPNETCORE_DIAGNOSTICS_EXCEPTION_RESULT = 'aspnetcore.diagnostics.exception.result'
 
       # Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) implementation that handled the exception.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   Contoso.MyHandler
+      #
       ASPNETCORE_DIAGNOSTICS_HANDLER_TYPE = 'aspnetcore.diagnostics.handler.type'
 
       # Rate limiting policy name.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   fixed
+      #   sliding
+      #   token
+      #
       ASPNETCORE_RATE_LIMITING_POLICY = 'aspnetcore.rate_limiting.policy'
 
       # Rate-limiting result, shows whether the lease was acquired or contains a rejection reason
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   acquired
+      #   request_canceled
+      #
       ASPNETCORE_RATE_LIMITING_RESULT = 'aspnetcore.rate_limiting.result'
 
       # Flag indicating if request was handled by the application pipeline.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   true
+      #
       ASPNETCORE_REQUEST_IS_UNHANDLED = 'aspnetcore.request.is_unhandled'
 
       # A value that indicates whether the matched route is a fallback route.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   true
+      #
       ASPNETCORE_ROUTING_IS_FALLBACK = 'aspnetcore.routing.is_fallback'
 
       # Match result - success or failure
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   success
+      #   failure
+      #
       ASPNETCORE_ROUTING_MATCH_STATUS = 'aspnetcore.routing.match_status'
 
       # @!endgroup
-
-      # @!group Metric Names
-      # @!endgroup
     end
   end
 end

semantic_conventions/lib/opentelemetry/semconv/aspnetcore/metrics.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# This file was autogenerated. Do not edit it by hand.
+
+module OpenTelemetry
+  module SemConv
+    module ASPNETCORE
+      # @!group Metrics Names
+    
+      # Number of exceptions caught by exception handling middleware.
+      # 
+      # Meter name: `Microsoft.AspNetCore.Diagnostics`; Added in: ASP.NET Core 8.0
+      # 
+      # @note Stability Level: stable
+      ASPNETCORE_DIAGNOSTICS_EXCEPTIONS = 'aspnetcore.diagnostics.exceptions'
+  
+      # Number of requests that are currently active on the server that hold a rate limiting lease.
+      # 
+      # Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0
+      # 
+      # @note Stability Level: stable
+      ASPNETCORE_RATE_LIMITING_ACTIVE_REQUEST_LEASES = 'aspnetcore.rate_limiting.active_request_leases'
+  
+      # Number of requests that are currently queued, waiting to acquire a rate limiting lease.
+      # 
+      # Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0
+      # 
+      # @note Stability Level: stable
+      ASPNETCORE_RATE_LIMITING_QUEUED_REQUESTS = 'aspnetcore.rate_limiting.queued_requests'
+  
+      # The time the request spent in a queue waiting to acquire a rate limiting lease.
+      # 
+      # Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0
+      # 
+      # @note Stability Level: stable
+      ASPNETCORE_RATE_LIMITING_REQUEST_TIME_IN_QUEUE = 'aspnetcore.rate_limiting.request.time_in_queue'
+  
+      # The duration of rate limiting lease held by requests on the server.
+      # 
+      # Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0
+      # 
+      # @note Stability Level: stable
+      ASPNETCORE_RATE_LIMITING_REQUEST_LEASE_DURATION = 'aspnetcore.rate_limiting.request_lease.duration'
+  
+      # Number of requests that tried to acquire a rate limiting lease.
+      # 
+      # Requests could be:
+      # 
+      # - Rejected by global or endpoint rate limiting policies
+      # - Canceled while waiting for the lease.
+      # 
+      # Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0
+      # 
+      # @note Stability Level: stable
+      ASPNETCORE_RATE_LIMITING_REQUESTS = 'aspnetcore.rate_limiting.requests'
+  
+      # Number of requests that were attempted to be matched to an endpoint.
+      # 
+      # Meter name: `Microsoft.AspNetCore.Routing`; Added in: ASP.NET Core 8.0
+      # 
+      # @note Stability Level: stable
+      ASPNETCORE_ROUTING_MATCH_ATTEMPTS = 'aspnetcore.routing.match_attempts'
+  
+      # @!endgroup
+    end
+  end
+end

semantic_conventions/lib/opentelemetry/semconv/client.rb renamed to semantic_conventions/lib/opentelemetry/semconv/client/attributes.rb

@@ -28,19 +28,26 @@ module CLIENT
       # When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries,  for example proxies, if it's available.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   client.example.com
+      #   10.1.2.80
+      #   /tmp/my.sock
+      #
       CLIENT_ADDRESS = 'client.address'
 
       # Client port number.
       # 
       # When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries,  for example proxies, if it's available.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   65123
+      #
       CLIENT_PORT = 'client.port'
 
       # @!endgroup
-
-      # @!group Metric Names
-      # @!endgroup
     end
   end
 end

semantic_conventions/lib/opentelemetry/semconv/error.rb renamed to semantic_conventions/lib/opentelemetry/semconv/error/attributes.rb

@@ -46,12 +46,16 @@ module ERROR
       # - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   timeout
+      #   java.net.UnknownHostException
+      #   server_certificate_invalid
+      #   500
+      #
       ERROR_TYPE = 'error.type'
 
       # @!endgroup
-
-      # @!group Metric Names
-      # @!endgroup
     end
   end
 end

semantic_conventions/lib/opentelemetry/semconv/incubating/exception.rb renamed to semantic_conventions/lib/opentelemetry/semconv/exception/attributes.rb

@@ -20,7 +20,6 @@
 
 module OpenTelemetry
   module SemConv
-  module Incubating
     module EXCEPTION
       # @!group Attribute Names
 
@@ -44,36 +43,38 @@ module EXCEPTION
       # clear whether the exception will escape.
       # 
       # @note Stability Level: stable
-      #
-      # @deprecated Now available in the stable namespace at {OpenTelemetry::SemConv::Exception::EXCEPTION_ESCAPED}.
       EXCEPTION_ESCAPED = 'exception.escaped'
 
       # The exception message.
       # 
       # @note Stability Level: stable
       #
-      # @deprecated Now available in the stable namespace at {OpenTelemetry::SemConv::Exception::EXCEPTION_MESSAGE}.
+      # @example Sample Values
+      #   Division by zero
+      #   Can't convert 'int' object to str implicitly
+      #
       EXCEPTION_MESSAGE = 'exception.message'
 
       # A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG.
       # 
       # @note Stability Level: stable
       #
-      # @deprecated Now available in the stable namespace at {OpenTelemetry::SemConv::Exception::EXCEPTION_STACKTRACE}.
+      # @example Sample Values
+      #   Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)
+      #
       EXCEPTION_STACKTRACE = 'exception.stacktrace'
 
       # The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it.
       # 
       # @note Stability Level: stable
       #
-      # @deprecated Now available in the stable namespace at {OpenTelemetry::SemConv::Exception::EXCEPTION_TYPE}.
+      # @example Sample Values
+      #   java.net.ConnectException
+      #   OSError
+      #
       EXCEPTION_TYPE = 'exception.type'
 
       # @!endgroup
-
-      # @!group Metric Names
-      # @!endgroup
     end
   end
-  end
 end

semantic_conventions/lib/opentelemetry/semconv/http.rb renamed to semantic_conventions/lib/opentelemetry/semconv/http/attributes.rb

@@ -23,13 +23,24 @@ module SemConv
     module HTTP
       # @!group Attribute Names
 
+      # Must be called with a key for the full attribute name. See notes below about the expectations
+      # for the state of the key.
+      #
+      # @example Usage
+      #   HTTP_REQUEST_HEADER_LAMBDA.call('some-cool-key') #=> 'http.request.header.some-cool-key'
+      #
       # HTTP request headers, `<key>` being the normalized HTTP Header name (lowercase), the value being the header values.
       # 
       # Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
       # The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
       # The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   http.request.header.content-type=["application/json"]
+      #   http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]
+      #
       HTTP_REQUEST_HEADER_LAMBDA = ->(key) { "http.request.header.#{key}" }
 
       # HTTP request method.
@@ -50,32 +61,63 @@ module HTTP
       # Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   GET
+      #   POST
+      #   HEAD
+      #
       HTTP_REQUEST_METHOD = 'http.request.method'
 
       # Original HTTP method sent by the client in the request line.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   GeT
+      #   ACL
+      #   foo
+      #
       HTTP_REQUEST_METHOD_ORIGINAL = 'http.request.method_original'
 
       # The ordinal number of request resending attempt (for any reason, including redirects).
       # 
       # The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other).
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   3
+      #
       HTTP_REQUEST_RESEND_COUNT = 'http.request.resend_count'
 
+      # Must be called with a key for the full attribute name. See notes below about the expectations
+      # for the state of the key.
+      #
+      # @example Usage
+      #   HTTP_RESPONSE_HEADER_LAMBDA.call('some-cool-key') #=> 'http.response.header.some-cool-key'
+      #
       # HTTP response headers, `<key>` being the normalized HTTP Header name (lowercase), the value being the header values.
       # 
       # Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
       # Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
       # The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   http.response.header.content-type=["application/json"]
+      #   http.response.header.my-custom-header=["abc", "def"]
+      #
       HTTP_RESPONSE_HEADER_LAMBDA = ->(key) { "http.response.header.#{key}" }
 
       # [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   200
+      #
       HTTP_RESPONSE_STATUS_CODE = 'http.response.status_code'
 
       # The matched route, that is, the path template in the format used by the respective server framework.
@@ -84,12 +126,14 @@ module HTTP
       # SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
       # 
       # @note Stability Level: stable
+      #
+      # @example Sample Values
+      #   /users/:userID?
+      #   {controller}/{action}/{id?}
+      #
       HTTP_ROUTE = 'http.route'
 
       # @!endgroup
-
-      # @!group Metric Names
-      # @!endgroup
     end
   end
 end