txlemetry-ruby 4.0.0

data/lib/txlemetry/field_parser.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require 'txlemetry/logging'
+
+module Txlemetry
+  # Converts public SDK method arguments into Txlemetry API event payloads.
+  #
+  # @api private
+  class FieldParser
+    class << self
+      include Txlemetry::Utils
+      include Txlemetry::Logging
+
+      # In addition to the common fields, capture accepts:
+      #
+      # - "event"
+      # - "properties"
+      # - "groups"
+      # - "uuid"
+      # @param fields [Hash]
+      # @return [Hash]
+      def parse_for_capture(fields)
+        common = parse_common_fields(fields)
+
+        event = fields[:event]
+        properties = fields[:properties] || {}
+        groups = fields[:groups]
+        check_presence!(event, 'event')
+        check_is_hash!(properties, 'properties')
+
+        if groups
+          check_is_hash!(groups, 'groups')
+          properties['$groups'] = groups
+        end
+
+        isoify_dates! properties
+
+        common.merge(
+          {
+            type: 'capture',
+            event: event.to_s,
+            properties: properties.merge(common[:properties] || {})
+          }
+        )
+      end
+
+      # In addition to the common fields, identify accepts:
+      #
+      # - "properties"
+      # @param fields [Hash]
+      # @return [Hash]
+      def parse_for_identify(fields)
+        common = parse_common_fields(fields)
+
+        properties = fields[:properties] || {}
+        check_is_hash!(properties, 'properties')
+
+        isoify_dates! properties
+
+        common.merge(
+          {
+            type: 'identify',
+            event: '$identify',
+            '$set': properties,
+            properties: properties.merge(common[:properties] || {})
+          }
+        )
+      end
+
+      # @param fields [Hash]
+      # @return [Hash]
+      def parse_for_group_identify(fields)
+        properties = fields[:properties] || {}
+        group_type = fields[:group_type]
+        group_key = fields[:group_key]
+
+        check_presence!(group_type, 'group type')
+        check_presence!(group_key, 'group_key')
+        check_is_hash!(properties, 'properties')
+
+        fields[:distinct_id] ||= "$#{group_type}_#{group_key}"
+        common = parse_common_fields(fields)
+
+        isoify_dates! properties
+
+        common.merge(
+          {
+            event: '$groupidentify',
+            properties: (common[:properties] || {}).merge(
+              '$group_type': group_type,
+              '$group_key': group_key,
+              '$group_set': properties
+            )
+          }
+        )
+      end
+
+      # In addition to the common fields, alias accepts:
+      #
+      # - "alias"
+      # @param fields [Hash]
+      # @return [Hash]
+      def parse_for_alias(fields)
+        common = parse_common_fields(fields)
+
+        distinct_id = common[:distinct_id] # must both be set and move to properties
+
+        alias_field = fields[:alias]
+        check_presence! alias_field, 'alias'
+
+        common.merge(
+          {
+            type: 'alias',
+            event: '$create_alias',
+            distinct_id: distinct_id,
+            properties:
+              { distinct_id: distinct_id, alias: alias_field }.merge(
+                common[:properties] || {}
+              )
+          }
+        )
+      end
+
+      private
+
+      # Common fields are:
+      #
+      # - "timestamp"
+      # - "distinct_id"
+      # - "message_id" (deprecated; normalized to "uuid" when it is a valid UUID)
+      # - "send_feature_flags"
+      #
+      # A new "uuid" is generated when neither "uuid" nor "message_id" is valid.
+      def parse_common_fields(fields)
+        timestamp = fields[:timestamp] || Time.new
+        distinct_id = fields[:distinct_id]
+        send_feature_flags = fields[:send_feature_flags]
+
+        check_timestamp! timestamp
+        check_presence! distinct_id, 'distinct_id'
+
+        is_server = fields.fetch(:is_server, true) != false
+
+        properties = {
+          '$lib' => fields.fetch(:lib, 'txlemetry-ruby'),
+          '$lib_version' => fields.fetch(:lib_version, Txlemetry::VERSION.to_s)
+        }
+        properties['$is_server'] = true if is_server
+
+        parsed = {
+          timestamp: time_in_iso8601(timestamp.getutc),
+          distinct_id: distinct_id,
+          properties: properties
+        }
+
+        parsed['uuid'] = normalized_uuid(fields)
+
+        if send_feature_flags && fields[:feature_variants]
+          feature_variants = fields[:feature_variants]
+          active_feature_variants = {}
+          feature_variants.each do |key, value|
+            parsed[:properties]["$feature/#{key}"] = value
+            active_feature_variants[key] = value if value != false
+          end
+          parsed[:properties]['$active_feature_flags'] = active_feature_variants.keys
+        end
+        parsed
+      end
+
+      def check_timestamp!(timestamp)
+        return if timestamp.is_a? Time
+
+        raise ArgumentError, 'Timestamp must be a Time'
+      end
+
+      # private: Ensures that a string is non-empty
+      #
+      # obj    - String|Number that must be not blank
+      # name   - The name of the validated value
+      def check_presence!(obj, name)
+        return unless obj.nil? || (obj.is_a?(String) && obj.empty?)
+
+        raise ArgumentError, "#{name} must be given"
+      end
+
+      def check_is_hash!(obj, name)
+        raise ArgumentError, "#{name} must be a Hash" unless obj.is_a? Hash
+      end
+
+      def normalized_uuid(fields)
+        uuid = fields[:uuid]
+        return uuid if uuid && valid_uuid_for_event_props?(uuid)
+
+        message_id = fields[:message_id]
+        return message_id if message_id && valid_uuid_for_event_props?(message_id)
+
+        SecureRandom.uuid
+      end
+
+      # @param [Object] uuid - the UUID to validate, user provided, so we don't know the type
+      # @return [TrueClass, FalseClass] - true if the UUID is valid or absent, false otherwise
+      def valid_uuid_for_event_props?(uuid)
+        return true if uuid.nil?
+
+        unless uuid.is_a?(String)
+          logger.warn 'UUID is not a string. Ignoring it.'
+          return false
+        end
+
+        is_valid_uuid = uuid.match?(/^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$/i)
+        logger.warn "UUID is not valid: #{uuid}. Ignoring it." unless is_valid_uuid
+
+        is_valid_uuid
+      end
+    end
+  end
+end

