logtide 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a68971846b51c0b0413c804adac77efb0a47c2ac04431d2158e93b9124015581
+  data.tar.gz: 5ae7b9131a3d57b163756965bd036eb6b13c0fa1fa95346f7e3194771ff9f0ba
+SHA512:
+  metadata.gz: d96d2a0f31c1bd3a53bb4d4fa1a3e655de72ca7b41c9f83427b97a404d058005b1b08fb16c043a72c53e52b117c9527401ea7cd956047f1aca79ae7d58d1109c
+  data.tar.gz: 4f605cd5487d398297ae4a172b371322d645ed01d83f2cdbffc62804a0a7ca9f00b3e41600c024ab93ad05cdaa7d1e11c34b659d44d04a94c353246e6717f7ee

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/) and this project follows SemVer.
+
+## [1.0.0] - 2026-06-17
+
+First release. Implements the LogTide SDK spec v1.0.
+
+### Added
+- Log capture at five levels and structured exception capture with cause chains
+- Strict wire format with reserved metadata keys and robust serialisation
+- HTTP transport with batching, exponential-backoff retry (retryable statuses
+  only, Retry-After honoured) and a circuit breaker
+- Bounded buffer with drop accounting, `flush`/`close` and an at_exit hook
+- DSN parsing and explicit `api_url`/`api_key` configuration
+- Hub/Scope model with tags, user, breadcrumbs and per-request isolation
+- `before_send` hook, log sampling and trace sampling
+- W3C `traceparent` inbound/outbound propagation, spans and OTLP export
+- Rack middleware and Rails Railtie
+- stdlib `Logger` bridge
+- Self-metrics (`logs_sent`, `logs_dropped`, `errors`, `retries`,
+  `circuit_breaker_trips`)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LogTide
+
+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,168 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/logtide-dev/logtide/main/docs/images/logo.png" alt="LogTide Logo" width="400">
+</p>
+
+<h1 align="center">LogTide Ruby SDK</h1>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/logtide"><img src="https://img.shields.io/gem/v/logtide?color=blue" alt="Gem"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
+  <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/Ruby-3.1+-red.svg" alt="Ruby"></a>
+  <a href="https://github.com/logtide-dev/logtide-ruby/actions"><img src="https://img.shields.io/github/actions/workflow/status/logtide-dev/logtide-ruby/ci.yml?branch=main" alt="CI"></a>
+  <a href="https://github.com/logtide-dev/logtide-ruby/releases"><img src="https://img.shields.io/github/v/release/logtide-dev/logtide-ruby" alt="Release"></a>
+</p>
+
+<p align="center">
+  Official Ruby SDK for <a href="https://logtide.dev">LogTide</a> — self-hosted log management with distributed tracing, error capture, breadcrumbs, and Rack/Rails middleware.
+</p>
+
+---
+
+## Features
+
+- **Leveled logging** — `debug`, `info`, `warn`, `error`, `critical`, plus `capture_exception`
+- **Structured exception capture** with cause chains and stack frames
+- **Hub / Scope model** — per-request isolation with tags, user, breadcrumbs, and trace context
+- **Automatic batching** with configurable size and interval
+- **Retry with backoff** — exponential backoff with jitter; honours `Retry-After`
+- **Circuit breaker** to prevent cascading failures
+- **Bounded buffer** with a drop policy to cap memory; `flush`/`close` and a best-effort exit hook
+- **W3C `traceparent`** inbound and outbound propagation
+- **Spans + OTLP export** with log/trace correlation and sampling
+- **`before_send` hook** and log/trace sampling
+- **Rack middleware + Rails Railtie**
+- **stdlib `Logger` bridge**
+- **Self-metrics** (`logs_sent`, `logs_dropped`, `errors`, `retries`, `circuit_breaker_trips`)
+- **Standard library only** — no runtime dependencies
+- **Thread-safe**
+
+Implements the **LogTide SDK spec v1.0**.
+
+## Requirements
+
+- Ruby 3.1 or later
+- A LogTide instance and DSN
+
+## Installation
+
+```ruby
+# Gemfile
+gem "logtide"
+```
+
+```sh
+bundle install
+```
+
+## Quick start
+
+```ruby
+require "logtide"
+
+Logtide.init(
+  dsn: "https://lp_your_key@logs.example.com",
+  service: "checkout",
+  environment: "production"
+)
+
+Logtide.info("order placed", { order_id: 42 })
+
+begin
+  charge_card!
+rescue => e
+  Logtide.capture_exception(e)
+end
+
+Logtide.flush
+```
+
+Configuration also accepts explicit endpoint options:
+
+```ruby
+Logtide.init(api_url: "https://logs.example.com", api_key: "lp_your_key", service: "checkout")
+```
+
+## Scope, tags and breadcrumbs
+
+```ruby
+Logtide.configure_scope do |scope|
+  scope.set_user(id: "u_123", email: "alice@example.com")
+  scope.set_tag("region", "eu")
+end
+
+Logtide.add_breadcrumb(Logtide::Breadcrumb.new(type: "query", message: "SELECT * FROM carts"))
+
+Logtide.with_scope do |scope|
+  scope.set_tag("step", "payment")
+  Logtide.error("payment failed")
+end
+```
+
+## Rails
+
+The Railtie installs the Rack middleware automatically. Initialise the SDK in an
+initializer:
+
+```ruby
+# config/initializers/logtide.rb
+Logtide.init(dsn: ENV["LOGTIDE_DSN"], service: "my-app", release: ENV["GIT_SHA"])
+```
+
+## Plain Rack
+
+```ruby
+use Logtide::Rack::Middleware
+```
+
+## stdlib Logger bridge
+
+```ruby
+logger = Logtide::LoggerBridge.new
+logger.warn("disk almost full")   # delivered as a LogTide entry with scope context
+```
+
+## Tracing
+
+```ruby
+Logtide.start_span("checkout", kind: :server) do |span|
+  span.set_attribute("cart.size", 3)
+  Logtide.info("processing") # carries the span's trace_id/span_id
+end
+
+# Propagate the trace to a downstream service:
+headers = Logtide.trace_propagation_headers # { "traceparent" => "00-..." }
+```
+
+## Configuration options
+
+Defaults follow the spec exactly (durations in seconds):
+
+| Option | Default |
+|--------|---------|
+| `environment` | `"production"` |
+| `batch_size` | `100` |
+| `flush_interval` | `5` |
+| `max_buffer_size` | `10_000` |
+| `max_retries` | `3` |
+| `retry_delay` | `1` |
+| `circuit_breaker_threshold` | `5` |
+| `circuit_breaker_reset` | `30` |
+| `flush_timeout` | `10` |
+| `max_breadcrumbs` | `100` |
+| `sample_rate` | `1.0` |
+| `traces_sample_rate` | `1.0` |
+| `attach_stacktrace` | `true` |
+| `send_default_pii` | `false` |
+| `debug` | `false` |
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+[MIT](LICENSE)

