sumologic-query 1.3.3 → 1.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f674ac09efecc2c167df4d3853be9d9bd5c1c043bf6e0d574f068770e9979a8b
-  data.tar.gz: 4e43daf71638156ad4ac9f72b862daf501f4714037b3cee603aac1a6e8de1efb
+  metadata.gz: 72c4c0c9c57655df15506b9be19a21de47398ba2a2aedaae8e8d22d3efbd0873
+  data.tar.gz: 9cd38107b915187cb699e32305c8af8e6a970c2ea24c2b2340a443cc0a0e2637
 SHA512:
-  metadata.gz: cc1c1a801d4c0dcf282ae281cc4da00eb125095b036f45489cda7c74638e4116fde5ad5c317896fb8e05988fd143887d7b470f31d02fba10426cc3c3c7bd78a0
-  data.tar.gz: 3b360acf874598ea9ca2513d1ddd507c617e970b94f79efb5029fc3a2e37e807b1f8aac2e3e9cbe95793ef0d74f210fd2ab13e9d7d3f0d25fad446014f6f46cb
+  metadata.gz: a073e490f4714e8f11c8c495775937dd42bb420535c38d82137a71a940b4b9db2b9fe33d4e6ec4b7745385a7661ec657db5472b9761dbecc110fb473efca757f
+  data.tar.gz: 3a9aa83222b99b34fbcdceb45f2e1cdd126c29d28ba4a93db818ea34438b366f7a7b5eb0290f7986e0a9ef9d5deaed95465cca45a72468ec432ec5d6d97a29f4

data/CHANGELOG.md

@@ -6,6 +6,23 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and release notes are automatically generated from commit messages.
+## [1.3.4](https://github.com/patrick204nqh/sumologic-query/compare/v1.3.3...v1.3.4) (2025-11-19)
+
+### 🎉 New Features
+
+- add time parsing utility and enhance CLI time options for flexible querying
+- enhance debug logging to include request headers for better traceability
+
+### 🐛 Bug Fixes
+
+- freeze regex for relative time parsing and improve error message formatting
+
+### 📚 Documentation
+
+- update README and examples to enhance time format usage and add new time format examples
+
+
+
 ## [1.3.3](https://github.com/patrick204nqh/sumologic-query/compare/v1.3.2...v1.3.3) (2025-11-17)
 
 ### 🎉 New Features

data/README.md

@@ -8,8 +8,11 @@
 
 ## Why This Tool?
 
+- **Intuitive time parsing**: Use relative times like `-1h`, `-30m`, or `now` - no more calculating timestamps!
+- **Flexible timezone support**: US, Australian, and IANA timezone formats supported
 - **Minimal dependencies**: Uses only Ruby stdlib + Thor for CLI
 - **Fast queries**: Efficient polling and automatic pagination
+- **Interactive mode**: Explore logs with FZF-powered fuzzy search and preview
 - **Simple interface**: Just query, get results, done
 - **Read-only**: No write operations, perfect for safe log access
 - **Modular architecture**: Clean separation of concerns (HTTP, Search, Metadata)
@@ -62,7 +65,13 @@ export SUMO_DEPLOYMENT="us2"  # Optional: us1, us2 (default), eu, au, etc.
 ### 2. Run Your First Query
 
 ```bash
-# Search logs
+# Search logs from last hour (easy!)
+sumo-query search --query 'error' --from '-1h' --to 'now' --limit 10
+
+# Search logs from last 30 minutes
+sumo-query search --query 'error' --from '-30m' --to 'now'
+
+# Or use ISO 8601 format
 sumo-query search --query 'error' \
   --from '2025-11-13T14:00:00' \
   --to '2025-11-13T15:00:00' \
@@ -108,13 +117,13 @@ sumo-query search --query "YOUR_QUERY" \
 Explore your logs interactively with a powerful FZF-based interface:
 
 ```bash
