fix(semconv): correct & simplify codegen templates (#2059)

* fix(semconv): template, treat deprecated as a dict

(attribute|metric).deprecated is a dict, so dropping it into Yard doc
content gets weird with Yard treating {} as a reference to other Yard
content elsewhere.

This change uses deprecated.note (if present) or deprecated.reason
(always present, but less info) capitalized with a period.

* fix(semconv): result of the template update for deprecated

* fix(semconv): template, remove @examples

attribute.examples come in too many shapes to include in generated code
docs without a complicated template to interpret their shape.

WWJD: What Would Java Do?

Java doesn't include examples. Let's not, also.

* fix(semconv): result of the template removal for examples

* fix(semconv): correct typo carried over from semconv model data

* fix(semconv): let toys manage the VERSION constant

Record the current semconv version in a separate constant.

* Maybe some comments about how these differ?

* docs: update words about these version constants

Better directions for how to hold this update process.

Author: robbkidd

semantic_conventions/README.md

@@ -87,7 +87,10 @@ upstream [OpenTelemetry Semantic Conventions version][semconv].
 
 ## How do I rebuild the conventions?
 
-Bump the version number in the Rakefile, and then run `rake generate`.
+To build the library against a new version of the semantic conventions, update SPEC_VERSION in the Rakefile, and then run `rake generate`.
+
+Do not update the library's VERSION in version.rb.
+That will be handled by the automation for releasing the gem.
 
 ## How can I get involved?
 

semantic_conventions/Rakefile

@@ -48,7 +48,7 @@ default_tasks =
 task default: default_tasks
 
 desc 'update semantic conventions'
-task generate: %i[update_gem_version generate_semconv generate_require_rollups rubocop_autocorrect]
+task generate: %i[update_spec_version_constant generate_semconv generate_require_rollups rubocop_autocorrect]
 
 SPEC_VERSION = '1.37.0'
 OTEL_WEAVER_VERSION = 'v0.17.1'
@@ -125,8 +125,9 @@ task generate_require_rollups: %i[generate_semconv] do
 end
 
 desc 'Bump the semantic_conventions gem version to match the spec'
-task :update_gem_version do
-  puts "\n+++ Updating gem version to #{SPEC_VERSION}\n"
-  sh %(sed -i.bak "s/VERSION = '.*'/VERSION = '#{SPEC_VERSION}'/g" lib/opentelemetry/semantic_conventions/version.rb)
+task :update_spec_version_constant do
+  puts "\n+++ Updating library SPEC_VERSION constant to #{SPEC_VERSION}.\n"
+  puts "    ℹ️  VERSION is managed by release automation and left unchanged.\n"
+  sh %(sed -i.bak "s/SPEC_VERSION = '.*'/SPEC_VERSION = '#{SPEC_VERSION}'/g" lib/opentelemetry/semantic_conventions/version.rb)
   sh 'rm lib/opentelemetry/semantic_conventions/version.rb.bak'
 end

semantic_conventions/lib/opentelemetry/semantic_conventions/version.rb

@@ -6,6 +6,9 @@
 
 module OpenTelemetry
   module SemanticConventions
-    VERSION = '1.37.0'
+    # Version of the OpenTelemetry Semantic Conventions from which this library was generated.
+    SPEC_VERSION = '1.37.0'
+    # Release version of this gem. May not match SPEC_VERSION until gem is released after a spec update.
+    VERSION = '1.36.0'
   end
 end

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

@@ -26,70 +26,41 @@ 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'
 
       # A value that indicates whether the user is authenticated.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      # true
       ASPNETCORE_USER_IS_AUTHENTICATED = 'aspnetcore.user.is_authenticated'
 
       # @!endgroup

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

@@ -28,21 +28,13 @@ 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

semantic_conventions/lib/opentelemetry/semconv/code/attributes.rb

@@ -26,19 +26,11 @@ module CODE
       # The column number in `code.file.path` best representing the operation. It SHOULD point within the code unit named in `code.function.name`. This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Line'. This constraint is imposed to prevent redundancy and maintain data integrity.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      #   16
-      #
       CODE_COLUMN_NUMBER = 'code.column.number'
 
       # The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Function'. This constraint is imposed to prevent redundancy and maintain data integrity.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      #   /usr/local/MyApplication/content_root/app/index.php
-      #
       CODE_FILE_PATH = 'code.file.path'
 
       # The method or function fully-qualified name without arguments. The value should fit the natural representation of the language runtime, which is also likely the same used within `code.stacktrace` attribute value. This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Function'. This constraint is imposed to prevent redundancy and maintain data integrity.
@@ -60,29 +52,16 @@ module CODE
       # - C function: `fopen`
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      # com.example.MyHttpService.serveRequest
-      # GuzzleHttp\Client::transfer
-      # fopen
       CODE_FUNCTION_NAME = 'code.function.name'
 
       # The line number in `code.file.path` best representing the operation. It SHOULD point within the code unit named in `code.function.name`. This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Line'. This constraint is imposed to prevent redundancy and maintain data integrity.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      #   42
-      #
       CODE_LINE_NUMBER = 'code.line.number'
 
       # A stacktrace as a string in the natural representation for the language runtime. The representation is identical to [`exception.stacktrace`](/docs/exceptions/exceptions-spans.md#stacktrace-representation). This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Location'. This constraint is imposed to prevent redundancy and maintain data integrity.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      #   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)
-
       CODE_STACKTRACE = 'code.stacktrace'
 
       # @!endgroup

semantic_conventions/lib/opentelemetry/semconv/db/attributes.rb

@@ -36,10 +36,6 @@ module DB
       # collection name then that collection name SHOULD be used.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      # public.users
-      # customers
       DB_COLLECTION_NAME = 'db.collection.name'
 
       # The name of the database, fully qualified within the server address and port.
@@ -49,22 +45,13 @@ module DB
       # It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      # customers
-      # test.users
       DB_NAMESPACE = 'db.namespace'
 
       # The number of queries included in a batch operation.
       #
       # Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      # 2
-      # 3
-      # 4
       DB_OPERATION_BATCH_SIZE = 'db.operation.batch.size'
 
       # The name of the operation or command being executed.
@@ -85,11 +72,6 @@ module DB
       # system specific term if more applicable.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      # findAndModify
-      # HMSET
-      # SELECT
       DB_OPERATION_NAME = 'db.operation.name'
 
       # Low cardinality summary of a database query.
@@ -105,11 +87,6 @@ module DB
       # section.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      # SELECT wuser_table
-      # INSERT shipping_details SELECT orders
-      # get user by id
       DB_QUERY_SUMMARY = 'db.query.summary'
 
       # The database query being executed.
@@ -119,10 +96,6 @@ module DB
       # Parameterized query text SHOULD NOT be sanitized. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      # SELECT * FROM wuser_table where username = ?
-      # SET mykey ?
       DB_QUERY_TEXT = 'db.query.text'
 
       # Database response status code.
@@ -131,12 +104,6 @@ module DB
       # Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      # 102
-      # ORA-17002
-      # 08P01
-      # 404
       DB_RESPONSE_STATUS_CODE = 'db.response.status_code'
 
       # The name of a stored procedure within the database.
@@ -148,9 +115,6 @@ module DB
       # stored procedure name then that stored procedure name SHOULD be used.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      # GetCustomer
       DB_STORED_PROCEDURE_NAME = 'db.stored_procedure.name'
 
       # The database management system (DBMS) product as identified by the client instrumentation.

semantic_conventions/lib/opentelemetry/semconv/dotnet/attributes.rb

@@ -26,11 +26,6 @@ module DOTNET
       # Name of the garbage collector managed heap generation.
       #
       # @note Stability Level: stable
-      #
-      # @example Sample Values
-      # gen0
-      # gen1
-      # gen2
       DOTNET_GC_HEAP_GENERATION = 'dotnet.gc.heap.generation'
 
       # @!endgroup

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

@@ -46,12 +46,6 @@ 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

semantic_conventions/lib/opentelemetry/semconv/exception/attributes.rb

@@ -26,34 +26,22 @@ module EXCEPTION
       # Indicates that the exception is escaping the scope of the span.
       #
       # @note Stability Level: stable
-      # @deprecated {"note": "It's no longer recommended to record exceptions that are handled and do not escape the scope of a span.\n", "reason": "obsoleted"}
+      # @deprecated It's no longer recommended to record exceptions that are handled and do not escape the scope of a span.
       EXCEPTION_ESCAPED = 'exception.escaped'
 
       # The exception message.
       #
       # @note Stability Level: stable
-      #
-      # @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
-      #
-      # @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
-      #
-      # @example Sample Values
-      # java.net.ConnectException
-      # OSError
       EXCEPTION_TYPE = 'exception.type'
 
       # @!endgroup