cloudwatch_query 0.1.0

data/lib/cloudwatch_query/query.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module CloudwatchQuery
+  class Query
+    include Enumerable
+
+    DEFAULT_FIELDS = %w[@timestamp @message @logStream @log].freeze
+
+    def initialize
+      @log_groups = []
+      @conditions = []
+      @fields = DEFAULT_FIELDS.dup
+      @start_time = nil
+      @end_time = nil
+      @limit = nil
+      @sort_field = "@timestamp"
+      @sort_order = "desc"
+    end
+
+    # Log group selection
+    def logs(*groups)
+      @log_groups.concat(groups.flatten)
+      self
+    end
+    alias log_group logs
+
+    # Filtering
+    def where(**conditions)
+      conditions.each do |field, value|
+        field_name = field.to_s.start_with?("@") ? field.to_s : field.to_s
+        @conditions << "#{field_name} = '#{escape_value(value)}'"
+      end
+      self
+    end
+
+    def contains(text)
+      @conditions << "@message like /#{escape_regex(text)}/"
+      self
+    end
+
+    def matches(pattern)
+      @conditions << "@message like /#{pattern}/"
+      self
+    end
+
+    # Time range
+    def since(time)
+      @start_time = TimeHelpers.to_epoch(time)
+      self
+    end
+
+    def before(time)
+      @end_time = TimeHelpers.to_epoch(time)
+      self
+    end
+
+    def between(start_time, end_time)
+      @start_time = TimeHelpers.to_epoch(start_time)
+      @end_time = TimeHelpers.to_epoch(end_time)
+      self
+    end
+
+    def past(amount, unit)
+      seconds = TimeHelpers.duration_in_seconds(amount, unit)
+      @start_time = (Time.now - seconds).to_i
+      @end_time = Time.now.to_i
+      self
+    end
+
+    # Field selection
+    def fields(*field_list)
+      @fields = field_list.flatten.map { |f| f.to_s.start_with?("@") ? f.to_s : "@#{f}" }
+      self
+    end
+
+    def limit(n)
+      @limit = n
+      self
+    end
+
+    def sort(field, order = :desc)
+      @sort_field = field.to_s.start_with?("@") ? field.to_s : "@#{field}"
+      @sort_order = order.to_s
+      self
+    end
+
+    # Execution
+    def execute
+      validate!
+      client.execute(
+        query_string: to_insights_query,
+        log_group_names: @log_groups,
+        start_time: resolved_start_time,
+        end_time: resolved_end_time,
+        limit: resolved_limit
+      )
+    end
+    alias to_a execute
+
+    def each(&block)
+      execute.each(&block)
+    end
+
+    def to_insights_query
+      parts = []
+      parts << "fields #{@fields.join(', ')}"
+      @conditions.each { |c| parts << "filter #{c}" }
+      parts << "sort #{@sort_field} #{@sort_order}"
+      parts << "limit #{resolved_limit}" if resolved_limit
+      parts.join(" | ")
+    end
+
+    private
+
+    def client
+      @client ||= Client.new
+    end
+
+    def config
+      CloudwatchQuery.configuration
+    end
+
+    def resolved_start_time
+      @start_time || (Time.now - config.default_time_range).to_i
+    end
+
+    def resolved_end_time
+      @end_time || Time.now.to_i
+    end
+
+    def resolved_limit
+      @limit || config.default_limit
+    end
+
+    def validate!
+      raise ConfigError, "No log groups specified" if @log_groups.empty?
+    end
+
+    def escape_value(value)
+      value.to_s.gsub("'", "\\\\'")
+    end
+
+    def escape_regex(text)
+      Regexp.escape(text.to_s)
+    end
+  end
+end

data/lib/cloudwatch_query/result.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module CloudwatchQuery
+  class Result
+    attr_reader :data, :parsed, :parser_name
+
+    def initialize(data, registry: nil)
+      @data = data.transform_keys(&:to_sym)
+      @registry = registry
+      @parsed = nil
+      @parser_name = nil
+      parse_message! if @registry
+    end
+
+    def timestamp
+      @data[:timestamp]
+    end
+
+    def message
+      @data[:message]
+    end
+
+    def log_stream
+      @data[:logStream]
+    end
+
+    def log
+      @data[:log]
+    end
+
+    def [](key)
+      @data[key.to_sym]
+    end
+
+    def to_h
+      @data.dup
+    end
+
+    # Check if message was successfully parsed
+    def parsed?
+      !@parsed.nil?
+    end
+
+    # Get the type of parsed log (e.g., :rails_request, :sidekiq)
+    def log_type
+      @parsed&.type
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @data.key?(method_name.to_sym) || super
+    end
+
+    def method_missing(method_name, *args)
+      key = method_name.to_sym
+      return @data[key] if @data.key?(key)
+
+      super
+    end
+
+    private
+
+    def parse_message!
+      return unless message
+
+      @parsed, @parser_name = @registry.parse(message)
+    end
+  end
+end