data/lib/txlemetry/flag_definition_cache.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  # Interface for external caching of feature flag definitions.
+  #
+  # Enables multi-worker environments (Kubernetes, load-balanced servers,
+  # serverless functions) to share flag definitions via an external cache,
+  # reducing redundant API calls.
+  #
+  # Implement the four required methods on any object and pass it as the
+  # +:flag_definition_cache_provider+ option when creating a {Client}.
+  #
+  # == Required Methods
+  #
+  # @!method flag_definitions
+  #   Retrieve cached flag definitions. Return a Hash with +:flags+,
+  #   +:group_type_mapping+, +:cohorts+, +:minimal_flag_called_events+, and +:property_matching_version+
+  #   keys, or +nil+ if the cache is empty. Returning +nil+ triggers an API
+  #   fetch when no flags are loaded yet (emergency fallback). Providers
+  #   written before +:minimal_flag_called_events+ existed continue to work;
+  #   a missing key is treated as +false+. Preserve +:property_matching_version+
+  #   with the definitions: exactly +2+ selects explicit equality; missing/1
+  #   (including older cache entries) selects service legacy boolean matching.
+  #   A fresh entry without the version resets to legacy, even after version 2.
+  #   @return [Hash, nil]
+  #
+  # @!method should_fetch_flag_definitions?
+  #   Return +true+ if this instance should fetch new definitions from the
+  #   API, +false+ to read from cache instead. Use for distributed lock
+  #   coordination so only one worker fetches at a time.
+  #   @return [Boolean]
+  #
+  # @!method on_flag_definitions_received(data)
+  #   Called after successfully fetching new definitions from the API.
+  #   +data+ is a Hash with +:flags+, +:group_type_mapping+, +:cohorts+,
+  #   +:minimal_flag_called_events+, and +:property_matching_version+ keys
+  #   (plain Ruby types, not Concurrent:: wrappers). Store the entire snapshot
+  #   together in your external cache, including version-only updates.
+  #   @param data [Hash]
+  #   @return [void]
+  #
+  # @!method shutdown
+  #   Called when the Txlemetry client shuts down. Release any distributed
+  #   locks and clean up resources.
+  #   @return [void]
+  #
+  # == Error Handling
+  #
+  # All methods are wrapped in +begin/rescue+. Errors are logged but never
+  # break flag evaluation:
+  # - +should_fetch_flag_definitions?+ errors default to fetching (fail-safe)
+  # - +flag_definitions+ errors fall back to API fetch
+  # - +on_flag_definitions_received+ errors are logged; flags remain in memory
+  # - +shutdown+ errors are logged; shutdown continues
+  #
+  # == Example
+  #
+  #   cache = RedisFlagCache.new(redis, service_key: 'my-service')
+  #   client = Txlemetry::Client.new(
+  #     api_key: '<project_api_key>',
+  #     secret_key: '<secret_key>',
+  #     flag_definition_cache_provider: cache
+  #   )
+  #
+  module FlagDefinitionCacheProvider
+    REQUIRED_METHODS = %i[
+      flag_definitions
+      should_fetch_flag_definitions?
+      on_flag_definitions_received
+      shutdown
+    ].freeze
+
+    # Validates that +provider+ implements all required methods.
+    # Raises +ArgumentError+ listing any missing methods.
+    #
+    # @param provider [Object] the cache provider to validate
+    # @raise [ArgumentError] if any required methods are missing
+    # @return [void]
+    def self.validate!(provider)
+      missing = REQUIRED_METHODS.reject { |m| provider.respond_to?(m) }
+      return if missing.empty?
+
+      raise ArgumentError,
+            "Flag definition cache provider is missing required methods: #{missing.join(', ')}. " \
+            'See Txlemetry::FlagDefinitionCacheProvider for the required interface.'
+    end
+  end
+end

