jekyll-l10n 1.5.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21d081d43cd7503f98fb38d64526397eaf5ff3164e0eb3d6525aa8d88290b9d7
-  data.tar.gz: 382bb065f52fed1d762c2cd5110afc349de73a4780d564f813e8a7be4929373b
+  metadata.gz: 6a5b62e4bb13db9fc2b93ad555425b1819c6e26aa64189c8ca31a009c55b861a
+  data.tar.gz: fe68489182fa03670d02e537366dfb25f4c85d12f233cf1f785d5cf2a8b36dac
 SHA512:
-  metadata.gz: cab0e3382f953d8f88acc764be019ccdb02bf382e65a4f227f99206e7e6c4370e4a6b158da960cf7a762e28d84765f75917ee0f351cfcd2b434aecd8d8bb8969
-  data.tar.gz: f5dc58255fd89efe2014d63e9a916d9ff3ff04d20ebf67a0d863469fd082bee7d3b399586a1f32392f78b2e4f1e6cb7c26254986faacaf0b1208a6fe5ed0c3f6
+  metadata.gz: 5a0822316cb1cb87bfb5dba17c2bdaa43c224df30b6f52157a061dc2de85432df43fa38715a7a8ffa05c68b48d282c0f727d7e64fa84491d14565272625ff998
+  data.tar.gz: 002d73f80ff7bb1ca6f2133f3d39cbc3f6ed82d2a7997b300261f1514c99aea05d30a18f9cdfa1ebe748a57f2d932cafbf2e9a79f466dbb92d18007b801e11c4