data/lib/cloudwatch_query/result_set.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module CloudwatchQuery
+  class ResultSet
+    include Enumerable
+
+    attr_reader :results, :statistics
+
+    def initialize(results: [], statistics: {}, registry: nil)
+      @results = results.map { |r| Result.new(r, registry: registry) }
+      @statistics = statistics
+    end
+
+    def each(&block)
+      @results.each(&block)
+    end
+
+    def count
+      @results.count
+    end
+    alias size count
+    alias length count
+
+    def empty?
+      @results.empty?
+    end
+
+    def first(n = nil)
+      n ? @results.first(n) : @results.first
+    end
+
+    def last(n = nil)
+      n ? @results.last(n) : @results.last
+    end
+
+    def to_a
+      @results
+    end
+
+    # Filter results by log type
+    def by_type(type)
+      @results.select { |r| r.log_type == type }
+    end
+
+    # Get only parsed results
+    def parsed
+      @results.select(&:parsed?)
+    end
+
+    # Get only unparsed results
+    def unparsed
+      @results.reject(&:parsed?)
+    end
+
+    # Group results by request_id (for Rails logs)
+    def group_by_request
+      @results
+        .select { |r| r.parsed&.respond_to?(:request_id) && r.parsed.request_id }
+        .group_by { |r| r.parsed.request_id }
+    end
+  end
+end

data/lib/cloudwatch_query/time_helpers.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module CloudwatchQuery
+  module TimeHelpers
+    UNIT_MULTIPLIERS = {
+      seconds: 1,
+      second: 1,
+      minutes: 60,
+      minute: 60,
+      hours: 3600,
+      hour: 3600,
+      days: 86400,
+      day: 86400,
+      weeks: 604800,
+      week: 604800
+    }.freeze
+
+    def self.duration_in_seconds(amount, unit)
+      multiplier = UNIT_MULTIPLIERS[unit.to_sym]
+      raise ConfigError, "Unknown time unit: #{unit}" unless multiplier
+
+      amount * multiplier
+    end
+
+    def self.to_epoch(time)
+      case time
+      when Time, DateTime
+        time.to_i
+      when Integer
+        time
+      when String
+        Time.parse(time).to_i
+      else
+        raise ConfigError, "Cannot convert #{time.class} to epoch time"
+      end
+    end
+
+    def self.parse_relative_time(str)
+      return nil unless str.is_a?(String)
+
+      match = str.match(/^(\d+)(s|m|h|d|w)$/)
+      return nil unless match
+
+      amount = match[1].to_i
+      unit = case match[2]
+             when "s" then :seconds
+             when "m" then :minutes
+             when "h" then :hours
+             when "d" then :days
+             when "w" then :weeks
+             end
+
+      Time.now - duration_in_seconds(amount, unit)
+    end
+  end
+end

data/lib/cloudwatch_query/version.rb

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

data/lib/cloudwatch_query.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "cloudwatch_query/version"
+require_relative "cloudwatch_query/errors"
+require_relative "cloudwatch_query/configuration"
+require_relative "cloudwatch_query/time_helpers"
+require_relative "cloudwatch_query/parsers"
+require_relative "cloudwatch_query/result"
+require_relative "cloudwatch_query/result_set"
+require_relative "cloudwatch_query/client"
+require_relative "cloudwatch_query/query"
+
+module CloudwatchQuery
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Parser registry - manages log message parsers
+    def parsers
+      @parsers ||= begin
+        registry = Parsers::Registry.new
+        registry.register(*Parsers.default_parsers)
+        registry
+      end
+    end
+
+    # Reset parsers to defaults
+    def reset_parsers!
+      @parsers = nil
+      parsers
+    end
+
+    # Start a query for the specified log groups
+    def logs(*groups)
+      Query.new.logs(*groups)
+    end
+    alias log_group logs
+
+    # Quick search shorthand
+    def search(term, groups:, since: nil, limit: nil)
+      query = Query.new.logs(*Array(groups)).contains(term)
+      query = query.since(since) if since
+      query = query.limit(limit) if limit
+      query.execute
+    end
+
+    # List available log groups
+    def list_log_groups(prefix: nil)
+      Client.new.list_log_groups(prefix: prefix)
+    end
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: cloudwatch_query
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Igor Irianto
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-02-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-cloudwatchlogs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Query AWS CloudWatch Logs using a fluent, ActiveRecord-style interface.
+  Supports chainable queries, automatic Insights query generation, and enumerable
+  results.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- cloudwatch_query.gemspec
+- lib/cloudwatch_query.rb
+- lib/cloudwatch_query/client.rb
+- lib/cloudwatch_query/configuration.rb
+- lib/cloudwatch_query/errors.rb
+- lib/cloudwatch_query/parsers.rb
+- lib/cloudwatch_query/parsers/base.rb
+- lib/cloudwatch_query/parsers/rails/rails_log.rb
+- lib/cloudwatch_query/parsers/rails/sub_parsers.rb
+- lib/cloudwatch_query/parsers/rails_parser.rb
+- lib/cloudwatch_query/parsers/registry.rb
+- lib/cloudwatch_query/parsers/sidekiq/sidekiq_log.rb
+- lib/cloudwatch_query/parsers/sidekiq/sub_parsers.rb
+- lib/cloudwatch_query/parsers/sidekiq_parser.rb
+- lib/cloudwatch_query/query.rb
+- lib/cloudwatch_query/result.rb
+- lib/cloudwatch_query/result_set.rb
+- lib/cloudwatch_query/time_helpers.rb
+- lib/cloudwatch_query/version.rb
+homepage: https://github.com/iggredible/cloudwatch_query
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/iggredible/cloudwatch_query
+  source_code_uri: https://github.com/iggredible/cloudwatch_query
+  changelog_uri: https://github.com/iggredible/cloudwatch_query/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: A Ruby gem for querying AWS CloudWatch Logs with a simple, chainable interface
+test_files: []