insika 0.0.1 → 0.2.0

data/lib/insika/telemetry/pricing.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  module Telemetry
+    # Estimated cost of a turn, from a rates table given as DATA.
+    #
+    # Insika never ships prices: they change weekly, differ per contract and per
+    # region, and a stale table in the engine would be worse than no number at all.
+    # The operator declares the rates, Insika only multiplies — which is why the
+    # attribute is documented as an ESTIMATE, not a bill.
+    #
+    # Rates are **USD per million tokens** (the unit every provider publishes):
+    #
+    #   { "deepseek-v4-flash" => { "input" => 0.27, "output" => 1.10,
+    #                          "cached_input" => 0.07, "cache_write" => 0.34 } }
+    #
+    # A key matches the model id the provider reports, with or without the
+    # `provider/` prefix (`deepseek/deepseek-v4-flash` and `deepseek-v4-flash` both hit the
+    # entry above). An UNKNOWN model -> nil: a missing price is not a zero cost, so
+    # nothing is emitted and the dashboard shows a gap instead of a lie.
+    #
+    # Token accounting (matches `Executor#usage_of`, which mirrors the providers):
+    # `cached_tokens` is a SUBSET of `input_tokens`, `cache_creation_tokens` is not.
+    #   - `cached_input` given -> cached tokens are billed at that rate and
+    #     subtracted from the fresh input; absent -> they stay at the input rate.
+    #   - `cache_write` given -> cache-creation tokens billed at that rate; absent
+    #     -> at the input rate (they are input tokens the provider did write).
+    class Pricing
+      # 12 decimals: a single cheap turn can cost ~1e-6 USD, and rounding is only
+      # here to keep float noise out of the exported attribute.
+      PRECISION = 12
+
+      # rates: Hash of model id -> Hash of rate name -> USD per million tokens.
+      # Anything not shaped like that is ignored (a bad table degrades to "no cost",
+      # never to a wrong number).
+      def initialize(rates)
+        @rates = normalize(rates)
+      end
+
+      def empty? = @rates.empty?
+
+      # -> Float (USD) | nil when the model is absent/unpriced.
+      def cost(usage)
+        return nil if usage.nil?
+
+        rate = rate_for(usage[:model]) or return nil
+
+        input   = usage[:input_tokens].to_i
+        cached  = usage[:cached_tokens].to_i
+        written = usage[:cache_creation_tokens].to_i
+        output  = usage[:output_tokens].to_i
+
+        cached_rate = rate["cached_input"]
+        fresh = cached_rate ? [input - cached, 0].max : input
+
+        millionths = fresh * rate["input"].to_f +
+                     (cached_rate ? cached * cached_rate.to_f : 0.0) +
+                     written * (rate["cache_write"] || rate["input"]).to_f +
+                     output * rate["output"].to_f
+        (millionths / 1_000_000.0).round(PRECISION)
+      end
+
+      # Parses the operator's table. Accepts a JSON object; anything else (blank,
+      # malformed, not an object) -> an EMPTY Pricing, never an exception: telemetry
+      # config must not be able to stop a boot.
+      def self.parse(json)
+        return new({}) if json.nil? || json.to_s.strip.empty?
+
+        parsed = JSON.parse(json.to_s)
+        new(parsed.is_a?(Hash) ? parsed : {})
+      rescue JSON::ParserError
+        new({})
+      end
+
+      private
+
+      # Indexes each entry under BOTH spellings (full id and the part after the
+      # last "/") so a lookup is a single hash hit, never a scan.
+      def normalize(rates)
+        return {} unless rates.is_a?(Hash)
+
+        rates.each_with_object({}) do |(model, rate), acc|
+          next unless rate.is_a?(Hash)
+
+          entry = rate.transform_keys(&:to_s)
+          next unless entry["input"] || entry["output"]
+
+          key = model.to_s
+          acc[key] = entry
+          acc[key.split("/").last] ||= entry
+        end
+      end
+
+      def rate_for(model)
+        key = model.to_s
+        return nil if key.empty?
+
+        @rates[key] || @rates[key.split("/").last]
+      end
+    end
+  end
+end

