jekyll-link-decorator 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58e0cbaffc8dddaa356b97b7f9523197377c98862ec3398cef26b7436b69d8d1
-  data.tar.gz: 5fab208572e92de8982ed60159799b02b729f196a54ba5f0465c86dee212275a
+  metadata.gz: 7edfd6ee252b912cb6d3c30f50fcf6c0da0f0e5dc49694f3d2990ac6511e4584
+  data.tar.gz: 8cf8478f0a431f2b436356d5cd905586629bc3eea130cd777516435f9260284c
 SHA512:
-  metadata.gz: fa74e76b3aed60bd4be998dd4b227268323aabae2f00ec67d718ec71c2b04f85bb356bdea7ac8622b6d4caabbc778cff534d2796dbd06bd55989611db4760ca7
-  data.tar.gz: 233d5cde8f2bfdf617b595a2783633e37d4b3794ba3ccfd8b8e838f8c4906348c4a8cd8979f78ea543861ab648633f004bc81c18aa7b44f6cec3170585d75c4d
+  metadata.gz: 8ece38e9ce327d4c4868ff3d1273cee59abcf0b02f6e7171b4bae061c175eaec359e6a359549f2c9f534a73356f8024a4cf1141ff9b8bb7a38e5a179b55b8994
+  data.tar.gz: 3327e7a86426bc7c43931f579fa9924b30970e7a8f6ee38c2a5dbf7d2a3345e388f157e34a89fd069945d2a41513514db82bf02e7a9f8e6032ea85f44530525c

data/README.md

@@ -1,9 +1,10 @@
 # jekyll-link-decorator
 
-A Jekyll plugin that automatically enhances Markdown links with Bootstrap CSS
-classes, security attributes, Font Awesome icons, and context-aware styling.
-Simplifies link management across Jekyll sites by handling styling, external
-link protection, and icon injection without manual intervention.
+`jekyll-link-decorator` is a Jekyll plugin that automatically enhances Markdown
+links with Bootstrap CSS classes, security attributes, Font Awesome icons, and
+context-aware styling. It simplifies link management across Jekyll sites by
+handling styling, external link protection, and icon injection without manual
+intervention.
 
 ## Documentation
 

data/lib/jekyll-link-decorator/instrumentation.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module LinkDecorator
+    # OpenTelemetry instrumentation facade for jekyll-link-decorator.
+    #
+    # 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-link-decorator
+    #   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+    module Instrumentation
+      TRACER_NAME = 'jekyll-link-decorator'
+
+      # 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
+      TRACED_METHODS = [
+        # decorate_html is the converter's entry point — one span per page converted
+        ['Jekyll::Converters::LinkDecorator', :instance, :decorate_html, 'link.decorate_page',
+         lambda { |span, _this, args, result|
+           span.set_attribute('link.html_size_bytes', args[0].to_s.bytesize)
+           span.set_attribute('link.output_size_bytes', result.to_s.bytesize)
+         }],
+
+        ['Jekyll::Converters::LinkDecorator', :instance, :apply_link_styles, 'link.style_apply',
+         lambda { |span, _this, args, _result|
+           doc = args[0]
+           span.set_attribute('link.styled_link_count', doc.respond_to?(:css) ? doc.css('a:not(.btn)').size : 0)
+         }],
+
+        ['Jekyll::Converters::LinkDecorator', :instance, :add_external_link_features,
+         'link.external_link_features',
+         lambda { |span, _this, args, _result|
+           doc = args[0]
+           span.set_attribute('link.external_link_count',
+                              doc.respond_to?(:css) ? doc.css('a[target="_blank"]').size : 0)
+         }],
+
+        # add_heading_anchors is private on LinkDecorator; visibility is preserved on the wrapper
+        ['Jekyll::Converters::LinkDecorator', :private, :add_heading_anchors, 'link.heading_anchors', nil]
+      ].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::LinkDecorator::VERSION)
+            # :nocov:
+          else
+            NoopTracer.new
+          end
+      end
+
+      # Wraps a block in an OTel span.
+      #
+      # @param span_name [String] Dot-separated span name (e.g. 'link.style_apply')
+      # @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-link-decorator.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 (decorate_page) 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
+      # (jekyll-l10n uses the 'l10n.' tracer, jekyll-minify uses 'minify.'), 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-link-decorator/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module LinkDecorator
+    # Autogenerated by jekyll-link-decorator.gemspec.rb — do not edit by hand.
+    # Regenerated alongside the gemspec on every `make gemspec` run (locally
+    # or in CI), so it always matches spec.version in the built gem. Any
+    # hand edit is overwritten on the next run.
+    VERSION = '1.4.0'
+  end
+end

data/lib/jekyll-link-decorator.rb

@@ -51,7 +51,7 @@
 #   are injected. Set to true to enable.
 #
 # * `with_heading_anchor_data`: A dictionary containing optional configuration keys:
-#   - `icon`: Font Awesome icon classes (default: "fa-solid fa-link")
+#   - `icon`: Font Awesome icon classes (default: "fa-solid fa-hashtag")
 #   - `icon_size`: Font Awesome size modifier appended after icon classes (optional)
 #   - `copy_success_message`: Feedback text after copying (consumed by heading-anchor.js,
 #     default: "Copied!")
@@ -75,12 +75,14 @@
 #
 # with_heading_anchor: true
 # with_heading_anchor_data:
-#   icon: "fa-solid fa-link"
+#   icon: "fa-solid fa-hashtag"
 #   copy_success_message: "Copied!"
 #   reset_delay: 2000
 # ```
 
 require 'nokogiri'
+require_relative 'jekyll-link-decorator/version'
+require_relative 'jekyll-link-decorator/instrumentation'
 
 EXISTING_ICON_SELECTORS = [
   'i[class*="fa-external-link"]',
@@ -103,7 +105,7 @@ module Jekyll
       DEFAULT_EXTERNAL_LINK_ICON = true
       DEFAULT_EXTERNAL_LINK_ICON_EXCLUDED_TAGS = [].freeze
       DEFAULT_HEADING_ANCHOR      = false
-      DEFAULT_HEADING_ANCHOR_ICON = 'fa-solid fa-link'
+      DEFAULT_HEADING_ANCHOR_ICON = 'fa-solid fa-hashtag'
 
       def self.name
         'LinkDecorator'
@@ -381,3 +383,5 @@ module Jekyll
 end
 
 Liquid::Template.register_filter(Jekyll::Filters::LinkDecoratorFilter)
+
+Jekyll::LinkDecorator::Instrumentation.install! if Jekyll::LinkDecorator::Instrumentation.enabled?

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-link-decorator
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
-- ReleaseBot
+- Alain Reguera Delgado
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -49,6 +49,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
@@ -194,7 +208,7 @@ description: A Jekyll plugin that automatically enhances Markdown links with Boo
   Simplifies link management across Jekyll sites by handling styling, external link
   protection, and icon injection without manual intervention.
 email:
-- group_58921183_bot_c5520aeba366578e2e444dd181ff3e23@noreply.gitlab.com
+- alain.reguera@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -202,6 +216,8 @@ files:
 - LICENSE
 - README.md
 - lib/jekyll-link-decorator.rb
+- lib/jekyll-link-decorator/instrumentation.rb
+- lib/jekyll-link-decorator/version.rb
 homepage: https://gitlab.com/CentOS/artwork/centos-web/jekyll-link-decorator
 licenses:
 - MIT