Crucible CLI — die fehlende Kommandozeile für Azure Service Bus

Azure Service Bus hat kein CLI für Nachrichtenoperationen. az servicebus verwaltet Namespaces und Queues, kann aber keine Nachricht einsehen, keinen Dead Letter wiederholen und nicht nach Inhalten suchen. Crucible löst genau das.

---

Das Problem

Wer mit Azure Service Bus arbeitet, kennt den Schmerz:

• Dead-Letter-Queues laufen voll und man klickt sich im Portal Nachricht für Nachricht durch
• az servicebus hat null Befehle auf Nachrichtenebene — man kann eine Queue anlegen, aber nicht hineinschauen
• ServiceBusExplorer ist nur für Windows — auf macOS oder Linux schreibt man Wegwerf-Skripte
• Keine Suche im Nachrichteninhalt — man kann nach Sequenznummer peeken, aber die Nachricht mit OrderId: 12345 findet man nur mit eigenem Code
• Bulk-Replay? Nicht im Portal. Nicht per CLI. Man schreibt eine .NET-Konsolenanwendung, führt sie einmal aus und löscht sie wieder.

Jedes Service-Bus-Team baut dieselben internen Skripte. Wir haben stattdessen ein Tool gebaut.

---

Was Crucible CLI kann

# Alles auf einen Blick
$ crucible status

Namespace: sb-prod.servicebus.windows.net

Entity                          Active    DLQ    Scheduled
──────────────────────────────────────────────────────────
orders/process-order               142      0           0
orders/notify-warehouse             38      0           2
payments/validate-payment            0     47           0  ← 🔴
payments/process-refund              3      0           0
events/audit-logger                891      0           0

1 Entity mit Dead-Letter-Nachrichten.

# Was ist in der Dead-Letter-Queue?
$ crucible deadletter payments/validate-payment --reasons

Dead-Letter-Gründe für payments/validate-payment:

Reason                              Count    Oldest
────────────────────────────────────────────────────
MaxDeliveryCountExceeded               31    vor 2 Std.
HeaderSizeExceeded                     12    vor 18 Std.
TTLExpired                              4    vor 3 Tagen

Gesamt: 47 Nachrichten

# Die gesuchte Nachricht finden
$ crucible search payments/validate-payment --dlq --body "INV-2026-0847"

1 Nachricht gefunden:

Seq: 4892  |  Enqueued: 2026-03-21T14:32:01Z  |  DLQ-Grund: MaxDeliveryCountExceeded
{
  "invoiceId": "INV-2026-0847",
  "amount": 1420.00,
  "currency": "EUR",
  "customerId": "C-9912"
}

# Alle wiederholen — mit vorherigem Backup
$ crucible replay payments/validate-payment --filter "reason=MaxDeliveryCountExceeded" --backup

Sichere 31 Nachrichten nach ./crucible-backup-2026-03-22T10-15-00.json
Wiederhole 31 Nachrichten an payments/validate-payment...
████████████████████████████████ 31/31 abgeschlossen

Fertig. 31 Nachrichten wiederholt. Backup gespeichert.

# Testnachricht senden
$ crucible send orders/process-order --file test-payload.json --property "env=staging"

Nachricht an orders/process-order gesendet (seq: 10294)

---

Und es kann noch mehr

Live-Monitoring

crucible monitor bietet ein Live-TUI-Dashboard — sozusagen htop für Service Bus. Echtzeit-Zähler, farbcodierte DLQ-Trends, automatische Aktualisierung alle 5 Sekunden.

$ crucible monitor

┌─ sb-prod.servicebus.windows.net ──────────── Aktualisierung alle 5s ─┐
│ Entity                      Active   DLQ   Sched   Trend             │
│ orders/process-order           142     0       0                      │
│ orders/notify-warehouse         38     0       2                      │
│ payments/validate-payment        0    47       0    ▲ HOCH            │
│ payments/process-refund          3     0       0                      │
│ events/audit-logger            891     0       0                      │
└──────────────────────────────────────────────────────────────────────┘

Namespace-Topologie

Die gesamte Namespace-Struktur anzeigen — Topics, Subscriptions, Rules — als Baum. Export als Mermaid für die Dokumentation.

$ crucible topology

sb-prod.servicebus.windows.net
├── [queue] orders-dlq-parking
├── [topic] orders
│   ├── [sub] process-order
│   │   └── [rule] high-priority (CorrelationFilter)
│   └── [sub] notify-warehouse
│       └── [rule] $Default (TrueFilter)
└── [topic] payments
    ├── [sub] validate-payment
    └── [sub] process-refund

$ crucible topology --format mermaid > topology.md

Drift-Erkennung

Namespace-Konfiguration als Snapshot speichern und später vergleichen — oder zwei Namespaces nebeneinander prüfen (Dev vs. Prod).

$ crucible snapshot --output baseline.json
Snapshot gespeichert: 3 Topics, 5 Subscriptions, 2 Queues, 8 Rules

$ crucible diff baseline.json
Änderungen seit 2026-03-20T14:00:00Z:
  + [sub] orders/audit-logger           (hinzugefügt)
  ~ [queue] orders-dlq-parking          maxDeliveryCount: 5 → 10
  - [rule] payments/validate/legacy     (entfernt)

Export & Import

Nachrichten zwischen Umgebungen verschieben. Aus der DLQ exportieren, Daten korrigieren, in eine andere Queue importieren.

