ask-observability 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d0e28b911f472b83c6a7c93bcd632b9fe981fb39aa6a73e43dbeadc287199faa
+  data.tar.gz: 8480c74048d04b7e9cf83bfe9614d5d927bdb31865f11a5e159db2ba3ccbce26
+SHA512:
+  metadata.gz: 49f733327ed7c5c5f3c53931919c41bb7234ec2b487f0dae8d85814cfa3eb3416009cc53e2deba9901d6bb00f1991db5e1ececfed726fe02c274628c031ee65e
+  data.tar.gz: ac2fa10d43298f99c045c3136bc9c524b1f50f1c9251378907d9df69c9b8f4ee9144284faa5afa3bd6e041784f7253bdaba796232f751224901f5c28d6931baa

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# 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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-06
+
+### Added
+
+- Subscriber turning `ask-instrumentation` events into Prometheus metrics:
+  `ask_llm_calls_total`, `ask_llm_tokens_total` (input/output),
+  `ask_llm_duration_seconds` histogram, `ask_llm_errors_total`.
+- `Ask::Observability.install` (idempotent) and `uninstall` (test isolation).
+- `Ask::Observability.registry` — process registry, injectable for tests.
+- `Ask::Observability.with_context` — metadata into events AND Rails log tags.
+- `Ask::Observability::Bootstrap` — OTel SDK + OTLP exporter wiring and JSON
+  structured logging via `rails_semantic_logger`, gated by `OTEL_DISABLED`
+  and the test environment.
+- `Ask::Observability::MetricsApp` — Rack endpoint serving the registry in
+  Prometheus text format.
+- Rails railtie — auto bootstrap, auto install, `/metrics` mount; all
+  honoring `Configuration#enabled`.
+- `rails generate ask:observability:install` initializer generator.
+- Configuration: `enabled`, `service_name`, `otlp_endpoint`, `json_logging`,
+  `metrics_path`, `label_metadata` (with cardinality guardrails).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# ask-observability
+
+Prometheus metrics, OpenTelemetry bootstrap, and structured logging for the
+ask-rb ecosystem.
+
+The ask-rb observability story composes four small gems:
+
+| Gem | Job |
+|---|---|
+| `ask-instrumentation` | emits an event for every LLM operation |
+| `ask-opentelemetry` | events → OpenTelemetry **spans** |
+| **ask-observability** | events → Prometheus **metrics**, plus the OTel + logging bootstrap and `/metrics` |
+| `ask-monitoring` | events → in-app **dashboard** + alerts |
+
+`ask-observability` is the infra-observability twin of `ask-monitoring`:
+where the dashboard answers "what is the app spending?" inside the product,
+these metrics answer "is the service healthy?" in Prometheus/OpenObserve/
+Grafana, with alerting.
+
+## Installation
+
+```ruby
+gem "ask-observability"
+gem "ask-instrumentation"
+```
+
+## Quick start (plain Ruby)
+
+```ruby
+require "ask/observability"
+
+Ask::Observability.install
+```
+
+Every `Ask::Instrumentation` event now maintains:
+
+```
+ask_llm_calls_total{provider,model,kind}
+ask_llm_tokens_total{provider,model,kind,direction}
+ask_llm_duration_seconds{provider,model,kind}
+ask_llm_errors_total{provider,kind}
+```
+
+Read the registry from anywhere:
+
+```ruby
+Ask::Observability.registry
+```
+
+## Quick start (Rails)
+
+The railtie auto-installs: OpenTelemetry spans export to the OTLP collector,
+logs become JSON on stdout, `/metrics` is mounted, and the subscriber runs.
+Run the generator for a config file to tune it:
+
+```sh
+rails generate ask:observability:install
+```
+
+```ruby
+Ask::Observability.configure do |config|
+  config.service_name = "my-app"
+  config.label_metadata = [:workspace_id] # low-cardinality ONLY
+end
+```
+
+### Configuration
+
+| Option | Default | Purpose |
+|---|---|---|
+| `enabled` | `true` | master switch (set `false` in tests/CI) |
+| `service_name` | Rails app name / `"ask-app"` | `service.name` for spans and logs |
+| `otlp_endpoint` | `ENV["OTEL_EXPORTER_OTLP_ENDPOINT"]` or `http://localhost:4318/v1/traces` | OTLP/HTTP span export |
+| `json_logging` | `true` | JSON logs on stdout via `rails_semantic_logger` (skipped if the app configured its own appenders) |
+| `metrics_path` | `"/metrics"` | where `/metrics` is mounted (`nil` disables the mount) |
+| `label_metadata` | `[]` | `Ask::Instrumentation.with_metadata` keys exposed as metric labels |
+
+> **Cardinality warning:** every distinct label value creates a new time
+> series. Only configure low-cardinality metadata keys (`workspace_id`,
+> `org`, `tenant`). Never put request ids or call ids in `label_metadata`.
+> Configure before the first event — prometheus-client fixes a metric's
+> label keys at creation.
+
+### Correlating a unit of work everywhere
+
+`with_context` pushes the same metadata into instrumentation events (and
+thus spans + metrics) *and* into Rails log lines as tags:
+
+```ruby
+Ask::Observability.with_context(call_id: "abc", workspace_id: 4) do
+  # events carry call_id/workspace_id; Rails logs are tagged with them
+end
+```
+
+## Serving metrics yourself
+
+If the mounted path conflicts with your app, point `metrics_path` elsewhere
+or `nil` and mount the Rack app yourself:
+
+```ruby
+# config/routes.rb
+mount Ask::Observability::MetricsApp, at: "/ops/metrics"
+```
+
+## Disabling
+
+Set `config.enabled = false` — the subscriber, the OTel bootstrap, and the
+/metrics mount all no-op. For tests, `OTEL_DISABLED=true` (or the test
+environment) additionally skips the OpenTelemetry SDK configuration.
+
+## Development
+
+```sh
+bin/setup          # bundle install + git hooks
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/observability/bootstrap.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/string/inflections'
+
+module Ask
+  module Observability
+    # One-call runtime setup for a Rails app, mirroring what every
+    # OpenTelemetry + structured-logging app hand-rolls:
+    #
+    #   * OpenTelemetry SDK wired to the OTLP collector (spans out),
+    #     gated by OTEL_DISABLED and the test environment;
+    #   * JSON structured logs on stdout via rails_semantic_logger (when
+    #     that gem is present and the app hasn't configured appenders).
+    #
+    # The railtie calls +install+ automatically; everything can be disabled
+    # through Configuration.
+    module Bootstrap
+      module_function
+
+      # Installs both halves. Safe to call multiple times.
+      def install
+        install_otel
+        install_json_logging
+      end
+
+      # Configure the global OpenTelemetry SDK once: batch span processor
+      # exporting OTLP/HTTP to Configuration#otlp_endpoint, service name
+      # from Configuration (or the Rails app name). The host app decides
+      # which instrumentations to bundle (rack, rails, active_job, ...);
+      # +use_all+ picks up whichever are installed.
+      def install_otel
+        return if @otel_installed
+        return if ENV['OTEL_DISABLED'] == 'true'
+        # ::Rails — inside Ask::*, the bare constant resolves to the sibling
+        # Ask::Rails module when ask-rails is loaded.
+        return if defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.test?
+
+        require 'opentelemetry-sdk'
+        require 'opentelemetry-exporter-otlp'
+
+        # Absolute ::OpenTelemetry: from inside Ask::*, the bare constant
+        # would resolve to Ask::OpenTelemetry (the sibling gem) first.
+        ::OpenTelemetry::SDK.configure do |config|
+          config.service_name = service_name
+          config.add_span_processor(
+            ::OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+              ::OpenTelemetry::Exporter::OTLP::Exporter.new(endpoint: Ask::Observability.config.otlp_endpoint)
+            )
+          )
+          config.use_all if defined?(::OpenTelemetry::Instrumentation::Rack)
+        end
+        @otel_installed = true
+      rescue LoadError, StandardError => e
+        warn "[ask-observability] OpenTelemetry bootstrap skipped: #{e.class}: #{e.message}"
+      end
+
+      # JSON appender on stdout — one line per record, shippable to any
+      # log collector. Only applied when rails_semantic_logger is present
+      # and the host app hasn't declared its own appenders.
+      def install_json_logging
+        return unless Ask::Observability.config.json_logging
+        return unless defined?(::Rails) && ::Rails.respond_to?(:application)
+
+        app = ::Rails.application
+        options = app.config.rails_semantic_logger
+        return unless options
+        return if options.respond_to?(:appenders?) && options.appenders?
+
+        app.config.rails_semantic_logger.appenders do |appenders|
+          appenders.add(io: $stdout, formatter: :json)
+        end
+      end
+
+      # service.name for spans: explicit config, else the Rails app name,
+      # else a generic fallback.
+      def service_name
+        Ask::Observability.config.service_name || begin
+          if defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+            ::Rails.application.class.module_parent_name.to_s.underscore
+          else
+            'ask-app'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/observability/configuration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ask
+  module Observability
+    # Configuration for ask-observability. Set before the railtie runs
+    # (config/initializers/ask_observability.rb) so the metrics are created
+    # with their final label set — prometheus-client fixes a metric's label
+    # keys at creation time.
+    class Configuration
+      # Master switch: when false, the subscriber, the OpenTelemetry
+      # bootstrap, and the /metrics mount all no-op. Set in tests/CI to
+      # keep output clean.
+      attr_accessor :enabled
+
+      # service.name for OpenTelemetry spans and logs. Defaults to the
+      # Rails app name when running under Rails, else "ask-app".
+      attr_accessor :service_name
+
+      # OTLP/HTTP endpoint spans are exported to. Defaults to the local
+      # collector (OpenObserve reference stack).
+      attr_accessor :otlp_endpoint
+
+      # Structured JSON logs on stdout via rails_semantic_logger (applied
+      # when that gem is present and the app hasn't configured appenders).
+      attr_accessor :json_logging
+
+      # Mount path for the /metrics Rack endpoint; nil disables the mount
+      # (a host app that serves its own /metrics can point this elsewhere
+      # or nil and serve Ask::Observability.registry itself).
+      attr_accessor :metrics_path
+
+      # Metadata keys from Ask::Instrumentation.with_metadata to expose as
+      # metric labels. WARNING: every distinct value creates a new series —
+      # only use low-cardinality keys (workspace_id, org, tenant), never
+      # per-request ids.
+      attr_accessor :label_metadata
+
+      def initialize
+        @enabled = true
+        @service_name = nil
+        @otlp_endpoint = ENV.fetch('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://localhost:4318/v1/traces')
+        @json_logging = true
+        @metrics_path = '/metrics'
+        @label_metadata = []
+      end
+
+      # The configured metadata keys, normalized to symbols.
+      #
+      # @return [Array<Symbol>]
+      def metadata_label_keys
+        @label_metadata.map(&:to_sym)
+      end
+    end
+  end
+end

data/lib/ask/observability/metrics.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Ask
+  module Observability
+    # Prometheus metric definitions for ask-instrumentation events.
+    #
+    # Created lazily on a registry so gems/apps that never emit events don't
+    # pay for registry entries, and so tests can inject a fresh registry.
+    # The label set is fixed at creation (prometheus-client requires stable
+    # label keys per metric) — hence the metadata keys must be configured
+    # before the metrics are first touched.
+    class Metrics
+      # Label keys every metric carries.
+      BASE_LABELS = %i[provider model kind].freeze
+
+      class << self
+        # Memoized per (registry, metadata keys) pair.
+        def for(registry, metadata_label_keys: [])
+          instances[[registry.object_id, metadata_label_keys]] ||=
+            new(registry, metadata_label_keys: metadata_label_keys)
+        end
+
+        def instances
+          @instances ||= {}
+        end
+
+        # For tests: forget every Metrics instance (fresh registries).
+        def reset!
+          instances.clear
+        end
+      end
+
+      def initialize(registry, metadata_label_keys: [])
+        @registry = registry
+        @metadata_label_keys = metadata_label_keys
+      end
+
+      # ask_llm_calls_total{provider,model,kind}
+      def calls_total
+        @calls_total ||= @registry.counter(
+          :ask_llm_calls_total,
+          docstring: 'LLM calls by provider, model, and kind',
+          labels: label_keys(:provider, :model, :kind)
+        )
+      end
+
+      # ask_llm_tokens_total{provider,model,kind,direction}
+      def tokens_total
+        @tokens_total ||= @registry.counter(
+          :ask_llm_tokens_total,
+          docstring: 'LLM tokens by provider, model, kind, and direction',
+          labels: label_keys(:provider, :model, :kind, :direction)
+        )
+      end
+
+      # ask_llm_duration_seconds{provider,model,kind}
+      def duration_seconds
+        @duration_seconds ||= @registry.histogram(
+          :ask_llm_duration_seconds,
+          docstring: 'LLM call duration in seconds',
+          labels: label_keys(:provider, :model, :kind),
+          buckets: [0.1, 0.25, 0.5, 1, 2, 4, 8, 16, 32, 64]
+        )
+      end
+
+      # ask_llm_errors_total{provider,kind}
+      def errors_total
+        @errors_total ||= @registry.counter(
+          :ask_llm_errors_total,
+          docstring: 'LLM calls that errored',
+          labels: label_keys(:provider, :kind)
+        )
+      end
+
+      private
+
+      def label_keys(*keys)
+        (keys + @metadata_label_keys).uniq
+      end
+    end
+  end
+end

data/lib/ask/observability/metrics_app.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Ask
+  module Observability
+    # Rack endpoint rendering the registry in Prometheus text format.
+    # Mounted by the railtie at Configuration#metrics_path; the collector
+    # scrapes it and ships to OpenObserve/Grafana.
+    class MetricsApp
+      def call(_env)
+        body = Prometheus::Client::Formats::Text.marshal(Ask::Observability.registry)
+        [200,
+         { 'Content-Type' => 'text/plain; version=0.0.4; charset=utf-8',
+           'Content-Length' => body.bytesize.to_s },
+         [body]]
+      end
+    end
+  end
+end

data/lib/ask/observability/railtie.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ask
+  module Observability
+    # Rails Railtie that wires ask-observability into any Rails app:
+    #
+    #   * bootstraps OpenTelemetry + JSON logging,
+    #   * installs the metrics subscriber,
+    #   * mounts the /metrics endpoint (Configuration#metrics_path).
+    #
+    # Everything honors Configuration#enabled; a host app that wants none
+    # of it sets `enabled = false` in an initializer.
+    class Railtie < ::Rails::Railtie
+      # JSON logging must be declared before rails_semantic_logger builds
+      # the logger: its +:initialize_logger+ initializer (which replaces
+      # Rails') runs in group :all and consumes the appenders config there
+      # — anything added later lands on the default colored appender.
+      initializer 'ask.observability.logging', group: :all, before: :initialize_logger do |_app|
+        next if Ask::Observability.config.enabled == false
+
+        Ask::Observability::Bootstrap.install_json_logging
+      end
+
+      initializer 'ask.observability' do |_app|
+        next if Ask::Observability.config.enabled == false
+
+        Ask::Observability::Bootstrap.install
+        Ask::Observability.install
+      end
+
+      initializer 'ask.observability.metrics' do |app|
+        path = Ask::Observability.config.metrics_path
+        next if path.nil? || Ask::Observability.config.enabled == false
+
+        app.routes.append do
+          # MetricsApp is a Rack app (instance #call), so mount an instance.
+          mount Ask::Observability::MetricsApp.new, at: path
+        end
+      end
+    end
+  end
+end

data/lib/ask/observability/subscriber.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Ask
+  module Observability
+    # Turns Ask::Instrumentation events into Prometheus metrics:
+    #
+    #   ask_llm_calls_total{provider,model,kind}
+    #   ask_llm_tokens_total{provider,model,kind,direction}
+    #   ask_llm_duration_seconds{provider,model,kind}
+    #   ask_llm_errors_total{provider,kind}
+    #
+    # Metadata attached via Ask::Instrumentation.with_metadata is merged
+    # into every event payload, so configured metadata keys (see
+    # Configuration#label_metadata) are read straight off the payload —
+    # missing values render as "unknown".
+    class Subscriber
+      # Event name → metric kind (mirrors ask-opentelemetry's span map).
+      KIND_BY_EVENT = {
+        'chat.ask' => 'chat',
+        'chat.stream.ask' => 'chat',
+        'tool.ask' => 'tool',
+        'embedding.ask' => 'embedding',
+        'image.ask' => 'image'
+      }.freeze
+
+      # Invoked by ActiveSupport::Notifications for each matching event.
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def call(event)
+        kind = KIND_BY_EVENT[event.name]
+        return unless kind
+
+        payload = event.payload
+        metrics = Ask::Observability.metrics
+        labels = base_labels(payload, kind).merge(metadata_labels(payload))
+
+        metrics.calls_total.increment(labels: labels)
+        metrics.duration_seconds.observe(event.duration / 1000.0, labels: labels)
+        record_tokens(metrics, labels, payload)
+        record_error(metrics, labels, payload) if payload[:error]
+      end
+
+      private
+
+      def base_labels(payload, kind)
+        {
+          provider: stringify(payload[:provider]),
+          model: stringify(payload[:model]),
+          kind: kind
+        }
+      end
+
+      def record_tokens(metrics, labels, payload)
+        input = payload[:input_tokens].to_i
+        output = payload[:output_tokens].to_i
+        return if input.zero? && output.zero?
+
+        metrics.tokens_total.increment(by: input, labels: labels.merge(direction: 'input')) if input.positive?
+        metrics.tokens_total.increment(by: output, labels: labels.merge(direction: 'output')) if output.positive?
+      end
+
+      def record_error(metrics, labels, _payload)
+        metrics.errors_total.increment(labels: labels.except(:model))
+      end
+
+      # Configured metadata keys present in the payload, as label values.
+      def metadata_labels(payload)
+        Ask::Observability.config.metadata_label_keys.to_h do |key|
+          [key, stringify(payload[key])]
+        end
+      end
+
+      # Prometheus label values must be strings; absent values become
+      # "unknown" so the series stays addressable.
+      def stringify(value)
+        value.to_s.empty? ? 'unknown' : value.to_s
+      end
+    end
+  end
+end

data/lib/ask/observability/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Observability
+    VERSION = '0.1.0'
+  end
+end

data/lib/ask/observability.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'ask/instrumentation'
+require 'prometheus/client'
+require 'prometheus/client/formats/text'
+
+require_relative 'observability/version'
+
+# Rails discovers gem railties only when they are required, so load the
+# railtie from the entry file once Rails itself is on the stack (the
+# documented pattern: "require my_gem/railtie if defined?(Rails::Railtie)").
+require_relative 'observability/railtie' if defined?(Rails::Railtie)
+
+module Ask
+  # Ask::Observability — Prometheus metrics, OpenTelemetry bootstrap, and
+  # structured logging for the ask-rb ecosystem.
+  #
+  # The ask-rb observability story composes:
+  #   * ask-instrumentation   — emits events for every LLM operation
+  #   * ask-opentelemetry     — events → OpenTelemetry spans
+  #   * ask-observability     — events → Prometheus metrics, plus the
+  #                             OTel/logging bootstrap and /metrics
+  #   * ask-monitoring        — events → in-app dashboard + alerts
+  #
+  # == Usage
+  #
+  #   Ask::Observability.install
+  #
+  # In a Rails app the railtie auto-installs (bootstrap + subscriber +
+  # /metrics); configure it first:
+  #
+  #   Ask::Observability.configure do |config|
+  #     config.service_name = "my-app"
+  #     config.label_metadata = [:workspace_id]
+  #   end
+  module Observability
+    autoload :Bootstrap, 'ask/observability/bootstrap'
+    autoload :Configuration, 'ask/observability/configuration'
+    autoload :Metrics, 'ask/observability/metrics'
+    autoload :MetricsApp, 'ask/observability/metrics_app'
+    autoload :Railtie, 'ask/observability/railtie'
+    autoload :Subscriber, 'ask/observability/subscriber'
+
+    class << self
+      # The process-wide configuration. Configure before install (or
+      # before the railtie runs) so metrics carry the final label set.
+      #
+      # @return [Configuration]
+      def config
+        @config ||= Configuration.new
+      end
+
+      # @yield [Configuration]
+      def configure
+        yield config
+      end
+
+      # The Prometheus registry backing every metric (and the /metrics
+      # endpoint). Tests inject a fresh registry to isolate state.
+      #
+      # @return [Prometheus::Client::Registry]
+      def registry
+        @registry ||= Prometheus::Client::Registry.new
+      end
+
+      attr_writer :registry
+
+      # Subscribe to every ask-instrumentation event and start maintaining
+      # Prometheus metrics. Idempotent — subsequent calls are no-ops.
+      def install
+        return if installed?
+        return if config.enabled == false
+
+        @subscriber = Ask::Instrumentation.subscribe(/\.ask$/, Subscriber.new)
+        @installed = true
+      end
+
+      # Remove the subscriber (tests use this to keep suites isolated).
+      def uninstall
+        return unless @subscriber
+
+        Ask::Instrumentation.unsubscribe(@subscriber)
+        @subscriber = nil
+        @installed = false
+      end
+
+      # @return [Boolean] whether the subscriber is installed
+      def installed?
+        !!@installed
+      end
+
+      # Wrap a block so the given metadata flows into ask-instrumentation
+      # events (and thus into spans and metrics) AND into Rails log lines
+      # as tags, when Rails is present. One call to correlate a unit of
+      # work — a request, a job, a call — everywhere.
+      #
+      # @param metadata [Hash] e.g. {call_id: "abc", workspace_id: 4}
+      # @yield the block to run under the context
+      # @return [Object] the block's return value
+      def with_context(metadata, &block)
+        Ask::Instrumentation.with_metadata(metadata) do
+          if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger.respond_to?(:tagged)
+            ::Rails.logger.tagged(**metadata, &block)
+          else
+            yield
+          end
+        end
+      end
+
+      # The metric definitions for the current registry.
+      #
+      # @return [Metrics]
+      def metrics
+        Metrics.for(registry, metadata_label_keys: config.metadata_label_keys)
+      end
+    end
+  end
+end

data/lib/ask-observability.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ask/observability'

data/lib/generators/ask/observability/install/templates/initializer.rb.erb

@@ -0,0 +1,29 @@
+# ask-observability configuration.
+#
+# The railtie bootstraps OpenTelemetry (spans → OTLP collector), installs
+# JSON structured logging, mounts /metrics, and subscribes to
+# ask-instrumentation events to maintain ask_llm_* Prometheus metrics.
+# Set the knobs below BEFORE boot completes so metrics get their final
+# label set.
+
+Ask::Observability.configure do |config|
+  # Master switch (useful in tests/CI).
+  # config.enabled = true
+
+  # service.name for spans and logs; defaults to the Rails app name.
+  # config.service_name = "my-app"
+
+  # OTLP/HTTP endpoint for spans (default: local OTel collector).
+  # config.otlp_endpoint = "http://localhost:4318/v1/traces"
+
+  # JSON logs on stdout via rails_semantic_logger.
+  # config.json_logging = true
+
+  # Where the /metrics endpoint is mounted (nil disables the mount).
+  # config.metrics_path = "/metrics"
+
+  # Metadata keys (from Ask::Instrumentation.with_metadata) to expose as
+  # metric labels. ONLY low-cardinality keys — every distinct value creates
+  # a new series. Never put request/call ids here.
+  # config.label_metadata = [:workspace_id]
+end

data/lib/generators/ask/observability/install_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Ask
+  module Observability
+    # Writes a config initializer so the app can tune ask-observability
+    # before the railtie runs (label metadata, service name, /metrics path).
+    #
+    #   rails generate ask:observability:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def copy_initializer
+        template 'initializer.rb.erb', 'config/initializers/ask_observability.rb'
+      end
+
+      def show_next_steps
+        say 'ask-observability installed. Configure it in ' \
+            'config/initializers/ask_observability.rb — the railtie ' \
+            'bootstraps OpenTelemetry + JSON logs, mounts /metrics, and ' \
+            'tracks ask_llm_* metrics automatically.'
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: ask-observability
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-instrumentation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: prometheus-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: Turns ask-instrumentation events into Prometheus metrics (calls, tokens,
+  duration, errors), bootstraps OpenTelemetry span export and JSON structured logging
+  for Rails apps, and serves a /metrics endpoint — the infra-observability twin of
+  ask-monitoring's in-app dashboard.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ask-observability.rb
+- lib/ask/observability.rb
+- lib/ask/observability/bootstrap.rb
+- lib/ask/observability/configuration.rb
+- lib/ask/observability/metrics.rb
+- lib/ask/observability/metrics_app.rb
+- lib/ask/observability/railtie.rb
+- lib/ask/observability/subscriber.rb
+- lib/ask/observability/version.rb
+- lib/generators/ask/observability/install/templates/initializer.rb.erb
+- lib/generators/ask/observability/install_generator.rb
+homepage: https://github.com/ask-rb/ask-observability
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-observability
+  source_code_uri: https://github.com/ask-rb/ask-observability
+  changelog_uri: https://github.com/ask-rb/ask-observability/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Prometheus metrics, OpenTelemetry, and structured logging for the ask-rb
+  ecosystem
+test_files: []