octri 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b7710dbc38e8c6678e6e5a38456e0dfdf26ce8098b580e5cad6a00ed7ef210e2
+  data.tar.gz: b3496fdae687f5e386361fa122bf61d80af342a2d22a6cc239cccbc2c74fcb9c
+SHA512:
+  metadata.gz: cd2be05e16cd704c0e1118dbf477b632e764c3cc5f770f3ce6fbfb821b72d67a97ecf912b2d12ab1e15239fa247ed15947d61e830c1da0d5c7d32abd23f66893
+  data.tar.gz: 6d0783dd74030d6657e45b7c507add769195eeab6d07bf9024e4b2c79e3f4ab9dbc5b58d1228d2cfc38bc2a16790f3780a8b8579729ae46713704f44dcef3556

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Octri
+
+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,131 @@
+# octri (Ruby)
+
+**Error and performance monitoring for Ruby backends.** Report errors out of Rack
+or Rails with original-source context per stack frame, time every request and any
+sub-span you open into a waterfall, and join each server error to the client SDK
+error for the same request through the W3C `traceparent` header. In the
+dashboard you see the full client → server stack under one trace.
+
+Octri turns an OpenAPI spec into a documentation site, client SDKs for ten
+languages, an MCP server your AI assistant can call, and monitoring for the
+API behind them. This gem is the Ruby monitoring runtime, and it works on its
+own: a generated Octri API SDK is not required. See
+[octri.dev/monitoring](https://octri.dev/monitoring).
+
+Ruby 2.7 or newer. Standard library only. The Ruby sibling of
+[`@octri/node`](https://github.com/octridev/octri-node).
+
+## Install
+
+```bash
+gem install octri
+```
+
+## Setup (Rack / Rails)
+
+```ruby
+require "octri"
+require "octri/rack"
+
+Octri.init(
+  url: "https://monitoring.example.com",
+  token: ENV["OCTRI_TOKEN"],
+  environment: "<your project id>",
+  release: ENV["GIT_SHA"] # optional
+)
+
+# config.ru / Rails middleware stack:
+use Octri::Rack
+```
+
+Hosted users can copy the project-scoped URL, token, and environment from the
+Monitoring connection settings (or its API). Omit `token:` only when pointing
+at an open self-hosted ingest endpoint. Every request carries an idempotency key.
+
+## Standalone events
+
+No generated API SDK is required to send your own events:
+
+```ruby
+Octri.capture_event(
+  "checkout.completed",
+  user: { id: customer.id },
+  tags: { region: "eu-west", plan: "growth" },
+  context: { order_id: order.id, total: order.total }
+)
+```
+
+Delivery is best-effort and runs on a background thread. Pass `event_id:` to
+make a retried delivery idempotent.
+
+`Octri::Rack` captures any exception raised by the app (linked to the request's
+trace) and re-raises, and times the request as a server span.
+
+## Automatic instrumentation
+
+```ruby
+Octri.auto_instrument                            # traces outbound Net::HTTP calls
+Octri.instrument(PG::Connection, [:exec], op: "db")  # your DB client / util class, once
+Octri.instrument(cache, [:get, :set], op: "cache")
+```
+
+Every instrumented call (and every outbound HTTP request) becomes a sub-span
+under the current request — no per-call code. Calls to your monitoring backend
+are never traced (no feedback loop).
+
+## Sub-spans (where time goes)
+
+```ruby
+Octri.span("orders.list", op: "db") do
+  Order.where(status: "open").to_a
+end
+
+# or manual control:
+s = Octri.start_span("cache.get", op: "cache")
+value = cache.read(key)
+s.finish
+```
+
+`op` ("db", "cache", "http", …) color-codes the waterfall; nested `Octri.span`
+calls nest correctly.
+
+## Manual error capture
+
+```ruby
+begin
+  risky!
+rescue => e
+  Octri.capture_error(e)
+  raise
+end
+```
+
+---
+
+## The rest of Octri
+
+| Product | What it does |
+|---|---|
+| [API Studio](https://octri.dev/api-studio) | Your OpenAPI spec becomes a hosted documentation site with a live request playground, editable page by page. |
+| [SDK Studio](https://octri.dev/sdk-studio) | The same spec becomes client libraries for ten languages, versioned and released together. |
+| [MCP](https://octri.dev/mcp) | Your endpoints and docs become tools an AI assistant can call, generated from the same spec. |
+| [Monitoring](https://octri.dev/monitoring) | Errors, traces, uptime and releases for the API, joined to the SDK calls that reached it. |
+
+### Monitoring runtimes
+
+[Node](https://github.com/octridev/octri-node) ·
+[Python](https://github.com/octridev/octri-python) ·
+[Go](https://github.com/octridev/octri-go) ·
+[Ruby](https://github.com/octridev/octri-ruby) ·
+[Rust](https://github.com/octridev/octri-rust) ·
+[PHP](https://github.com/octridev/octri-php) ·
+[Java](https://github.com/octridev/octri-java) ·
+[Kotlin](https://github.com/octridev/octri-kotlin) ·
+[Swift](https://github.com/octridev/octri-swift) ·
+[Dart](https://github.com/octridev/octri-dart)
+
+[Documentation](https://docs.octri.dev/docs) ·
+[Pricing](https://octri.dev/pricing) ·
+[Changelog](https://docs.octri.dev/changelog)
+
+MIT licensed.

data/lib/octri/rack.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "octri"
+
+module Octri
+  # Rack middleware: times each request as a server span (a child of the client
+  # SDK span via the incoming `traceparent`) and reports any raised exception as
+  # an error linked to the same trace, then re-raises. Sub-spans opened with
+  # Octri.span / Octri.start_span during the request nest under it.
+  #
+  #   use Octri::Rack
+  class Rack
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      trace = Octri.trace_from_header(env["HTTP_TRACEPARENT"])
+      span_id = Octri.new_span_id
+      start = Octri.now_iso
+      prev = Octri.set_current_span(trace.trace_id, span_id)
+      method = env["REQUEST_METHOD"]
+      path = env["PATH_INFO"]
+      status = 500
+
+      begin
+        result = @app.call(env)
+        status = result[0]
+        result
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        Octri.capture_error(e, trace: trace, method: method, path: path, status_code: 500)
+        raise
+      ensure
+        Octri.reset_current_span(prev)
+        Octri.capture_span(
+          trace_id: trace.trace_id, span_id: span_id, parent_span_id: trace.parent_span_id,
+          name: "#{method} #{path}", service: "server", start_time: start,
+          end_time: Octri.now_iso, status: status.to_i >= 500 ? "error" : "ok"
+        )
+      end
+    end
+  end
+end

data/lib/octri.rb

@@ -0,0 +1,413 @@
+# frozen_string_literal: true
+
+# Octri — server-side error monitoring for Ruby backends.
+#
+# Add it to your live API; it reports backend errors to your Octri monitoring
+# project (with original-source context per stack frame) and links each one to
+# the client SDK error for the same request via the W3C `traceparent` header —
+# so the dashboard shows the full client -> server stack under one trace. It also
+# times requests (and any sub-spans you open) into the request waterfall.
+#
+#   require "octri"
+#   require "octri/rack"
+#   Octri.init(url: "https://monitoring.example.com", token: ENV["OCTRI_TOKEN"], environment: "<project id>")
+#   use Octri::Rack
+
+require "securerandom"
+require "net/http"
+require "uri"
+require "json"
+require "time"
+
+module Octri
+  Config = Struct.new(:url, :token, :environment, :release)
+  Trace = Struct.new(:trace_id, :parent_span_id)
+
+  CONTEXT_LINES = 5
+  REQUEST_TIMEOUT_SECONDS = 5
+  MAX_IDEMPOTENCY_KEY_LENGTH = 256
+  TRACEPARENT_RE = /\A00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}\z/i.freeze
+
+  class << self
+    # Configure the reporter. Call once at startup before mounting the middleware.
+    def init(url:, token: nil, environment:, release: nil)
+      @config = Config.new(url.sub(%r{/+\z}, ""), token, environment, release)
+      @source_cache = {}
+      @config
+    end
+
+    attr_reader :config
+
+    def new_span_id
+      SecureRandom.hex(8)
+    end
+
+    # ── Trace context (W3C) ──────────────────────────────────────────────────
+    def trace_from_header(traceparent)
+      if traceparent && (m = traceparent.to_s.strip.match(TRACEPARENT_RE))
+        unless all_zeros?(m[1]) || all_zeros?(m[2])
+          return Trace.new(m[1].downcase, m[2].downcase)
+        end
+        Trace.new(SecureRandom.hex(16), nil)
+      else
+        Trace.new(SecureRandom.hex(16), nil)
+      end
+    end
+
+    # ── Sub-span context (thread-local) ───────────────────────────────────────
+    def current_span
+      Thread.current[:octri_span]
+    end
+
+    def set_current_span(trace_id, span_id)
+      prev = Thread.current[:octri_span]
+      Thread.current[:octri_span] = { trace_id: trace_id, span_id: span_id }
+      prev
+    end
+
+    def reset_current_span(prev)
+      Thread.current[:octri_span] = prev
+    end
+
+    # Open a sub-span under the active request span; call #finish when done.
+    # Returns a no-op handle outside a request or before init.
+    def start_span(name, op: nil)
+      ctx = current_span
+      return NoopSpan.new if @config.nil? || ctx.nil?
+
+      ActiveSpan.new(ctx[:trace_id], new_span_id, ctx[:span_id], name, op || "server")
+    end
+
+    # Time a block as a sub-span under the active request span (nests correctly).
+    #
+    #   Octri.span("orders.list", op: "db") { db.query(sql) }
+    def span(name, op: nil)
+      ctx = current_span
+      return yield if @config.nil? || ctx.nil?
+
+      span_id = new_span_id
+      start = now_iso
+      prev = set_current_span(ctx[:trace_id], span_id)
+      status = "ok"
+      begin
+        yield
+      rescue Exception # rubocop:disable Lint/RescueException
+        status = "error"
+        raise
+      ensure
+        reset_current_span(prev)
+        capture_span(
+          trace_id: ctx[:trace_id], span_id: span_id, parent_span_id: ctx[:span_id],
+          name: name, service: op || "server", start_time: start, end_time: now_iso, status: status
+        )
+      end
+    end
+
+    # ── Automatic instrumentation ─────────────────────────────────────────────
+    # Wrap the given methods so every call becomes a sub-span. Point it at a DB
+    # client, cache, or util class once and all calls are traced without per-call
+    # code. `target` may be a Class/Module (wraps instance methods) or an object
+    # (wraps its singleton methods).
+    #
+    #   Octri.instrument(PG::Connection, [:exec, :exec_params], op: "db")
+    #   Octri.instrument(cache, [:get, :set], op: "cache")
+    def instrument(target, methods, op: nil, name: nil)
+      mod = Module.new
+      owner = target.is_a?(Module) ? target : target.singleton_class
+      methods.each do |method_name|
+        next unless owner.method_defined?(method_name) || owner.private_method_defined?(method_name)
+
+        mod.define_method(method_name) do |*args, **kwargs, &blk|
+          span_name = name ? name.call(method_name, args) : method_name.to_s
+          Octri.span(span_name, op: op) { super(*args, **kwargs, &blk) }
+        end
+      end
+      owner.prepend(mod)
+      target
+    end
+
+    # Turn on zero-config tracing for outbound HTTP (Net::HTTP). Calls to your
+    # monitoring backend are never traced (no feedback loop).
+    def auto_instrument(http: true)
+      patch_net_http if http
+    end
+
+    # ── Reporting ──────────────────────────────────────────────────────────────
+    # Log an application event directly, without a generated Octri API SDK.
+    # Delivery is fire-and-forget; event_id may be supplied for idempotency.
+    def capture_event(message, level: "info", timestamp: nil, operation_id: nil,
+                      method: nil, path: nil, status_code: nil, latency_ms: nil,
+                      attempt: nil, request_id: nil, user: nil, tags: nil,
+                      context: nil, breadcrumbs: nil, fingerprint: nil, trace: nil,
+                      span_id: nil, event_id: nil)
+      return if @config.nil?
+
+      resolved_event_id = resolve_event_id(event_id)
+      payload = {
+        eventId: resolved_event_id,
+        timestamp: timestamp || now_iso,
+        level: level,
+        message: message,
+        environment: @config.environment,
+        tags: { "octri.origin" => "standalone" }.merge(tags || {})
+      }
+      payload[:release] = @config.release if @config.release
+      payload[:operationId] = operation_id if operation_id
+      payload[:method] = method if method
+      payload[:path] = path if path
+      payload[:statusCode] = status_code unless status_code.nil?
+      payload[:latencyMs] = latency_ms unless latency_ms.nil?
+      payload[:attempt] = attempt unless attempt.nil?
+      payload[:requestId] = request_id if request_id
+      payload[:user] = user if user
+      payload[:context] = context if context
+      payload[:breadcrumbs] = breadcrumbs if breadcrumbs
+      payload[:fingerprint] = fingerprint if fingerprint
+      payload[:traceId] = trace.trace_id if trace
+      payload[:spanId] = span_id if span_id
+      post_json("/ingest", payload, idempotency_key: resolved_event_id)
+    rescue StandardError
+      # Invalid caller data must never affect the host application.
+      nil
+    end
+
+    def capture_error(exception, trace: nil, method: nil, path: nil, status_code: nil, level: "error")
+      return if @config.nil?
+
+      tr = trace || trace_from_current
+      event_id = SecureRandom.hex(16)
+      payload = {
+        eventId: event_id,
+        timestamp: now_iso,
+        level: level,
+        environment: @config.environment,
+        traceId: tr.trace_id,
+        spanId: new_span_id,
+        tags: { "octri.origin" => "server" },
+        error: {
+          name: exception.class.name,
+          message: exception.message.to_s,
+          frames: build_frames(exception)
+        }
+      }
+      payload[:release] = @config.release if @config.release
+      payload[:method] = method if method
+      payload[:path] = path if path
+      payload[:statusCode] = status_code if status_code
+      post_json("/ingest", payload, idempotency_key: event_id)
+    rescue StandardError
+      # Invalid exception-like objects must not affect the host application.
+      nil
+    end
+
+    def capture_span(trace_id:, span_id:, name:, start_time:, parent_span_id: nil,
+                     service: "server", operation_id: nil, end_time: nil, status: "ok")
+      return if @config.nil?
+      return unless valid_required_span_value?(trace_id) && valid_required_span_value?(span_id) &&
+                    valid_required_span_value?(name) && valid_iso_time?(start_time)
+      return if end_time && !valid_iso_time?(end_time)
+      return if (trace_id.length == 32 && all_zeros?(trace_id)) ||
+                (span_id.length == 16 && all_zeros?(span_id))
+
+      payload = { traceId: trace_id, spanId: span_id, environment: @config.environment,
+                  name: name, service: service, startTime: start_time, status: status }
+      payload[:parentSpanId] = parent_span_id if parent_span_id
+      payload[:endTime] = end_time if end_time
+      payload[:operationId] = operation_id if operation_id
+      post_json("/traces", payload, idempotency_key: "#{trace_id}:#{span_id}")
+    rescue StandardError
+      # Invalid caller data must never affect the host application.
+      nil
+    end
+
+    def now_iso
+      Time.now.utc.iso8601(3)
+    end
+
+    # True when host:port is the monitoring backend — used to avoid tracing our
+    # own reporting requests (which would recurse).
+    def monitoring_endpoint?(host, port)
+      return false if @config.nil? || @config.url.nil?
+
+      uri = URI(@config.url)
+      uri.host == host && uri.port == port
+    rescue StandardError
+      false
+    end
+
+    private
+
+    def all_zeros?(value)
+      value.is_a?(String) && !value.empty? && value.each_char.all? { |char| char == "0" }
+    end
+
+    def safe_header_value?(value)
+      value.is_a?(String) && !value.empty? && !value.include?("\r") && !value.include?("\n")
+    end
+
+    def safe_idempotency_key?(value)
+      safe_header_value?(value) && value.bytesize <= MAX_IDEMPOTENCY_KEY_LENGTH
+    end
+
+    def resolve_event_id(value)
+      candidate = value.is_a?(String) ? value.strip : ""
+      safe_idempotency_key?(candidate) ? candidate : SecureRandom.hex(16)
+    end
+
+    def valid_required_span_value?(value)
+      value.is_a?(String) && !value.strip.empty?
+    end
+
+    def valid_iso_time?(value)
+      return false unless valid_required_span_value?(value)
+
+      Time.iso8601(value)
+      true
+    rescue ArgumentError
+      false
+    end
+
+    def patch_net_http
+      require "net/http"
+      return if Net::HTTP.instance_variable_get(:@octri_patched)
+
+      Net::HTTP.prepend(NetHTTPPatch)
+      Net::HTTP.instance_variable_set(:@octri_patched, true)
+    end
+
+    def trace_from_current
+      ctx = current_span
+      return Trace.new(ctx[:trace_id], ctx[:span_id]) if ctx
+
+      Trace.new(SecureRandom.hex(16), nil)
+    end
+
+    # An exception's backtrace is innermost-first, matching the dashboard's
+    # culprit = top frame.
+    def build_frames(exception)
+      locations = exception.backtrace_locations
+      return [] if locations.nil?
+
+      locations.map do |loc|
+        path = loc.absolute_path || loc.path
+        lineno = loc.lineno
+        frame = { function: loc.label, filename: path, lineno: lineno, colno: 0, inApp: in_app?(path) }
+        lines = read_source(path)
+        if lines && lineno >= 1 && lineno <= lines.length
+          idx = lineno - 1
+          frame[:contextLine] = lines[idx]
+          pre = lines[[0, idx - CONTEXT_LINES].max...idx]
+          post = lines[(idx + 1)...(idx + 1 + CONTEXT_LINES)]
+          frame[:preContext] = pre if pre && !pre.empty?
+          frame[:postContext] = post if post && !post.empty?
+        end
+        frame
+      end
+    end
+
+    def in_app?(path)
+      return false if path.nil?
+
+      !path.include?("/gems/") && !path.include?("/ruby/") &&
+        !path.start_with?(RbConfig::CONFIG["libdir"].to_s)
+    end
+
+    def read_source(path)
+      return nil if path.nil?
+
+      @source_cache ||= {}
+      return @source_cache[path] if @source_cache.key?(path)
+
+      lines = begin
+        File.readlines(path, chomp: true)
+      rescue StandardError
+        nil
+      end
+      @source_cache[path] = lines
+      lines
+    end
+
+    def post_json(path, payload, idempotency_key:)
+      cfg = @config
+      return if cfg.nil?
+      return unless safe_idempotency_key?(idempotency_key)
+      return if cfg.token && cfg.token != "" && !safe_header_value?(cfg.token)
+
+      begin
+        Thread.new do
+          body = JSON.generate(payload)
+          uri = URI("#{cfg.url}#{path}")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = REQUEST_TIMEOUT_SECONDS
+          http.read_timeout = REQUEST_TIMEOUT_SECONDS
+          http.write_timeout = REQUEST_TIMEOUT_SECONDS if http.respond_to?(:write_timeout=)
+          req = Net::HTTP::Post.new(uri)
+          req["content-type"] = "application/json"
+          req["idempotency-key"] = idempotency_key
+          req["authorization"] = "Bearer #{cfg.token}" if cfg.token && cfg.token != ""
+          req.body = body
+          http.request(req)
+        rescue StandardError
+          # A reporting failure must never affect the app.
+        end
+      rescue StandardError
+        # Thread exhaustion must not make monitoring affect the application.
+        nil
+      end
+    end
+  end
+
+  # Prepended to Net::HTTP by auto_instrument: wraps outbound requests in an
+  # `http` span (skipping requests to the monitoring backend, and when there's no
+  # active request span).
+  module NetHTTPPatch
+    def request(req, body = nil, &block)
+      cfg = Octri.config
+      if cfg.nil? || Octri.current_span.nil? || Octri.monitoring_endpoint?(address, port)
+        return super
+      end
+
+      path = req.respond_to?(:path) ? req.path : ""
+      method = req.respond_to?(:method) ? req.method : "GET"
+      Octri.span("#{method} #{address}:#{port}#{path}", op: "http") { super }
+    end
+  end
+
+  # A sub-span handle for manual control; #finish reports it (named `finish`
+  # rather than `end`, which is a Ruby keyword).
+  class ActiveSpan
+    def initialize(trace_id, span_id, parent_span_id, name, service)
+      @trace_id = trace_id
+      @span_id = span_id
+      @parent_span_id = parent_span_id
+      @name = name
+      @service = service
+      @start = Octri.now_iso
+      @status = "ok"
+      @ended = false
+    end
+
+    def fail
+      @status = "error"
+    end
+
+    def finish(status = nil)
+      return if @ended
+
+      @ended = true
+      Octri.capture_span(
+        trace_id: @trace_id, span_id: @span_id, parent_span_id: @parent_span_id,
+        name: @name, service: @service, start_time: @start,
+        end_time: Octri.now_iso, status: status || @status
+      )
+    end
+  end
+
+  # No-op handle returned outside a request.
+  class NoopSpan
+    def fail; end
+
+    def finish(_status = nil); end
+  end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: octri
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Octri
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Reports backend errors to your Octri monitoring project and links them
+  to client SDK errors via W3C trace context; times requests and sub-spans into the
+  request waterfall.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/octri.rb
+- lib/octri/rack.rb
+homepage: https://octri.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://octri.dev
+  documentation_uri: https://docs.octri.dev/docs
+  bug_tracker_uri: https://octri.dev/support
+  source_code_uri: https://github.com/octridev/octri-ruby
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Server-side error monitoring for Ruby backends (Rack / Rails).
+test_files: []