sumologic-query 1.3.5 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83e78d35f43a7e12f98e3ed11d9d4b0ddd7fe4cf567c281fa4729c8873c583a0
-  data.tar.gz: 4cc242bc523b5ce0cf709ec9f9aceb44cb1fe5911582983ae80e3a49d00a175d
+  metadata.gz: f62e0cd6d7ee0fbfd44b2720b0075e4f1776e086ef1ccbe39ad9e520f539f951
+  data.tar.gz: da262a85a0fa2d556c310876d011705edd4fc1b46db47c43d6f892adf71649ff
 SHA512:
-  metadata.gz: 7b9d63d998ff14e1b9db86dc982dd84b508f642c01a62883b7bdce997ec21aed3097477956776319f01b68da2e8ed967b713894ed8002353ab99ee9fd72bad85
-  data.tar.gz: '084c1c7db713d88f88979941d8b6a261f48c4bc533f3ce2ac04cb97ea3bae5fb0762889611dbfffd790740e0c7928acffb9e7df144c6e6d7b0fa129128d49e23'
+  metadata.gz: 458d97b1853c3626d85f84770faaf918ebbd2842718ffed416ead1736a8a075bc4061eb040e003a24227e8af6b7f6f125baf2b2aec5627f0398abd6b054fe880
+  data.tar.gz: '078544851f936431eea88d6b0783f39c58789072bbfa8fe17f5147c2a9aff9df8bc0b3f5e71c48e7d6793f8ad94a69a134bfabe5ab3d46689ff35613a13446f5'

data/CHANGELOG.md

