stationery 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dab8be06e23e27d74ddd2ec627bc34923a79a9c0cb5fe40da55f43bdcb81e337
-  data.tar.gz: a7f90eadef2004318933e8a65cd1f86841c5b9bfc4cba8ff6191b2f96946b8e5
+  metadata.gz: bfd8cada05438bcc43cc85da2535da95b55c2dbf6020bf95607bd8ebb65c8346
+  data.tar.gz: 1115be789042eebfdd48a036fc433994694236c4c133ede893a554478b6174bf
 SHA512:
-  metadata.gz: ce40fc76233a4c6ba0ca455c9c80ac3a651832ba86ab7003c8f907b2abd8291cbe0a7421302b4a6762e876df284ebe98ed862017eaed7cb4854d609e3fa557ec
-  data.tar.gz: b1c1928f47210a8b29586f73881b8430978c644a2ea7489fab251796b7192213057a414c3145c47502fa267e3c857d5b581f91d8bf2bca394e61384844fc21d8
+  metadata.gz: 2e55c39993d7c6c7c66373f5097a8796ac655b46eabe34eb148808cca220823112a728d4c26b971c54f163dc2b6c45f50f3b6481c050089871daf5964a4011d6
+  data.tar.gz: 456ca535dc230cbc747dac22322d7a0886ea8da7f70b159bb59224a2afe211dd1cb1a6e79a2a1a7c1f7b0d2007701b465fb49434484953db010a869ae6e4ad97

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.6.0 (2026-09-28)
+
+Instrumentation, so a render shows up in AppSignal and friends, and a faster text pipeline.
+
+- Instrumentation: `Stationery.instrument` emits `render.stationery` (the whole `to_pdf`: `document:`, `pages:`, `bytes:`, `warnings:`), `build.stationery`, `paginate.stationery`, `write.stationery` (serialise, subset, deflate), `image.stationery` (each decode on a cache miss: `format:`, `width:`, `height:`, `bytes:`), `font.stationery` (`action: :parse` on a cache miss, `action: :subset` per embedded font with `glyphs:`) and `parse.stationery` (`format: :html | :markdown`). `Stationery.instrumenter` is `ActiveSupport::Notifications` when it is loaded (the Railtie pins it), so AppSignal, Skylight and log subscribers pick the events up with no setup; otherwise a no-op. Assign any object responding to `instrument(name, payload, &block)` to plug something else in. Output is unchanged.
+- `FontBook#resolve` memoises by family, weight and style instead of hashing the whole 13-field `Text::Style` on every measurement: the lookup is 4x faster and a photo-heavy 4-page document renders 22% faster.
+
 ## 0.5.0 (2026-09-27)
 
 Rotated, overlapping, cropped photos (the collage look), and fixes from the first weeks of use.

data/README.md

@@ -606,6 +606,41 @@ between the children, as for a `P` holding a `Link`) or `[type]` when empty; a
   a browser per worker; stray processes and memory are the price.
 - **Typst** is excellent but a native extension and a second template language.
 