data/lib/logtide/breadcrumb.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Logtide
+  # A breadcrumb: a small structured event in the trail leading up to an entry
+  # (spec 003 section 5).
+  class Breadcrumb
+    TYPES = %w[http navigation ui console query error custom].freeze
+
+    def initialize(type: "custom", category: nil, message: nil, data: nil,
+                   level: "info", timestamp: nil)
+      @type = type
+      @category = category
+      @message = message
+      @data = data
+      @level = level.to_s
+      @timestamp = timestamp || Time.now.utc
+    end
+
+    def to_h
+      result = {
+        "type" => @type,
+        "level" => @level,
+        "timestamp" => @timestamp.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+      }
+      result["category"] = @category if @category
+      result["message"] = @message if @message
+      result["data"] = @data if @data
+      result
+    end
+  end
+
+  # A ring buffer of breadcrumbs, oldest first, capped at max_breadcrumbs
+  # (spec 004 section 4).
+  class BreadcrumbBuffer
+    def initialize(max_breadcrumbs)
+      @max = max_breadcrumbs
+      @crumbs = []
+    end
+
+    def add(crumb)
+      @crumbs << crumb
+      @crumbs.shift while @crumbs.size > @max
+      crumb
+    end
+
+    def to_a
+      @crumbs.dup
+    end
+
+    def clear
+      @crumbs.clear
+    end
+
+    def empty?
+      @crumbs.empty?
+    end
+
+    def initialize_copy(other)
+      super
+      @crumbs = other.to_a
+    end
+  end
+end

