ruby_llm-instrumentation 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67942ad10a363e6e530277085f6750ea53eb547e88df806f19ddbbebef286adc
-  data.tar.gz: 4a2208687976b6744d1cbe6e19aa03d0a5bf9d080f4597ad1341e8d9cf590a4b
+  metadata.gz: 40d0077ab75737f0cc26a40df7249d3a1c0b2907504adbf753dc1b5d97dc249c
+  data.tar.gz: eb7d1694584584c1f0e9cea0fe8161e53e34e02a9f38aa6676cb2c66d7c4ae26
 SHA512:
-  metadata.gz: f9190dea5c2c5d4c8824f4e93c278a527c770204370b93a0e69d622cd09369597674ceb1dc6fa72e499b5e6858afb95a83d1582d8ed67fa9cac44b53fd94e95f
-  data.tar.gz: 254a5922c0a6fa80c8d907de2575e8d43cff803f0d4c9c1892d3285ef16159bf53abb61e73a49552345bdd83566b9837c5509327cad344cce9f99e41bfce2ddf
+  metadata.gz: 77b54c9936dc4fe603c59c1525202af80d31c317fdf9ea22fe3b04914c76c501bfbdb5ae1785a2a314ee57da65685184ddcb680d9f5c39d3e53460bd806d56bd
+  data.tar.gz: 1885dec884b5396c1ff055af82a5c40253e3339f53bd2f02c43945d6304be1176cac2d95135662627d6551ea29a5c7efe4d2d660362ad0effecbdaf7bdf013ce

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-01-20
+
+### Added
+
+- Custom metadata support via `RubyLLM::Instrumentation.with` block method. [#10](https://github.com/sinaptia/ruby_llm-instrumentation/pull/10) [@marckohlbrugge](https://github.com/marckohlbrugge)

data/README.md

@@ -20,7 +20,9 @@ Now, RubyLLM will instrument all calls to your configured LLM.
 
 ## Usage
 
-RubyLLM::Instrumentation uses ActiveSupport::Notifications to publish events. You can subscribe to these events to build custom monitoring, logging, or analytics:
+RubyLLM::Instrumentation uses ActiveSupport::Notifications to publish events. You can subscribe to these events to build custom monitoring, logging, or analytics.
+
+### Subscribing to events
 
 ```ruby
 # Subscribe to all LLM events
@@ -31,6 +33,48 @@ ActiveSupport::Notifications.subscribe(/ruby_llm/) do |name, start, finish, id,
   Rails.logger.info "Duration: #{duration}ms"
   Rails.logger.info "Input tokens: #{payload[:input_tokens]}"
   Rails.logger.info "Output tokens: #{payload[:output_tokens]}"
+  Rails.logger.info "Metadata: #{payload[:metadata]}" if payload[:metadata]
+end
+```
+
+### Metadata
+
+You can attach custom metadata to any RubyLLM call for tracking, attribution, or analytics purposes. Metadata is included in the event payload under the `metadata` key.
+
+```ruby
+# Block form - great for controller around_actions
+RubyLLM::Instrumentation.with(user_id: current_user.id, feature: "chat_assistant") do
+  RubyLLM.chat.ask("Hello")
+end
+
+# One-liners work too
+RubyLLM::Instrumentation.with(feature: "search") { RubyLLM.embed("text") }
+```
+
+The block form is particularly useful for setting request-level context:
+
+```ruby
+class ApplicationController < ActionController::Base
+  around_action :instrument_llm_calls
+
+  private
+
+  def instrument_llm_calls
+    RubyLLM::Instrumentation.with(user_id: current_user&.id, request_id: request.uuid) do
+      yield
+    end
+  end
+end
+```
+
+Nested blocks merge metadata, so you can set global context and add specific metadata per-call:
+
+```ruby
+RubyLLM::Instrumentation.with(user_id: 123) do
+  RubyLLM::Instrumentation.with(feature: "chat") do
+    RubyLLM.chat.ask("Hello")
+    # metadata: { user_id: 123, feature: "chat" }
+  end
 end
 ```
 
@@ -53,6 +97,7 @@ Triggered when `#ask` is called.
 | output_tokens         | Output tokens consumed                  |
 | cached_tokens         | Cache reads tokens (if supported)       |
 | cache_creation_tokens | Cache write tokens (if supported)       |
+| metadata              | Custom metadata hash (if provided)      |
 
 #### execute_tool.ruby_llm
 
@@ -67,6 +112,7 @@ Triggered when `#execute_tool` is called.
 | arguments | The arguments                                       |
 | chat      | The chat, a RubyLLM::Chat instance                  |
 | halted    | Indicates if the tool stopped the conversation loop |
+| metadata  | Custom metadata hash (if provided)                  |
 
 ### RubyLLM::Embedding
 
@@ -82,6 +128,7 @@ Triggered when `.embed` is called.
 | dimensions   | Number of embedding dimensions (or array of sizes if multiple) |
 | input_tokens | Input tokens consumed                                          |
 | vector_count | Number of vectors generated                                    |
+| metadata     | Custom metadata hash (if provided)                             |
 
 ### RubyLLM::Image
 
@@ -93,8 +140,9 @@ Triggered when `.paint` is called.
 | -------- | -------------------------------------------- |
 | provider | Provider slug                                |
 | size     | Image dimensions                             |
-| image    | The inage generated, a RubyLLM::Image object |
+| image    | The image generated, a RubyLLM::Image object |
 | model    | Model ID                                     |
+| metadata | Custom metadata hash (if provided)           |
 
 ### RubyLLM::Moderation
 
@@ -108,6 +156,7 @@ Triggered when `.moderate` is called.
 | moderation | The moderation, a RubyLLM::Moderation object |
 | model      | Model ID                                     |
 | flagged    | Whether the text was flagged                 |
+| metadata   | Custom metadata hash (if provided)           |
 
 ### RubyLLM::Transcription
 
@@ -123,6 +172,7 @@ Triggered when `.transcribe` is called.
 | input_tokens  | Input tokens consumed                              |
 | output_tokens | Output tokens consumed                             |
 | duration      | Audio duration in seconds (if available)           |
+| metadata      | Custom metadata hash (if provided)                 |
 
 ## Contributing
 

data/lib/ruby_llm/instrumentation/chat.rb

@@ -9,8 +9,9 @@ module RubyLLM
           raw_payload = {
             provider: @provider.slug,
             model: @model.id,
-            streaming: block_given?
-          }
+            streaming: block_given?,
+            metadata: RubyLLM::Instrumentation.current_metadata.presence
+          }.compact
 
           ActiveSupport::Notifications.instrument("complete_chat.ruby_llm", raw_payload) do |payload|
             original_complete(&).tap do |response|
