rivulet-rb 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9136fe495990a216c80bd3d82b93e7677c8b32a57783aaf14ec8fe8e4030c41
-  data.tar.gz: 394d3af940cd77e33316318cd47d5b640399f3de01f7c3f1b2420395f826d7dc
+  metadata.gz: 622289122f59a270997655c87af3287273f2f16f820f7713dd95092a32cb102b
+  data.tar.gz: 99896962459012b47744e0e8466a1b691bf5bc04f5337ef44ab3039b12938296
 SHA512:
-  metadata.gz: 949131806a94fed7dd142974eae0ecf740e176c23521035ef7a16473bdb555740d4dfc1f6dd2eb2c58fd32395bef16b6ef2308b65cd52bf32f15079583b84aaf
-  data.tar.gz: 18e342d91c24f28379df3511430adb63d6cf5f1e32d9134eea658f21bce791bfbe9a2a4fda38f8b03c234388785b9b6d86454c2a611eec3a19f3c7fca50f2771
+  metadata.gz: '081156052069871b24b394ef91db773c57a9c3c1225fb52b76499f944e7d834edb0319f87211e0c53bc5d57d24e43c6d744df0455f3206a850c427c72ef0db87'
+  data.tar.gz: 25b0d8cdb73570dd48c16d5e15d8bfb371f2721e47ffff66b12d9f87c9057957629c4fc2b005c85295fd7e1c4fa2d460b0522aea2b80da67aef5ddb8c6253038

data/docs/AGENTS.md

@@ -84,7 +84,7 @@ app/
       utils/
   models/            # Sequel models
 config/
-  application.rb     # App configuration (DSN, logger, sendfile)
+  application.rb     # App configuration (DSN, logger, sendfile, telemetry)
   routes.rb          # Route definitions
 db/
   migrations/        # SQL migration files
@@ -739,3 +739,8 @@ must be self-contained SQL; there is no `drop`/`alter` safety net.
   them in the container instead.
 - Keep nesting in routes shallow and meaningful — express context, not the
   full domain hierarchy.
+- Every request is automatically timed through `Rivulet::Telemetry` (one node
+  per operation and step, plus DB timing). The tree is logged at the end of
+  each request. If `config.telemetry.sink` is set (e.g. to
+  `Rivulet::OTel::Sink.new` via `rivulet-otel setup`), the sink receives
+  callbacks for each lifecycle event. The default sink is a no-op.

data/docs/telemetry.md

@@ -0,0 +1,54 @@
+# Telemetry
+
+Rivulet includes a built-in, fiber-local telemetry system that records the
+execution flow of every request. Each `Rivulet::Operation` and `Rivulet::Step`
+is automatically timed via `Rivulet::Telemetry::TimingWrapper`, which is
+prepended into every subclass. Database queries are timed through
+`Rivulet::Telemetry::SequelExtension`. The resulting tree of nodes is logged
+at the end of each request:
+
+```
+Completed total_ms=42.3 db_ms=8.1 flow:
+Handlers::Posts::Operations::Show (2.1) =>
+  Services::Posts::Steps::LoadPost (35.4) =>
+    Services::Posts::Steps::Authorize (1.2)
+  Handlers::Posts::Steps::BuildResponse (1.1)
+```
+
+## Sink Protocol
+
+The telemetry system is extensible through a sink protocol
+(`Rivulet::Telemetry::Sink`). A sink receives callbacks for each lifecycle
+event:
+
+- `on_start(node, parent)` — called when an operation or step begins.
+- `on_stop(node)` — called when it ends, with `duration_ms` and `self_ms`
+  already computed.
+- `on_db(elapsed_ms)` — called after each database query.
+- `on_root(node, total_ms)` — called at the end of the request, after the
+  full tree is built.
+
+The default sink is `Rivulet::Telemetry::Sink::Null` (no-op). Apps configure
+a custom sink via `config.telemetry.sink` in `config/application.rb`.
+
+## OpenTelemetry
+
+Add the `rivulet-opentelemetry` gem to your application and run
+`bundle exec rivulet-otel setup` to wire in OpenTelemetry. The gem provides:
+
+- `Rivulet::OTel::Sink` — implements the sink protocol, emitting one span
+  per operation and per step, with correct parent-child nesting via a
+  fiber-local span stack. Also records metrics (request count/duration,
+  DB queries/duration, step duration) on each callback.
+- `Rivulet::OTel::Logger` — replaces the default dry-logger. Each log
+  record is emitted as a real OTel log with the current span context
+  attached (trace_id, span_id), enabling trace-to-log correlation in
+  Grafana. Logs are also written to stdout for local visibility.
+- `Rivulet::OTel.configure(service_name:)` — boots the OTel SDK with
+  traces, logs, and metrics exporters, gated on
+  `OTEL_EXPORTER_OTLP_ENDPOINT` (no-op when unset).
+
+The setup command adds a single `grafana/otel-lgtm` service to
+`docker-compose.yml` and wires in the initializer. Grafana is available at
+`http://localhost:3000` (admin/admin) with Tempo, Loki, and Prometheus
+pre-configured.