data/lib/txlemetry/internal/context.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  module Internal
+    # Internal request/fiber-local context applied to capture calls.
+    # Uses Rails' isolated execution state when available, otherwise falls back
+    # to thread-local storage in the core SDK.
+    #
+    # This is intentionally not exposed as a public SDK API in Ruby yet. It exists
+    # to let framework integrations such as txlemetry-rails propagate request-scoped
+    # tracing headers to regular capture and exception events without making the
+    # server-side SDK globally stateful per user.
+    class Context
+      STORAGE_KEY = :txlemetry_context
+
+      attr_reader :distinct_id, :session_id, :properties
+
+      def initialize(distinct_id: nil, session_id: nil, properties: {})
+        @distinct_id = distinct_id
+        @session_id = session_id
+        @properties = properties ? properties.dup : {}
+        apply_session_property!
+      end
+
+      def self.current
+        if defined?(ActiveSupport::IsolatedExecutionState)
+          ActiveSupport::IsolatedExecutionState[STORAGE_KEY]
+        else
+          Thread.current[STORAGE_KEY]
+        end
+      end
+
+      def self.current=(context)
+        if defined?(ActiveSupport::IsolatedExecutionState)
+          ActiveSupport::IsolatedExecutionState[STORAGE_KEY] = context
+        else
+          Thread.current[STORAGE_KEY] = context
+        end
+      end
+
+      def self.with_context(data = nil, fresh: false, **kwargs)
+        previous_context = current
+        raise ArgumentError, 'with_context requires a block' unless block_given?
+
+        self.current = resolve(merge_data_and_kwargs(data, kwargs), previous_context, fresh: fresh)
+        yield
+      ensure
+        self.current = previous_context
+      end
+
+      def self.resolve(data, parent, fresh: false)
+        data = normalize_data(data)
+
+        parent_properties = fresh || parent.nil? ? {} : parent.properties
+        properties = merge_properties(parent_properties, data[:properties] || {})
+        if data[:session_id] && !session_property_key?(data[:properties])
+          properties.delete('$session_id')
+          properties.delete(:$session_id)
+        end
+
+        new(
+          distinct_id: data[:distinct_id] || (fresh || parent.nil? ? nil : parent.distinct_id),
+          session_id: data[:session_id] || (fresh || parent.nil? ? nil : parent.session_id),
+          properties: properties
+        )
+      end
+      private_class_method :resolve
+
+      def self.merge_data_and_kwargs(data, kwargs)
+        data ||= {}
+        raise ArgumentError, 'context data must be a Hash' unless data.is_a?(Hash)
+
+        data.merge(kwargs)
+      end
+      private_class_method :merge_data_and_kwargs
+
+      def self.merge_properties(base, overrides)
+        merged = (base || {}).dup
+        (overrides || {}).each do |key, value|
+          merged.delete(key.to_s) if key.is_a?(Symbol)
+          merged.delete(key.to_sym) if key.is_a?(String)
+          merged[key] = value
+        end
+        merged
+      end
+
+      def self.normalize_data(data)
+        data ||= {}
+        raise ArgumentError, 'context data must be a Hash' unless data.is_a?(Hash)
+
+        properties = data[:properties] || data['properties'] || {}
+        raise ArgumentError, 'context properties must be a Hash' unless properties.is_a?(Hash)
+
+        {
+          distinct_id: data[:distinct_id] || data['distinct_id'] || data[:distinctId] || data['distinctId'],
+          session_id: data[:session_id] || data['session_id'] || data[:sessionId] || data['sessionId'],
+          properties: properties
+        }
+      end
+      private_class_method :normalize_data
+
+      def self.session_property_key?(properties)
+        return false unless properties.is_a?(Hash)
+
+        properties.key?('$session_id') || properties.key?(:$session_id)
+      end
+      private_class_method :session_property_key?
+
+      def apply_session_property!
+        return if session_id.nil? || properties.key?('$session_id') || properties.key?(:$session_id)
+
+        properties['$session_id'] = session_id
+      end
+      private :apply_session_property!
+    end
+  end
+
+  private_constant :Internal
+end

