Add monitor-queues command for live queue statistics

Introduces a new command that displays Service Bus queue statistics in a
live-updating console table using Rx.NET and Spectre.Console. Features:

- Real-time polling with configurable refresh interval (min 1 second)
- Queue name filtering with wildcards (*, ?) or contains matching
- Color-coded counts: red for DLQ > 0, yellow for active > 1000
- Only updates display when counts change (DistinctUntilChanged)
- Graceful Ctrl+C shutdown

Also adds CLAUDE.md for project context and updates documentation.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: kyurkchyan

CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Run
+
+```bash
+dotnet build
+dotnet run -- <command> [options]
+dotnet run -- --help
+```
+
+## Architecture
+
+.NET 10 CLI tool for Azure Service Bus operations using CommandLineParser for argument parsing and DefaultAzureCredential for authentication.
+
+### Project Structure
+
+```
+ServiceBusToolset/
+├── Options/      # CLI options with [Verb] and [Option] attributes
+├── Commands/     # Command implementations
+├── Services/     # Business logic and external integrations
+└── Models/       # Data models
+```
+
+### Adding a New Command
+
+1. **Create Options class** in `Options/`:
+   - Use `[Verb("command-name", HelpText = "...")]`
+   - Use `[Option('c', "long-name", Required = true/false, HelpText = "...")]`
+   - Add `Validate()` method returning `string?` (null = valid)
+
+2. **Create Command class** in `Commands/`:
+   - Implement `ICommand<TOptions>` interface
+   - Inherit `BaseCommand<TOptions>` for DLQ operations (provides `CreateDlqReceiver`, `GetEntityDescription`)
+   - Use primary constructor pattern
+   - Handle exceptions: `AuthenticationFailedException`, `ServiceBusException`, `OperationCanceledException`
+
+3. **Register in Program.cs**:
+   - Add options type to `ParseArguments<...>()`
+   - Add `MapResult` handler that creates command and calls `ExecuteAsync`
+
+### Key Services
+
+- `IServiceBusClientFactory` - Creates `ServiceBusClient` and `ServiceBusAdministrationClient`
+- `IConsoleOutput` - Console output abstraction (Info, Success, Warning, Error, Verbose, Table)
+- `IDlqCategoryAnalyzer` - Groups DLQ messages by Label and DeadLetterReason
+- `IAppInsightsService` - Queries Application Insights for diagnostics
+
+### Dependencies
+
+- `CommandLineParser` - CLI argument parsing with verbs
+- `Spectre.Console` - Rich console output and tables
+- `System.Reactive` - Rx.NET for reactive streams (monitor-queues)
+- `Azure.Identity` - DefaultAzureCredential (requires `az login` for local dev)

README.md

@@ -15,12 +15,13 @@ dotnet build
 
 ## Commands
 
-| Command                              | Description                                                       |
-|--------------------------------------|-------------------------------------------------------------------|
-| [purge-dlq](docs/purge-dlq.md)       | Purge messages from a dead letter queue                           |
-| [resubmit-dlq](docs/resubmit-dlq.md) | Resubmit messages from a dead letter queue back to the main queue |
-| [dump-dlq](docs/dump-dlq.md)         | Export DLQ messages to a JSON file                                |
-| [diagnose-dlq](docs/diagnose-dlq.md) | Diagnose DLQ messages using Application Insights telemetry        |
+| Command                                  | Description                                                       |
+|------------------------------------------|-------------------------------------------------------------------|
+| [purge-dlq](docs/purge-dlq.md)           | Purge messages from a dead letter queue                           |
+| [resubmit-dlq](docs/resubmit-dlq.md)     | Resubmit messages from a dead letter queue back to the main queue |
+| [dump-dlq](docs/dump-dlq.md)             | Export DLQ messages to a JSON file                                |
+| [diagnose-dlq](docs/diagnose-dlq.md)     | Diagnose DLQ messages using Application Insights telemetry        |
+| [monitor-queues](docs/monitor-queues.md) | Monitor queue statistics in a live-updating console table         |
 
 ## Quick Start
 
@@ -46,6 +47,12 @@ dotnet run -- dump-dlq -n mynamespace.servicebus.windows.net -q myqueue -o dlq-m
 # Diagnose DLQ messages using Application Insights
 dotnet run -- diagnose-dlq -n mynamespace.servicebus.windows.net -q myqueue \
   -a "/subscriptions/.../resourceGroups/.../providers/microsoft.insights/components/my-app-insights"