data/lib/rivulet/application.rb

@@ -74,7 +74,7 @@ module Rivulet
     private
 
     def with_telemetry
-      t = Telemetry.new
+      t = Telemetry.new(sink: config.telemetry.sink)
       Fiber[:rivulet_telemetry] = t
 
       result = yield
@@ -84,6 +84,7 @@ module Rivulet
       )
       result
     ensure
+      t&.finish
       Fiber[:rivulet_telemetry] = nil
     end
   end

data/lib/rivulet/cli/new.rb

@@ -19,6 +19,7 @@ module Rivulet
           app/services/shared/utils
           app/models
           config
+          config/initializers
           db/migrations
         ].freeze
 
@@ -100,13 +101,14 @@ module Rivulet
 
           <<~RUBY
             Rivulet.configure do |config|
+              config.app.name = name
+
               #{dsn_line}
 
               # config.sendfile.enabled   = true
               # config.sendfile.variation = 'x-accel-redirect'
               # config.sendfile.mappings   = [['/var/www/', '/files/']]
 
-              config.logger.name  = :#{name}
               config.logger.level = :info
             end
           RUBY

data/lib/rivulet/container.rb

@@ -20,6 +20,7 @@ module Rivulet
       register('load_settings')     { Rivulet::Steps::LoadSettings.new }
       register('load_db')           { Rivulet::Steps::LoadDb.new }
       register('load_routes')       { Rivulet::Steps::LoadRoutes.new }
+      register('load_initializers') { Rivulet::Steps::LoadInitializers.new }
       register('run_migrations')    { Rivulet::Steps::RunMigrations.new }
       register('run_console')       { Rivulet::Steps::RunConsole.new }
       register('print_routes')      { Rivulet::Steps::PrintRoutes.new }

data/lib/rivulet/operations/run_console.rb

@@ -2,12 +2,13 @@ module Rivulet
   module Operations
     class RunConsole < Rivulet::Operation
       include Import[
-        build_config:  'steps.build_config',
-        load_settings: 'steps.load_settings',
-        load_app:      'steps.load_app',
-        load_db:       'steps.load_db',
-        load_routes:   'steps.load_routes',
-        run_console:   'steps.run_console'
+        build_config:      'steps.build_config',
+        load_settings:     'steps.load_settings',
+        load_app:          'steps.load_app',
+        load_db:           'steps.load_db',
+        load_routes:       'steps.load_routes',
+        load_initializers: 'steps.load_initializers',
+        run_console:       'steps.run_console'
       ]
 
       def call(input = {})
@@ -16,6 +17,7 @@ module Rivulet
         result = step load_db.(result)
         result = step load_app.(result)
         result = step load_routes.(result)
+        result = step load_initializers.(result)
         result = step run_console.(result)
 
         result

data/lib/rivulet/operations/startup.rb

@@ -2,11 +2,12 @@ module Rivulet
   module Operations
     class Startup < Rivulet::Operation
       include Import[
-        build_config:  'steps.build_config',
-        load_settings: 'steps.load_settings',
-        load_app:      'steps.load_app',
-        load_db:       'steps.load_db',
-        load_routes:   'steps.load_routes'
+        build_config:      'steps.build_config',
+        load_settings:     'steps.load_settings',
+        load_app:          'steps.load_app',
+        load_db:           'steps.load_db',
+        load_routes:       'steps.load_routes',
+        load_initializers: 'steps.load_initializers'
       ]
 
       def call(input = {})
@@ -15,6 +16,7 @@ module Rivulet
         result = step load_db.(result)
         result = step load_app.(result)
         result = step load_routes.(result)
+        result = step load_initializers.(result)
 
         result
       end

data/lib/rivulet/steps/build_config.rb

@@ -2,6 +2,10 @@ module Rivulet
   module Steps
     class BuildConfig < Rivulet::Step
       def call(input)
+        Rivulet::Application.setting :app do
+          setting :name
+        end
+
         Rivulet::Application.setting :database do
           setting :dsn
           setting :pool
@@ -9,7 +13,6 @@ module Rivulet
 
         Rivulet::Application.setting :logger, reader: true do
           setting :engine
-          setting :name
           setting :level
         end
 
@@ -19,6 +22,10 @@ module Rivulet
           setting :mappings, default: []
         end
 
+        Rivulet::Application.setting :telemetry do
+          setting :sink, default: Rivulet::Telemetry::Sink::Null.new
+        end
+
         Success(input)
       end
     end

data/lib/rivulet/steps/load_db.rb

@@ -1,6 +1,11 @@
 require 'sequel'
 require_relative '../telemetry/sequel_extension'
 
+# Load globally BEFORE connecting — fiber_concurrency is a Sequel-wide extension,
+# not a per-database extension. It replaces the default connection pool with a
+# fiber-aware one that gives each fiber its own connection.
+Sequel.extension(:fiber_concurrency)
+
 module Rivulet
   module Steps
     class LoadDb < Rivulet::Step