-# Launch interactive mode
-sumo-query search --query 'error' \
-  --from '2025-11-13T14:00:00' \
-  --to '2025-11-13T15:00:00' \
-  --interactive
+# Launch interactive mode - last hour
+sumo-query search --query 'error' --from '-1h' --to 'now' --interactive
 
-# Or use the shorthand
+# Last 30 minutes with shorthand
+sumo-query search -q 'error' -f '-30m' -t 'now' -i
+
+# Or use ISO 8601 format
 sumo-query search -q 'error' -f '2025-11-13T14:00:00' -t '2025-11-13T15:00:00' -i
 ```
 
@@ -141,6 +150,27 @@ sumo-query search -q 'error' -f '2025-11-13T14:00:00' -t '2025-11-13T15:00:00' -
 - Install FZF: `brew install fzf` (macOS) or `apt-get install fzf` (Linux)
 - See: https://github.com/junegunn/fzf#installation
 
+### Time Format Examples
+
+Combine relative times with timezones for powerful queries:
+
+```bash
+# Last hour in Sydney time
+sumo-query search -q 'error' -f '-1h' -t 'now' -z AEST
+
+# Last 30 minutes in US Eastern time
+sumo-query search -q 'error' -f '-30m' -t 'now' -z EST
+
+# Last 7 days with output to file (directories auto-created)
+sumo-query search -q 'error' -f '-7d' -t 'now' -o logs/weekly/errors.json
+
+# Mix relative and ISO 8601 formats
+sumo-query search -q 'error' -f '-24h' -t '2025-11-19T12:00:00'
+
+# Unix timestamps from last hour to now
+sumo-query search -q 'error' -f '1700000000' -t 'now'
+```
+
 ### List Collectors
 
 ```bash
@@ -157,12 +187,9 @@ sumo-query sources [--output FILE]
 
 Lists all sources from active collectors.
 
-**See [examples/queries.md](examples/queries.md) for more query patterns and examples.**
 
 ## Ruby Library Usage
 
-Use the library directly in your Ruby code:
-
 ```ruby
 require 'sumologic'
 
@@ -182,35 +209,48 @@ results = client.search(
   limit: 1000
 )
 
-results.each do |message|
-  puts message['map']['message']
-end
-
-# List collectors
+# List collectors and sources
 collectors = client.list_collectors
-
-# List all sources
 sources = client.list_all_sources
 ```
 
-**See [docs/api-reference.md](docs/api-reference.md) for complete API documentation.**
+**Time parsing utilities:**
+
+```ruby
+require 'sumologic/utils/time_parser'
+
+# Parse relative times and timezones
+from_time = Sumologic::Utils::TimeParser.parse('-1h')
+timezone = Sumologic::Utils::TimeParser.parse_timezone('AEST')
+```
+
 
 ## Time Formats
 
-Use ISO 8601 format for timestamps:
+Multiple time formats are supported:
 
 ```bash
-# UTC timestamps (default)
---from "2025-11-13T14:30:00" --to "2025-11-13T15:00:00"
+# Relative time (easiest!)
+sumo-query search -q 'error' -f '-1h' -t 'now'
+sumo-query search -q 'error' -f '-30m' -t 'now'
+
+# ISO 8601
+sumo-query search -q 'error' -f '2025-11-13T14:00:00' -t '2025-11-13T15:00:00'
 
-# With timezone
---from "2025-11-13T14:30:00" --time-zone "America/New_York"
+# Unix timestamps
+sumo-query search -q 'error' -f '1700000000' -t 'now'
 
-# Using shell helpers
---from "$(date -u -v-1H '+%Y-%m-%dT%H:%M:%S')"  # 1 hour ago
---to "$(date -u '+%Y-%m-%dT%H:%M:%S')"          # now
+# With timezones
+sumo-query search -q 'error' -f '-1h' -t 'now' -z 'AEST'
+sumo-query search -q 'error' -f '-1h' -t 'now' -z 'America/New_York'
 ```
 