$ crucible export payments/validate-payment --dlq --format json > failed-payments.json
47 Nachrichten exportiert

$ crucible import payments/validate-payment --file failed-payments.json --delay 100ms
47 Nachrichten importiert (4,7s)

Schwellenwert-Benachrichtigungen

Eine Queue überwachen und einen Befehl oder eine Desktop-Benachrichtigung auslösen, wenn der DLQ-Wert einen Schwellenwert überschreitet.

$ crucible watch payments/validate-payment --dlq-threshold 10 --exec "curl -X POST https://hooks.slack.com/..."
Überwache payments/validate-payment (Abfrage alle 30s, Schwellenwert: 10)

---

Warum wir es gebaut haben

Wir betreiben Power Platform → Azure-Integrationen für Kunden. Service Bus ist das Rückgrat. Wenn eine Dead-Letter-Queue um 2 Uhr morgens volläuft, will man nicht das Azure Portal öffnen, zum Namespace navigieren, die Subscription finden, auf „Peek” klicken, eine Nachricht nach der anderen lesen und dann ein Skript zum Wiederholen schreiben.

Man will eintippen:

crucible deadletter payments/validate-payment --reasons
crucible replay payments/validate-payment --filter "reason=MaxDeliveryCountExceeded"

Und fertig.

Wir haben nach einem Tool gesucht, das das kann. Das hier haben wir gefunden:

Tool	Peek	Inhalt durchsuchen	Bulk-Replay	Live-Monitor	Topologie	Namespace-Diff	Export/Import	CLI	Plattformübergreifend
Azure Portal	Ja	Nein	Nein	Nein	Nein	Nein	Nein	Nein	Ja (Browser)
az servicebus	Nein	Nein	Nein	Nein	Nein	Nein	Nein	Ja	Ja
ServiceBusExplorer	Ja	Nein	Teilweise	Nein	Nein	Nein	Nein	Nein	Nur Windows
Crucible CLI	Ja	Ja	Ja	Ja	Ja	Ja	Ja	Ja	Ja

Nichts konnte die Lücke füllen. Also haben wir Crucible gebaut.

---

Erste Schritte

# Installieren
npm install -g @crucible/cli

# Namespace hinzufügen (Entra ID — nutzt die az login-Session)
crucible config add prod --namespace sb-prod.servicebus.windows.net

# Oder mit Connection String
crucible config add dev --connection-string "Endpoint=sb://..."

# Fertig
crucible status

Crucible nutzt DefaultAzureCredential — es greift auf die az login-Session, Umgebungsvariablen oder Managed Identity zurück. Keine Connection Strings nötig (aber unterstützt, wenn bevorzugt).

---

Lieber ein Dashboard?

Wer eine visuelle Oberfläche bevorzugt — oder Funktionen wie Auto-Remediation, DLQ-Trend-Charts, Incident-Timeline und Audit-Trail braucht — für den gibt es ein selbst gehostetes Web-Dashboard aus demselben Projekt:

docker run -e SERVICE_BUS_CONNECTION_STRING="..." -p 3000:3000 ghcr.io/broediger/crucible

Das war’s. localhost:3000 öffnen. Kein Konto, keine Registrierung. Nutzt standardmäßig eingebettetes SQLite — kein Datenbank-Setup nötig.

Was das Dashboard zusätzlich zum CLI bietet:

• DLQ-Trend-Sparklines über alle Entities
• Auto-Remediation-Regeln (Replay/Redirect/Discard basierend auf Bedingungen — ohne menschliches Eingreifen)
• Interaktives Flussdiagramm (Topics → Subscriptions → Rules)
• Incident-Timeline mit Korrelation von DLQ-Spitzen und Deployments
• Webhook-Benachrichtigungen (Slack, Teams, E-Mail)
• Audit-Trail für alle destruktiven Operationen

CLI und Dashboard sind Begleiter, keine Konkurrenten. Das CLI für schnelle Terminal-Operationen, das Dashboard für Monitoring und Team-Transparenz. Oder beides — sie verbinden sich mit denselben Namespaces.

---

Was es nicht ist

Crucible versucht nicht, Azure Monitor oder Datadog zu ersetzen. Es macht kein generisches Cloud-Monitoring. Es macht eine Sache — Azure Service Bus-Operationen — und das richtig gut.

---

Open Source

Crucible CLI ist Open Source unter [MIT/Apache 2.0 — TBD]. Der Code ist auf GitHub:

→ github.com/broediger/crucible-cli

Stern geben, ausprobieren, Issues melden. Wir bauen das für die Teams, die es leid sind, immer wieder dieselben Service Bus-Skripte zu schreiben.

---

Was kommt als Nächstes

• crucible costs — geschätzte monatliche Kosten und Optimierungsvorschläge (ungenutzte Queues, überdimensionierte Topics)
• crucible remediate --rules rules.yaml — deklarative Auto-Remediation aus einer Konfigurationsdatei (wie kubectl apply für DLQ-Regeln)
• Homebrew Tap — brew install crucible für macOS/Linux
• Standalone-Binaries — Einzeldatei-Downloads für Umgebungen ohne Node.js

---

Crucible wird von Rubj IT entwickelt — eine spezialisierte Power Platform und Azure-Architekturpraxis. Von der Spezifikation bis zur Produktion.