data/lib/jekyll-l10n/instrumentation.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # OpenTelemetry instrumentation facade for jekyll-l10n.
+    #
+    # All tracing is configured centrally in TRACED_METHODS — no span code lives
+    # in business logic classes. To add a span: append one entry. To rename a
+    # method: update the one entry. When a method is removed from its class the
+    # stale entry raises NoMethodError in tests, signalling the entry to delete.
+    #
+    # Requires opentelemetry-api at runtime; falls back to a no-op if absent.
+    # Users opt in to real tracing by adding opentelemetry-sdk and
+    # opentelemetry-exporter-otlp to their site Gemfile and exporting:
+    #
+    #   OTEL_SERVICE_NAME=jekyll-l10n
+    #   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+    module Instrumentation
+      TRACER_NAME = 'jekyll-l10n'
+
+      # Central instrumentation registry.
+      #
+      # Each row: [class_name, method_type, method_name, span_name, attribute_proc]
+      #
+      # method_type:
+      #   :instance  — public instance method
+      #   :private   — private instance method (visibility is preserved on the wrapper)
+      #   :class     — class / module method (prepended on the singleton class)
+      #
+      # attribute_proc: ->(span, this, args, result) or nil
+      #   span   — OTel span (or NoopSpan); call span.set_attribute after super returns
+      #   this   — receiver object (instance or nil for class methods)
+      #   args   — positional args array as passed to the method
+      #   result — return value of the original method
+      # :nocov: — attribute procs are configuration data; coverage comes from integration tests
+
+      # Helpers for common attribute patterns used inside TRACED_METHODS procs.
+      def self.hash_val(hash, key)
+        hash.is_a?(Hash) ? hash[key].to_i : 0
+      end
+
+      def self.hash_size(hash)
+        hash.is_a?(Hash) ? hash.size : 0
+      end
+
+      def self.array_size(val)
+        val.is_a?(Array) ? val.size : 0
+      end
+
+      TRACED_METHODS = [
+        # ── Jekyll integration ────────────────────────────────────────────────
+        ['Jekyll::L10n::Generator', :instance, :generate, 'l10n.generate',
+         lambda { |span, _this, args, _result|
+           span.set_attribute('l10n.site_page_count', args[0]&.pages&.size || 0)
+         }],
+
+        ['Jekyll::L10n::PostWriteProcessor', :instance, :process_localizations,
+         'l10n.post_write', nil],
+
+        # translate is the post_render hook entry point — one span per localized page
+        ['Jekyll::L10n::Translator', :instance, :translate, 'l10n.translate_render',
+         lambda { |span, this, _args, _result|
+           span.set_attribute('l10n.locale', this.page.data['locale'].to_s)
+           span.set_attribute('l10n.page_url', this.page.url.to_s)
+         }],
+
+        # ── Extraction pipeline ───────────────────────────────────────────────
+        ['Jekyll::L10n::Extractor', :instance, :extract_site, 'l10n.extract_site',
+         lambda { |span, _this, _args, result|
+           span.set_attribute('l10n.file_count', Instrumentation.hash_val(result, :files_processed))
+         }],
+
+        # process_file is the per-page body called from the html_files loop
+        ['Jekyll::L10n::Extractor', :private, :process_file, 'l10n.extract_page',
+         lambda { |span, _this, args, result|
+           span.set_attribute('l10n.page_path', args[0].to_s)
+           span.set_attribute('l10n.strings_extracted',
+                              Instrumentation.hash_val(result, :strings_extracted))
+         }],
+
+        ['Jekyll::L10n::HtmlStringExtractor', :instance, :extract, 'l10n.html_extract',
+         lambda { |span, _this, args, result|
+           span.set_attribute('l10n.html_size_bytes', args[0].bytesize)
+           span.set_attribute('l10n.extracted_count', Instrumentation.array_size(result))
+         }],
+
+        ['Jekyll::L10n::ExtractionResultSaver', :instance, :save_results, 'l10n.po_file_write',
+         lambda { |span, _this, args, result|
+           span.set_attribute('l10n.page_path', args[2].to_s)
+           span.set_attribute('l10n.entry_count', Instrumentation.array_size(args[1]))
+           span.set_attribute('l10n.po_files_created',
+                              Instrumentation.hash_val(result, :po_files_created))
+         }],
+
+        ['Jekyll::L10n::CompendiumMerger', :instance, :merge_compendia,
+         'l10n.compendium_merge', nil],
+
+        ['Jekyll::L10n::CompendiumTranslator', :instance, :translate_compendia,
+         'l10n.translate_compendia',
+         lambda { |span, _this, args, _result|
+           config = args[0]
+           span.set_attribute('l10n.locale_count', config.locales.size) if config.respond_to?(:locales)
+         }],
+
+        # ── Translation pipeline ──────────────────────────────────────────────
+        ['Jekyll::L10n::PostWriteHtmlReprocessor', :instance, :reprocess_localized_pages,
+         'l10n.reprocess_localized_pages', nil],
+
+        # translate_html_file is the per-page body called from the localized_files loop
+        ['Jekyll::L10n::PostWriteHtmlReprocessor', :private, :translate_html_file,
+         'l10n.translate_page',
+         lambda { |span, _this, args, _result|
+           span.set_attribute('l10n.page_path', args[0].to_s)
+           span.set_attribute('l10n.locale', args[1].to_s)
+         }],
+
+        ['Jekyll::L10n::PageTranslationLoader', :class, :load, 'l10n.translation_load',
+         lambda { |span, _this, args, result|
+           span.set_attribute('l10n.locale', args[1].to_s)
+           span.set_attribute('l10n.page_path', args[2].to_s)
+           span.set_attribute('l10n.entry_count', Instrumentation.hash_size(result))
+         }],
+
+        ['Jekyll::L10n::HtmlTranslator', :instance, :translate, 'l10n.dom_translate',
+         lambda { |span, this, args, _result|
+           span.set_attribute('l10n.locale', (args[2] || 'en').to_s)
+           span.set_attribute('l10n.fallback_mode', this.fallback_mode.to_s)
+         }],
+
+        ['Jekyll::L10n::LibreTranslator', :private, :make_api_request,
+         'l10n.libretranslate_batch',
+         lambda { |span, _this, args, _result|
+           span.set_attribute('l10n.locale', args[1].to_s)
+           span.set_attribute('l10n.batch_size', args[0].is_a?(Array) ? args[0].size : 1)
+         }],
+
+        # ── Utilities ─────────────────────────────────────────────────────────
+        ['Jekyll::L10n::HtmlParser', :class, :parse_document, 'l10n.html_parse',
+         lambda { |span, _this, args, _result|
+           span.set_attribute('l10n.html_size_bytes', args[0].bytesize)
+         }],
+
+        ['Jekyll::L10n::UrlTransformer', :class, :transform_document, 'l10n.url_transform',
+         lambda { |span, _this, args, _result|
+           span.set_attribute('l10n.locale', args[1].to_s)
+           doc = args[0]
+           span.set_attribute('l10n.href_count',
+                              doc.respond_to?(:css) ? doc.css('a[href]').size : 0)
+         }],
+
+        ['Jekyll::L10n::ExternalLinkIconPreserver', :class, :preserve,
+         'l10n.icon_preserve', nil],
+
+        # ── PO file operations ────────────────────────────────────────────────
+        ['Jekyll::L10n::PoFileReader', :instance, :parse_for_translation,
+         'l10n.po_file_read',
+         lambda { |span, this, _args, result|
+           span.set_attribute('l10n.file_path', this.po_path.to_s)
+           span.set_attribute('l10n.entry_count', Instrumentation.hash_size(result))
+         }],
+
+        ['Jekyll::L10n::PoFileMerger', :class, :merge_for_locale, 'l10n.po_merge',
+         lambda { |span, _this, args, result|
+           span.set_attribute('l10n.locale', args[2].to_s)
+           span.set_attribute('l10n.merged_count', Instrumentation.hash_size(result))
+         }]
+      ].freeze
+      # :nocov:
+
+      # Returns the active OTel tracer, or a no-op tracer if opentelemetry-api is absent.
+      def self.tracer
+        @tracer ||=
+          if defined?(OpenTelemetry)
+            # :nocov:
+            OpenTelemetry.tracer_provider.tracer(TRACER_NAME, Jekyll::L10n::VERSION)
+            # :nocov:
+          else
+            NoopTracer.new
+          end
+      end
+
+      # Wraps a block in an OTel span.
+      #
+      # @param span_name [String] Dot-separated span name (e.g. 'l10n.extract_page')
+      # @param attributes [Hash] Initial span attributes
+      # @yieldparam span [OpenTelemetry::Trace::Span, NoopSpan] Active span
+      # @return [Object] The return value of the block
+      def self.instrument(span_name, attributes: {}, &block)
+        tracer.in_span(span_name, attributes: attributes, &block)
+      end
+
+      # Resets the cached tracer and installation flag. Call in tests after changing OTel configuration.
+      def self.reset!
+        @tracer    = nil
+        @installed = false
+      end
+
+      # Returns true when OTel is requested via standard environment variables.
+      #
+      # install! guards on this so the prepend wrappers are only applied when
+      # a real exporter is configured. In CI and local tests (no OTel env vars)
+      # business logic classes are untouched, keeping allow_any_instance_of stubs
+      # and other RSpec mechanics fully functional.
+      def self.enabled?
+        ENV.key?('OTEL_EXPORTER_OTLP_ENDPOINT') || ENV.key?('OTEL_SERVICE_NAME')
+      end
+
+      # Installs wrappers on all classes listed in TRACED_METHODS using Module#prepend.
+      #
+      # Called once at plugin load time (end of jekyll-l10n.rb, after all requires),
+      # but only when enabled? returns true. Use OTEL_EXPORTER_OTLP_ENDPOINT or
+      # OTEL_SERVICE_NAME to activate tracing.
+      def self.install!
+        return if @installed
+
+        @installed = true
+        setup_sdk!
+        TRACED_METHODS.group_by { |e| e[0] }.each do |class_name, entries|
+          prepend_wrappers(resolve_class(class_name), entries)
+        end
+      end
+
+      # Configures the OTel SDK from standard env vars if the SDK gem is available.
+      #
+      # Called from install! so that spans are exported to the configured backend
+      # without requiring sites to add a separate initializer. Silently no-ops when
+      # opentelemetry-sdk or opentelemetry-exporter-otlp is not installed.
+      #
+      # SimpleSpanProcessor is used instead of the SDK default (BatchSpanProcessor)
+      # because Jekyll is a short-lived CLI process. BatchSpanProcessor exports on a
+      # 5-second schedule; outer spans that close last (post_write, generate) are
+      # silently dropped when the process exits before the next flush. Simple exports
+      # each span synchronously the moment it closes, guaranteeing no span loss.
+      #
+      # jekyll-theme-centos loads several instrumented plugins in one process,
+      # and OpenTelemetry::SDK.configure unconditionally overwrites the global
+      # tracer_provider on every call — so only the first plugin to reach this
+      # method (see sdk_already_configured?) actually configures the SDK; every
+      # later plugin's call becomes a no-op and reuses that provider. The
+      # at_exit and post_write hooks below are therefore registered once, by
+      # whichever plugin wins, and cover every plugin's spans, not just this one's.
+      def self.setup_sdk!
+        return if sdk_already_configured?
+
+        # :nocov:
+        require 'opentelemetry/sdk'
+        require 'opentelemetry/exporter/otlp'
+        exporter  = OpenTelemetry::Exporter::OTLP::Exporter.new
+        processor = OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(exporter)
+        OpenTelemetry::SDK.configure { |c| c.add_span_processor(processor) }
+
+        at_exit { OpenTelemetry.tracer_provider&.shutdown }
+        Jekyll::Hooks.register(:site, :post_write, priority: 0) { OpenTelemetry.tracer_provider&.force_flush }
+      rescue LoadError
+        nil
+        # :nocov:
+      end
+
+      # True when some plugin (this one or another) already installed a real
+      # SDK-backed tracer_provider, in which case setup_sdk! must not run again.
+      def self.sdk_already_configured?
+        defined?(OpenTelemetry::SDK::Trace::TracerProvider) &&
+          OpenTelemetry.tracer_provider.is_a?(OpenTelemetry::SDK::Trace::TracerProvider)
+      end
+
+      # Resolves a dot-separated class name to a constant; returns nil on NameError.
+      def self.resolve_class(name)
+        name.split('::').reduce(Object) { |m, c| m.const_get(c) }
+      rescue NameError
+        nil
+      end
+
+      # Applies instance and class-method wrappers to klass; skips if klass is nil.
+      def self.prepend_wrappers(klass, entries)
+        return unless klass
+
+        class_entries, instance_entries = entries.partition { |e| e[1] == :class }
+        klass.prepend(build_wrapper_module(instance_entries)) unless instance_entries.empty?
+        klass.singleton_class.prepend(build_wrapper_module(class_entries)) unless class_entries.empty?
+      end
+
+      # Builds an anonymous module that wraps each listed method in a span.
+      def self.build_wrapper_module(entries)
+        Module.new do
+          entries.each do |_class_name, method_type, method_name, span_name, attr_proc|
+            define_method(method_name) do |*args, **kwargs, &blk|
+              Instrumentation.instrument(span_name) do |span|
+                result = super(*args, **kwargs, &blk)
+                attr_proc&.call(span, self, args, result)
+                result
+              rescue StandardError => e
+                span.record_exception(e)
+                raise
+              end
+            end
+            private method_name if method_type == :private
+          end
+        end
+      end
+
+      private_class_method :build_wrapper_module, :prepend_wrappers, :setup_sdk!, :sdk_already_configured?
+
+      # No-op tracer used when opentelemetry-api is not loaded.
+      class NoopTracer
+        def in_span(_name, **_opts)
+          yield NoopSpan.new
+        end
+      end
+
+      # No-op span that silently accepts all attribute and event calls.
+      class NoopSpan
+        def set_attribute(*)
+          self
+        end
+
+        def record_exception(*)
+          self
+        end
+
+        def status=(*); end
+      end
+    end
+  end
+end