data/lib/insika/telemetry/recorder.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Telemetry
+    # Translates the insika Event Stream into OTEL SPANS and METRICS — the
+    # already-existing observability spine becomes telemetry without touching the
+    # core (Events observe; Telemetry only consumes).
+    #
+    # SPANS: one per TURN (insika.turn) with child spans per tool (insika.tool /
+    # insika.data_tool), correlated by task_id. Latency is the span duration; the
+    # agent/tenant/model/tokens/cost ride as ATTRIBUTES.
+    #
+    # METRICS: the SAME events also feed counters and histograms, so
+    # volume/latency/tokens/cost are chartable WITHOUT span aggregation (which not
+    # every backend does, and none does cheaply at retention). Metric attributes are
+    # a deliberate LOW-CARDINALITY subset of the span attributes — never task_id or
+    # session_id. `meter:` nil -> spans only (the metrics SDK is optional).
+    #
+    # `pricing:` nil -> no cost attribute/metric. Cost is an ESTIMATE from an
+    # operator-declared rates table (see Pricing) — the engine ships no prices.
+    #
+    # PURE/testable: talks to a DUCK-TYPED `tracer` (start_span/set_attribute/
+    # record_error/finish) and `meter` (create_counter/create_histogram -> add/
+    # record) — the real OTEL adapters are injected in Telemetry.setup, fakes in
+    # tests. Does NOT reference OpenTelemetry:: (loads without the gem).
+    #
+    # Robust: `record` NEVER raises (telemetry doesn't bring down a turn). Timestamps
+    # come from each event's `meta.at` (spans reconstructed with real time).
+    class Recorder
+      Turn = Struct.new(:span, :tools, :labels, :start) # tools = FIFO queue of open tools
+      OpenTool = Struct.new(:span, :name, :start)
+
+      # Ceiling of open turns: a kill -9 without a terminal event would leave the turn
+      # hanging; when exceeded, the oldest is closed (defensive, bounded memory).
+      MAX_OPEN = 1_000
+
+      # The metric instruments of the convention, created once per Recorder. Names
+      # and units are part of the documented contract (docs/OBSERVABILITY.md) —
+      # renaming one breaks every dashboard built on it.
+      class Instruments
+        attr_reader :turns, :turn_duration, :tokens, :cost, :tool_calls, :tool_duration
+
+        def initialize(meter)
+          @turns = meter.create_counter("insika.turns", unit: "{turn}",
+                                                        description: "Turns completed, by outcome")
+          @turn_duration = meter.create_histogram("insika.turn.duration", unit: "s",
+                                                                         description: "Wall time of a turn")
+          @tokens = meter.create_counter("insika.tokens", unit: "{token}",
+                                                          description: "Tokens consumed, by type")
+          @cost = meter.create_counter("insika.cost", unit: "{USD}",
+                                                      description: "Estimated turn cost in USD")
+          @tool_calls = meter.create_counter("insika.tool.calls", unit: "{call}",
+                                                                  description: "Tool invocations")
+          @tool_duration = meter.create_histogram("insika.tool.duration", unit: "s",
+                                                                         description: "Wall time of a tool call")
+        end
+      end
+
+      def initialize(tracer:, meter: nil, pricing: nil)
+        @tracer = tracer
+        @instruments = meter && Instruments.new(meter)
+        @pricing = pricing
+        @turns = {}
+      end
+
+      def record(event)
+        meta = event.meta || {}
+        data = event.data || {}
+        case event.type
+        when :task_started   then start_turn(meta, data)
+        when :tool_call      then start_tool(meta, data)
+        when :tool_result    then finish_tool(meta)
+        when :data_tool_call then point_tool(meta, data)
+        when :task_completed then finish_turn(meta, data, :ok)
+        when :task_failed    then finish_turn(meta, data, :error)
+        when :task_cancelled then finish_turn(meta, data, :cancelled)
+        end
+        nil
+      rescue StandardError
+        nil # telemetry NEVER brings down the consumer/turn
+      end
+
+      private
+
+      def start_turn(meta, data)
+        id = meta[:task_id] or return
+        evict_oldest if @turns.size >= MAX_OPEN
+        at = ts(meta[:at])
+        # The metric label base: agent/tenant/command only — the low-cardinality
+        # dimensions a dashboard groups by. task_id/session_id stay on the span.
+        labels = attrs("insika.agent" => data[:agent], "insika.tenant" => data[:tenant],
+                       "insika.command" => data[:command]&.to_s)
+        span = @tracer.start_span(
+          "insika.turn", parent: nil, start_time: at,
+          attributes: labels.merge(attrs("insika.task_id" => id, "insika.session_id" => meta[:session_id]))
+        )
+        @turns[id] = Turn.new(span, [], labels, at)
+      end
+
+      def start_tool(meta, data)
+        turn = @turns[meta[:task_id]] or return
+        at = ts(meta[:at])
+        name = data[:name]&.to_s
+        span = @tracer.start_span("insika.tool", parent: turn.span, start_time: at,
+                                  attributes: attrs("insika.tool" => name))
+        turn.tools << OpenTool.new(span, name, at)
+      end
+
+      # FIFO: the model calls a tool and receives the result before the next one, so
+      # the result matches the first open tool span of the turn.
+      def finish_tool(meta)
+        turn = @turns[meta[:task_id]] or return
+        tool = turn.tools.shift or return
+        at = ts(meta[:at])
+        tool.span.finish(end_time: at)
+        count_tool(turn, tool.name, "tool", elapsed(tool.start, at))
+      end
+
+      # data-tool emits a single event (name + HTTP status) -> point span.
+      def point_tool(meta, data)
+        turn = @turns[meta[:task_id]] or return
+        at = ts(meta[:at])
+        name = data[:tool]&.to_s
+        span = @tracer.start_span("insika.data_tool", parent: turn.span, start_time: at,
+                                  attributes: attrs("insika.tool" => name,
+                                                    "insika.http.status" => data[:status]))
+        span.finish(end_time: at)
+        count_tool(turn, name, "data_tool", nil, "insika.http.status" => data[:status])
+      end
+
+      def finish_turn(meta, data, status)
+        turn = @turns.delete(meta[:task_id]) or return
+        at = ts(meta[:at])
+        usage = data[:usage]
+        set_usage(turn.span, usage)
+        turn.span.set_attribute("insika.status", status.to_s)
+        turn.span.record_error(data[:message].to_s) if status == :error
+        turn.tools.each { |t| t.span.finish(end_time: at) } # orphans (failure mid-way)
+        turn.span.finish(end_time: at)
+        count_turn(turn, usage, status.to_s, elapsed(turn.start, at))
+      end
+
+      def set_usage(span, usage)
+        return unless usage
+
+        span.set_attribute("insika.tokens.input", usage[:input_tokens]) if usage[:input_tokens]
+        span.set_attribute("insika.tokens.output", usage[:output_tokens]) if usage[:output_tokens]
+        span.set_attribute("insika.tokens.total", usage[:total_tokens]) if usage[:total_tokens]
+        span.set_attribute("insika.tokens.cached", usage[:cached_tokens]) if usage[:cached_tokens]
+        span.set_attribute("insika.tokens.cache_creation", usage[:cache_creation_tokens]) if usage[:cache_creation_tokens]
+        span.set_attribute("insika.model", usage[:model].to_s) if usage[:model]
+        span.set_attribute("insika.model_source", usage[:model_source].to_s) if usage[:model_source]
+        cost = estimated_cost(usage)
+        span.set_attribute("insika.cost.usd", cost) if cost
+      end
+
+      # --- metrics (no-op when no meter was injected) ------------------------
+
+      def count_turn(turn, usage, status, seconds)
+        return unless @instruments
+
+        model = usage && usage[:model]
+        labels = turn.labels.merge(attrs("insika.status" => status, "insika.model" => model&.to_s))
+        @instruments.turns.add(1, attributes: labels)
+        @instruments.turn_duration.record(seconds, attributes: labels) if seconds
+        count_usage(turn, usage)
+      end
+
+      # Tokens ride ONE counter split by `insika.token.type` (instead of four
+      # instruments) so a dashboard sums or splits them with the same query.
+      def count_usage(turn, usage)
+        return unless usage
+
+        base = turn.labels.merge(attrs("insika.model" => usage[:model]&.to_s))
+        { "input" => usage[:input_tokens], "output" => usage[:output_tokens],
+          "cached" => usage[:cached_tokens], "cache_creation" => usage[:cache_creation_tokens] }.each do |type, n|
+          @instruments.tokens.add(n.to_i, attributes: base.merge("insika.token.type" => type)) if n
+        end
+        cost = estimated_cost(usage)
+        @instruments.cost.add(cost, attributes: base) if cost
+      end
+
+      def count_tool(turn, name, kind, seconds, extra = {})
+        return unless @instruments
+
+        labels = turn.labels.merge(attrs({ "insika.tool" => name, "insika.tool.kind" => kind }.merge(extra)))
+        @instruments.tool_calls.add(1, attributes: labels)
+        @instruments.tool_duration.record(seconds, attributes: labels) if seconds
+      end
+
+      def estimated_cost(usage) = @pricing&.cost(usage)
+
+      # -----------------------------------------------------------------------
+
+      def evict_oldest
+        _id, turn = @turns.shift
+        return unless turn
+
+        turn.tools.each { |t| t.span.finish(end_time: nil) }
+        turn.span.set_attribute("insika.status", "abandoned")
+        turn.span.finish(end_time: nil)
+        count_turn(turn, nil, "abandoned", nil)
+      end
+
+      # OTEL doesn't accept an attribute with a nil value — drops the absent keys.
+      def attrs(hash) = hash.reject { |_, v| v.nil? }
+
+      # Seconds between two reconstructed timestamps; nil when either is unknown
+      # (a histogram must not record a made-up duration).
+      def elapsed(from, to)
+        return nil if from.nil? || to.nil?
+
+        [to - from, 0.0].max.to_f
+      end
+
+      # ISO8601 (meta.at) -> Time; nil-safe (the span uses "now" when nil).
+      def ts(at)
+        return nil if at.nil? || at.to_s.empty?
+
+        Time.parse(at.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/insika/telemetry.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "async"
+require_relative "telemetry/pricing"
+require_relative "telemetry/recorder"
+
+module Insika
+  # OPT-IN observability: OTEL mounted at the edge, core untouched. Rides
+  # the Event Stream — the Recorder consumes the events and emits spans and metrics.
+  # Off (the default) -> `setup` returns nil and nothing is loaded or instrumented
+  # (parity, zero overhead). The OTEL gems are only REQUIRED lazily in `setup`
+  # (enabled), never at core load — like ruby_llm in the Executor.
+  #
+  # Turn on: `INSIKA_OTEL=1` OR the standard OTEL envs
+  # (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_TRACES_EXPORTER`). The destination/protocol
+  # follows the OTEL SDK's default config (env) — SigNoz/Tempo/Jaeger/Collector. The
+  # OTEL_* keys are the OpenTelemetry SDK's own env and stay verbatim; only our opt-in
+  # toggle is renamed (INSIKA_OTEL, with the HARNESS_OTEL alias still read).
+  #
+  # Metrics ride the same switch and the SAME standard env: the SDK
+  # registers a periodic metric reader when the OTLP metrics exporter is loadable,
+  # and `OTEL_METRICS_EXPORTER=none` turns metrics off while traces stay on. No
+  # Insika-specific toggle is invented for it.
+  module Telemetry
+    module_function
+
+    def enabled?(env = ENV)
+      truthy(Insika::EnvSchema.read("INSIKA_OTEL", env)) ||
+        present?(env["OTEL_EXPORTER_OTLP_ENDPOINT"]) ||
+        present?(env["OTEL_TRACES_EXPORTER"])
+    end
+
+    # -> Recorder wired to the real OTEL | nil (disabled). Idempotent per process
+    # (configures the SDK once). It's the gem BOUNDARY: not covered by unit tests (like
+    # the Executor's create_chat); the Recorder's logic is tested with a fake tracer.
+    def setup(service_name: "insika", env: ENV)
+      return nil unless enabled?(env)
+
+      require "opentelemetry/sdk"
+      require "opentelemetry/exporter/otlp"
+      load_metrics_sdk
+      unless @configured
+        OpenTelemetry::SDK.configure { |c| c.service_name = service_name }
+        @configured = true
+      end
+      meter = otel_meter
+      @metrics = !meter.nil?
+      Recorder.new(tracer: OTelTracer.new(OpenTelemetry.tracer_provider.tracer("insika")),
+                   meter: meter, pricing: pricing(env))
+    end
+
+    # Did `setup` wire the metric instruments too (SDK present, at least one reader)?
+    # Only meaningful after `setup` — it exists for the boot banners.
+    def metrics? = @metrics == true
+
+    # Wires the Recorder to the Event Stream: subscribes to ALL events and feeds the
+    # recorder in a long-lived fiber (sibling of serving). Call INSIDE the reactor
+    # (serving arm). No-op if recorder is nil. -> the Subscription (or nil).
+    def attach(event_stream:, recorder:, parent: nil)
+      return nil if recorder.nil? # nil BEFORE touching the reactor (disabled path)
+
+      parent ||= Async::Task.current
+      sub = event_stream.subscribe
+      parent.async { sub.each { |e| recorder.record(e) } }
+      sub
+    end
+
+    # Operator-declared rates (USD per million tokens) as JSON in
+    # INSIKA_MODEL_PRICING. Unset/malformed -> an empty table -> no cost is reported.
+    def pricing(env = ENV)
+      table = Pricing.parse(Insika::EnvSchema.read("INSIKA_MODEL_PRICING", env))
+      table.empty? ? nil : table
+    end
+
+    # One home for "is this flag on?" — EnvSchema, which is also what validates the
+    # :boolean keys in `insika env`/doctor. A local copy is how the deployment's egress
+    # flags drifted into accepting only "1".
+    def truthy(value) = Insika::EnvSchema.truthy?(value)
+    def present?(value) = Insika::Coercion.present?(value)
+
+    # The metrics SDK is OPTIONAL: absent from the bundle -> traces only, never a
+    # boot failure. Present -> `SDK.configure` picks it up and registers the
+    # periodic reader from the standard OTEL_METRICS_* env.
+    def load_metrics_sdk
+      require "opentelemetry-metrics-sdk"
+      require "opentelemetry-exporter-otlp-metrics"
+      @metrics_sdk = true
+    rescue LoadError
+      @metrics_sdk = false
+    end
+
+    # -> the OTEL meter | nil. nil whenever nothing would drain the instruments —
+    # SDK absent, or every metric reader disabled (`OTEL_METRICS_EXPORTER=none`).
+    # Recording into a provider with no reader would accumulate a point per
+    # attribute set forever, so "no reader" MUST mean "no meter".
+    def otel_meter
+      return nil unless @metrics_sdk
+
+      provider = OpenTelemetry.meter_provider
+      return nil unless provider.respond_to?(:metric_readers) && !provider.metric_readers.empty?
+
+      provider.meter("insika")
+    end
+
+    # --- OTEL adapters (gem boundary; only instantiated after setup's require).
+    # They hide OpenTelemetry:: from the Recorder — which stays testable without the gem.
+
+    # Translates the Recorder's duck-typed contract to the OTEL tracer.
+    class OTelTracer
+      def initialize(otel) = (@otel = otel)
+
+      def start_span(name, parent:, attributes:, start_time:)
+        ctx = parent ? OpenTelemetry::Trace.context_with_span(parent.raw) : OpenTelemetry::Context.current
+        OTelSpan.new(@otel.start_span(name, with_parent: ctx, attributes: attributes, start_timestamp: start_time))
+      end
+    end
+
+    class OTelSpan
+      attr_reader :raw
+
+      def initialize(raw) = (@raw = raw)
+      def set_attribute(key, value) = @raw.set_attribute(key, value)
+      def record_error(message) = (@raw.status = OpenTelemetry::Trace::Status.error(message))
+      def finish(end_time:) = @raw.finish(end_timestamp: end_time)
+    end
+  end
+end