ditliti 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '05886e9711c1cbe6a5c8d27fa42a2663ef98d57e04a76f557f16b21b6db59b5c'
+  data.tar.gz: f8b4dd43af968bc050a58e370a243e1280434213acc53c80898d2886c0f446c1
+SHA512:
+  metadata.gz: 033ec9d232d630eabdd803000d2f5527f4cd63280e0cec0c56ec462eecc8fbc8c352411bb91edf63f38b7b2c6e52422c8c44ed052d5eb5ef7a6dc490caeadcdd
+  data.tar.gz: 33f4b8de25f65db24de77362d88e44005be1511a1d0f6982976c262b34a8e7495df503a82cac58546ad76e4ae1fa14477649b6ffc22fbadad116459d2664d0e7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 candrabasic
+
+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/lib/ditliti/db.rb

@@ -0,0 +1,99 @@
+require_relative "../ditliti"
+
+module Ditliti
+  # Database query auto-instrumentation.
+  #
+  # Wraps a query execution with a `db.query` span carrying OpenTelemetry-
+  # shaped database attributes. The backend (ingestion-api) parameterizes
+  # and sanitizes `db.query.text` server-side and derives
+  # `db.query.summary` / `db.operation.name` / `db.collection.name` /
+  # `ditliti.query_hash` from it - callers here only need to supply the
+  # real SQL text, exactly like every other span already sent by this SDK
+  # travels over the same trust boundary to the user's own ingestion-api.
+  #
+  # This never changes the wrapped call's exception flow: span-recording
+  # failures are swallowed, and the original exception (if any) is always
+  # re-raised unchanged.
+  #
+  # Note: this environment has no Ruby runtime available, so this file has
+  # been carefully written (mirroring the already-tested Python/PHP/Elixir
+  # adapters' generic-wrapper + ORM-notification shape) but has not itself
+  # been executed - review before relying on it in production.
+  module DbTracing
+    module_function
+
+    def trace_query(client, system:, text:, collection: nil, operation: nil)
+      tags = { "db.system.name" => system, "db.query.text" => text }
+      tags["db.operation.name"] = operation if operation
+      tags["db.collection.name"] = collection if collection
+
+      span = client.start_span("db.query", tags: tags)
+      begin
+        result = yield
+        count = extract_row_count(result)
+        safe_finish(span, count ? { "db.response.returned_rows" => count.to_s } : {})
+        result
+      rescue => error
+        safe_finish(span, { "error.type" => error.class.name })
+        raise
+      end
+    end
+
+    # Subscribes to ActiveRecord's `sql.active_record` notification - no
+    # query wrapping required, works for the query builder, Active Record
+    # models, and raw `connection.execute` alike. Requires ActiveSupport to
+    # already be loaded by the host application (this SDK has no Rails
+    # dependency of its own).
+    def subscribe_active_record(client, system: "postgresql")
+      ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        next if event.payload[:name] == "SCHEMA" # migrations/introspection queries, not app queries
+
+        record_completed_span(
+          client,
+          system: system,
+          text: event.payload[:sql],
+          duration_ms: event.duration,
+          collection: event.payload[:name]
+        )
+      end
+    end
+
+    # Records a span whose duration is already known (e.g. from
+    # ActiveRecord's notification, which reports a query's elapsed time
+    # only after it has already completed) - unlike `trace_query`, there's
+    # no separate "finish" step since the operation is already over.
+    def record_completed_span(client, system:, text:, duration_ms:, collection: nil, operation: nil, error_type: nil)
+      client.start_trace if client.trace.nil?
+      parent_span_id = client.trace.span_id
+      ctx = client.trace.child
+
+      tags = { "db.system.name" => system, "db.query.text" => text }
+      tags["db.operation.name"] = operation if operation
+      tags["db.collection.name"] = collection if collection
+      tags["error.type"] = error_type if error_type
+
+      client.record_span(
+        trace_id: ctx.trace_id,
+        span_id: ctx.span_id,
+        parent_span_id: parent_span_id,
+        operation_name: "db.query",
+        duration_ms: duration_ms,
+        tags: tags
+      )
+    end
+
+    def safe_finish(span, extra_tags)
+      span.finish(extra_tags: extra_tags)
+    rescue StandardError
+      # Instrumentation must never break the caller's query path.
+    end
+
+    def extract_row_count(result)
+      return result if result.is_a?(Integer) && result >= 0
+      return result.length if result.respond_to?(:length)
+
+      nil
+    end
+  end
+end

data/lib/ditliti.rb

@@ -0,0 +1,297 @@
+require "digest"
+require "json"
+require "net/http"
+require "securerandom"
+require "time"
+require "uri"
+
+module Ditliti
+  # A W3C trace-context (https://www.w3.org/TR/trace-context/) carried
+  # across service boundaries via the `traceparent` header, so a trace
+  # started in one process is continued - not restarted - in the next.
+  class TraceContext
+    attr_reader :trace_id, :span_id, :sampled
+
+    def self.generate_trace_id
+      SecureRandom.hex(16)
+    end
+
+    def self.generate_span_id
+      SecureRandom.hex(8)
+    end
+
+    def self.start
+      new(generate_trace_id, generate_span_id, true)
+    end
+
+    def self.from_traceparent(header)
+      return nil if header.nil? || header.strip.empty?
+
+      parts = header.strip.split("-")
+      return nil unless parts.length == 4
+
+      _version, trace_id, span_id, flags = parts
+      return nil unless trace_id =~ /\A[0-9a-f]{32}\z/ && trace_id != "0" * 32
+      return nil unless span_id =~ /\A[0-9a-f]{16}\z/ && span_id != "0" * 16
+
+      flags_value = Integer(flags, 16) rescue nil
+      return nil if flags_value.nil?
+
+      new(trace_id, span_id, (flags_value & 1) == 1)
+    end
+
+    def initialize(trace_id, span_id, sampled = true)
+      @trace_id = trace_id
+      @span_id = span_id
+      @sampled = sampled
+    end
+
+    def child
+      self.class.new(trace_id, self.class.generate_span_id, sampled)
+    end
+
+    def to_traceparent
+      "00-#{trace_id}-#{span_id}-#{sampled ? "01" : "00"}"
+    end
+  end
+
+  # Returned by Client#start_span; call #finish when the operation completes
+  # to record and send the span.
+  class Span
+    def initialize(client, operation_name, parent_span_id, ctx, tags)
+      @client = client
+      @operation_name = operation_name
+      @parent_span_id = parent_span_id
+      @ctx = ctx
+      @tags = tags
+      @started_at = Time.now.utc
+      @started_monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def trace_id
+      @ctx.trace_id
+    end
+
+    def span_id
+      @ctx.span_id
+    end
+
+    def traceparent
+      @ctx.to_traceparent
+    end
+
+    def finish(extra_tags: {})
+      duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_monotonic) * 1000
+      @client.record_span(
+        trace_id: @ctx.trace_id,
+        span_id: @ctx.span_id,
+        parent_span_id: @parent_span_id,
+        operation_name: @operation_name,
+        duration_ms: duration_ms,
+        started_at: @started_at,
+        tags: @tags.merge(extra_tags)
+      )
+    end
+  end
+
+  class Client
+    attr_accessor :user, :session_id
+    attr_reader :trace
+
+    def initialize(endpoint:, api_key:, project_id:, release: nil, environment: nil, timeout: 1.5)
+      @endpoint = endpoint.sub(%r{/$}, "")
+      @api_key = api_key
+      @project_id = project_id
+      @release = release
+      @environment = environment
+      @timeout = timeout
+      @breadcrumbs = []
+      @trace = nil
+    end
+
+    # Start (or continue, if an inbound `traceparent` header is given) the
+    # active trace. Downstream calls should read #get_traceparent and
+    # forward it as the `traceparent` header of any outgoing HTTP request to
+    # propagate the trace into the next service.
+    def start_trace(incoming_traceparent = nil)
+      parent = TraceContext.from_traceparent(incoming_traceparent)
+      @trace = parent ? parent.child : TraceContext.start
+      @trace
+    end
+
+    def get_traceparent
+      @trace&.to_traceparent
+    end
+
+    # Start a child span under the active trace (starting one implicitly if
+    # none is active yet).
+    def start_span(operation_name, tags: {})
+      start_trace if @trace.nil?
+      parent_span_id = @trace.span_id
+      ctx = @trace.child
+      Span.new(self, operation_name, parent_span_id, ctx, { runtime: "ruby" }.merge(tags))
+    end
+
+    def record_span(trace_id:, span_id:, operation_name:, duration_ms:, parent_span_id: nil, started_at: nil, tags: {})
+      base_tags = { runtime: "ruby" }
+      base_tags[:environment] = @environment if @environment
+      base_tags[:release] = @release if @release
+      send_envelope({
+        spans: [{
+          trace_id: trace_id,
+          span_id: span_id,
+          parent_span_id: parent_span_id,
+          project_id: @project_id,
+          operation_name: operation_name,
+          start_time: (started_at || Time.now.utc).iso8601(3),
+          duration_ms: duration_ms,
+          tags: base_tags.merge(tags)
+        }]
+      })
+    end
+
+    private
+
+    def current_trace_tags
+      @trace ? { trace_id: @trace.trace_id } : {}
+    end
+
+    public
+
+    def add_breadcrumb(message:, category: nil, level: "info", data: {})
+      @breadcrumbs << {
+        timestamp: Time.now.utc.iso8601,
+        category: category,
+        message: message.to_s,
+        level: level,
+        data: data || {}
+      }
+      @breadcrumbs.shift while @breadcrumbs.length > 100
+    end
+
+    def capture_exception(error, context: {}, tags: {}, transaction: nil, user_agent: nil)
+      payload = {
+        id: SecureRandom.uuid,
+        project_id: @project_id,
+        level: "error",
+        message: error.message.to_s,
+        exception_type: error.class.name,
+        stack_trace: stack_frames(error),
+        tags: { runtime: "ruby" }.merge(current_trace_tags).merge(tags || {}),
+        context: context || {},
+        user_agent: user_agent,
+        release: @release,
+        environment: @environment,
+        transaction: transaction,
+        session_id: @session_id,
+        breadcrumbs: @breadcrumbs,
+        user: @user
+      }
+      post("/api/v1/ingest", payload, stable_id(payload))
+    end
+
+    def capture_rack_exception(error, env)
+      request_method = env["REQUEST_METHOD"]
+      path = env["PATH_INFO"] || env["REQUEST_URI"]
+      capture_exception(
+        error,
+        context: {
+          framework: "rack",
+          method: request_method,
+          path: path,
+          query: env["QUERY_STRING"]
+        },
+        tags: { framework: "rack" },
+        transaction: "#{request_method || "HTTP"} #{path || "/"}",
+        user_agent: env["HTTP_USER_AGENT"]
+      )
+    end
+
+    def send_envelope(envelope)
+      post("/api/v1/envelope", {
+        project_id: @project_id,
+        events: envelope.fetch(:events, []),
+        spans: envelope.fetch(:spans, []),
+        logs: envelope.fetch(:logs, []),
+        replays: envelope.fetch(:replays, []),
+        profiles: envelope.fetch(:profiles, [])
+      })
+    end
+
+    def capture_replay_segment(duration_ms:, session_id: @session_id, segment_index: 0, events: [], tags: {}, user: @user, release: @release, environment: @environment)
+      raise ArgumentError, "replay session_id is required" if session_id.nil? || session_id.to_s.empty?
+
+      send_envelope({
+        replays: [{
+          project_id: @project_id,
+          session_id: session_id,
+          started_at: Time.now.utc.iso8601,
+          duration_ms: duration_ms,
+          segment_index: segment_index,
+          events: events || [],
+          tags: { runtime: "ruby" }.merge(tags || {}),
+          user: user,
+          release: release,
+          environment: environment
+        }]
+      })
+    end
+
+    def capture_profile(duration_ms:, trace_id: nil, transaction: nil, platform: "ruby", samples: [], tags: {}, release: @release, environment: @environment)
+      send_envelope({
+        profiles: [{
+          project_id: @project_id,
+          trace_id: trace_id || @trace&.trace_id,
+          transaction: transaction,
+          started_at: Time.now.utc.iso8601,
+          duration_ms: duration_ms,
+          platform: platform,
+          samples: samples || [],
+          tags: { runtime: "ruby" }.merge(tags || {}),
+          release: release,
+          environment: environment
+        }]
+      })
+    end
+
+    private
+
+    def post(path, payload, event_id = nil)
+      uri = URI("#{@endpoint}#{path}")
+      request = Net::HTTP::Post.new(uri)
+      request["content-type"] = "application/json"
+      request["x-api-key"] = @api_key
+      request["x-event-id"] = event_id if event_id
+      request.body = JSON.generate(payload)
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: @timeout, open_timeout: @timeout) do |http|
+        http.request(request)
+      end
+      raise "ditliti ingestion failed with status #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+    end
+
+    def stack_frames(error)
+      Array(error.backtrace_locations).map do |frame|
+        { function: frame.label, file: frame.path, line: frame.lineno, column: nil }
+      end
+    end
+
+    def stable_id(payload)
+      Digest::SHA256.hexdigest("#{payload[:project_id]}|#{payload[:exception_type]}|#{payload[:message]}")
+    end
+  end
+
+  class RackMiddleware
+    def initialize(app, client)
+      @app = app
+      @client = client
+    end
+
+    def call(env)
+      @client.start_trace(env["HTTP_TRACEPARENT"])
+      @app.call(env)
+    rescue => error
+      @client.capture_rack_exception(error, env)
+      raise
+    end
+  end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: ditliti
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- candrabasic
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-15 00:00:00.000000000 Z
+dependencies: []
+description: Error tracking, tracing, replay, and profiling ingestion client for a
+  self-hosted Ditliti instance.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- lib/ditliti.rb
+- lib/ditliti/db.rb
+homepage: https://github.com/kangartha/inspectora/tree/main/sdk/ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kangartha/inspectora
+  bug_tracker_uri: https://github.com/kangartha/inspectora/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for Ditliti
+test_files: []