data/lib/logtide/circuit_breaker.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Logtide
+  # Circuit breaker around batch delivery (spec 002 section 7).
+  #
+  # closed   -> count consecutive failures; at threshold -> open
+  # open      -> fail fast until reset_timeout has elapsed -> half-open
+  # half-open -> allow exactly one probe; success -> closed, failure -> open
+  #
+  # A threshold of 0 disables the breaker entirely.
+  class CircuitBreaker
+    def initialize(threshold:, reset_timeout:, clock: -> { Time.now })
+      @threshold = threshold
+      @reset_timeout = reset_timeout
+      @clock = clock
+      @mutex = Mutex.new
+      @state = :closed
+      @failures = 0
+      @opened_at = nil
+      @probe_in_flight = false
+    end
+
+    def state
+      @mutex.synchronize do
+        refresh
+        @state
+      end
+    end
+
+    def allow?
+      return true if disabled?
+
+      @mutex.synchronize do
+        refresh
+        case @state
+        when :closed then true
+        when :half_open
+          if @probe_in_flight
+            false
+          else
+            @probe_in_flight = true
+            true
+          end
+        else
+          false
+        end
+      end
+    end
+
+    def record_success
+      return if disabled?
+
+      @mutex.synchronize do
+        @state = :closed
+        @failures = 0
+        @opened_at = nil
+        @probe_in_flight = false
+      end
+    end
+
+    def record_failure
+      return if disabled?
+
+      @mutex.synchronize do
+        if @state == :half_open
+          open!
+        else
+          @failures += 1
+          open! if @failures >= @threshold
+        end
+      end
+    end
+
+    private
+
+    def disabled?
+      @threshold.zero?
+    end
+
+    # Must be called holding the mutex.
+    def refresh
+      return unless @state == :open && @opened_at
+
+      @state = :half_open if @clock.call - @opened_at >= @reset_timeout
+    end
+
+    def open!
+      @state = :open
+      @opened_at = @clock.call
+      @probe_in_flight = false
+    end
+  end
+end