@@ -32,8 +33,9 @@ module RubyLLM
             model: @model.id,
             tool_call: tool_call,
             tool_name: tool_call.name,
-            arguments: tool_call.arguments
-          }
+            arguments: tool_call.arguments,
+            metadata: RubyLLM::Instrumentation.current_metadata.presence
+          }.compact
 
           ActiveSupport::Notifications.instrument("execute_tool.ruby_llm", raw_payload) do |payload|
             original_execute_tool(tool_call).tap do |response|

data/lib/ruby_llm/instrumentation/embedding.rb

@@ -8,8 +8,9 @@ module RubyLLM
           alias_method :original_embed, :embed
           def embed(text, model: nil, provider: nil, assume_model_exists: false, context: nil, dimensions: nil)
             raw_payload = {
-              provider:
-            }
+              provider:,
+              metadata: RubyLLM::Instrumentation.current_metadata.presence
+            }.compact
 
             ActiveSupport::Notifications.instrument("embed_text.ruby_llm", raw_payload) do |payload|
               original_embed(text, model:, provider:, assume_model_exists:, context:, dimensions:).tap do |response|

data/lib/ruby_llm/instrumentation/image.rb

@@ -9,8 +9,9 @@ module RubyLLM
           def paint(prompt, model: nil, provider: nil, assume_model_exists: false, size: "1024x1024", context: nil)
             raw_payload = {
               provider:,
-              size:
-            }
+              size:,
+              metadata: RubyLLM::Instrumentation.current_metadata.presence
+            }.compact
 
             ActiveSupport::Notifications.instrument("paint_image.ruby_llm", raw_payload) do |payload|
               original_paint(prompt, model:, provider:, assume_model_exists:, size:, context:).tap do |response|