data/lib/rivulet/steps/load_initializers.rb

@@ -0,0 +1,15 @@
+module Rivulet
+  module Steps
+    class LoadInitializers < Rivulet::Step
+      def call(input)
+        init_dir = Dir[File.expand_path('config/initializers/**/*.rb')]
+
+        init_dir.each do |init_file|
+          require init_file
+        end
+
+        Success(input)
+      end
+    end
+  end
+end

data/lib/rivulet/steps/load_settings.rb

@@ -17,7 +17,7 @@ module Rivulet
       private
 
       def default_logger(app)
-        Dry.Logger(app.config.logger.name, level: app.config.logger.level) do |setup|
+        Dry.Logger(app.config.app.name, level: app.config.logger.level) do |setup|
           setup.add_backend(
             stream: $stdout,
             log_if: :debug?,

data/lib/rivulet/telemetry/sink.rb

@@ -0,0 +1,19 @@
+module Rivulet
+  class Telemetry
+    module Sink
+      class Null
+        def on_start(node, parent)
+        end
+
+        def on_stop(node)
+        end
+
+        def on_db(elapsed_ms)
+        end
+
+        def on_root(node, total_ms)
+        end
+      end
+    end
+  end
+end

data/lib/rivulet/telemetry.rb

@@ -2,11 +2,12 @@ module Rivulet
   class Telemetry
     attr_reader :db_ms
 
-    def initialize
+    def initialize(sink:)
       @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       @root       = nil
       @stack      = []
       @db_ms      = 0.0
+      @sink       = sink
     end
 
     def start_recording(activity)
@@ -16,12 +17,15 @@ module Rivulet
         children: []
       )
 
+      parent = @stack.last
+
       if @stack.empty?
         @root = node
       else
         @stack.last[:children] << node
       end
 
+      @sink.on_start(node, parent)
       @stack << node
     end
 
@@ -32,10 +36,13 @@ module Rivulet
         ((node.ended_at - node.started_at) * 1000.0).round(3)
       node.self_ms =
         (node.duration_ms - node.children.sum(&:duration_ms)).round(3)
+
+      @sink.on_stop(node)
     end
 
     def record_db(ms)
       @db_ms = (@db_ms + ms).round(3)
+      @sink.on_db(ms)
     end
 
     def total_ms
@@ -58,5 +65,9 @@ module Rivulet
 
       entry
     end
+
+    def finish
+      @sink.on_root(@root, total_ms)
+    end
   end
 end

data/lib/rivulet/version.rb

@@ -1,3 +1,3 @@
 module Rivulet
-  VERSION = '0.2.2'
+  VERSION = '0.3.0'
 end

data/lib/rivulet.rb

@@ -17,6 +17,7 @@ require 'sequel'
 
 require_relative 'rivulet/version'
 require_relative 'rivulet/telemetry'
+require_relative 'rivulet/telemetry/sink'
 require_relative 'rivulet/telemetry/node'
 require_relative 'rivulet/telemetry/sequel_extension'
 require_relative 'rivulet/telemetry/timing_wrapper'
@@ -37,6 +38,7 @@ require_relative 'rivulet/steps/load_app'
 require_relative 'rivulet/steps/load_db'
 require_relative 'rivulet/steps/load_routes'
 require_relative 'rivulet/steps/load_settings'
+require_relative 'rivulet/steps/load_initializers'
 require_relative 'rivulet/steps/print_routes'
 require_relative 'rivulet/steps/run_migrations'
 require_relative 'rivulet/steps/run_console'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rivulet-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Vladimir Dombrovskiy <vold@fastmail.com>
@@ -219,6 +219,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -269,6 +283,7 @@ files:
 - bin/rivulet
 - docs/AGENTS.md
 - docs/architecture.md
+- docs/telemetry.md
 - lib/rivulet.rb
 - lib/rivulet/application.rb
 - lib/rivulet/cli.rb
@@ -305,6 +320,7 @@ files:
 - lib/rivulet/steps/dispatch.rb
 - lib/rivulet/steps/load_app.rb
 - lib/rivulet/steps/load_db.rb
+- lib/rivulet/steps/load_initializers.rb
 - lib/rivulet/steps/load_routes.rb
 - lib/rivulet/steps/load_settings.rb
 - lib/rivulet/steps/print_routes.rb
@@ -314,9 +330,11 @@ files:
 - lib/rivulet/telemetry.rb
 - lib/rivulet/telemetry/node.rb
 - lib/rivulet/telemetry/sequel_extension.rb
+- lib/rivulet/telemetry/sink.rb
 - lib/rivulet/telemetry/timing_wrapper.rb
 - lib/rivulet/version.rb
-licenses: []
+licenses:
+- Apache-2.0
 metadata: {}
 rdoc_options: []
 require_paths:
@@ -325,14 +343,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.19
 specification_version: 4
 summary: A small Rack web framework built on dry-rb, falcon and forced layering architecture
 test_files: []