miniapm 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 525eb11f5af8c0b35aedcb05f67523d4f390c56af7fd3fd1dc3169ad1f934967
+  data.tar.gz: '09aa0e5d42736b39c895174cdddc9aec4944de4168beae335c6e335b212fb3ba'
+SHA512:
+  metadata.gz: bfd98917e4502be3f040ade6c9b5e1666d3a0e1f05d99cda07be033eee5f82d99e8e5584906d6e09514b01c2e8dd22d4ed9e6e76beab24cd16240d4a1d9e321d
+  data.tar.gz: 9b8f7707deb4cd5c3a941c87c5416a64188527fe19c605c3fdc37a27f1ac3df44cf0a6de3c5acc72f4ef0fe67bb870e711418ac28ded78c726fff9538a8077ac

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-01-03
+
+### Added
+- Initial release
+- OTLP trace export to MiniAPM server
+- Error tracking with fingerprinting and parameter filtering
+- W3C Trace Context support for distributed tracing
+- Automatic instrumentation for:
+  - Rails (ActionController, ActionView)
+  - ActiveRecord
+  - ActiveJob (SolidQueue, Sidekiq adapter)
+  - Sidekiq
+  - Rails Cache
+  - Net::HTTP
+  - HTTParty
+  - Faraday
+  - Elasticsearch
+  - OpenSearch
+  - Searchkick
+  - Redis (redis-client and legacy redis gem)
+- Async batched sending with configurable batch size and flush interval
+- Sampling support with configurable sample rate
+- Rails generator for easy setup (`rails g miniapm:install`)
+- Testing helpers for capturing spans and errors in tests
+- Health check endpoint verification
+- Retry logic with exponential backoff for failed exports
+
+### Security
+- Automatic parameter filtering for sensitive data
+- SQL query sanitization option
+- No sensitive data logged by default
+
+[Unreleased]: https://github.com/miniapm/miniapm-ruby/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/miniapm/miniapm-ruby/releases/tag/v1.0.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Chris Hasinski
+
+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,174 @@
+# MiniAPM Ruby Client
+
+A lightweight, zero-dependency APM client for Rails applications. Exports traces in OTLP format, captures errors, and provides comprehensive instrumentation.
+
+**Website:** [miniapm.com](https://miniapm.com)
+
+## Features
+
+- **OTLP Compatible**: Exports traces in OpenTelemetry Protocol format
+- **Error Tracking**: Automatic exception capture with fingerprinting
+- **W3C Trace Context**: Distributed tracing across microservices
+- **Zero Runtime Dependencies**: Uses only Ruby stdlib
+- **Auto-instrumentation**: Detects and instruments installed gems
+- **Non-blocking**: Async batched sending never blocks requests
+
+## Supported Instrumentations
+
+| Category | Library | Method |
+|----------|---------|--------|
+| **Rails** | ActionController, ActionView | ActiveSupport::Notifications |
+| **Database** | ActiveRecord | ActiveSupport::Notifications |
+| **Background Jobs** | ActiveJob, SolidQueue | ActiveSupport::Notifications |
+| **Background Jobs** | Sidekiq | Server Middleware |
+| **Cache** | Rails Cache | ActiveSupport::Notifications |
+| **HTTP Clients** | Net::HTTP | Monkey-patch |
+| **HTTP Clients** | HTTParty | Monkey-patch |
+| **HTTP Clients** | Faraday | Auto-injected Middleware |
+| **Search** | Elasticsearch | Monkey-patch |
+| **Search** | OpenSearch | Monkey-patch |
+| **Search** | Searchkick | ActiveSupport::Notifications |
+| **Redis** | redis-client | Middleware |
+| **Redis** | redis (legacy) | Monkey-patch |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'miniapm'
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate miniapm:install
+```
+
+## Configuration
+
+Set environment variables:
+
+```bash
+export MINI_APM_URL="http://your-miniapm-server:3000"
+export MINI_APM_API_KEY="your_project_api_key"
+```
+
+Or configure in `config/initializers/miniapm.rb`:
+
+```ruby
+MiniAPM.configure do |config|
+  # Required
+  config.endpoint = ENV["MINI_APM_URL"]
+  config.api_key = ENV["MINI_APM_API_KEY"]
+
+  # Service identification
+  config.service_name = "my-rails-app"
+  config.environment = Rails.env
+
+  # Sampling (0.0 to 1.0)
+  config.sample_rate = 1.0
+
+  # Batching
+  config.batch_size = 100
+  config.flush_interval = 5.0
+
+  # Configure instrumentations
+  config.instrument :activerecord, log_sql: true
+  config.instrument :redis, enabled: false
+
+  # Error filtering
+  config.ignored_exceptions = ["ActionController::RoutingError"]
+  config.filter_parameters = [:password, :token]
+
+  # Disable in test
+  config.enabled = !Rails.env.test?
+end
+```
+
+## Manual Instrumentation
+
+Create custom spans:
+
+```ruby
+MiniAPM.span("process_order", category: :internal) do |span|
+  span.add_attribute("order.id", order.id)
+  span.add_attribute("order.total", order.total)
+
+  process_order(order)
+end
+```
+
+Report errors manually:
+
+```ruby
+begin
+  risky_operation
+rescue => e
+  MiniAPM.record_error(e, context: {
+    user_id: current_user.id,
+    params: { order_id: params[:id] }
+  })
+  raise
+end
+```
+
+## Distributed Tracing
+
+MiniAPM automatically propagates trace context using W3C Trace Context headers. When making HTTP requests with instrumented clients (Net::HTTP, HTTParty, Faraday), the `traceparent` header is automatically injected.
+
+For incoming requests, MiniAPM extracts the trace context from the `traceparent` header to continue the trace.
+
+## Testing
+
+Disable MiniAPM in tests:
+
+```ruby
+# config/initializers/miniapm.rb
+config.enabled = !Rails.env.test?
+```
+
+Or use the test helpers:
+
+```ruby
+require 'miniapm/testing'
+
+RSpec.describe "MyFeature", :miniapm do
+  it "tracks spans" do
+    perform_action
+
+    expect(MiniAPM::Testing.recorded_spans).to include(
+      having_attributes(name: /process_action/)
+    )
+  end
+end
+```
+
+## Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `endpoint` | `http://localhost:3000` | MiniAPM server URL |
+| `api_key` | `nil` | API key for authentication |
+| `service_name` | `rails-app` | Service identifier |
+| `environment` | `Rails.env` | Deployment environment |
+| `sample_rate` | `1.0` | Sampling rate (0.0 to 1.0) |
+| `batch_size` | `100` | Max spans per batch |
+| `flush_interval` | `5.0` | Seconds between flushes |
+| `max_queue_size` | `10000` | Max queued items |
+| `enabled` | `true` | Enable/disable tracing |
+| `auto_start` | `true` | Start on Rails boot |
+
+## Requirements
+
+- Ruby 3.0+
+- Rails 7.0+ (optional, for auto-setup)
+
+## License
+
+MIT
+
+---
+
+[Documentation](https://miniapm.com/docs) | [Source Code](https://github.com/miniapm/miniapm-ruby)

data/lib/generators/miniapm/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Miniapm
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a MiniAPM initializer file at config/initializers/miniapm.rb"
+
+      def create_initializer_file
+        template "initializer.rb", "config/initializers/miniapm.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+
+      private
+
+      def readme(path)
+        say File.read(File.expand_path(path, self.class.source_root))
+      end
+    end
+  end
+end

data/lib/generators/miniapm/templates/README

@@ -0,0 +1,19 @@
+
+===============================================================================
+
+MiniAPM has been installed!
+
+Next steps:
+
+1. Set your API key in your environment:
+
+   export MINI_APM_API_KEY="your_project_api_key"
+   export MINI_APM_URL="http://your-miniapm-server:3000"
+
+2. Review the generated config/initializers/miniapm.rb file
+
+3. Start your Rails server and MiniAPM will begin collecting traces
+
+For more information, see: https://github.com/hasik/miniapm
+
+===============================================================================

data/lib/generators/miniapm/templates/initializer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# MiniAPM Configuration
+# Documentation: https://miniapm.com/docs
+MiniAPM.configure do |config|
+  # Required: MiniAPM server endpoint
+  config.endpoint = ENV.fetch("MINI_APM_URL", "http://localhost:3000")
+
+  # Required: API key for authentication
+  config.api_key = ENV["MINI_APM_API_KEY"]
+
+  # Service identification
+  config.service_name = ENV.fetch("MINI_APM_SERVICE_NAME", "<%= Rails.application.class.module_parent_name.underscore.dasherize %>")
+  config.environment = Rails.env
+
+  # Optional: Service version for tracking deployments
+  # config.service_version = ENV["APP_VERSION"]
+
+  # Optional: Git SHA for deployment tracking
+  # config.git_sha = ENV["GIT_SHA"] || ENV["HEROKU_SLUG_COMMIT"]
+
+  # Batching configuration (defaults are usually fine)
+  # config.batch_size = 100         # Max spans per batch
+  # config.flush_interval = 5.0     # Seconds between flushes
+  # config.max_queue_size = 10_000  # Max queued items before dropping
+
+  # Sampling (1.0 = 100%, 0.1 = 10%)
+  # Useful for high-traffic applications
+  config.sample_rate = Rails.env.production? ? 1.0 : 1.0
+
+  # Enable/disable specific instrumentations
+  # config.instrument :activerecord, log_sql: true  # Include SQL in spans
+  # config.instrument :redis, enabled: false        # Disable Redis tracing
+
+  # Error tracking configuration
+  # Exceptions to ignore (won't be reported)
+  config.ignored_exceptions = [
+    "ActionController::RoutingError",
+    "ActionController::InvalidAuthenticityToken",
+    "ActionController::UnknownFormat",
+    "ActiveRecord::RecordNotFound"
+  ]
+
+  # Parameters to filter from error reports (merged with Rails defaults)
+  config.filter_parameters = Rails.application.config.filter_parameters
+
+  # Custom span modification (return false to drop span)
+  # config.before_send = ->(span) {
+  #   # Add custom attributes
+  #   span.add_attribute("custom.attribute", "value")
+  #
+  #   # Return false to drop this span
+  #   # return false if span.name.include?("health_check")
+  #
+  #   true
+  # }
+
+  # Disable in test environment
+  config.enabled = !Rails.env.test?
+end

data/lib/miniapm/configuration.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module MiniAPM
+  class Configuration
+    # Core settings
+    attr_accessor :endpoint          # MiniAPM server URL
+    attr_accessor :api_key           # Bearer token for authentication
+    attr_accessor :enabled           # Enable/disable the gem
+    attr_accessor :auto_start        # Auto-start on Rails boot
+
+    # Service identification
+    attr_accessor :service_name      # e.g., "my-rails-app"
+    attr_accessor :service_version   # e.g., "1.2.3"
+    attr_accessor :environment       # e.g., "production"
+
+    # Metadata
+    attr_accessor :host              # Hostname
+    attr_accessor :rails_version     # Auto-detected
+    attr_accessor :ruby_version      # Auto-detected
+    attr_accessor :git_sha           # Git SHA for deploys
+
+    # Batching settings
+    attr_accessor :batch_size        # Max spans per batch
+    attr_accessor :flush_interval    # Seconds between flushes
+    attr_accessor :max_queue_size    # Max queued items before dropping
+
+    # Instrumentation toggles
+    attr_reader :instrumentations
+
+    # Sampling
+    attr_accessor :sample_rate       # 0.0 to 1.0
+
+    # Error filtering
+    attr_accessor :ignored_exceptions
+
+    # Parameter filtering
+    attr_accessor :filter_parameters
+
+    # Callbacks
+    attr_accessor :before_send       # Proc to modify/filter spans
+
+    def initialize
+      @endpoint = ENV.fetch("MINI_APM_URL", "http://localhost:3000")
+      @api_key = ENV["MINI_APM_API_KEY"]
+      @enabled = true
+      @auto_start = true
+
+      @service_name = ENV.fetch("MINI_APM_SERVICE_NAME", "rails-app")
+      @service_version = ENV["MINI_APM_SERVICE_VERSION"]
+      @environment = ENV.fetch("RAILS_ENV", ENV.fetch("RACK_ENV", "development"))
+
+      @host = Socket.gethostname rescue "unknown"
+      @rails_version = defined?(Rails::VERSION::STRING) ? Rails::VERSION::STRING : nil
+      @ruby_version = RUBY_VERSION
+      @git_sha = ENV["GIT_SHA"] || ENV["HEROKU_SLUG_COMMIT"] || detect_git_sha
+
+      @batch_size = 100
+      @flush_interval = 5.0
+      @max_queue_size = 10_000
+
+      @instrumentations = InstrumentationConfig.new
+
+      @sample_rate = 1.0
+
+      @ignored_exceptions = [
+        "ActionController::RoutingError",
+        "ActionController::InvalidAuthenticityToken",
+        "ActionController::UnknownFormat",
+        "ActiveRecord::RecordNotFound"
+      ]
+
+      @filter_parameters = [:password, :password_confirmation, :token, :secret, :api_key, :access_token]
+
+      @before_send = nil
+    end
+
+    def instrument(name, enabled: true, **options)
+      @instrumentations.configure(name, enabled: enabled, **options)
+    end
+
+    # Validate configuration and raise on errors
+    def validate!
+      errors = []
+
+      # Validate endpoint
+      if @endpoint.nil? || @endpoint.empty?
+        errors << "endpoint is required"
+      else
+        begin
+          uri = URI.parse(@endpoint)
+          unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+            errors << "endpoint must be an HTTP(S) URL"
+          end
+        rescue URI::InvalidURIError
+          errors << "endpoint is not a valid URL"
+        end
+      end
+
+      # Validate sample_rate
+      unless @sample_rate.is_a?(Numeric) && @sample_rate >= 0.0 && @sample_rate <= 1.0
+        errors << "sample_rate must be a number between 0.0 and 1.0"
+      end
+
+      # Validate batch settings
+      errors << "batch_size must be a positive integer" unless @batch_size.is_a?(Integer) && @batch_size > 0
+      errors << "flush_interval must be a positive number" unless @flush_interval.is_a?(Numeric) && @flush_interval > 0
+      errors << "max_queue_size must be a positive integer" unless @max_queue_size.is_a?(Integer) && @max_queue_size > 0
+
+      # Warn about missing api_key (not an error, as it might be set later)
+      if @api_key.nil? || @api_key.empty?
+        MiniAPM.logger.warn { "MiniAPM: api_key is not configured - requests will fail" }
+      end
+
+      raise ConfigurationError, "Invalid configuration: #{errors.join(', ')}" if errors.any?
+
+      true
+    end
+
+    def valid?
+      validate!
+      true
+    rescue ConfigurationError
+      false
+    end
+
+    private
+
+    def detect_git_sha
+      sha = `git rev-parse HEAD 2>/dev/null`.strip
+      sha.empty? ? nil : sha
+    rescue StandardError
+      nil
+    end
+  end
+
+  class InstrumentationConfig
+    DEFAULTS = {
+      rails: { enabled: true },
+      activerecord: { enabled: true, log_sql: false },
+      activejob: { enabled: true },
+      sidekiq: { enabled: true },
+      cache: { enabled: true },
+      net_http: { enabled: true },
+      httparty: { enabled: true },
+      faraday: { enabled: true },
+      opensearch: { enabled: true },
+      elasticsearch: { enabled: true },
+      searchkick: { enabled: true },
+      redis: { enabled: true },
+      redis_client: { enabled: true }
+    }.freeze
+
+    def initialize
+      @config = DEFAULTS.transform_values(&:dup)
+    end
+
+    def configure(name, **options)
+      @config[name.to_sym] ||= {}
+      @config[name.to_sym].merge!(options)
+    end
+
+    def [](name)
+      @config[name.to_sym] || { enabled: false }
+    end
+
+    def enabled?(name)
+      self[name][:enabled]
+    end
+
+    def options(name)
+      self[name]
+    end
+  end
+end

data/lib/miniapm/context.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module MiniAPM
+  # Fiber-safe context for trace propagation
+  # Uses Fiber.[] storage (Ruby 3.2+) with Thread.current fallback
+  module Context
+    TRACE_KEY = :miniapm_trace
+    SPAN_STACK_KEY = :miniapm_span_stack
+
+    class << self
+      # Ruby 3.2+ has Fiber.[] for fiber-local storage
+      # Fall back to Thread.current for older Ruby (not fiber-safe)
+      if Fiber.respond_to?(:[])
+        def current_trace
+          Fiber[TRACE_KEY]
+        end
+
+        def current_trace=(trace)
+          Fiber[TRACE_KEY] = trace
+        end
+
+        def span_stack
+          Fiber[SPAN_STACK_KEY] ||= []
+        end
+
+        def span_stack=(stack)
+          Fiber[SPAN_STACK_KEY] = stack
+        end
+      else
+        # Fallback for Ruby < 3.2 (not fiber-safe, but thread-safe)
+        def current_trace
+          Thread.current[TRACE_KEY]
+        end
+
+        def current_trace=(trace)
+          Thread.current[TRACE_KEY] = trace
+        end
+
+        def span_stack
+          Thread.current[SPAN_STACK_KEY] ||= []
+        end
+
+        def span_stack=(stack)
+          Thread.current[SPAN_STACK_KEY] = stack
+        end
+      end
+
+      def current_trace_id
+        current_trace&.trace_id
+      end
+
+      def current_span
+        span_stack.last
+      end
+
+      def push_span(span)
+        span_stack.push(span)
+      end
+
+      def pop_span
+        span_stack.pop
+      end
+
+      def with_span(span)
+        push_span(span)
+        yield span
+      ensure
+        pop_span
+      end
+
+      def with_trace(trace)
+        old_trace = current_trace
+        old_stack = span_stack
+
+        self.current_trace = trace
+        self.span_stack = []
+
+        yield trace
+      ensure
+        self.current_trace = old_trace
+        self.span_stack = old_stack
+      end
+
+      def clear!
+        self.current_trace = nil
+        self.span_stack = nil
+      end
+
+      def fiber_safe?
+        Fiber.respond_to?(:[])
+      end
+
+      # Extract trace context from incoming HTTP headers (W3C Trace Context)
+      # Format: 00-{trace_id}-{parent_span_id}-{flags}
+      # Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+      def extract_from_headers(headers)
+        traceparent = headers["traceparent"] ||
+                      headers["HTTP_TRACEPARENT"] ||
+                      headers["Traceparent"]
+        return nil unless traceparent
+
+        parts = traceparent.to_s.split("-")
+        return nil unless parts.length == 4
+        return nil unless parts[0] == "00" # version check
+
+        trace_id = parts[1]
+        parent_span_id = parts[2]
+        flags = parts[3].to_i(16)
+
+        # Validate format
+        return nil unless trace_id.match?(/\A[0-9a-f]{32}\z/)
+        return nil unless parent_span_id.match?(/\A[0-9a-f]{16}\z/)
+
+        {
+          trace_id: trace_id,
+          parent_span_id: parent_span_id,
+          sampled: (flags & 0x01) == 1
+        }
+      end
+
+      # Inject trace context into outgoing HTTP headers (W3C Trace Context)
+      def inject_into_headers(headers)
+        return headers unless current_span
+
+        flags = current_trace&.sampled? ? "01" : "00"
+        traceparent = format(
+          "00-%s-%s-%s",
+          current_trace_id,
+          current_span.span_id,
+          flags
+        )
+
+        headers["traceparent"] = traceparent
+        headers
+      end
+    end
+  end
+end