apmlens 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d80552cd71dc91bdca452f949b714ea91ff20171d2e2914cf74aa0bf1f66009
+  data.tar.gz: e3b2920157f387daf32f3e1892f8896020380f47ca3b9fb0a314e8c86bce2c33
+SHA512:
+  metadata.gz: 69afa3bdfbca8277b28324eb8f4ced78ab453d382d3c41d875e3398d449f6a76d77eaaaf4eaa8c68ab5269f6ce8b145e1f69841843947d0417291bdbc31ebc5a
+  data.tar.gz: 1b21f0ce85d6b320d8b8fd3e86c657881c3527feefff27786e9429348a51b2c9e6be40636df2e664cffdfd8ce6b08f416ea0b3a97ddb7e472e5d772a4292a46c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 APMLens Team
+
+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,51 @@
+# APMLens Ruby Gem
+
+The official Ruby agent for [APMLens](https://apmlens.com). 
+
+This gem is designed with the **Power Law** in mind: It delivers 95% of the monitoring value (Error Tracking + P95 Latency) with < 200 lines of code and zero external dependencies.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'apmlens', '~> 1.0'
+```
+
+## Usage
+
+### Rails
+It works automatically. Just configure it in `config/initializers/apmlens.rb`:
+
+```ruby
+Apmlens.configure do |c|
+  c.ingestion_key = ENV['APMLENS_KEY']
+  c.service = 'my-rails-app'
+end
+```
+
+### Manual Usage (Ruby Scripts)
+
+```ruby
+require 'apmlens'
+
+# 1. Config
+Apmlens.configure do |c|
+  c.ingestion_key = 'ik_...'
+end
+
+# 2. Track Errors
+begin
+  risk_method
+rescue => e
+  Apmlens.capture_error(e, user_id: current_user.id)
+end
+
+# 3. Track Metrics (Aggregated automatically)
+Apmlens.capture_trace('job.duration', 500)
+```
+
+## Architecture
+
+*   **In-Memory Buffer**: Metrics are aggregated locally (P95, Avg, Max) and flushed once per minute. This solves the "N+1 Query" scalability problem.
+*   **Non-Blocking**: All network calls happen in a background thread. Your app never waits for APMLens.

data/lib/apmlens/client.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "thread"
+require "singleton"
+
+module Apmlens
+  # The Heavy Lifter.
+  # Handles buffering, threading, and network transmission.
+  class Client
+    include Singleton
+
+    def initialize
+      @queue = Queue.new
+      @metric_buffer = Hash.new { |h, k| h[k] = [] }
+      @metric_lock = Mutex.new
+      @metric_count = 0
+    end
+
+    def start!
+      start_worker_thread!
+    end
+
+    def capture_error(exception, context = {})
+      param_hash = {
+        type: "errors",
+        body: {
+          service: Apmlens.configuration.service,
+          error: {
+            class: exception.class.name,
+            message: exception.message,
+            stack_trace: exception.backtrace&.first(20),
+            occurred_at: Time.now.utc.iso8601,
+            metadata: context
+          }
+        }
+      }
+      enqueue(param_hash)
+    end
+
+    def capture_trace(name, value, tags = {})
+      key = { name: name, tags: tags }
+      config = Apmlens.configuration
+
+      @metric_lock.synchronize do
+        # 1. Series Limit: Check if this is a new series and if we've reached the limit
+        if !@metric_buffer.key?(key) && @metric_buffer.size >= config.max_series_limit
+          return
+        end
+
+        # 2. Samples Limit: Check if we've reached the total samples limit
+        if @metric_count >= config.max_samples_limit
+          return
+        end
+
+        @metric_buffer[key] << value
+        @metric_count += 1
+      end
+    end
+
+    private
+
+    def enqueue(payload)
+      # Circuit Breaker: Drop if queue is full to avoid memory leaks
+      return if @queue.size >= Apmlens.configuration.max_queue_limit
+      @queue.push(payload)
+    end
+
+    def start_worker_thread!
+      return if @worker_thread&.alive?
+
+      @worker_thread = Thread.new do
+        last_flush = Time.now
+        loop do
+          # 1. Process Queue (Non-blocking wait for up to 10s)
+          # We wait less than 60s so we can check if we need to flush metrics
+          begin
+            # Wait up to 10 seconds for an error event
+            item = @queue.pop(timeout: 10)
+            if item
+              send_http(item[:type], item[:body])
+            end
+          rescue ThreadError
+            # Queue empty (legacy behavior if non_block=true used)
+            # Timeout, check metrics flush
+          rescue => e
+            warn "[Apmlens] Worker Error: #{e.message}"
+          end
+
+          # 2. Flush Metrics (Every 60s)
+          if Time.now - last_flush > 60
+            flush_metrics!
+            last_flush = Time.now
+          end
+        end
+      end
+    end
+
+    def flush_metrics!
+      snapshot = {}
+      @metric_lock.synchronize do
+        snapshot = @metric_buffer
+        @metric_buffer = Hash.new { |h, k| h[k] = [] }
+        @metric_count = 0
+      end
+
+      return if snapshot.empty?
+
+      # Client Service Aggregation (P95, Avg, Max)
+      payload = snapshot.map do |key, values|
+        values.compact!
+        next if values.empty?
+
+        sorted = values.sort
+        count = values.size
+        sum = values.sum
+
+        {
+          name: key[:name],
+          tags: key[:tags],
+          stats: {
+            count: count,
+            min: sorted.first,
+            max: sorted.last,
+            avg: sum / count.to_f,
+            p95: sorted[(count * 0.95).to_i]
+          }
+        }
+      end.compact
+
+      send_http("metrics", { service: Apmlens.configuration.service, metrics: payload })
+    end
+
+    def send_http(type, data)
+      uri = URI("#{Apmlens.configuration.endpoint}/api/v1/ingest/#{type}")
+      req = Net::HTTP::Post.new(uri)
+      req["Authorization"] = "Bearer #{Apmlens.configuration.ingestion_key}"
+      req["Content-Type"] = "application/json"
+      req.body = data.to_json
+
+      Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", open_timeout: 2, read_timeout: 5) do |http|
+        http.request(req)
+      end
+    rescue => e
+      warn "[Apmlens] HTTP Error: #{e.message}"
+    end
+  end
+end

data/lib/apmlens/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Apmlens
+  class Configuration
+    attr_accessor :ingestion_key, :service, :endpoint, :environment,
+                  :max_series_limit, :max_samples_limit, :max_queue_limit,
+                  :slow_query_threshold, :large_result_threshold
+
+    def initialize
+      @ingestion_key = ENV["APMLENS_KEY"]
+      @service = "ruby-app"
+      @endpoint = ENV.fetch("APMLENS_ENDPOINT", "https://app.apmlens.com")
+      @environment = ENV.fetch("RAILS_ENV", "development")
+      @enabled = false
+      @max_series_limit = 2_000
+      @max_samples_limit = 100_000
+      @max_queue_limit = 1_000
+      @slow_query_threshold = 500 # ms
+      @large_result_threshold = 2000 # records
+    end
+
+    def enabled?
+      @enabled && !@ingestion_key.nil?
+    end
+
+    def enable!
+      @enabled = true
+    end
+
+    def disable!
+      @enabled = false
+    end
+  end
+end

data/lib/apmlens/query_tracking_middleware.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Apmlens
+  class QueryTrackingMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      Thread.current[:apmlens_query_tracker] = {}
+      @app.call(env)
+    ensure
+      Thread.current[:apmlens_query_tracker] = nil
+    end
+  end
+end

data/lib/apmlens/railtie.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Apmlens
+  class Railtie < Rails::Railtie
+    initializer "apmlens.configure_rails_initialization" do |app|
+      # 1. Subscribe to Unhandled Exceptions (Rails 7+)
+      if app.respond_to?(:error)
+        app.error.subscribe do |error, handled:, severity:, context:, source:|
+          next if handled
+          Apmlens.capture_error(error, context)
+        end
+      end
+
+      # 2. Subscribe to SQL Queries (N+1 Detection Support + Full Table Scan)
+      ActiveSupport::Notifications.subscribe("sql.active_record") do |_, start, finish, _, payload|
+        duration = (finish - start) * 1000
+        Apmlens.capture_trace("db.query", duration, { name: payload[:name] })
+
+        # Track query fingerprints for N+1 detection
+        query_tracker = Thread.current[:apmlens_query_tracker]
+        if query_tracker
+          fingerprint = fingerprint_sql(payload[:sql])
+          query_tracker[fingerprint] ||= 0
+          query_tracker[fingerprint] += 1
+        end
+
+        # Slow Query Detection
+        if duration > Apmlens.configuration.slow_query_threshold
+          Apmlens.capture_trace("slow_query.detected", duration, {
+            sql: payload[:sql],
+            sql_fingerprint: fingerprint_sql(payload[:sql])
+          })
+        end
+      end
+
+      # 3. Request Duration + N+1 Detection
+      ActiveSupport::Notifications.subscribe("process_action.action_controller") do |_, start, finish, _, payload|
+        duration = (finish - start) * 1000
+        Apmlens.capture_trace("http.request", duration, { 
+          controller: payload[:controller], 
+          action: payload[:action],
+          status: payload[:status]
+        })
+
+        # Check for N+1 patterns
+        query_tracker = Thread.current[:apmlens_query_tracker]
+        if query_tracker
+          query_tracker.each do |fingerprint, count|
+            if count > 5  # Threshold for N+1 detection
+              Apmlens.capture_trace("n_plus_one.detected", count, {
+                sql_fingerprint: fingerprint,
+                controller: payload[:controller],
+                action: payload[:action]
+              })
+            end
+          end
+        end
+      end
+
+      # 4. Large Result Set Detection (Memory Bloat)
+      ActiveSupport::Notifications.subscribe("instantiation.active_record") do |_, start, finish, _, payload|
+        record_count = payload[:record_count]
+        
+        if record_count && record_count > Apmlens.configuration.large_result_threshold
+          duration = (finish - start) * 1000
+          Apmlens.capture_trace("large_result_set.detected", duration, {
+            record_count: record_count,
+            class_name: payload[:class_name]
+          })
+        end
+      end
+
+      # 5. Initialize query tracker at the start of each request
+      app.middleware.use Apmlens::QueryTrackingMiddleware
+    end
+
+    private
+
+    def self.fingerprint_sql(sql)
+      return "unknown" if sql.nil?
+      
+      # Remove literals and normalize whitespace
+      normalized = sql.gsub(/\b\d+\b/, '?')                    # Numbers
+                      .gsub(/'[^']*'/, '?')                     # Strings
+                      .gsub(/\s+/, ' ')                         # Whitespace
+                      .strip
+      
+      # Extract table name if possible
+      if normalized =~ /FROM\s+["']?(\w+)["']?/i
+        table = $1
+        "#{table}:#{normalized[0..50]}"
+      else
+        normalized[0..50]
+      end
+    end
+  end
+end

data/lib/apmlens/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Apmlens
+  VERSION = "1.0.0"
+end

data/lib/apmlens.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "apmlens/version"
+require_relative "apmlens/configuration"
+require_relative "apmlens/client"
+require_relative "apmlens/query_tracking_middleware"
+require_relative "apmlens/railtie" if defined?(Rails)
+
+# The Main Entry Point
+# This file is loaded when user does `require 'apmlens'`
+module Apmlens
+  class << self
+    # @return [Apmlens::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the gem in an initializer
+    def configure
+      yield(configuration)
+      configuration.enable!
+      start!
+    end
+
+    # Initialize the background worker
+    def start!
+      return unless configuration.enabled?
+      Client.instance.start!
+    end
+
+    # Public API: Notify an error
+    def capture_error(exception, context = {})
+      return unless configuration.enabled?
+      Client.instance.capture_error(exception, context)
+    end
+
+    # Public API: Record a metric
+    def capture_trace(name, value, tags = {})
+      return unless configuration.enabled?
+      Client.instance.capture_trace(name, value, tags)
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: apmlens
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- APMLens Team
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: A lightweight, non-blocking APM agent that monitors errors and performance
+  metrics with client-side aggregation.
+email:
+- help@apmlens.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/apmlens.rb
+- lib/apmlens/client.rb
+- lib/apmlens/configuration.rb
+- lib/apmlens/query_tracking_middleware.rb
+- lib/apmlens/railtie.rb
+- lib/apmlens/version.rb
+homepage: https://apmlens.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://apmlens.com
+  source_code_uri: https://github.com/apmlens/apmlens
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Official APMLens APM Agent for Ruby
+test_files: []