semconv 1.25: update in a non-breaking way

semantic_conventions/.gitignore

@@ -0,0 +1 @@
+tmp/

semantic_conventions/.rubocop.yml

@@ -26,6 +26,8 @@ Metrics/MethodLength:
 Metrics/ModuleLength:
   Enabled: false
 
+Naming/ClassAndModuleCamelCase: # because the source for generating module names isn't Rubyish enough
+  Enabled: false
 Naming/FileName:
   Exclude:
     - lib/opentelemetry-semantic_conventions.rb

semantic_conventions/.yardopts

@@ -1,9 +1,9 @@
 --no-private
 --title=OpenTelemetry Semantic Conventions
 --markup=markdown
+--markup-provider=kramdown
 --main=README.md
-./lib/opentelemetry/semantic_conventions/**/*.rb
-./lib/opentelemetry/semantic_conventions.rb
+./lib/opentelemetry/**/*.rb
 -
 README.md
 CHANGELOG.md

semantic_conventions/Rakefile

@@ -1,16 +1,29 @@
 # frozen_string_literal: true
 
+COPYRIGHT_NOTICE = <<~COPYRIGHT_NOTICE
 # 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
+COPYRIGHT_NOTICE
 
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 require 'yard'
 require 'rubocop/rake_task'
 require 'tmpdir'
-
-SPEC_VERSION = '1.10.0'
+require 'pathname'
 
 RuboCop::RakeTask.new
 
@@ -31,34 +44,78 @@ else
   task default: %i[generate test rubocop yard]
 end
 
-task :generate do
-  cwd = Dir.pwd
+task generate: %i[update_gem_version generate_semconv generate_require_rollups]
 
-  Dir.mktmpdir('opentelemetry-specification', Dir.pwd) do |tmpdir|
-    `git clone https://github.com/open-telemetry/opentelemetry-specification.git #{tmpdir}`
-    Dir.chdir(tmpdir) do
-      `git fetch`
-      `git checkout "v#{SPEC_VERSION}"`
-    end
+SPEC_VERSION = '1.26.0'
+OTEL_WEAVER_VERSION = 'v0.9.2'
+semconv_source_dir = Pathname.new('./tmp/semconvrepo')
+semconv_output_dir = Pathname.new('./lib/opentelemetry/semconv')
 
-    %w[trace resource].each do |kind|
-      cmd = %W[
-        docker run --rm
-        -v "#{tmpdir}/semantic_conventions/#{kind}":/source
-        -v "#{cwd}/templates":/templates
-        -v "#{cwd}/lib":/output
-        otel/semconvgen:0.11.1
-        -f /source code
-        --template /templates/semantic_conventions.j2
-        --output /output/opentelemetry/semantic_conventions/#{kind}.rb
-        -Dmodule=#{kind[0].upcase}#{kind[1..]}
-      ]
-
-      puts "Running: #{cmd.join(' ')}"
-      `#{cmd.join(' ')}`
-    end
+directory semconv_source_dir do
+  puts "\n+++ Cloning semantic conventions repository\n"
+  sh "git clone --tags --depth=1 --branch v#{SPEC_VERSION} https://github.com/open-telemetry/semantic-conventions.git #{semconv_source_dir}"
+end
+
+task check_out_semconv_version: [semconv_source_dir] do
+  puts "\n+++ Checking out semantic conventions version #{SPEC_VERSION}\n"
+  Dir.chdir(semconv_source_dir) do
+    sh "git fetch --depth 1 origin tag v#{SPEC_VERSION}"
+    sh "git checkout 'v#{SPEC_VERSION}'"
   end
+end
+
+task :clean_generated_code do
+  puts "\n+++ Removing previously generated semantic conventions code.\n"
+  semconv_output_dir
+    .glob('**/*.rb')
+    .then { |files| FileUtils.rm(files) }
+end
+
+task generate_semconv: %i[check_out_semconv_version clean_generated_code] do
+  puts "\n+++ Generating semantic conventions code.\n"
+  sh <<~DOCKER_COMMAND
+    docker run --rm \
+      -v "#{semconv_source_dir}/model":/source \
+      -v ./templates:/templates \
+      -v ./:/output \
+      otel/weaver:#{OTEL_WEAVER_VERSION} \
+      registry generate \
+      --registry=/source \
+      --templates=/templates \
+      ruby \
+      /output/#{semconv_output_dir}
+  DOCKER_COMMAND
+end
+
+task generate_require_rollups: %i[generate_semconv] do
+  puts "\n+++ Generating rollup/barrel files for semconv namespaces.\n"
+
+  Rake::FileList[  # find all the generated semconv files
+    semconv_output_dir + "**" + "attributes.rb",
+    semconv_output_dir + "**" + "metrics.rb",
+  ]
+    .pathmap("%d") # turn the list into the parent directories (root_namespaces)
+    .uniq          # remove duplicates
+    .each do |namespace_dir| # in each directory, write out a file to require the generated signal names
+      directory = Pathname.new(namespace_dir)
+      rollup_filename = directory.dirname + "#{directory.basename}.rb"
+      File.open(rollup_filename, "w") do |rollup|
+        rollup << <<~FILE_HEADER
+          # frozen_string_literal: true
+
+          #{COPYRIGHT_NOTICE}
+          # This file was autogenerated. Do not edit it by hand.
+
+        FILE_HEADER
+        rollup << "require_relative './#{directory.basename}/attributes.rb'\n" if File.exist?(directory + "attributes.rb")
+        rollup << "require_relative './#{directory.basename}/metrics.rb'\n" if File.exist?(directory + "metrics.rb")
+      end
+      puts "✅ Generated file \"#{rollup_filename}\""
+    end
+end
 
-  `sed -i.bak "s/VERSION = '.*'/VERSION = '#{SPEC_VERSION}'/g" lib/opentelemetry/semantic_conventions/version.rb`
-  `rm lib/opentelemetry/semantic_conventions/version.rb.bak`
+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)
+  sh 'rm lib/opentelemetry/semantic_conventions/version.rb.bak'
 end

semantic_conventions/lib/opentelemetry/semantic_conventions.rb

@@ -5,10 +5,22 @@
 # SPDX-License-Identifier: Apache-2.0
 
 module OpenTelemetry
-  # Auto-generated semantic convention constants.
+  # OpenTelemetry semantic convention attribute names as constants.
+  # These are auto-generated from source YAML in {https://github.com/open-telemetry/semantic-conventions the semantic-conventions repository}.
+  #
+  # Except for the {Resource} and {Trace} modules, constants in this namespace have been declared stable by the OpenTelemetry semantic conventions working group.
+  #
+  # @note The constants here ought to remain within major versions of this library.
+  #   However, there risk with auto-generated code.
+  #   The maintainers try to prevent constants disappearing, but we cannot gaurantee this.
+  #   We strongly recommend that any constants you use in your code are exercised in your test suite to catch missing constants before release or production runtime.
   module SemanticConventions
   end
 end
 
+# TODO: test to make sure the trace and resource constants are present in SemConv::Incubating
+# TODO: test to make sure the SemConv (stable) constants are all still present in the SemConv::Incubating constants
+# TODO: remove these convenience requires in the next major version
 require_relative 'semantic_conventions/trace'
 require_relative 'semantic_conventions/resource'
+# TODO: we're not going to add any more convenience requires here; require directly what you use