+## Instrumentation
+
+Every render reports its phases as events named `<phase>.stationery`, so an
+APM that subscribes to `ActiveSupport::Notifications` (AppSignal, Skylight,
+Rails' own log subscribers) shows where a slow PDF spends its time with no
+setup: AppSignal groups them under "stationery" in the event tree. Outside
+Rails the events go to a null instrumenter that costs one method call.
+
+| Event | Around | Payload |
+|---|---|---|
+| `render.stationery` | the whole `to_pdf` | `document:`, `pages:`, `bytes:`, `warnings:` (count) |
+| `build.stationery` | building the component tree | `document:` |
+| `paginate.stationery` | layout, page breaks and page templates | `document:`, `pages:` |
+| `write.stationery` | serialising, subsetting and deflating | `document:`, `bytes:` |
+| `image.stationery` | decoding one image (cache misses only) | `format:`, `width:`, `height:`, `bytes:` |
+| `font.stationery` | parsing a font file (`action: :parse`, cache misses only) or subsetting one for a document (`action: :subset`, `glyphs:`) | `path:` or `font:`, `action:` |
+| `parse.stationery` | parsing an `html` or `markdown` source | `format:`, `bytes:` |
+
+Payload values known only afterwards (`pages:`, `bytes:`) are filled in
+before the event finishes, so subscribers always see them. Log every phase
+slower than 100 ms:
+
+```ruby
+ActiveSupport::Notifications.subscribe(/\.stationery\z/) do |name, start, finish, _id, payload|
+  ms = (finish - start) * 1000
+  Rails.logger.info("#{name} #{ms.round}ms #{payload.inspect}") if ms > 100
+end
+```
+
+Any object answering `instrument(name, payload) { |payload| }` can take the
+events instead (`Stationery.instrumenter = MyInstrumenter.new`), and
+`Stationery.instrument("custom.stationery", key: value) { … }` adds your own
+spans inside a document. When you hit a slow render, a trace with these
+events attached is the most useful thing to put in an issue.
+
 ## Performance
 
 `bundle exec rake bench` renders two documents with Stationery and with Prawn

data/lib/stationery/document.rb

@@ -95,21 +95,9 @@ module Stationery
 
     def to_pdf(target = nil, strict: self.class.config[:strict], debug: false, encrypt: self.class.config[:encrypt],
                tagged: self.class.config[:tagged])
-      encryption = encrypt && PDF::Encryption::StandardSecurity.new(**encrypt)
-      tagging = Tagging::Tree.new if tagged
-      warnings = Warnings.new
-      book = Fonts::FontBook.new(self.class.config[:families], fallbacks: self.class.config[:fallbacks], warnings:)
-      call(builder = Builder.new(book:, text: self.class.config[:text]))
-      resources = Resources.new
-      pages = paginate(builder.root, book:, resources:, warnings:, debug:, tagging:)
-      outline = builder.outline.resolve(Structure.resolve(pages, warnings:, resources:, book:, tagging:))
-      tagging&.audit(pages, warnings, lang: metadata[:lang])
-      @warnings = warnings
-      @fields = Forms::AcroForm.values(pages)
-      raise WarningsError, warnings if strict && warnings.any?
-
-      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:, tagging:, lang: metadata[:lang])
-      write(assembler.render, target)
+      Stationery.instrument("render.stationery", document: self.class.name) do |event|
+        write(render_pdf(event, strict:, debug:, encrypt:, tagged:), target)
+      end
     end
 
     # Used by page templates to build nodes into their own root.
@@ -130,11 +118,43 @@ module Stationery
 
     private
 
+    # The PDF bytes; `event` is the render.stationery payload it fills in.
+    def render_pdf(event, strict:, debug:, encrypt:, tagged:)
+      tagging = Tagging::Tree.new if tagged
+      warnings = Warnings.new
+      book = Fonts::FontBook.new(self.class.config[:families], fallbacks: self.class.config[:fallbacks], warnings:)
+      builder = Builder.new(book:, text: self.class.config[:text])
+      Stationery.instrument("build.stationery", document: self.class.name) { call(builder) }
+      resources = Resources.new
+      pages = paginate(builder.root, book:, resources:, warnings:, debug:, tagging:)
+      outline = builder.outline.resolve(Structure.resolve(pages, warnings:, resources:, book:, tagging:))
+      tagging&.audit(pages, warnings, lang: metadata[:lang])
+      @warnings = warnings
+      @fields = Forms::AcroForm.values(pages)
+      event[:pages] = pages.size
+      event[:warnings] = warnings.size
+      raise WarningsError, warnings if strict && warnings.any?
+
+      assemble(pages, resources, outline, encrypt:, tagging:).tap { |pdf| event[:bytes] = pdf.bytesize }
+    end
+
+    def assemble(pages, resources, outline, encrypt:, tagging:)
+      encryption = encrypt && PDF::Encryption::StandardSecurity.new(**encrypt)
+      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:, tagging:,
+                                     lang: metadata[:lang])
+      Stationery.instrument("write.stationery", document: self.class.name) do |event|
+        assembler.render.tap { |pdf| event[:bytes] = pdf.bytesize }
+      end
+    end
+
     def paginate(root, book:, resources:, warnings:, debug:, tagging:)
