managing-activemq

name	managing-activemq
description	Use when working with Activemq — activeMQ broker health, destination management, advisory topic monitoring, network connector status, and message flow analysis.
connection_type	activemq
preload	false

ActiveMQ Management Skill

Analyze and manage ActiveMQ brokers with safe, read-only operations.

MANDATORY: Two-Phase Execution

You MUST follow this two-phase pattern. Skipping Phase 1 causes hallucinated queue/topic names.

Phase 1: Discovery (ALWAYS run first)

#!/bin/bash

# 1. Broker info (Jolokia/REST API)
curl -s -u "$AMQ_USER:$AMQ_PASSWORD" \
    "http://$AMQ_HOST:8161/api/jolokia/read/org.apache.activemq:type=Broker,brokerName=*"

# 2. List queues
curl -s -u "$AMQ_USER:$AMQ_PASSWORD" \
    "http://$AMQ_HOST:8161/api/jolokia/read/org.apache.activemq:type=Broker,brokerName=localhost/Queues"

# 3. List topics
curl -s -u "$AMQ_USER:$AMQ_PASSWORD" \
    "http://$AMQ_HOST:8161/api/jolokia/read/org.apache.activemq:type=Broker,brokerName=localhost/Topics"

# For ActiveMQ Artemis (newer):
# 4. List queues (Artemis)
curl -s -u "$AMQ_USER:$AMQ_PASSWORD" \
    "http://$AMQ_HOST:8161/console/jolokia/read/org.apache.activemq.artemis:broker=\"*\",component=addresses"

# 5. Queue stats
curl -s -u "$AMQ_USER:$AMQ_PASSWORD" \
    "http://$AMQ_HOST:8161/api/jolokia/read/org.apache.activemq:type=Broker,brokerName=localhost,destinationType=Queue,destinationName=my_queue"

Phase 1 outputs:

• Broker name and version
• Queue and topic list with message counts
• Consumer and producer counts

Phase 2: Analysis (only after Phase 1)

Only reference queues, topics, and destinations confirmed in Phase 1.

Shell Script Patterns

Helper Function

#!/bin/bash

# Jolokia API helper — always use this
amq_jolokia() {
    local mbean="$1"
    curl -s -u "${AMQ_USER:-admin}:${AMQ_PASSWORD:-admin}" \
        "http://${AMQ_HOST:-localhost}:8161/api/jolokia/read/$mbean"
}

# Jolokia exec helper (for operations)
amq_exec() {
    local mbean="$1" operation="$2"
    curl -s -u "${AMQ_USER:-admin}:${AMQ_PASSWORD:-admin}" \
        -X POST -H "Content-Type: application/json" \
        -d "{\"type\":\"exec\",\"mbean\":\"$mbean\",\"operation\":\"$operation\"}" \
        "http://${AMQ_HOST:-localhost}:8161/api/jolokia/"
}

# ActiveMQ Web Console API
amq_api() {
    local endpoint="$1"
    curl -s -u "${AMQ_USER:-admin}:${AMQ_PASSWORD:-admin}" \
        "http://${AMQ_HOST:-localhost}:8161/api/$endpoint"
}

Anti-Hallucination Rules

• NEVER reference a queue or topic without confirming via Jolokia API or web console
• NEVER assume broker name — always query broker info first
• NEVER guess destination names — always list destinations
• NEVER assume Classic vs Artemis — check broker type first
• NEVER assume network connector names — list them from broker config

Safety Rules

• READ-ONLY ONLY: Use only Jolokia read operations, web console GET endpoints
• FORBIDDEN: purge, removeQueue, removeTopic, sendMessage without explicit user request
• NEVER browse messages on high-volume production queues — it can cause memory issues
• Use Jolokia read for metrics, not message browsing

Common Operations

Broker Health Overview

#!/bin/bash
echo "=== Broker Info ==="
amq_jolokia "org.apache.activemq:type=Broker,brokerName=localhost" | jq '.value | {BrokerId, BrokerName, BrokerVersion, Uptime, MemoryLimit, StoreLimit, TempLimit, MemoryPercentUsage, StorePercentUsage, TempPercentUsage}'

echo ""
echo "=== Queue Summary ==="
amq_jolokia "org.apache.activemq:type=Broker,brokerName=localhost" | jq '.value.Queues | length | tostring + " queues"'

echo ""
echo "=== Topic Summary ==="
amq_jolokia "org.apache.activemq:type=Broker,brokerName=localhost" | jq '.value.Topics | length | tostring + " topics"'

echo ""
echo "=== Health ==="
amq_jolokia "org.apache.activemq:type=Health,brokerName=localhost" 2>/dev/null | jq '.value'

Destination Management

#!/bin/bash
echo "=== Queue Details ==="
for QUEUE in $(amq_jolokia "org.apache.activemq:type=Broker,brokerName=localhost" | jq -r '.value.Queues[].objectName' 2>/dev/null); do
    amq_jolokia "$QUEUE" | jq '.value | {Name, QueueSize, EnqueueCount, DequeueCount, ConsumerCount, ProducerCount, MemoryPercentUsage, InFlightCount}'
done

echo ""
echo "=== Topics with Subscribers ==="
for TOPIC in $(amq_jolokia "org.apache.activemq:type=Broker,brokerName=localhost" | jq -r '.value.Topics[].objectName' 2>/dev/null); do
    amq_jolokia "$TOPIC" | jq '.value | select(.ConsumerCount > 0) | {Name, ConsumerCount, EnqueueCount, DequeueCount}'
done

Network Connector Status

#!/bin/bash
echo "=== Network Connectors ==="
amq_jolokia "org.apache.activemq:type=Broker,brokerName=localhost,connector=networkConnectors,networkConnectorName=*" | jq '.value | to_entries[] | {name: .key, active: .value.Started, duplex: .value.Duplex}' 2>/dev/null || echo "No network connectors configured"

echo ""
echo "=== Transport Connectors ==="
amq_jolokia "org.apache.activemq:type=Broker,brokerName=localhost,connector=clientConnectors,connectorName=*" | jq '.value' 2>/dev/null

Advisory Topics

#!/bin/bash
echo "=== Advisory Topics ==="
amq_jolokia "org.apache.activemq:type=Broker,brokerName=localhost" | jq '[.value.Topics[].objectName | select(contains("Advisory"))]' 2>/dev/null

echo ""
echo "=== Connection Count ==="
amq_jolokia "org.apache.activemq:type=Broker,brokerName=localhost" | jq '.value | {CurrentConnectionsCount, TotalConnectionsCount, TotalConsumerCount, TotalProducerCount, TotalMessageCount}'

Output Format

Present results as a structured report:

Managing Activemq Report
════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Counter-Rationalizations

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative

Common Pitfalls

• Store limit: When store usage hits 100%, producers are blocked — monitor StorePercentUsage
• Memory limit: Memory usage exceeding threshold triggers flow control
• DLQ accumulation: Failed messages go to ActiveMQ.DLQ — monitor its size
• Slow consumers: Slow consumers on topics cause memory buildup — check advisory topics
• Network bridge lag: Network connectors between brokers can have replication lag
• Classic vs Artemis API: ActiveMQ Classic and Artemis have different JMX/Jolokia endpoints