data/lib/logtide/client.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "event"
+require_relative "scope"
+require_relative "metrics"
+require_relative "circuit_breaker"
+require_relative "retry_policy"
+require_relative "structured_exception"
+require_relative "tracing"
+require_relative "tracing/span"
+require_relative "transport/http"
+require_relative "transport/otlp"
+require_relative "transport/batcher"
+
+module Logtide
+  # Owns configuration and the transport, and runs the capture pipeline:
+  # merge scope + global metadata, stamp the sdk, run event processors and
+  # before_send, sample, then enqueue. Public capture methods are
+  # fire-and-forget and never raise for transport problems (spec 001).
+  class Client
+    LEVELS = %w[debug info warn error critical].freeze
+
+    attr_reader :configuration
+
+    def initialize(configuration, batcher: nil, span_batcher: nil, sampler: -> { rand })
+      @configuration = configuration
+      @metrics = Metrics.new
+      @sampler = sampler
+      @batcher = batcher || build_batcher
+      @span_batcher = span_batcher
+    end
+
+    def capture_log(level, message, metadata = nil, scope: nil, hint: nil,
+                    trace_id: nil, span_id: nil, time: nil)
+      dispatch(
+        level: normalize_level(level), message: message, metadata: metadata,
+        scope: scope, hint: hint || {}, trace_id: trace_id, span_id: span_id, time: time
+      )
+    end
+
+    def capture_exception(exception, message: nil, level: "error", metadata: nil,
+                          scope: nil, hint: nil, trace_id: nil, span_id: nil, time: nil)
+      structured = StructuredException.serialize(exception, include_stacktrace: @configuration.attach_stacktrace)
+      hint = (hint || {}).merge(exception: exception)
+      dispatch(
+        level: normalize_level(level), message: message || exception.message.to_s,
+        metadata: metadata, scope: scope, hint: hint, exception: structured,
+        trace_id: trace_id, span_id: span_id, time: time
+      )
+    end
+
+    # Start a span. The returned span becomes the active span on the given scope
+    # (the caller is responsible for finishing it). Sampling is decided once per
+    # trace at the root span (spec 005 section 5).
+    def start_span(name, scope:, kind: :internal)
+      parent = scope&.span
+      trace_id = parent&.trace_id || scope&.trace_id || Tracing.generate_trace_id
+      sampled = parent ? parent.sampled? : sample_trace?
+
+      Tracing::Span.new(
+        name: name, trace_id: trace_id, span_id: Tracing.generate_span_id,
+        parent_span_id: parent&.span_id || scope&.span_id, kind: kind,
+        sampled: sampled, reporter: ->(span) { export_span(span) }
+      )
+    end
+
+    def flush(timeout = @configuration.flush_timeout)
+      @batcher.flush(timeout)
+      @span_batcher&.flush(timeout)
+    end
+
+    def close(timeout = @configuration.flush_timeout)
+      @batcher.close(timeout)
+      @span_batcher&.close(timeout)
+    end
+
+    def metrics
+      @metrics.snapshot
+    end
+
+    def reset_metrics
+      @metrics.reset
+    end
+
+    private
+
+    def dispatch(level:, message:, metadata:, scope:, hint:, trace_id:, span_id:,
+                 time:, exception: nil)
+      event = build_event(
+        level: level, message: message, metadata: metadata, scope: scope,
+        exception: exception, trace_id: trace_id, span_id: span_id, time: time
+      )
+      wire = event.to_wire
+
+      wire = run_processors(scope, wire, hint)
+      return nil if wire.nil?
+
+      wire = run_before_send(wire, hint)
+      return nil if wire.nil?
+
+      return nil unless sampled?
+
+      @batcher.enqueue(wire)
+      wire.dig("metadata", "event_id")
+    end
+
+    def build_event(level:, message:, metadata:, scope:, exception:, trace_id:, span_id:, time:)
+      Event.new(
+        service: @configuration.service,
+        level: level,
+        message: message,
+        time: time,
+        metadata: merged_metadata(scope, metadata),
+        tags: scope_value(scope) { |s| s.tags unless s.tags.empty? },
+        user: scope_value(scope, &:user),
+        breadcrumbs: breadcrumbs_for(scope),
+        exception: exception,
+        event_id: SecureRandom.hex(16),
+        release: @configuration.release,
+        environment: @configuration.environment,
+        server_name: @configuration.server_name,
+        session_id: scope_value(scope, &:session_id),
+        trace_id: trace_id || resolve_trace_id(scope),
+        span_id: span_id || resolve_span_id(scope)
+      )
+    end
+
+    # Resolution order: explicit per-entry > active span > scope trace context
+    # (spec 005 section 4).
+    def resolve_trace_id(scope)
+      scope_value(scope) { |s| s.span&.trace_id || s.trace_id }
+    end
+
+    def resolve_span_id(scope)
+      scope_value(scope) { |s| s.span&.span_id || s.span_id }
+    end
+
+    # entry wins over scope, scope wins over global (spec 004 section 4).
+    def merged_metadata(scope, metadata)
+      merged = @configuration.global_metadata.dup
+      merged.merge!(scope.extra) if scope
+      merged.merge!(metadata) if metadata
+      merged
+    end
+
+    def breadcrumbs_for(scope)
+      return nil unless scope
+
+      crumbs = scope.breadcrumbs.to_a
+      crumbs.empty? ? nil : crumbs.map(&:to_h)
+    end
+
+    def scope_value(scope)
+      return nil unless scope
+
+      yield scope
+    end
+
+    def run_processors(scope, wire, hint)
+      return wire unless scope
+
+      scope.event_processors.reduce(wire) do |event, processor|
+        return nil if event.nil?
+
+        processor.call(event, hint)
+      end
+    end
+
+    def run_before_send(wire, hint)
+      hook = @configuration.before_send
+      return wire unless hook
+
+      hook.call(wire, hint)
+    end
+
+    def sampled?
+      sample_at?(@configuration.sample_rate)
+    end
+
+    def sample_trace?
+      sample_at?(@configuration.traces_sample_rate)
+    end
+
+    def sample_at?(rate)
+      return true if rate >= 1.0
+      return false if rate <= 0
+
+      @sampler.call < rate
+    end
+
+    def export_span(span)
+      span_batcher.enqueue(span)
+    end
+
+    def span_batcher
+      @span_batcher ||= build_span_batcher
+    end
+
+    def normalize_level(level)
+      level = level.to_s
+      LEVELS.include?(level) ? level : "info"
+    end
+
+    def build_batcher
+      sender = Transport::HTTP.new(
+        url: @configuration.ingest_url,
+        api_key: @configuration.api_key,
+        timeout: @configuration.flush_timeout
+      )
+      build_transport_batcher(sender: sender, metrics: @metrics)
+    end
+
+    def build_span_batcher
+      sender = Transport::Otlp.new(
+        url: @configuration.otlp_traces_url,
+        api_key: @configuration.api_key,
+        timeout: @configuration.flush_timeout,
+        resource: {
+          service_name: @configuration.service,
+          environment: @configuration.environment,
+          service_version: @configuration.release
+        }
+      )
+      build_transport_batcher(sender: sender, metrics: Metrics.new)
+    end
+
+    def build_transport_batcher(sender:, metrics:)
+      Transport::Batcher.new(
+        sender: sender,
+        metrics: metrics,
+        circuit_breaker: CircuitBreaker.new(
+          threshold: @configuration.circuit_breaker_threshold,
+          reset_timeout: @configuration.circuit_breaker_reset
+        ),
+        retry_policy: RetryPolicy.new(
+          base: @configuration.retry_delay,
+          max_backoff: @configuration.max_backoff,
+          max_retries: @configuration.max_retries
+        ),
+        batch_size: @configuration.batch_size,
+        max_buffer_size: @configuration.max_buffer_size,
+        flush_interval: @configuration.flush_interval,
+        flush_timeout: @configuration.flush_timeout,
+        logger: debug_logger
+      )
+    end
+
+    def debug_logger
+      return nil unless @configuration.debug
+
+      ->(message) { warn(message) }
+    end
+  end
+end