d-subrahmanyam/azure-service-bus

Azure Service Bus Core Knowledge

Full Reference: See advanced.md for Java/Python/C# producer patterns, Java processor consumer, session consumer, and Terraform security/monitoring configurations.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: azure-service-bus for comprehensive documentation.

Quick Start (Local Emulator)

# docker-compose.yml (Azure Service Bus Emulator - preview)
services:
  servicebus:
    image: mcr.microsoft.com/azure-messaging/servicebus-emulator:latest
    ports:
      - "5672:5672"
    environment:
      - ACCEPT_EULA=Y
      - SQL_SERVER=sqlserver
    depends_on:
      - sqlserver

  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourStrong!Passw0rd

# Azure CLI
az servicebus namespace create --name myservicebus --resource-group mygroup
az servicebus queue create --namespace-name myservicebus --name orders
az servicebus topic create --namespace-name myservicebus --name events
az servicebus topic subscription create --namespace-name myservicebus \
  --topic-name events --name order-processor

Core Concepts

| Concept | Description | |---------|-------------| | Namespace | Container for messaging entities | | Queue | Point-to-point messaging | | Topic | Publish-subscribe messaging | | Subscription | Topic consumer with filters | | Session | Ordered message processing | | Dead-letter | Failed message destination |

Tiers Comparison

| Feature | Basic | Standard | Premium | |---------|-------|----------|---------| | Queues | Yes | Yes | Yes | | Topics | No | Yes | Yes | | Sessions | No | Yes | Yes | | Transactions | No | Yes | Yes | | Max message size | 256KB | 256KB | 100MB | | Throughput | Shared | Shared | Dedicated |

Producer Pattern (Node.js)

import { ServiceBusClient } from '@azure/service-bus';

const client = new ServiceBusClient(connectionString);
const sender = client.createSender('orders');

// Send single message
await sender.sendMessages({
  body: order,
  contentType: 'application/json',
  correlationId: correlationId,
  messageId: order.id,
  applicationProperties: {
    orderType: order.type,
    priority: order.priority,
  },
});

// Send batch
const batch = await sender.createMessageBatch();
for (const order of orders) {
  if (!batch.tryAddMessage({ body: order, messageId: order.id })) {
    await sender.sendMessages(batch);
    batch = await sender.createMessageBatch();
    batch.tryAddMessage({ body: order, messageId: order.id });
  }
}
await sender.sendMessages(batch);

// Schedule message
await sender.scheduleMessages(
  { body: order },
  new Date(Date.now() + 60000) // 1 minute delay
);

// Send to topic
const topicSender = client.createSender('events');
await topicSender.sendMessages({
  body: { type: 'OrderCreated', data: order },
  subject: 'orders',  // For subscription filtering
  correlationId: correlationId,
});

await sender.close();
await client.close();

Consumer Pattern (Node.js)

const receiver = client.createReceiver('orders', {
  receiveMode: 'peekLock',
  maxAutoLockRenewalDurationInMs: 300000,
});

// Process messages
const messageHandler = async (message) => {
  try {
    const order = message.body;
    await processOrder(order);
    await receiver.completeMessage(message);
  } catch (error) {
    if (message.deliveryCount >= 3) {
      await receiver.deadLetterMessage(message, {
        deadLetterReason: 'MaxRetriesExceeded',
        deadLetterErrorDescription: error.message,
      });
    } else {
      await receiver.abandonMessage(message);
    }
  }
};

const errorHandler = async (error) => {
  console.error('Error:', error);
};

receiver.subscribe({
  processMessage: messageHandler,
  processError: errorHandler,
});

// Subscription consumer with filter
const subscriptionReceiver = client.createReceiver('events', 'order-processor');

// Session consumer (ordered processing)
const sessionReceiver = await client.acceptSession('orders', 'session-1');
const messages = await sessionReceiver.receiveMessages(10);
for (const msg of messages) {
  await processMessage(msg);
  await sessionReceiver.completeMessage(msg);
}

// Dead letter consumer
const dlqReceiver = client.createReceiver('orders', {
  subQueueType: 'deadLetter',
});

Subscription Filters

# SQL filter
az servicebus topic subscription rule create \
  --namespace-name myservicebus \
  --topic-name events \
  --subscription-name high-priority \
  --name priority-filter \
  --filter-sql-expression "priority > 5"

# Correlation filter
az servicebus topic subscription rule create \
  --namespace-name myservicebus \
  --topic-name events \
  --subscription-name orders-only \
  --name order-filter \
  --correlation-filter subject=orders

// Create subscription with filter (SDK)
const adminClient = new ServiceBusAdministrationClient(connectionString);

await adminClient.createSubscription('events', 'high-priority');
await adminClient.createRule('events', 'high-priority', 'priority-filter', {
  filter: {
    sqlExpression: "priority > 5",
  },
});

Production Readiness

Security Configuration

// Managed Identity
import { DefaultAzureCredential } from '@azure/identity';

const client = new ServiceBusClient(
  'myservicebus.servicebus.windows.net',
  new DefaultAzureCredential()
);

// SAS Token
const client = new ServiceBusClient(connectionString);

Monitoring Metrics

| Metric | Alert Threshold | |--------|-----------------| | ActiveMessages | > 10000 | | DeadletteredMessages | > 0 | | Size | > 80% of quota | | ThrottledRequests | > 0 | | ServerErrors | > 0 |

Checklist

• [ ] Managed Identity authentication
• [ ] Private endpoints configured
• [ ] Network rules (firewall)
• [ ] Dead-letter queue handling
• [ ] Auto-forwarding for routing
• [ ] Duplicate detection enabled
• [ ] Message TTL configured
• [ ] Sessions for ordering (if needed)
• [ ] Azure Monitor alerts
• [ ] Diagnostic logs enabled

When NOT to Use This Skill

Use alternative messaging solutions when:

• AWS-native architecture - SQS integrates better
• GCP-native architecture - Use Google Pub/Sub
• Event streaming with replay - Use Azure Event Hubs or Kafka
• On-premise deployment - Use RabbitMQ or ActiveMQ
• Multi-cloud strategy - Use Kafka or RabbitMQ
• Simple pub/sub - Use Redis or NATS
• Ultra-high throughput - Event Hubs or Kafka scale better

Anti-Patterns

| Anti-Pattern | Why It's Bad | Solution | |--------------|--------------|----------| | Basic tier in production | No topics, limited features | Use Standard or Premium tier | | No dead letter queue | Failed messages lost | Enable DLQ on all queues/subscriptions | | Short lock duration | Duplicate processing | Set lock duration > processing time | | No auto-delete on idle | Wasted resources and cost | Set auto-delete for temporary queues | | Connection string everywhere | Security risk | Use Managed Identity | | No batching | Higher latency and cost | Batch up to 10 messages | | Peek-lock without complete | Messages expire and reprocess | Always complete or abandon | | Standard tier for ordering | No sessions available | Use Premium tier for sessions | | Large message bodies | Higher costs | Use claim check pattern with Blob Storage | | No monitoring | Invisible issues | Enable Azure Monitor metrics/alerts |

Quick Troubleshooting

| Issue | Likely Cause | Fix | |-------|--------------|-----| | Messages not received | Wrong queue/topic name or permissions | Verify name and check RBAC/SAS | | Duplicate messages | Lock duration expired | Increase lock duration or process faster | | Messages in DLQ | Max delivery count exceeded | Check processing logic, review DLQ | | Access denied | Missing RBAC role or invalid SAS | Assign Sender/Receiver roles | | Throttling errors | Exceeded tier limits | Upgrade tier or reduce send rate | | Lock lost exception | Processing time > lock duration | Renew lock or increase duration | | Session not available | No sessions in queue | Enable sessions on queue creation | | Filter not working | Wrong SQL filter syntax | Test filter, check message properties | | Connection errors | Network issues or firewall | Check VNet, private endpoints, firewall | | High costs | Too many operations | Use batching, optimize polling |

Reference Documentation

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: azure-service-bus for comprehensive documentation.

Available topics: basics, producers, consumers, production