data/lib/ruby_llm/instrumentation/moderation.rb

@@ -8,8 +8,9 @@ module RubyLLM
           alias_method :original_moderate, :moderate
           def moderate(input, model: nil, provider: nil, assume_model_exists: false, context: nil)
             raw_payload = {
-              provider:
-            }
+              provider:,
+              metadata: RubyLLM::Instrumentation.current_metadata.presence
+            }.compact
 
             ActiveSupport::Notifications.instrument("moderate_text.ruby_llm", raw_payload) do |payload|
               original_moderate(input, model:, provider:, assume_model_exists:, context:).tap do |response|

data/lib/ruby_llm/instrumentation/transcription.rb

@@ -8,8 +8,9 @@ module RubyLLM
           alias_method :original_transcribe, :transcribe
           def transcribe(audio_file, **kwargs)
             raw_payload = {
-              provider: kwargs[:provider]
-            }
+              provider: kwargs[:provider],
+              metadata: RubyLLM::Instrumentation.current_metadata.presence
+            }.compact
 
             ActiveSupport::Notifications.instrument("transcribe_audio.ruby_llm", raw_payload) do |payload|
               original_transcribe(audio_file, **kwargs).tap do |response|

data/lib/ruby_llm/instrumentation/version.rb

@@ -1,5 +1,5 @@
 module RubyLLM
   module Instrumentation
-    VERSION = "0.1.1"
+    VERSION = "0.2.0"
   end
 end

data/lib/ruby_llm/instrumentation.rb

@@ -4,11 +4,27 @@ require "ruby_llm/instrumentation/railtie"
 
 module RubyLLM
   module Instrumentation
+    METADATA_KEY = :ruby_llm_instrumentation_metadata
+
     autoload :Chat, "ruby_llm/instrumentation/chat"
     autoload :Embedding, "ruby_llm/instrumentation/embedding"
     autoload :Image, "ruby_llm/instrumentation/image"
     autoload :Transcription, "ruby_llm/instrumentation/transcription"
     autoload :Moderation, "ruby_llm/instrumentation/moderation"
+
+    class << self
+      def with(metadata = {})
+        previous_metadata = Thread.current[METADATA_KEY]
+        Thread.current[METADATA_KEY] = (previous_metadata || {}).merge(metadata)
+        yield
+      ensure
+        Thread.current[METADATA_KEY] = previous_metadata
+      end
+
+      def current_metadata
+        Thread.current[METADATA_KEY] || {}
+      end
+    end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-instrumentation
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Patricio Mac Adden
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: 7.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: 7.2.0
 - !ruby/object:Gem::Dependency
   name: ruby_llm
   requirement: !ruby/object:Gem::Requirement
@@ -44,6 +44,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - README.md
 - Rakefile
 - lib/ruby_llm/instrumentation.rb
@@ -60,6 +61,7 @@ licenses: []
 metadata:
   homepage_uri: https://github.com/sinaptia/ruby_llm-instrumentation
   source_code_uri: https://github.com/sinaptia/ruby_llm-instrumentation
+  changelog_uri: https://github.com/sinaptia/ruby_llm-instrumentation/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib