obtrace-sdk-ruby 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c7468e55374f6c051c0def7f03f87796ebab9d4d69ff05132965e66b57bdbadb
+  data.tar.gz: a1d5629df790ebe12837155bb1bf94a9c61edd4ac737450ca4a3a24466dc144f
+SHA512:
+  metadata.gz: 77d495287ed0a0f010b57c08e860cec323a138f8a7c23e46051a9bd23abc8b8cc5c4dd6d717c08fefb8aac49d6285d57329846c830bd5a30dcaf3b4cb84bfbbe
+  data.tar.gz: 49fb1d19befa93b2d97485d70d1bf3106e64d340c3e26eb96f7c035e63adfbdff963da1b05787e2b06caedde5f8c7d61ab23fb4282378c29e3766b4ef12b6312

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Obtrace
+
+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,113 @@
+# obtrace-sdk-ruby
+
+Ruby backend SDK for Obtrace telemetry transport and instrumentation.
+
+## Scope
+- OTLP logs/traces/metrics transport
+- Context propagation
+- Rack/Rails middleware baseline
+
+## Design Principle
+SDK is thin/dumb.
+- No business logic authority in client SDK.
+- Policy and product logic are server-side.
+
+## Install
+
+```bash
+# when published as gem
+gem install obtrace-sdk-ruby
+```
+
+Current workspace usage:
+
+```ruby
+require_relative "lib/obtrace_sdk"
+```
+
+## Configuration
+
+Required:
+- `api_key`
+- `ingest_base_url`
+- `service_name`
+
+Optional (auto-resolved from API key on the server side):
+- `tenant_id`
+- `project_id`
+- `app_id`
+- `env`
+- `service_version`
+
+## Quickstart
+
+### Simplified setup
+
+The API key resolves `tenant_id`, `project_id`, `app_id`, and `env` automatically on the server side, so only three fields are needed:
+
+```ruby
+require "obtrace_sdk"
+
+cfg = ObtraceSDK::Config.new(
+  api_key: "obt_live_...",
+  ingest_base_url: "https://ingest.obtrace.io",
+  service_name: "my-service"
+)
+
+client = ObtraceSDK::Client.new(cfg)
+```
+
+### Full configuration
+
+For advanced use cases you can override the resolved values explicitly:
+
+```ruby
+require_relative "lib/obtrace_sdk"
+
+cfg = ObtraceSDK::Config.new(
+  api_key: "<API_KEY>",
+  ingest_base_url: "https://inject.obtrace.ai",
+  service_name: "ruby-api"
+)
+
+client = ObtraceSDK::Client.new(cfg)
+client.log("info", "started")
+client.metric(ObtraceSDK::SemanticMetrics::RUNTIME_CPU_UTILIZATION, 0.41)
+client.span("checkout.charge", attrs: {
+  "feature.name" => "checkout",
+  "payment.provider" => "stripe"
+})
+client.flush
+```
+
+## Canonical metrics and custom spans
+
+- Use `ObtraceSDK::SemanticMetrics::*` for globally normalized metric names.
+- Custom spans use `client.span("name", attrs: {...})`.
+- Keep free-form metric names only for application-specific signals outside the shared catalog.
+
+## Frameworks
+
+- Rack-compatible middleware baseline for Rails usage
+- Reference docs:
+  - `docs/frameworks.md`
+
+## Production Hardening
+
+1. Keep API keys in environment/secret managers.
+2. Separate keys per environment.
+3. Use graceful shutdown hooks to flush queue before exit.
+4. Validate telemetry flow after deploy.
+
+## Troubleshooting
+
+- Missing telemetry: verify endpoint reachability and auth key.
+- Missing correlation: ensure propagation headers are injected.
+- Debug transport with `debug: true` in config.
+
+## Documentation
+- Docs index: `docs/index.md`
+- LLM context file: `llm.txt`
+- MCP metadata: `mcp.json`
+
+## Reference

data/lib/obtrace_sdk/client.rb

@@ -0,0 +1,208 @@
+require "json"
+require "net/http"
+require "uri"
+require "thread"
+require_relative "context"
+require_relative "otlp"
+require_relative "http_instrumentation"
+require_relative "logger_capture"
+
+module ObtraceSDK
+  class Client
+    def initialize(cfg)
+      raise ArgumentError, "api_key, ingest_base_url and service_name are required" if cfg.api_key.to_s.empty? || cfg.ingest_base_url.to_s.empty? || cfg.service_name.to_s.empty?
+
+      @cfg = cfg
+      @queue = []
+      @lock = Mutex.new
+      @http = nil
+      @http_uri = nil
+      @circuit_failures = 0
+      @circuit_open_until = Time.at(0)
+      @seen_exceptions = {}
+      @seen_lock = Mutex.new
+
+      install_exception_tracepoint
+      HttpInstrumentation.install(self) if @cfg.auto_instrument_http
+      LoggerCapture.install(self) if @cfg.auto_capture_logs
+      at_exit { capture_fatal; shutdown }
+    end
+
+    def log(level, message, context = nil)
+      enqueue("/otlp/v1/logs", Otlp.logs_payload(@cfg, level, truncate(message, 32768), context))
+    end
+
+    def metric(name, value, unit = "1", context = nil)
+      warn("[obtrace-sdk-ruby] non-canonical metric name: #{name}") if @cfg.validate_semantic_metrics && @cfg.debug && !SemanticMetrics.semantic_metric?(name)
+      enqueue("/otlp/v1/metrics", Otlp.metric_payload(@cfg, truncate(name, 1024), value, unit, context))
+    end
+
+    def span(name, trace_id: nil, span_id: nil, start_unix_nano: nil, end_unix_nano: nil, status_code: nil, status_message: "", attrs: nil)
+      trace_id ||= Context.random_hex(16)
+      span_id ||= Context.random_hex(8)
+      start_ns = start_unix_nano || Otlp.now_unix_nano
+      end_ns = end_unix_nano || Otlp.now_unix_nano
+
+      name = truncate(name, 32768)
+      if attrs
+        attrs = attrs.transform_values { |v| v.is_a?(String) ? truncate(v, 4096) : v }
+      end
+
+      enqueue("/otlp/v1/traces", Otlp.span_payload(@cfg, name, trace_id, span_id, start_ns, end_ns, status_code, status_message, attrs))
+      { trace_id: trace_id, span_id: span_id }
+    end
+
+    def inject_propagation(headers = {}, trace_id: nil, span_id: nil, session_id: nil)
+      Context.ensure_propagation_headers(headers, trace_id: trace_id, span_id: span_id, session_id: session_id)
+    end
+
+    def flush
+      batch = []
+      @lock.synchronize do
+        return if Time.now < @circuit_open_until
+        half_open = @circuit_failures >= 5
+        if half_open
+          return if @queue.empty?
+          batch = [@queue.shift]
+        else
+          batch = @queue.dup
+          @queue.clear
+        end
+      end
+      batch.each do |item|
+        success = send_item(item)
+        @lock.synchronize do
+          if success
+            if @circuit_failures > 0
+              warn("[obtrace-sdk-ruby] circuit breaker closed") if @cfg.debug
+              @circuit_failures = 0
+              @circuit_open_until = Time.at(0)
+            end
+          else
+            @circuit_failures += 1
+            if @circuit_failures >= 5
+              @circuit_open_until = Time.now + 30
+              warn("[obtrace-sdk-ruby] circuit breaker opened") if @cfg.debug
+            end
+          end
+        end
+      end
+    end
+
+    def shutdown
+      @tracepoint&.disable
+      flush
+      @lock.synchronize do
+        if @http
+          @http.finish rescue nil
+          @http = nil
+          @http_uri = nil
+        end
+      end
+    end
+
+    private
+
+    def install_exception_tracepoint
+      client = self
+      @tracepoint = TracePoint.new(:raise) do |tp|
+        ex = tp.raised_exception
+        eid = ex.object_id
+        seen = client.instance_variable_get(:@seen_lock).synchronize do
+          cache = client.instance_variable_get(:@seen_exceptions)
+          next true if cache[eid]
+          cache[eid] = true
+          cache.shift if cache.size > 200
+          false
+        end
+        unless seen
+          bt = (ex.backtrace || []).first(10).join("\n")
+          client.log("error", "#{ex.class}: #{ex.message}", {
+            "exception.type" => ex.class.to_s,
+            "exception.message" => ex.message.to_s,
+            "exception.stacktrace" => bt,
+            "code.filepath" => tp.path.to_s,
+            "code.lineno" => tp.lineno.to_s,
+            "auto.source" => "tracepoint"
+          })
+        end
+      end
+      @tracepoint.enable
+    end
+
+    def capture_fatal
+      return unless $!
+      ex = $!
+      bt = (ex.backtrace || []).first(10).join("\n")
+      log("fatal", "#{ex.class}: #{ex.message}", {
+        "exception.type" => ex.class.to_s,
+        "exception.message" => ex.message.to_s,
+        "exception.stacktrace" => bt,
+        "auto.source" => "at_exit"
+      })
+    end
+
+    def truncate(s, max)
+      return s if s.length <= max
+      s[0, max] + "...[truncated]"
+    end
+
+    def enqueue(endpoint, payload)
+      @lock.synchronize do
+        if @queue.length >= @cfg.max_queue_size
+          @queue.shift
+          warn("[obtrace-sdk-ruby] queue full, dropping oldest item") if @cfg.debug
+        end
+        @queue << { endpoint: endpoint, payload: payload.dup.freeze }
+      end
+    end
+
+    def connection_for(uri)
+      if @http && @http_uri && @http_uri.host == uri.host && @http_uri.port == uri.port
+        begin
+          return @http if @http.started?
+        rescue StandardError
+        end
+      end
+
+      @http.finish rescue nil if @http
+      @http = Net::HTTP.new(uri.host, uri.port)
+      @http.use_ssl = uri.scheme == "https"
+      @http.read_timeout = @cfg.request_timeout_sec
+      @http.start
+      @http_uri = uri
+      @http
+    end
+
+    def send_item(item)
+      uri = URI.parse("#{@cfg.ingest_base_url.to_s.sub(%r{/$}, "")}#{item[:endpoint]}")
+      http = connection_for(uri)
+      req = Net::HTTP::Post.new(uri.request_uri)
+      req["Authorization"] = "Bearer #{@cfg.api_key}"
+      req["Content-Type"] = "application/json"
+      (@cfg.default_headers || {}).each { |k, v| req[k] = v.to_s }
+      req.body = JSON.generate(item[:payload])
+
+      retries = 0
+      begin
+        res = http.request(req)
+        if res.code.to_i >= 300
+          warn("[obtrace-sdk-ruby] status=#{res.code} endpoint=#{item[:endpoint]} body=#{res.body}") if @cfg.debug
+          return false
+        end
+        true
+      rescue StandardError => e
+        if retries < 2
+          retries += 1
+          sleep 1
+          @http.finish rescue nil
+          @http = nil
+          http = connection_for(uri)
+          retry
+        end
+        warn("[obtrace-sdk-ruby] send failed endpoint=#{item[:endpoint]} err=#{e.message}") if @cfg.debug
+        false
+      end
+    end
+  end
+end

data/lib/obtrace_sdk/context.rb

@@ -0,0 +1,18 @@
+require "securerandom"
+
+module ObtraceSDK
+  module Context
+    module_function
+
+    def random_hex(bytes)
+      SecureRandom.hex(bytes)
+    end
+
+    def ensure_propagation_headers(headers = {}, trace_id: nil, span_id: nil, session_id: nil)
+      out = (headers || {}).dup
+      out["traceparent"] ||= "00-#{trace_id || random_hex(16)}-#{span_id || random_hex(8)}-01"
+      out["x-obtrace-session-id"] ||= session_id if session_id && !session_id.empty?
+      out
+    end
+  end
+end

data/lib/obtrace_sdk/framework.rb

@@ -0,0 +1,15 @@
+module ObtraceSDK
+  module Framework
+    module_function
+
+    # Rack-compatible middleware baseline used by Rails.
+    def rack_middleware(client, app)
+      lambda do |env|
+        client.log("info", "request.start", { method: env["REQUEST_METHOD"], path: env["PATH_INFO"] })
+        status, headers, body = app.call(env)
+        client.log("info", "request.finish", { status: status.to_i })
+        [status, headers, body]
+      end
+    end
+  end
+end

data/lib/obtrace_sdk/http_instrumentation.rb

@@ -0,0 +1,122 @@
+require "net/http"
+
+module ObtraceSDK
+  module HttpInstrumentation
+    @client = nil
+    @installed = false
+
+    module_function
+
+    def install(client)
+      return if @installed
+      @client = client
+      @installed = true
+
+      Net::HTTP.prepend(NetHttpPatch)
+    end
+
+    def client
+      @client
+    end
+
+    def installed?
+      @installed
+    end
+
+    def reset!
+      @client = nil
+      @installed = false
+    end
+
+    module NetHttpPatch
+      def request(req, body = nil, &block)
+        client = ObtraceSDK::HttpInstrumentation.client
+        unless client
+          return super
+        end
+
+        uri = URI.parse("#{use_ssl? ? 'https' : 'http'}://#{address}:#{port}#{req.path}")
+
+        if uri.host && ObtraceSDK::HttpInstrumentation.own_endpoint?(uri)
+          return super
+        end
+
+        trace_id = ObtraceSDK::Context.random_hex(16)
+        span_id = ObtraceSDK::Context.random_hex(8)
+
+        req["traceparent"] ||= "00-#{trace_id}-#{span_id}-01"
+
+        start_ns = ObtraceSDK::Otlp.now_unix_nano
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        status_code = nil
+        error = nil
+
+        begin
+          response = super
+          status_code = response.code.to_i
+          response
+        rescue => e
+          error = e
+          raise
+        ensure
+          end_ns = ObtraceSDK::Otlp.now_unix_nano
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+
+          attrs = {
+            "http.method" => req.method,
+            "http.url" => uri.to_s,
+            "http.host" => uri.host.to_s,
+            "net.peer.port" => uri.port.to_s,
+            "http.duration_ms" => duration_ms,
+            "auto.source" => "http_instrumentation"
+          }
+
+          if status_code
+            attrs["http.status_code"] = status_code
+          end
+
+          if error
+            attrs["error"] = true
+            attrs["error.type"] = error.class.to_s
+            attrs["error.message"] = error.message.to_s
+          end
+
+          span_status = if error
+            status_code = 500
+            500
+          elsif status_code && status_code >= 400
+            status_code
+          else
+            nil
+          end
+
+          client.span(
+            "HTTP #{req.method}",
+            trace_id: trace_id,
+            span_id: span_id,
+            start_unix_nano: start_ns,
+            end_unix_nano: end_ns,
+            status_code: span_status,
+            status_message: error ? error.message : "",
+            attrs: attrs
+          )
+
+          client.log(
+            status_code && status_code >= 400 ? "warn" : "info",
+            "HTTP #{req.method} #{uri.host}#{uri.path} #{status_code || 'ERR'}",
+            attrs
+          )
+        end
+      end
+    end
+
+    def self.own_endpoint?(uri)
+      return false unless @client
+      cfg = @client.instance_variable_get(:@cfg)
+      return false unless cfg
+      ingest_uri = URI.parse(cfg.ingest_base_url.to_s) rescue nil
+      return false unless ingest_uri
+      uri.host == ingest_uri.host && uri.port == ingest_uri.port
+    end
+  end
+end

data/lib/obtrace_sdk/logger_capture.rb

@@ -0,0 +1,68 @@
+require "logger"
+
+module ObtraceSDK
+  module LoggerCapture
+    @client = nil
+    @installed = false
+
+    SEVERITY_MAP = {
+      0 => "debug",
+      1 => "info",
+      2 => "warn",
+      3 => "error",
+      4 => "fatal",
+      5 => "unknown"
+    }.freeze
+
+    module_function
+
+    def install(client)
+      return if @installed
+      @client = client
+      @installed = true
+
+      ::Logger.prepend(LoggerPatch)
+    end
+
+    def client
+      @client
+    end
+
+    def installed?
+      @installed
+    end
+
+    def reset!
+      @client = nil
+      @installed = false
+    end
+
+    module LoggerPatch
+      def add(severity, message = nil, progname = nil, &block)
+        result = super
+
+        client = ObtraceSDK::LoggerCapture.client
+        if client
+          if message.nil?
+            if block
+              msg = block.call
+            else
+              msg = progname
+            end
+          else
+            msg = message
+          end
+
+          if msg && !msg.to_s.empty?
+            level = ObtraceSDK::LoggerCapture::SEVERITY_MAP[severity] || "unknown"
+            attrs = { "auto.source" => "logger_capture" }
+            attrs["logger.progname"] = progname.to_s if progname && message
+            client.log(level, msg.to_s, attrs)
+          end
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/obtrace_sdk/middleware.rb

@@ -0,0 +1,86 @@
+module ObtraceSDK
+  class Middleware
+    def initialize(app, client)
+      @app = app
+      @client = client
+    end
+
+    def call(env)
+      trace_id = extract_trace_id(env) || Context.random_hex(16)
+      span_id = Context.random_hex(8)
+      start_ns = Otlp.now_unix_nano
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      status = nil
+      error = nil
+
+      begin
+        status, headers, body = @app.call(env)
+        [status, headers, body]
+      rescue => e
+        error = e
+        raise
+      ensure
+        end_ns = Otlp.now_unix_nano
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+        status_code = error ? 500 : status.to_i
+
+        attrs = {
+          "http.method" => env["REQUEST_METHOD"],
+          "http.target" => env["PATH_INFO"],
+          "http.host" => env["HTTP_HOST"].to_s,
+          "http.scheme" => env["rack.url_scheme"].to_s,
+          "http.status_code" => status_code,
+          "http.duration_ms" => duration_ms,
+          "http.user_agent" => env["HTTP_USER_AGENT"].to_s,
+          "net.peer.ip" => (env["HTTP_X_FORWARDED_FOR"] || env["REMOTE_ADDR"]).to_s
+        }
+
+        if error
+          attrs["error"] = true
+          attrs["error.type"] = error.class.to_s
+          attrs["error.message"] = error.message.to_s
+        end
+
+        if env["QUERY_STRING"] && !env["QUERY_STRING"].empty?
+          attrs["http.query"] = env["QUERY_STRING"]
+        end
+
+        @client.span(
+          "#{env["REQUEST_METHOD"]} #{env["PATH_INFO"]}",
+          trace_id: trace_id,
+          span_id: span_id,
+          start_unix_nano: start_ns,
+          end_unix_nano: end_ns,
+          status_code: status_code >= 400 ? status_code : nil,
+          status_message: error ? error.message : "",
+          attrs: attrs
+        )
+
+        level = if status_code >= 500
+          "error"
+        elsif status_code >= 400
+          "warn"
+        else
+          "info"
+        end
+
+        @client.log(
+          level,
+          "#{env["REQUEST_METHOD"]} #{env["PATH_INFO"]} #{status_code} #{duration_ms}ms",
+          attrs
+        )
+      end
+    end
+
+    private
+
+    def extract_trace_id(env)
+      traceparent = env["HTTP_TRACEPARENT"]
+      return nil unless traceparent
+      parts = traceparent.split("-")
+      return nil unless parts.length >= 3
+      parts[1]
+    end
+  end
+end