+**Supported time units:** `s`, `m`, `h`, `d`, `w`, `M`, `now`
+
+**Supported timezones:** IANA names (`UTC`, `America/New_York`, `Australia/Sydney`), US abbreviations (`EST`, `PST`), Australian abbreviations (`AEST`, `ACST`, `AWST`), UTC offsets (`+10:00`)
+
+See [examples/time-formats.md](examples/time-formats.md) for comprehensive examples.
+
 ## Output Format
 
 Results are returned as JSON:
@@ -253,11 +293,10 @@ Query execution time depends on data volume:
 
 ## Documentation
 
-- **[Quick Reference (tldr)](docs/tldr.md)** - Concise command examples in tldr format
-- **[Query Examples](examples/queries.md)** - Common query patterns and use cases
-- **[API Reference](docs/api-reference.md)** - Complete Ruby library documentation
-- **[Architecture](docs/architecture/)** - System design and architecture decisions
-- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
+- **[Quick Reference (tldr)](docs/tldr.md)** - Concise command examples
+- **[Query Examples](examples/queries.md)** - Common query patterns
+- **[Time Format Examples](examples/time-formats.md)** - Time parsing and timezone options
+- **[Architecture](docs/architecture/)** - Design and architecture decisions
 
 ## Development
 
@@ -271,16 +310,19 @@ git clone https://github.com/patrick204nqh/sumologic-query.git
 cd sumologic-query
 bundle install
 
-# Run tests
+# Run tests (73+ specs including time parser tests)
 bundle exec rspec
 
 # Run linter
 bundle exec rubocop
 
-# Test locally
+# Test locally with new time formats
+bundle exec bin/sumo-query search --query "error" \
+  --from "-1h" --to "now"
+
+# Test with timezone support
 bundle exec bin/sumo-query search --query "error" \