data/lib/txlemetry/logging.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Txlemetry
+  # Wraps an existing logger and adds a prefix to all messages.
+  #
+  # @api private
+  class PrefixedLogger
+    # @param logger [Logger, #debug, #info, #warn, #error]
+    # @param prefix [String]
+    def initialize(logger, prefix)
+      @logger = logger
+      @prefix = prefix
+    end
+
+    def debug(msg)
+      @logger.debug("#{@prefix} #{msg}")
+    end
+
+    def info(msg)
+      @logger.info("#{@prefix} #{msg}")
+    end
+
+    def warn(msg)
+      @logger.warn("#{@prefix} #{msg}")
+    end
+
+    def error(msg)
+      @logger.error("#{@prefix} #{msg}")
+    end
+
+    def level=(severity)
+      @logger.level = severity
+    end
+
+    def level
+      @logger.level
+    end
+  end
+
+  module Logging
+    class << self
+      # @return [Logger, Txlemetry::PrefixedLogger] The logger used by the SDK.
+      def logger
+        return @logger if @logger
+
+        base_logger =
+          if defined?(::Rails)
+            ::Rails.logger
+          else
+            logger = Logger.new $stdout
+            logger.progname = 'Txlemetry'
+            logger.level = Logger::WARN
+            logger
+          end
+        @logger = PrefixedLogger.new(base_logger, '[txlemetry-ruby]')
+      end
+
+      # @param logger [Logger, #debug, #info, #warn, #error] Custom logger used by the SDK.
+      attr_writer :logger
+    end
+
+    def self.included(base)
+      class << base
+        def logger
+          Logging.logger
+        end
+      end
+    end
+
+    # @return [Logger, Txlemetry::PrefixedLogger] The logger used by the SDK.
+    def logger
+      Logging.logger
+    end
+  end
+end