data/lib/obtrace_sdk/otlp.rb

@@ -0,0 +1,127 @@
+module ObtraceSDK
+  module Otlp
+    module_function
+
+    def attrs(hash)
+      return [] if hash.nil?
+      hash.map do |k, v|
+        value =
+          case v
+          when TrueClass, FalseClass
+            { "boolValue" => v }
+          when Numeric
+            { "doubleValue" => v.to_f }
+          else
+            { "stringValue" => v.to_s }
+          end
+        { "key" => k.to_s, "value" => value }
+      end
+    end
+
+    def resource(cfg)
+      base = {
+        "service.name" => cfg.service_name,
+        "service.version" => cfg.service_version,
+        "deployment.environment" => cfg.env || "dev",
+        "runtime.name" => "ruby"
+      }
+      base["obtrace.tenant_id"] = cfg.tenant_id if cfg.tenant_id
+      base["obtrace.project_id"] = cfg.project_id if cfg.project_id
+      base["obtrace.app_id"] = cfg.app_id if cfg.app_id
+      base["obtrace.env"] = cfg.env if cfg.env
+      attrs(base)
+    end
+
+    def now_unix_nano
+      (Time.now.to_f * 1_000_000_000).to_i.to_s
+    end
+
+    def logs_payload(cfg, level, message, context = nil)
+      context_attrs = { "obtrace.log.level" => level }
+      if context
+        context.each { |k, v| context_attrs["obtrace.attr.#{k}"] = v }
+      end
+
+      {
+        "resourceLogs" => [
+          {
+            "resource" => { "attributes" => resource(cfg) },
+            "scopeLogs" => [
+              {
+                "scope" => { "name" => "obtrace-sdk-ruby", "version" => "1.0.0" },
+                "logRecords" => [
+                  {
+                    "timeUnixNano" => now_unix_nano,
+                    "severityText" => level.to_s.upcase,
+                    "body" => { "stringValue" => message.to_s },
+                    "attributes" => attrs(context_attrs)
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    end
+
+    def metric_payload(cfg, name, value, unit = "1", context = nil)
+      {
+        "resourceMetrics" => [
+          {
+            "resource" => { "attributes" => resource(cfg) },
+            "scopeMetrics" => [
+              {
+                "scope" => { "name" => "obtrace-sdk-ruby", "version" => "1.0.0" },
+                "metrics" => [
+                  {
+                    "name" => name.to_s,
+                    "unit" => unit.to_s,
+                    "gauge" => {
+                      "dataPoints" => [
+                        {
+                          "timeUnixNano" => now_unix_nano,
+                          "asDouble" => value.to_f,
+                          "attributes" => attrs(context || {})
+                        }
+                      ]
+                    }
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    end
+
+    def span_payload(cfg, name, trace_id, span_id, start_unix_nano, end_unix_nano, status_code = nil, status_message = "", attrs_hash = nil)
+      {
+        "resourceSpans" => [
+          {
+            "resource" => { "attributes" => resource(cfg) },
+            "scopeSpans" => [
+              {
+                "scope" => { "name" => "obtrace-sdk-ruby", "version" => "1.0.0" },
+                "spans" => [
+                  {
+                    "traceId" => trace_id,
+                    "spanId" => span_id,
+                    "name" => name.to_s,
+                    "kind" => 3,
+                    "startTimeUnixNano" => start_unix_nano,
+                    "endTimeUnixNano" => end_unix_nano,
+                    "attributes" => attrs(attrs_hash || {}),
+                    "status" => {
+                      "code" => status_code && status_code.to_i >= 400 ? 2 : 1,
+                      "message" => status_message.to_s
+                    }
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    end
+  end
+end

data/lib/obtrace_sdk/rails.rb

@@ -0,0 +1,37 @@
+require "obtrace_sdk"
+
+module ObtraceSDK
+  class Railtie < ::Rails::Railtie
+    initializer "obtrace_sdk.configure" do |app|
+      api_key = credentials_fetch("obtrace_api_key") || ENV["OBTRACE_API_KEY"]
+      ingest_url = credentials_fetch("obtrace_ingest_url") || ENV["OBTRACE_INGEST_BASE_URL"] || "https://inject.obtrace.ai"
+      service_name = credentials_fetch("obtrace_service_name") || ENV["OBTRACE_SERVICE_NAME"] || ::Rails.application.class.module_parent_name.underscore rescue "rails-app"
+
+      next unless api_key
+
+      cfg = ObtraceSDK::Config.new(
+        api_key: api_key,
+        ingest_base_url: ingest_url,
+        service_name: service_name,
+        env: ::Rails.env.to_s,
+        tenant_id: credentials_fetch("obtrace_tenant_id") || ENV["OBTRACE_TENANT_ID"],
+        project_id: credentials_fetch("obtrace_project_id") || ENV["OBTRACE_PROJECT_ID"],
+        app_id: credentials_fetch("obtrace_app_id") || ENV["OBTRACE_APP_ID"],
+        debug: ENV["OBTRACE_DEBUG"] == "true"
+      )
+
+      client = ObtraceSDK::Client.new(cfg)
+      ObtraceSDK.instance_variable_set(:@rails_client, client)
+
+      app.middleware.insert(0, ObtraceSDK::Middleware, client)
+    end
+
+    def credentials_fetch(key)
+      ::Rails.application.credentials.send(key) rescue nil
+    end
+  end
+
+  def self.rails_client
+    @rails_client
+  end
+end

data/lib/obtrace_sdk/semantic_metrics.rb

@@ -0,0 +1,55 @@
+module ObtraceSDK
+  module SemanticMetrics
+    THROUGHPUT = "http_requests_total"
+    ERROR_RATE = "http_5xx_total"
+    LATENCY_P95 = "latency_p95"
+    RUNTIME_CPU_UTILIZATION = "runtime.cpu.utilization"
+    RUNTIME_MEMORY_USAGE = "runtime.memory.usage"
+    RUNTIME_THREAD_COUNT = "runtime.thread.count"
+    RUNTIME_GC_PAUSE = "runtime.gc.pause"
+    RUNTIME_EVENTLOOP_LAG = "runtime.eventloop.lag"
+    CLUSTER_CPU_UTILIZATION = "cluster.cpu.utilization"
+    CLUSTER_MEMORY_USAGE = "cluster.memory.usage"
+    CLUSTER_NODE_COUNT = "cluster.node.count"
+    CLUSTER_POD_COUNT = "cluster.pod.count"
+    DB_OPERATION_LATENCY = "db.operation.latency"
+    DB_CLIENT_ERRORS = "db.client.errors"
+    DB_CONNECTIONS_USAGE = "db.connections.usage"
+    MESSAGING_CONSUMER_LAG = "messaging.consumer.lag"
+    WEB_VITAL_LCP = "web.vital.lcp"
+    WEB_VITAL_FCP = "web.vital.fcp"
+    WEB_VITAL_INP = "web.vital.inp"
+    WEB_VITAL_CLS = "web.vital.cls"
+    WEB_VITAL_TTFB = "web.vital.ttfb"
+    USER_ACTIONS = "obtrace.sim.web.react.actions"
+
+    ALL = [
+      THROUGHPUT,
+      ERROR_RATE,
+      LATENCY_P95,
+      RUNTIME_CPU_UTILIZATION,
+      RUNTIME_MEMORY_USAGE,
+      RUNTIME_THREAD_COUNT,
+      RUNTIME_GC_PAUSE,
+      RUNTIME_EVENTLOOP_LAG,
+      CLUSTER_CPU_UTILIZATION,
+      CLUSTER_MEMORY_USAGE,
+      CLUSTER_NODE_COUNT,
+      CLUSTER_POD_COUNT,
+      DB_OPERATION_LATENCY,
+      DB_CLIENT_ERRORS,
+      DB_CONNECTIONS_USAGE,
+      MESSAGING_CONSUMER_LAG,
+      WEB_VITAL_LCP,
+      WEB_VITAL_FCP,
+      WEB_VITAL_INP,
+      WEB_VITAL_CLS,
+      WEB_VITAL_TTFB,
+      USER_ACTIONS
+    ].freeze
+
+    def self.semantic_metric?(name)
+      ALL.include?(name)
+    end
+  end
+end

data/lib/obtrace_sdk/types.rb

@@ -0,0 +1,26 @@
+module ObtraceSDK
+  class Config
+    attr_accessor :api_key, :ingest_base_url, :tenant_id, :project_id, :app_id, :env
+    attr_accessor :service_name, :service_version, :max_queue_size, :request_timeout_sec
+    attr_accessor :default_headers, :debug, :validate_semantic_metrics
+    attr_accessor :auto_instrument_http, :auto_capture_logs
+
+    def initialize(api_key:, ingest_base_url:, service_name:, tenant_id: nil, project_id: nil, app_id: nil, env: "dev", service_version: "1.0.0", max_queue_size: 1000, request_timeout_sec: 5, default_headers: {}, validate_semantic_metrics: false, debug: false, auto_instrument_http: true, auto_capture_logs: true)
+      @api_key = api_key
+      @ingest_base_url = ingest_base_url
+      @tenant_id = tenant_id
+      @project_id = project_id
+      @app_id = app_id
+      @env = env
+      @service_name = service_name
+      @service_version = service_version
+      @max_queue_size = max_queue_size
+      @request_timeout_sec = request_timeout_sec
+      @default_headers = default_headers
+      @validate_semantic_metrics = validate_semantic_metrics
+      @debug = debug
+      @auto_instrument_http = auto_instrument_http
+      @auto_capture_logs = auto_capture_logs
+    end
+  end
+end

data/lib/obtrace_sdk/version.rb

@@ -0,0 +1,3 @@
+module ObtraceSDK
+  VERSION = "1.0.2"
+end

data/lib/obtrace_sdk.rb

@@ -0,0 +1,9 @@
+require_relative "obtrace_sdk/types"
+require_relative "obtrace_sdk/context"
+require_relative "obtrace_sdk/otlp"
+require_relative "obtrace_sdk/http_instrumentation"
+require_relative "obtrace_sdk/logger_capture"
+require_relative "obtrace_sdk/middleware"
+require_relative "obtrace_sdk/client"
+require_relative "obtrace_sdk/framework"
+require_relative "obtrace_sdk/semantic_metrics"

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: obtrace-sdk-ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.2
+platform: ruby
+authors:
+- Obtrace
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby SDK for Obtrace observability platform. Captures logs, traces, and
+  metrics via OTLP.
+email:
+- dev@obtrace.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/obtrace_sdk.rb
+- lib/obtrace_sdk/client.rb
+- lib/obtrace_sdk/context.rb
+- lib/obtrace_sdk/framework.rb
+- lib/obtrace_sdk/http_instrumentation.rb
+- lib/obtrace_sdk/logger_capture.rb
+- lib/obtrace_sdk/middleware.rb
+- lib/obtrace_sdk/otlp.rb
+- lib/obtrace_sdk/rails.rb
+- lib/obtrace_sdk/semantic_metrics.rb
+- lib/obtrace_sdk/types.rb
+- lib/obtrace_sdk/version.rb
+homepage: https://github.com/obtraceai/obtrace-sdk-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/obtraceai/obtrace-sdk-ruby
+  source_code_uri: https://github.com/obtraceai/obtrace-sdk-ruby
+  changelog_uri: https://github.com/obtraceai/obtrace-sdk-ruby/releases
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Obtrace Ruby SDK — observability for Ruby applications
+test_files: []