+
+# Monitor all queues with live-updating table
+dotnet run -- monitor-queues -n mynamespace.servicebus.windows.net
+
+# Monitor queues matching a pattern with 10-second refresh
+dotnet run -- monitor-queues -n mynamespace.servicebus.windows.net -f "order-*" -r 10
 ```
 
 ## Authentication

ServiceBusToolset/Commands/MonitorQueuesCommand.cs

@@ -0,0 +1,123 @@
+using System.Reactive.Linq;
+using Azure.Identity;
+using Azure.Messaging.ServiceBus;
+using ServiceBusToolset.Models;
+using ServiceBusToolset.Options;
+using ServiceBusToolset.Services;
+using Spectre.Console;
+
+namespace ServiceBusToolset.Commands;
+
+public class MonitorQueuesCommand(IQueueMonitorService monitorService, IConsoleOutput output) : ICommand<MonitorQueuesOptions>
+{
+    public async Task<int> ExecuteAsync(MonitorQueuesOptions options, CancellationToken cancellationToken = default)
+    {
+        var validationError = options.Validate();
+        if (validationError != null)
+        {
+            output.Error(validationError);
+            return 1;
+        }
+
+        try
+        {
+            output.Info($"Connecting to Service Bus namespace: {options.Namespace}");
+            if (!string.IsNullOrEmpty(options.Filter))
+            {
+                output.Info($"Filter: {options.Filter}");
+            }
+
+            output.Info($"Refresh interval: {options.RefreshInterval} seconds");
+            output.Info("Press Ctrl+C to stop monitoring.");
+            output.Info("");
+
+            var refreshInterval = TimeSpan.FromSeconds(options.RefreshInterval);
+
+            await monitorService
+                  .ObserveQueues(options.Namespace,
+                                 options.Filter,
+                                 refreshInterval,
+                                 cancellationToken)
+                  .ForEachAsync(stats =>
+                                {
+                                    Console.Clear();
+                                    var table = CreateTable(stats);
+                                    AnsiConsole.Write(table);
+
+                                    if (options.Verbose)
+                                    {
+                                        output.Verbose($"Updated at {DateTimeOffset.Now:HH:mm:ss} - {stats.Count} queues", options.Verbose);
+                                    }
+                                },
+                                cancellationToken);
+
+            return 0;
+        }
+        catch (AuthenticationFailedException ex)
+        {
+            output.Error($"Authentication failed: {ex.Message}");
+            output.Error("Ensure you are logged in with 'az login' or have valid environment credentials.");
+            return 1;
+        }
+        catch (ServiceBusException ex)
+        {
+            output.Error($"Service Bus error: {ex.Message}");
+            output.Verbose($"Reason: {ex.Reason}", options.Verbose);
+            return 1;
+        }
+        catch (OperationCanceledException)
+        {
+            output.Info("");
+            output.Info("Monitoring stopped.");
+            return 0;
+        }
+    }
+
+    private static Table CreateTable(IReadOnlyList<QueueStatistics> statistics)
+    {
+        var table = new Table()
+                    .Border(TableBorder.Rounded)
+                    .Title("[bold blue]Service Bus Queue Monitor[/]")
+                    .AddColumn(new TableColumn("[bold]Queue Name[/]").LeftAligned())
+                    .AddColumn(new TableColumn("[bold]Active[/]").RightAligned())
+                    .AddColumn(new TableColumn("[bold]DLQ[/]").RightAligned())
+                    .AddColumn(new TableColumn("[bold]Scheduled[/]").RightAligned());
+
+        long totalActive = 0;
+        long totalDlq = 0;
+        long totalScheduled = 0;
+
+        foreach (var stat in statistics)
+        {
+            var activeStyle = stat.ActiveMessageCount > 1000 ? "[yellow]" : "[white]";
+            var dlqStyle = stat.DeadLetterMessageCount > 0 ? "[red]" : "[white]";
+
+            table.AddRow(stat.Name,
+                         $"{activeStyle}{stat.ActiveMessageCount:N0}[/]",
+                         $"{dlqStyle}{stat.DeadLetterMessageCount:N0}[/]",
+                         $"[white]{stat.ScheduledMessageCount:N0}[/]");
+
+            totalActive += stat.ActiveMessageCount;
+            totalDlq += stat.DeadLetterMessageCount;
+            totalScheduled += stat.ScheduledMessageCount;
+        }
+
+        if (statistics.Count > 0)
+        {
+            table.AddEmptyRow();
+
+            var totalActiveStyle = totalActive > 1000 ? "[bold yellow]" : "[bold white]";
+            var totalDlqStyle = totalDlq > 0 ? "[bold red]" : "[bold white]";
+
+            table.AddRow("[bold]TOTAL[/]",
+                         $"{totalActiveStyle}{totalActive:N0}[/]",
+                         $"{totalDlqStyle}{totalDlq:N0}[/]",
+                         $"[bold white]{totalScheduled:N0}[/]");
+        }
+
+        var timestamp = statistics.Count > 0 ? statistics[0].UpdatedAt : DateTimeOffset.Now;
+        table.Caption($"Last updated: {timestamp:HH:mm:ss}");
+
+        return table;
+    }
+}

ServiceBusToolset/Models/QueueStatistics.cs

@@ -0,0 +1,14 @@
+namespace ServiceBusToolset.Models;
+
+public record QueueStatistics(string Name,
+                              long ActiveMessageCount,
+                              long DeadLetterMessageCount,
+                              long ScheduledMessageCount,
+                              DateTimeOffset UpdatedAt)
+{
+    public bool HasSameCountsAs(QueueStatistics other) =>
+        Name == other.Name &&
+        ActiveMessageCount == other.ActiveMessageCount &&
+        DeadLetterMessageCount == other.DeadLetterMessageCount &&
+        ScheduledMessageCount == other.ScheduledMessageCount;
+}

ServiceBusToolset/Options/MonitorQueuesOptions.cs

@@ -0,0 +1,32 @@
+using CommandLine;
+
+namespace ServiceBusToolset.Options;
+
+[Verb("monitor-queues", HelpText = "Monitor Service Bus queue statistics in a live-updating console table")]
+public class MonitorQueuesOptions
+{
+    [Option('n',
+            "namespace",
+            Required = true,
+            HelpText = "Fully qualified Service Bus namespace (e.g., mynamespace.servicebus.windows.net)")]
+    public required string Namespace { get; set; }
+
+    [Option('f',
+            "filter",
+            HelpText = "Queue name filter (wildcards * and ? supported, or contains match)")]
+    public string? Filter { get; set; }
+
+    [Option('r',
+            "refresh-interval",
+            Default = 5,
+            HelpText = "Refresh interval in seconds (minimum: 1)")]
+    public int RefreshInterval { get; set; }
+
+    [Option('v',
+            "verbose",
+            Default = false,
+            HelpText = "Enable verbose output")]
+    public bool Verbose { get; set; }
+
+    public string? Validate() => RefreshInterval < 1 ? "Refresh interval must be at least 1 second." : null;
+}

ServiceBusToolset/Program.cs

@@ -7,6 +7,7 @@
 var output = new ConsoleOutput();
 var categoryAnalyzer = new DlqCategoryAnalyzer();
 var appInsightsService = new AppInsightsService();
+var queueMonitorService = new QueueMonitorService(clientFactory);
 
 using var cts = new CancellationTokenSource();
 Console.CancelKeyPress += (_, e) =>
@@ -15,7 +16,7 @@
     cts.Cancel();
 };
 
-return await Parser.Default.ParseArguments<PurgeDlqOptions, ResubmitDlqOptions, DumpDlqOptions, DiagnoseDlqOptions>(args)
+return await Parser.Default.ParseArguments<PurgeDlqOptions, ResubmitDlqOptions, DumpDlqOptions, DiagnoseDlqOptions, MonitorQueuesOptions>(args)
                    .MapResult((PurgeDlqOptions opts) =>
                               {
                                   var command = new PurgeDlqCommand(clientFactory, output, categoryAnalyzer);
@@ -39,6 +40,11 @@
                                                                        appInsightsService);
                                   return command.ExecuteAsync(opts, cts.Token);
                               },
+                              (MonitorQueuesOptions opts) =>
+                              {
+                                  var command = new MonitorQueuesCommand(queueMonitorService, output);
+                                  return command.ExecuteAsync(opts, cts.Token);
+                              },
                               errors => Task.FromResult(HandleParseErrors(errors)));
 
 static int HandleParseErrors(IEnumerable<Error> errors)

ServiceBusToolset/ServiceBusToolset.csproj

@@ -13,6 +13,7 @@
         <PackageReference Include="Azure.Monitor.Query" Version="1.5.0"/>
         <PackageReference Include="CommandLineParser" Version="2.9.1"/>
         <PackageReference Include="Spectre.Console" Version="0.54.0"/>
+        <PackageReference Include="System.Reactive" Version="6.0.1"/>
     </ItemGroup>
 
 </Project>

ServiceBusToolset/Services/IQueueMonitorService.cs

@@ -0,0 +1,12 @@
+using ServiceBusToolset.Models;
+
+namespace ServiceBusToolset.Services;
+
+public interface IQueueMonitorService
+{
+    IObservable<IReadOnlyList<QueueStatistics>> ObserveQueues(
+        string fullyQualifiedNamespace,
+        string? queueFilter,
+        TimeSpan refreshInterval,
+        CancellationToken cancellationToken);
+}