-      regions = Regions.new(self.class.config[:regions], measure: region_measure(book))
-      paginator = Layout::Paginator.new(resources:, page: page_options, warnings:, debug:, regions:, tagging:)
-      paginator.paginate(root).tap do |pages|
-        PageTemplates.new(self, book:, resources:, debug:, regions:, warnings:, tagging:).apply(pages)
+      Stationery.instrument("paginate.stationery", document: self.class.name) do |event|
+        regions = Regions.new(self.class.config[:regions], measure: region_measure(book))
+        paginator = Layout::Paginator.new(resources:, page: page_options, warnings:, debug:, regions:, tagging:)
+        paginator.paginate(root).tap do |pages|
+          PageTemplates.new(self, book:, resources:, debug:, regions:, warnings:, tagging:).apply(pages)
+          event[:pages] = pages.size
+        end
       end
     end
 

data/lib/stationery/fonts/font.rb

@@ -104,7 +104,11 @@ module Stationery
 
       def build(writer)
         embedding = (@ttf.cff? ? Embedding::CFF : Embedding::TrueType).new(self)
-        name, cid_font = embedding.build(writer, @used.keys.sort)
+        gids = @used.keys.sort
+        name, cid_font = Stationery.instrument("font.stationery", font: @ttf.postscript_name, action: :subset,
+                                                                  glyphs: gids.size) do
+          embedding.build(writer, gids)
+        end
 
         writer.add(
           Type: :Font, Subtype: :Type0, BaseFont: name, Encoding: :"Identity-H",

data/lib/stationery/fonts/font_book.rb

@@ -26,9 +26,14 @@ module Stationery
         @families[name.to_s] = Family.build(name, **paths)
       end
 
-      # Returns [Font, Family::Face] for a Text::Style, memoised per style.
+      # Returns [Font, Family::Face] for a Text::Style, memoised by the three
+      # fields that pick a face (family, weight, style) in nested hashes: a
+      # style's size, colour and the rest do not matter here, and hashing a
+      # 13-field Data on every text measurement did.
       def resolve(style)
-        @resolved[style] ||= begin
+        weights = (@resolved[style.family] ||= {})
+        styles = (weights[style.weight] ||= {})
+        styles[style.style] ||= begin
           face = family(style.family).face(weight: style.weight, style: style.style)
           [@fonts[face.path] ||= Font.new(Registry.load(face.path)), face].freeze
         end

data/lib/stationery/fonts/registry.rb

@@ -36,11 +36,17 @@ module Stationery
         def fetch(path, index, mtime)
           key = [path, index]
           cached_mtime, ttf = @cache.delete(key)
-          ttf = TrueType.new(File.binread(path), index:) unless cached_mtime == mtime
+          ttf = parse(path, index) unless cached_mtime == mtime
           @cache[key] = [mtime, ttf]
           @cache.shift while @cache.size > SIZE
           ttf
         end
+
+        def parse(path, index)
+          Stationery.instrument("font.stationery", path: File.basename(path), action: :parse) do
+            TrueType.new(File.binread(path), index:)
+          end
+        end
       end
     end
   end

data/lib/stationery/html/document.rb

@@ -6,6 +6,10 @@ require_relative "tree_builder"
 module Stationery
   # Lenient HTML to rich-text blocks (see Stationery::Rich).
   module HTML
-    def self.parse(source) = TreeBuilder.parse(Tokenizer.tokenize(source))
+    def self.parse(source)
+      Stationery.instrument("parse.stationery", format: :html, bytes: source.bytesize) do
+        TreeBuilder.parse(Tokenizer.tokenize(source))
+      end
+    end
   end
 end

data/lib/stationery/images/images.rb

@@ -14,7 +14,15 @@ module Stationery
     # Accepts a path, a Pathname or an IO-like object (read from its start).
     def load(source)
       data = read(source)
-      Cache.fetch(data) { parse(data) }
+      Cache.fetch(data) do
+        Stationery.instrument("image.stationery", bytes: data.bytesize) do |event|
+          parse(data).tap do |image|
+            event[:format] = image.is_a?(JPEG) ? "JPEG" : "PNG"
+            event[:width] = image.width
+            event[:height] = image.height
+          end
+        end
+      end
     end
 
     def read(source)

data/lib/stationery/instrumentation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Events a render emits, named `<phase>.stationery` so tools that group by
+  # the last segment (AppSignal, Skylight, Rails log subscribers) file them
+  # together. With ActiveSupport::Notifications loaded they go there and
+  # subscribers see the same payload the block filled in; otherwise a Null
+  # instrumenter yields and costs one method call.
+  module Instrumentation
+    class Null
+      def instrument(_name, payload = {})
+        yield payload
+      end
+    end
+
+    class << self
+      # Any object answering `instrument(name, payload) { |payload| }`; set
+      # once at boot, so a plain module attribute is enough.
+      attr_writer :instrumenter # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+
+      def instrumenter
+        @instrumenter ||= defined?(::ActiveSupport::Notifications) ? ::ActiveSupport::Notifications : Null.new # rubocop:disable ThreadSafety/ClassInstanceVariable
+      end
+
+      def instrument(name, payload = {}, &)
+        instrumenter.instrument(name, payload, &)
+      end
+    end
+  end
+
+  class << self
+    def instrumenter = Instrumentation.instrumenter
+
+    def instrumenter=(value)
+      Instrumentation.instrumenter = value
+    end
+
+    # Runs the block as one `name` event; the block may add to `payload`.
+    def instrument(name, payload = {}, &) = Instrumentation.instrument(name, payload, &)
+  end
+end

data/lib/stationery/markdown/document.rb

@@ -7,8 +7,10 @@ module Stationery
   # A CommonMark subset (plus GFM tables and strikethrough) to rich-text blocks (see Stationery::Rich).
   module Markdown
     def self.parse(source)
-      refs = {}
-      Resolver.new(refs).blocks(BlockParser.parse(source, refs))
+      Stationery.instrument("parse.stationery", format: :markdown, bytes: source.bytesize) do
+        refs = {}
+        Resolver.new(refs).blocks(BlockParser.parse(source, refs))
+      end
     end
 
     # Runs the raw text the block parser left in paragraphs, headings and cells through the inline parser.

data/lib/stationery/railtie.rb

@@ -23,6 +23,11 @@ module Stationery
       Railtie.add_renderer if app.config.stationery.renderer
     end
 
+    # Whatever the require order, a Rails app reports through ActiveSupport::Notifications.
+    initializer "stationery.instrumentation" do
+      Stationery.instrumenter = ActiveSupport::Notifications
+    end
+
     initializer "stationery.previews" do |app|
       Railtie.add_previews(app.routes) if app.config.stationery.show_previews
     end

data/lib/stationery/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stationery
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/stationery.rb

@@ -2,6 +2,7 @@
 
 require_relative "stationery/version"
 require_relative "stationery/errors"
+require_relative "stationery/instrumentation"
 require_relative "stationery/pdf/types"
 require_relative "stationery/pdf/serializer"
 require_relative "stationery/pdf/stream"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stationery
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -99,6 +99,7 @@ files:
 - lib/stationery/images/jpeg.rb
 - lib/stationery/images/png.rb
 - lib/stationery/images/scanlines.rb
+- lib/stationery/instrumentation.rb
 - lib/stationery/layout/box.rb
 - lib/stationery/layout/field.rb
 - lib/stationery/layout/flow.rb