-  --from "2025-11-13T14:00:00" \
-  --to "2025-11-13T15:00:00"
+  --from "-30m" --to "now" --time-zone "AEST"
 ```
 
 ## Contributing

data/lib/sumologic/cli/commands/base_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'fileutils'
+
 module Sumologic
   class CLI < Thor
     module Commands
@@ -19,6 +21,10 @@ module Sumologic
           json_output = JSON.pretty_generate(data)
 
           if options[:output]
+            # Create parent directories if they don't exist
+            output_dir = File.dirname(options[:output])
+            FileUtils.mkdir_p(output_dir) unless output_dir == '.'
+
             File.write(options[:output], json_output)
             warn "\nResults saved to: #{options[:output]}"
           else

data/lib/sumologic/cli/commands/search_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'base_command'
+require_relative '../../utils/time_parser'
 
 module Sumologic
   class CLI < Thor
@@ -8,6 +9,7 @@ module Sumologic
       # Handles the search command execution
       class SearchCommand < BaseCommand
         def execute
+          parse_time_options
           log_search_info
           results = perform_search
 
@@ -22,11 +24,26 @@ module Sumologic
 
         private
 
+        def parse_time_options
+          # Parse time formats and store both original and parsed values
+          @original_from = options[:from]
+          @original_to = options[:to]
+          @parsed_from = Utils::TimeParser.parse(options[:from])
+          @parsed_to = Utils::TimeParser.parse(options[:to])
+          @parsed_timezone = Utils::TimeParser.parse_timezone(options[:time_zone])
+        rescue Utils::TimeParser::ParseError => e
+          warn "Error parsing time: #{e.message}"
+          exit 1
+        end
+
         def log_search_info
           warn '=' * 60
           warn 'Sumo Logic Search Query'
           warn '=' * 60
-          warn "Time Range: #{options[:from]} to #{options[:to]}"
+          warn "Time Range: #{@original_from} to #{@original_to}"
+          if @original_from != @parsed_from || @original_to != @parsed_to
+            warn "  (Parsed: #{@parsed_from} to #{@parsed_to})"
+          end
           warn "Query: #{options[:query]}"
           warn "Limit: #{options[:limit] || 'unlimited'}"
           warn '-' * 60
@@ -37,9 +54,9 @@ module Sumologic
         def perform_search
           client.search(
             query: options[:query],
-            from_time: options[:from],
-            to_time: options[:to],
-            time_zone: options[:time_zone],
+            from_time: @parsed_from,
+            to_time: @parsed_to,
+            time_zone: @parsed_timezone,
             limit: options[:limit]
           )
         end
@@ -54,9 +71,11 @@ module Sumologic
         def output_search_results(results)
           output_json(
             query: options[:query],
-            from: options[:from],
-            to: options[:to],
-            time_zone: options[:time_zone],
+            from: @parsed_from,
+            to: @parsed_to,
+            from_original: @original_from,
+            to_original: @original_to,
+            time_zone: @parsed_timezone,
             message_count: results.size,
             messages: results
           )
@@ -75,9 +94,9 @@ module Sumologic
         def build_formatted_results(results)
           {
             'query' => options[:query],
-            'from' => options[:from],
-            'to' => options[:to],
-            'time_zone' => options[:time_zone],
+            'from' => @parsed_from,
+            'to' => @parsed_to,
+            'time_zone' => @parsed_timezone,
             'message_count' => results.size,
             'messages' => results
           }

data/lib/sumologic/cli.rb

@@ -26,25 +26,38 @@ module Sumologic
     long_desc <<~DESC
       Search Sumo Logic logs using a query string.
 
+      Time Formats:
+        --from and --to support multiple formats:
+        • 'now' - current time
+        • Relative: '-30s', '-5m', '-2h', '-7d', '-1w', '-1M' (sec/min/hour/day/week/month)
+        • Unix timestamp: '1700000000' (seconds since epoch)
+        • ISO 8601: '2025-11-13T14:00:00'
+
       Examples:
-        # Error timeline with 5-minute buckets
+        # Last 30 minutes
+        sumo-query search --query 'error' --from '-30m' --to 'now'
+
+        # Last hour with ISO format
         sumo-query search --query 'error | timeslice 5m | count' \\
           --from '2025-11-13T14:00:00' --to '2025-11-13T15:00:00'
 
-        # Search for specific text
+        # Last 7 days
         sumo-query search --query '"connection timeout"' \\
-          --from '2025-11-13T14:00:00' --to '2025-11-13T15:00:00' \\
-          --limit 100
+          --from '-7d' --to 'now' --limit 100
+
+        # Using Unix timestamps
+        sumo-query search --query 'error' \\
+          --from '1700000000' --to '1700003600'
 
         # Interactive mode with FZF
         sumo-query search --query 'error' \\
-          --from '2025-11-13T14:00:00' --to '2025-11-13T15:00:00' \\
-          --interactive
+          --from '-1h' --to 'now' --interactive
     DESC
     option :query, type: :string, required: true, aliases: '-q', desc: 'Search query'
-    option :from, type: :string, required: true, aliases: '-f', desc: 'Start time (ISO 8601)'
-    option :to, type: :string, required: true, aliases: '-t', desc: 'End time (ISO 8601)'
-    option :time_zone, type: :string, default: 'UTC', aliases: '-z', desc: 'Time zone'
+    option :from, type: :string, required: true, aliases: '-f', desc: 'Start time (now, -30m, unix timestamp, ISO 8601)'
+    option :to, type: :string, required: true, aliases: '-t', desc: 'End time (now, -30m, unix timestamp, ISO 8601)'
+    option :time_zone, type: :string, default: 'UTC', aliases: '-z',
+                       desc: 'Time zone (UTC, EST, AEST, +00:00, America/New_York, Australia/Sydney)'
     option :limit, type: :numeric, aliases: '-l', desc: 'Maximum messages to return'
     option :interactive, type: :boolean, aliases: '-i', desc: 'Launch interactive browser (requires fzf)'
     def search

data/lib/sumologic/http/client.rb

@@ -29,7 +29,7 @@ module Sumologic
         uri = @request_builder.build_uri(path, query_params)
         request = @request_builder.build_request(method, uri, body)
 
-        DebugLogger.log_request(method, uri, body)
+        DebugLogger.log_request(method, uri, body, request.to_hash)
 
         response = execute_request(uri, request)
 

data/lib/sumologic/http/debug_logger.rb

@@ -9,12 +9,13 @@ module Sumologic
     module DebugLogger
       module_function
 
-      def log_request(method, uri, body)
+      def log_request(method, uri, body, headers = {})
         return unless $DEBUG
 
         warn "\n[DEBUG] API Request:"
         warn "  Method: #{method.to_s.upcase}"
         warn "  URL: #{uri}"
+        warn "  Cookie: #{headers['Cookie']}" if headers['Cookie']
         log_request_body(body) if body
         warn ''
       end

data/lib/sumologic/utils/time_parser.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Sumologic
+  module Utils
+    # Parses various time formats into ISO 8601 strings for the Sumo Logic API
+    # Supports:
+    # - 'now' - current time
+    # - Relative times: '-30s', '-5m', '-2h', '-7d', '-1w', '-1M'
+    # - Unix timestamps: '1700000000' or 1700000000
+    # - ISO 8601: '2025-11-13T14:00:00'
+    class TimeParser
+      # Time unit multipliers in seconds
+      UNITS = {
+        's' => 1,           # seconds
+        'm' => 60,          # minutes
+        'h' => 3600,        # hours
+        'd' => 86_400,       # days
+        'w' => 604_800,      # weeks (7 days)
+        'M' => 2_592_000 # months (30 days approximation)
+      }.freeze
+
+      RELATIVE_TIME_REGEX = /^([+-])(\d+)([smhdwM])$/.freeze
+
+      class ParseError < StandardError; end
+
+      # Parse a time string into ISO 8601 format
+      # @param time_str [String, Integer] Time string or Unix timestamp
+      # @param _timezone [String] IANA timezone name (default: 'UTC') - Reserved for future use
+      # @return [String] ISO 8601 formatted time string
+      def self.parse(time_str, _timezone: 'UTC')
+        return parse_now if time_str.to_s.downcase == 'now'
+
+        # Try relative time format (e.g., '-30m', '+1h')
+        if time_str.is_a?(String) && (match = time_str.match(RELATIVE_TIME_REGEX))
+          return parse_relative_time(match)
+        end
+
+        # Try Unix timestamp (integer or numeric string)
+        return parse_unix_timestamp(time_str) if unix_timestamp?(time_str)
+
+        # Try ISO 8601 format
+        begin
+          # Parse in UTC context to avoid local timezone conversion
+          parsed = Time.parse(time_str.to_s)
+          # If the input doesn't have timezone info, treat it as UTC
+          parsed = parsed.getutc unless time_str.to_s.match?(/Z|[+-]\d{2}:?\d{2}$/)
+          format_time(parsed)
+        rescue ArgumentError
+          raise ParseError,
+                "Invalid time format: '#{time_str}'. " \
+                "Supported formats: 'now', relative (e.g., '-30m'), Unix timestamp, or ISO 8601"
+        end
+      end
+
+      # Parse timezone string to standard format
+      # Accepts IANA names, offset formats, or common abbreviations
+      # @param timezone_str [String] Timezone string
+      # @return [String] Standardized timezone string
+      def self.parse_timezone(timezone_str)
+        return 'UTC' if timezone_str.nil? || timezone_str.empty?
+
+        # Handle offset formats like "+00:00", "-05:00", "+0000"
+        if timezone_str.match?(/^[+-]\d{2}:?\d{2}$/)
+          # Normalize to format with colon
+          normalized = timezone_str.sub(/^([+-]\d{2})(\d{2})$/, '\1:\2')
+          return normalized
+        end
+
+        # Map common abbreviations to IANA names
+        timezone_map = {
+          # US timezones
+          'EST' => 'America/New_York',
+          'EDT' => 'America/New_York',
+          'CST' => 'America/Chicago',
+          'CDT' => 'America/Chicago',
+          'MST' => 'America/Denver',
+          'MDT' => 'America/Denver',
+          'PST' => 'America/Los_Angeles',
+          'PDT' => 'America/Los_Angeles',
+          # Australian timezones
+          'AEST' => 'Australia/Sydney',      # Australian Eastern Standard Time
+          'AEDT' => 'Australia/Sydney',      # Australian Eastern Daylight Time
+          'ACST' => 'Australia/Adelaide',    # Australian Central Standard Time
+          'ACDT' => 'Australia/Adelaide',    # Australian Central Daylight Time
+          'AWST' => 'Australia/Perth',       # Australian Western Standard Time
+          'AWDT' => 'Australia/Perth'        # Australian Western Daylight Time (rarely used)
+        }
+
+        timezone_map[timezone_str.upcase] || timezone_str
+      end
+
+      private_class_method def self.parse_now
+        format_time(Time.now)
+      end
+
+      private_class_method def self.parse_relative_time(match)
+        sign, amount, unit = match.captures
+        amount = amount.to_i
+        amount = -amount if sign == '-'
+
+        seconds_delta = amount * UNITS[unit]
+        target_time = Time.now + seconds_delta
+
+        format_time(target_time)
+      end
+
+      private_class_method def self.parse_unix_timestamp(timestamp)
+        timestamp_int = timestamp.to_i
+
+        # Handle millisecond timestamps (13 digits) - convert to seconds
+        timestamp_int /= 1000 if timestamp.to_s.length == 13
+
+        # Validate reasonable range (between year 2000 and 2100)
+        min_timestamp = 946_684_800 # 2000-01-01
+        max_timestamp = 4_102_444_800 # 2100-01-01
+
+        unless timestamp_int.between?(min_timestamp, max_timestamp)
+          raise ParseError, "Unix timestamp out of reasonable range: #{timestamp}"
+        end
+
+        time = Time.at(timestamp_int).utc
+        format_time(time)
+      end
+
+      private_class_method def self.unix_timestamp?(value)
+        # Check if it's an integer or a string that looks like a Unix timestamp
+        # Unix timestamps are typically 10 digits (seconds) or 13 digits (milliseconds)
+        return true if value.is_a?(Integer) && value.to_s.length.between?(10, 13)
+
+        if value.is_a?(String)
+          # Must be all digits, and between 10-13 characters
+          return value.match?(/^\d{10,13}$/)
+        end
+
+        false
+      end
+
+      private_class_method def self.format_time(time)
+        # Format as ISO 8601 without timezone suffix
+        # Sumo Logic API expects format like "2025-11-13T14:00:00"
+        time.utc.strftime('%Y-%m-%dT%H:%M:%S')
+      end
+    end
+  end
+end

data/lib/sumologic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sumologic
-  VERSION = '1.3.3'
+  VERSION = '1.3.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sumologic-query
 version: !ruby/object:Gem::Version
-  version: 1.3.3
+  version: 1.3.4
 platform: ruby
 authors:
 - patrick204nqh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-17 00:00:00.000000000 Z
+date: 2025-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -123,6 +123,7 @@ files:
 - lib/sumologic/search/job.rb
 - lib/sumologic/search/message_fetcher.rb
 - lib/sumologic/search/poller.rb
+- lib/sumologic/utils/time_parser.rb
 - lib/sumologic/utils/worker.rb
 - lib/sumologic/version.rb
 homepage: https://github.com/patrick204nqh/sumologic-query