@@ -6,6 +6,58 @@ 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.4.1](https://github.com/patrick204nqh/sumologic-query/compare/v1.4.0...v1.4.1) (2026-02-11)
+
+### 🎉 New Features
+
+- add "Open in Sumo Logic" URL to search output
+- add command recipe and CLI command specs
+
+### 🐛 Bug Fixes
+
+- update source_code_uri metadata to use homepage
+
+### 🔧 Refactoring
+
+- resolve ADR-006, fix README links, extract command helpers
+
+### 📚 Documentation
+
+- consolidate query examples and document v1/v2 API split
+
+
+
+## [1.4.0](https://github.com/patrick204nqh/sumologic-query/compare/v1.3.5...v1.4.0) (2026-02-11)
+
+### 🎉 New Features
+
+- add comprehensive skills documentation for Sumo Logic CLI commands
+- add export-content command with async job handling
+- add get-content command for path-based content lookup
+- add get-lookup and list-apps commands
+- add list-health-events and list-fields commands
+- migrate monitors to search API with status/query filters
+- add support for retrieving monitors and dashboards in the CLI, refactor monitor collection logic for improved readability
+- Enhance Sumo Logic CLI with monitors, folders, and dashboards commands
+- implement aggregation queries and enhance error handling for rate limits
+
+### 🐛 Bug Fixes
+
+- migrate dashboards from v1 to v2 API
+
+### 🔧 Refactoring
+
+- clean design for AI agent readiness (v1.4.0)
+
+### 📚 Documentation
+
+- update naming conventions to match actual codebase
+- reorganize into SDLC structure
+- clarify discover-sources as search-based technique
+- revise architecture overview with enhanced clarity on design philosophy, component structure, and key features
+
+
+
 ## [1.3.5](https://github.com/patrick204nqh/sumologic-query/compare/v1.3.4...v1.3.5) (2025-11-19)
 
 ### 🎉 New Features

data/README.md

@@ -78,7 +78,7 @@ sumo-query search -q "YOUR_QUERY" -f "START" -t "END" [OPTIONS]
 sumo-query discover-sources [OPTIONS]
 ```
 
-Finds dynamic source names from log data (CloudWatch, ECS, Lambda streams).
+Discovers source names from log data using search aggregation (`* | count by _sourceName, _sourceCategory`). This is not an official Sumo Logic API — it complements `list-sources` by finding runtime sources (CloudWatch, ECS, Lambda streams) that use dynamic `_sourceName` values.
 
 **Options:**
 - `-f, --from` - Start time (default: `-24h`)
@@ -152,9 +152,9 @@ client.list_all_sources
 ## Documentation
 
 - [Query Examples](examples/queries.md) - Query patterns and examples
-- [Quick Reference](docs/tldr.md) - Command cheat sheet
-- [Rate Limiting](docs/rate-limiting.md) - Performance tuning
-- [Architecture](docs/architecture/) - Design decisions
+- [Quick Reference](docs/sdlc/7-maintain/tldr.md) - Command cheat sheet
+- [Rate Limiting](docs/sdlc/4-develop/rate-limiting.md) - Performance tuning
+- [Architecture](docs/sdlc/3-design/overview.md) - Design decisions
 
 ## Contributing
 

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

@@ -17,6 +17,18 @@ module Sumologic
 
         private
 
+        def list_resource(label:, key:)
+          warn "Fetching #{label}..."
+          items = yield
+          output_json(total: items.size, key => items)
+        end
+
+        def get_resource(label:, id:)
+          warn "Fetching #{label} #{id}..."
+          result = yield
+          output_json(result)
+        end
+
         def output_json(data)
           json_output = JSON.pretty_generate(data)
 
@@ -31,26 +43,6 @@ module Sumologic
             puts json_output
           end
         end
-
-        def format_collector(collector)
-          {
-            id: collector['id'],
-            name: collector['name'],
-            collectorType: collector['collectorType'],
-            alive: collector['alive'],
-            category: collector['category']
-          }
-        end
-
-        def format_source(source)
-          {
-            id: source['id'],
-            name: source['name'],
-            category: source['category'],
-            sourceType: source['sourceType'],
-            alive: source['alive']
-          }
-        end
       end
     end
   end

data/lib/sumologic/cli/commands/{discover_sources_command.rb → discover_source_metadata_command.rb}

@@ -6,8 +6,8 @@ require_relative '../../utils/time_parser'
 module Sumologic
   class CLI < Thor
     module Commands
-      # Handles the discover-sources command execution
-      class DiscoverSourcesCommand < BaseCommand
+      # Handles the discover-source-metadata command execution
+      class DiscoverSourceMetadataCommand < BaseCommand
         def execute
           parse_time_options
           log_discovery_info
@@ -32,7 +32,7 @@ module Sumologic
 
         def log_discovery_info
           warn '=' * 60
-          warn 'Discovering Dynamic Source Names'
+          warn 'Discovering Source Metadata'
           warn '=' * 60
           warn "Time Range: #{@original_from} to #{@original_to}"
           if @original_from != @parsed_from || @original_to != @parsed_to
@@ -46,7 +46,7 @@ module Sumologic
         end
 
         def perform_discovery
-          client.discover_dynamic_sources(
+          client.discover_source_metadata(
             from_time: @parsed_from,
             to_time: @parsed_to,
             time_zone: @parsed_timezone,

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Sumologic
+  class CLI < Thor
+    module Commands
+      # Handles the export-content command execution
+      class ExportContentCommand < BaseCommand
+        def execute
+          get_resource(label: 'content', id: options[:content_id]) do
+            client.export_content(content_id: options[:content_id])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Sumologic
+  class CLI < Thor
+    module Commands
+      # Handles the get-content command execution
+      class GetContentCommand < BaseCommand
+        def execute
+          get_resource(label: 'content at path:', id: options[:path]) do
+            client.get_content(path: options[:path])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Sumologic
+  class CLI < Thor
+    module Commands
+      # Handles the get-dashboard command execution
+      class GetDashboardCommand < BaseCommand
+        def execute
+          get_resource(label: 'dashboard', id: options[:dashboard_id]) do
+            client.get_dashboard(dashboard_id: options[:dashboard_id])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Sumologic
+  class CLI < Thor
+    module Commands
+      # Handles the get-lookup command execution
+      class GetLookupCommand < BaseCommand
+        def execute
+          get_resource(label: 'lookup table', id: options[:lookup_id]) do
+            client.get_lookup(lookup_id: options[:lookup_id])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Sumologic
+  class CLI < Thor
+    module Commands
+      # Handles the get-monitor command execution
+      class GetMonitorCommand < BaseCommand
+        def execute
+          get_resource(label: 'monitor', id: options[:monitor_id]) do
+            client.get_monitor(monitor_id: options[:monitor_id])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Sumologic
+  class CLI < Thor
+    module Commands
+      # Handles the list-apps command execution
+      class ListAppsCommand < BaseCommand
+        def execute
+          list_resource(label: 'app catalog', key: :apps) { client.list_apps }
+        end
+      end
+    end
+  end
+end

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

@@ -8,13 +8,7 @@ module Sumologic
       # Handles the list-collectors command execution
       class ListCollectorsCommand < BaseCommand
         def execute
-          warn 'Fetching collectors...'
-          collectors = client.list_collectors
-
-          output_json(
-            total: collectors.size,
-            collectors: collectors.map { |c| format_collector(c) }
-          )
+          list_resource(label: 'collectors', key: :collectors) { client.list_collectors }
         end
       end
     end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Sumologic
+  class CLI < Thor
+    module Commands
+      # Handles the list-dashboards command execution
+      class ListDashboardsCommand < BaseCommand
+        def execute
+          list_resource(label: 'dashboards', key: :dashboards) do
+            client.list_dashboards(limit: options[:limit] || 100)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Sumologic
+  class CLI < Thor
+    module Commands
+      # Handles the list-fields command execution
+      class ListFieldsCommand < BaseCommand
+        def execute
+          if options[:builtin]
+            warn 'Fetching built-in fields...'
+            fields = client.list_builtin_fields
+          else
+            warn 'Fetching custom fields...'
+            fields = client.list_fields
+          end
+
+          output_json(
+            total: fields.size,
+            fields: fields
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Sumologic
+  class CLI < Thor
+    module Commands
+      # Handles the list-folders command execution
+      class ListFoldersCommand < BaseCommand
+        def execute
+          if options[:tree]
+            fetch_tree
+          elsif options[:folder_id]
+            fetch_folder
+          else
+            fetch_personal
+          end
+        end
+
+        private
+
+        def fetch_personal
+          warn 'Fetching personal folder...'
+          folder = client.personal_folder
+          output_folder_with_children(folder)
+        end
+
+        def fetch_folder
+          folder_id = options[:folder_id]
+          warn "Fetching folder #{folder_id}..."
+          folder = client.get_folder(folder_id: folder_id)
+          output_folder_with_children(folder)
+        end
+
+        def fetch_tree
+          folder_id = options[:folder_id]
+          max_depth = options[:depth] || 3
+
+          if folder_id
+            warn "Fetching folder tree for #{folder_id} (depth: #{max_depth})..."
+          else
+            warn "Fetching personal folder tree (depth: #{max_depth})..."
+          end
+
+          tree = client.folder_tree(folder_id: folder_id, max_depth: max_depth)
+          output_json(tree)
+        end
+
+        def output_folder_with_children(folder)
+          output_json(folder)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Sumologic
+  class CLI < Thor
+    module Commands
+      # Handles the list-health-events command execution
+      class ListHealthEventsCommand < BaseCommand
+        def execute
+          list_resource(label: 'health events', key: :healthEvents) do
+            client.list_health_events(limit: options[:limit] || 100)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Sumologic
+  class CLI < Thor
+    module Commands
+      # Handles the list-monitors command execution
+      # Uses the monitors search API for flat, filterable results
+      class ListMonitorsCommand < BaseCommand
+        def execute
+          list_resource(label: 'monitors', key: :monitors) do
+            client.list_monitors(
+              query: options[:query],
+              status: options[:status],
+              limit: options[:limit] || 100
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -24,7 +24,7 @@ module Sumologic
           output_json(
             collector_id: options[:collector_id],
             total: sources.size,
-            sources: sources.map { |s| format_source(s) }
+            sources: sources
           )
         end
 
@@ -37,16 +37,9 @@ module Sumologic
           output_json(
             total_collectors: all_sources.size,
             total_sources: all_sources.sum { |c| c['sources'].size },
-            data: all_sources.map { |item| format_collector_with_sources(item) }
+            data: all_sources
           )
         end
-
-        def format_collector_with_sources(item)
-          {
-            collector: item['collector'],
-            sources: item['sources'].map { |s| format_source(s) }
-          }
-        end
       end
     end
   end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'erb'
 require_relative 'base_command'
 require_relative '../../utils/time_parser'
 
@@ -46,42 +47,83 @@ module Sumologic
           end
           warn "Query: #{options[:query]}"
           warn "Limit: #{options[:limit] || 'unlimited'}"
+          warn "Open in Sumo: #{build_search_url}"
           warn '-' * 60
           warn 'Creating search job...'
           $stderr.puts
         end
 
         def perform_search
-          client.search(
-            query: options[:query],
-            from_time: @parsed_from,
-            to_time: @parsed_to,
-            time_zone: @parsed_timezone,
-            limit: options[:limit]
-          )
+          if aggregate_mode?
+            client.search_aggregation(
+              query: options[:query],
+              from_time: @parsed_from,
+              to_time: @parsed_to,
+              time_zone: @parsed_timezone,
+              limit: options[:limit]
+            )
+          else
+            client.search(
+              query: options[:query],
+              from_time: @parsed_from,
+              to_time: @parsed_to,
+              time_zone: @parsed_timezone,
+              limit: options[:limit]
+            )
+          end
+        end
+
+        def aggregate_mode?
+          options[:aggregate] || aggregation_query?(options[:query])
+        end
+
+        def aggregation_query?(query)
+          query.match?(/\|\s*(count|sum|avg|min|max|pct|first|last|group)\b/i)
         end
 
         def display_results_summary(results)
+          result_type = aggregate_mode? ? 'records' : 'messages'
           warn '=' * 60
-          warn "Results: #{results.size} messages"
+          warn "Results: #{results.size} #{result_type}"
           warn '=' * 60
           $stderr.puts
         end
 
         def output_search_results(results)
-          output_json(
-            query: options[:query],
-            from: @parsed_from,
-            to: @parsed_to,
-            from_original: @original_from,
-            to_original: @original_to,
-            time_zone: @parsed_timezone,
-            message_count: results.size,
-            messages: results
-          )
+          if aggregate_mode?
+            output_json(
+              query: options[:query],
+              from: @parsed_from,
+              to: @parsed_to,
+              from_original: @original_from,
+              to_original: @original_to,
+              time_zone: @parsed_timezone,
+              search_url: build_search_url,
+              record_count: results.size,
+              records: results
+            )
+          else
+            output_json(
+              query: options[:query],
+              from: @parsed_from,
+              to: @parsed_to,
+              from_original: @original_from,
+              to_original: @original_to,
+              time_zone: @parsed_timezone,
+              search_url: build_search_url,
+              message_count: results.size,
+              messages: results
+            )
+          end
         end
 
         def launch_interactive_mode(results)
+          if aggregate_mode?
+            warn 'Interactive mode is not supported for aggregation queries'
+            output_search_results(results)
+            return
+          end
+
           require_relative '../../interactive'
 
           formatted_results = build_formatted_results(results)
@@ -97,10 +139,20 @@ module Sumologic
             'from' => @parsed_from,
             'to' => @parsed_to,
             'time_zone' => @parsed_timezone,
+            'search_url' => build_search_url,
             'message_count' => results.size,
             'messages' => results
           }
         end
+
+        def build_search_url
+          from_ms = (Time.parse("#{@parsed_from}Z").to_f * 1000).to_i
+          to_ms = (Time.parse("#{@parsed_to}Z").to_f * 1000).to_i
+          encoded_query = ERB::Util.url_encode(options[:query])
+          base = client.config.web_ui_base_url
+
+          "#{base}/ui/#/search/create?query=#{encoded_query}&startTime=#{from_ms}&endTime=#{to_ms}"
+        end
       end
     end
   end