data/lib/jekyll-l10n/po_file/reader.rb

@@ -36,6 +36,8 @@ module Jekyll
       MSGSTR_PATTERN = /^msgstr ['"](.*)['"] *$/.freeze unless const_defined?(:MSGSTR_PATTERN)
       NO_REFERENCE = nil unless const_defined?(:NO_REFERENCE)
 
+      attr_reader :po_path
+
       # Initialize a new PoFileReader.
       #
       # Accepts either a file path (if file exists) or inline PO content. Determines

data/lib/jekyll-l10n.rb

@@ -170,6 +170,7 @@ require 'gettext/po'
 # @see Jekyll::L10n::UrlFilter for liquid filters
 
 require_relative 'jekyll-l10n/version'
+require_relative 'jekyll-l10n/instrumentation'
 require_relative 'jekyll-l10n/constants'
 require_relative 'jekyll-l10n/errors'
 require_relative 'jekyll-l10n/po_file/reader'
@@ -271,3 +272,5 @@ Jekyll::Hooks.register :site, :post_write, priority: :high do |site|
 end
 
 Liquid::Template.register_filter(Jekyll::L10n::UrlFilter)
+
+Jekyll::L10n::Instrumentation.install! if Jekyll::L10n::Instrumentation.enabled?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-l10n
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.1
 platform: ruby
 authors:
 - Alain Reguera Delgado
@@ -69,6 +69,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -230,6 +244,7 @@ files:
 - lib/jekyll-l10n/extraction/html_string_extractor.rb
 - lib/jekyll-l10n/extraction/logger.rb
 - lib/jekyll-l10n/extraction/result_saver.rb
+- lib/jekyll-l10n/instrumentation.rb
 - lib/jekyll-l10n/jekyll/generator.rb
 - lib/jekyll-l10n/jekyll/localized_page.rb
 - lib/jekyll-l10n/jekyll/post_write_html_reprocessor.rb