data/lib/txlemetry/mcp/README.md

@@ -0,0 +1,53 @@
+# Txlemetry MCP analytics for Ruby
+
+> **Experimental and unsupported.** `Txlemetry::MCP` is not an officially supported Txlemetry SDK: no
+> support is provided for it, and its API, options, and the captured `$mcp_*` event schema may change
+> in a minor release. A one-line warning is logged when you require it. Bug reports and patches are
+> welcome at https://github.com/Txlemetry/txlemetry-ruby/issues, but don't build production reporting on
+> it yet.
+
+Product analytics for [Model Context Protocol](https://modelcontextprotocol.io) servers built on the
+official Ruby [`mcp`](https://rubygems.org/gems/mcp) gem. Wrap an `MCP::Server` so every tool call,
+agent intent, handshake, listing, prompt, resource read, and failure is captured to Txlemetry.
+
+**Documentation: https://txlemetry.com/docs/mcp-analytics** — setup, every option, the event and
+property catalog, sessions on stateless/multi-pod servers, conversation ids, intent, identifying
+users, privacy, and custom dispatchers. That's the single source of truth; this directory
+deliberately keeps no second copy of it.
+
+Install is just `gem 'txlemetry-ruby'`. `Txlemetry::MCP.instrument` needs the `mcp` gem (`>= 1.4`) at
+runtime, but anyone wrapping a server already has it. `Txlemetry::MCP::Client` (custom dispatchers)
+needs nothing beyond `txlemetry-ruby`.
+
+## Ruby-specific notes
+
+These are the few things that differ from what the docs describe for the other SDKs.
+
+* **`$lib` is per event.** MCP events report `$lib: "txlemetry-ruby-mcp"` while the client you pass in
+  keeps its own identity (`txlemetry-ruby` or `txlemetry-rails`) for everything else it sends, so
+  instrumenting a server inside a Rails app doesn't relabel the app's other events.
+* **Truncation is tighter.** Events are truncated to fit the core client's 32KB per-message limit,
+  because txlemetry-ruby drops larger messages at batch time - truncating harder beats losing the
+  event.
+* **Request scope needs Ruby 3.2+ to be inherited.** A custom event captured from a thread or fiber
+  a tool spawns is attributed to that request on 3.2+ (fiber storage); before 3.2 capture from the
+  tool body itself, or an HTTP server falls back to a standalone session.
+* **Composed schemas are left alone.** A tool whose `input_schema` is `oneOf`/`allOf`/`anyOf` or a
+  `$ref` has nothing injected into it and nothing stripped from its calls.
+* **stdio servers own `$stdout`.** The integration's own messages go only to the `logger:` you pass
+  (default: nowhere); the experimental notice and misconfiguration warnings go to stderr. Point the
+  core SDK's logger away from stdout too: `Txlemetry::Logging.logger = Logger.new($stderr)`.
+
+## Layout
+
+| File | What it does |
+|---|---|
+| `mcp.rb` (parent dir) | `Txlemetry::MCP.instrument` and the public helpers |
+| `server_extension.rb` | Prepended onto `MCP::Server` and the Streamable HTTP transport |
+| `instrumentation.rb` | Per-request dispatch: intent, identity, sessions, recording |
+| `client.rb` | `Txlemetry::MCP::Client` for custom dispatchers |
+| `rack_middleware.rb` | `Mcp-Session-Id` tokens for a custom Rack stack |
+| `sanitization.rb`, `truncation.rb` | Redaction and payload budgets |
+
+Runnable example: [`examples/mcp_server.rb`](../../../examples/mcp_server.rb). Specs:
+`spec/txlemetry/mcp/`.

data/lib/txlemetry/mcp/analytics.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  module MCP
+    # Handle returned by {Txlemetry::MCP.instrument}. Emits custom events onto the
+    # same pipeline as the auto-captured `$mcp_*` events.
+    #
+    # @note Experimental.
+    class Analytics
+      # @api private
+      def initialize(server)
+        @server = server
+      end
+
+      # Capture a custom event scoped to the current MCP session. The event
+      # name is sent verbatim (a customer event, not `$`-prefixed).
+      #
+      # Inside a tool body the session and the identity are the ones pinned to
+      # the in-flight request by {Instrumentation}, so a concurrent request on
+      # the same session cannot reattribute this event. Over stdio, where a
+      # server only ever talks to one client, the session is the server's
+      # current one. On an HTTP server a call that has lost the request scope
+      # gets a standalone session rather than the server's, which may belong to
+      # another caller's request.
+      #
+      # @param event [String] event name
+      # @param properties [Hash] event properties
+      # @return [void]
+      # @raise [ArgumentError] when the event name is blank
+      def capture(event, properties = {})
+        unless event.is_a?(String) && !event.strip.empty?
+          raise ArgumentError, 'capture() requires an event name, e.g. analytics.capture("feedback_submitted")'
+        end
+
+        data = Txlemetry::MCP.tracking_data(@server)
+        return if data.nil?
+
+        scope = RequestScope.current
+        scope = nil unless scope.is_a?(Hash)
+        Instrumentation.capture_event(data, {
+                                        'session_id' => current_session_id(data, scope),
+                                        'event_type' => EventType::CUSTOM,
+                                        'event_name' => event,
+                                        'timestamp' => Time.now.utc,
+                                        'properties' => properties
+                                      }, actor: scoped_actor(scope))
+        nil
+      end
+
+      # Flush the underlying Txlemetry client.
+      #
+      # @return [void]
+      def flush
+        data = Txlemetry::MCP.tracking_data(@server)
+        client = data&.sink&.client
+        client.flush if client.respond_to?(:flush)
+        nil
+      end
+
+      private
+
+      # The session pinned to the in-flight request, when there is one. On a server
+      # that has served an HTTP request the server-wide session is not a safe
+      # fallback: it belongs to whichever request settled it last, which under
+      # concurrency is somebody else's. That happens when a tool hands its work to
+      # a thread or fiber it spawned on Ruby 3.0/3.1, where {RequestScope} is
+      # fiber-local and is not inherited. Fail closed with a standalone session
+      # rather than filing the event under another caller's identity; over stdio a
+      # server only ever talks to one client, so the fallback stays.
+      def current_session_id(data, scope)
+        scoped = scope ? scope[:session_id] : nil
+        return scoped if scoped
+        return data.session_id unless data.http_transport_seen
+
+        warn_unscoped_capture(data)
+        Session.new_session_id
+      end
+
+      # The identity the in-flight request resolved, which {Instrumentation} pinned
+      # on the scope before running the tool body. Absent outside a request it
+      # started, and only then is the session-keyed cache consulted instead.
+      def scoped_actor(scope)
+        scope&.key?(:actor) ? scope[:actor] : Instrumentation::UNRESOLVED_ACTOR
+      end
+
+      def warn_unscoped_capture(data)
+        return if data.warned_unscoped_capture
+
+        data.warned_unscoped_capture = true
+        Log.warn(
+          data.options,
+          'Warning: analytics.capture() ran without the scope of the request that started it, so its event got ' \
+          'a standalone $session_id instead of the caller\'s. On Ruby 3.2+ the scope follows threads and fibers ' \
+          'a tool spawns; before that it does not, so capture custom events from the tool body itself.'
+        )
+      end
+    end
+
+    # Returned when instrumentation could not be set up; every call is a no-op.
+    #
+    # @api private
+    class NoopAnalytics < Analytics
+      def initialize
+        super(nil)
+      end
+
+      def capture(_event = nil, _properties = {})
+        nil
+      end
+
+      def flush
+        nil
+      end
+    end
+  end
+end