Skill v1.0.1
currentAutomated scan100/100+4 new
name: azure-eventhub-ts description: "High-throughput event streaming and real-time data ingestion." risk: critical source: community date_added: "2026-02-27" metadata: version: "1.0.1"
Azure Event Hubs SDK for TypeScript
High-throughput event streaming and real-time data ingestion.
Installation
npm install @azure/event-hubs @azure/identity
For checkpointing with consumer groups:
npm install @azure/eventhubs-checkpointstore-blob @azure/storage-blob
Environment Variables
EVENTHUB_NAMESPACE=<namespace>.servicebus.windows.netEVENTHUB_NAME=my-eventhubSTORAGE_ACCOUNT_NAME=<storage-account>STORAGE_CONTAINER_NAME=checkpoints
Authentication
import { EventHubProducerClient, EventHubConsumerClient } from "@azure/event-hubs";import { DefaultAzureCredential } from "@azure/identity";const fullyQualifiedNamespace = process.env.EVENTHUB_NAMESPACE!;const eventHubName = process.env.EVENTHUB_NAME!;const credential = new DefaultAzureCredential();// Producerconst producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential);// Consumerconst consumer = new EventHubConsumerClient("$Default", // Consumer groupfullyQualifiedNamespace,eventHubName,credential);
Core Workflow
Send Events
const producer = new EventHubProducerClient(namespace, eventHubName, credential);// Create batch and add eventsconst batch = await producer.createBatch();for (const body of [{ temperature: 72.5, deviceId: "sensor-1" }, { temperature: 68.2, deviceId: "sensor-2" }]) {if (!batch.tryAdd({ body })) throw new Error("Event does not fit this batch; flush/rebatch or reject oversized event");}await producer.sendBatch(batch);await producer.close();
Send to Specific Partition
// By partition IDconst batch = await producer.createBatch({ partitionId: "0" });// By partition key (consistent hashing)const batch = await producer.createBatch({ partitionKey: "device-123" });
Receive Events (Simple)
const consumer = new EventHubConsumerClient("$Default", namespace, eventHubName, credential);const subscription = consumer.subscribe({processEvents: async (events, context) => {for (const event of events) {console.log(`Partition: ${context.partitionId}, Body: ${JSON.stringify(event.body)}`);}},processError: async (err, context) => {console.error(`Error on partition ${context.partitionId}: ${err.message}`);},});// Stop after some timesetTimeout(async () => {await subscription.close();await consumer.close();}, 60000);
Receive with Checkpointing (Production)
import { EventHubConsumerClient } from "@azure/event-hubs";import { ContainerClient } from "@azure/storage-blob";import { BlobCheckpointStore } from "@azure/eventhubs-checkpointstore-blob";const containerClient = new ContainerClient(`https://${storageAccount}.blob.core.windows.net/${containerName}`,credential);const checkpointStore = new BlobCheckpointStore(containerClient);const consumer = new EventHubConsumerClient("$Default",namespace,eventHubName,credential,checkpointStore);const subscription = consumer.subscribe({processEvents: async (events, context) => {for (const event of events) {console.log(`Processing: ${JSON.stringify(event.body)}`);}// Checkpoint after processing batchif (events.length > 0) {await context.updateCheckpoint(events[events.length - 1]);}},processError: async (err, context) => {console.error(`Error: ${err.message}`);},});
Receive from Specific Position
const subscription = consumer.subscribe({processEvents: async (events, context) => { /* ... */ },processError: async (err, context) => { /* ... */ },}, {startPosition: {// Start from beginning"0": { offset: "@earliest" },// Start from end (new events only)"1": { offset: "@latest" },// Start from specific offset"2": { offset: "12345" },// Start from specific time"3": { enqueuedOn: new Date("2024-01-01") },},});
Event Hub Properties
// Get hub infoconst hubProperties = await producer.getEventHubProperties();console.log(`Partitions: ${hubProperties.partitionIds}`);// Get partition infoconst partitionProperties = await producer.getPartitionProperties("0");console.log(`Last sequence: ${partitionProperties.lastEnqueuedSequenceNumber}`);
Batch Processing Options
const subscription = consumer.subscribe({processEvents: async (events, context) => { /* ... */ },processError: async (err, context) => { /* ... */ },},{maxBatchSize: 100, // Max events per batchmaxWaitTimeInSeconds: 30, // Max wait for batch});
Key Types
import {EventHubProducerClient,EventHubConsumerClient,EventData,ReceivedEventData,PartitionContext,Subscription,SubscriptionEventHandlers,CreateBatchOptions,EventPosition,} from "@azure/event-hubs";import { BlobCheckpointStore } from "@azure/eventhubs-checkpointstore-blob";
Event Properties
// Send with propertiesconst batch = await producer.createBatch();batch.tryAdd({body: { data: "payload" },properties: {eventType: "telemetry",deviceId: "sensor-1",},contentType: "application/json",correlationId: "request-123",});// Access in receiverconsumer.subscribe({processEvents: async (events, context) => {for (const event of events) {console.log(`Type: ${event.properties?.eventType}`);console.log(`Sequence: ${event.sequenceNumber}`);console.log(`Enqueued: ${event.enqueuedTimeUtc}`);console.log(`Offset: ${event.offset}`);}},});
Error Handling
consumer.subscribe({processEvents: async (events, context) => {try {for (const event of events) {await processEvent(event);}if (events.length > 0) await context.updateCheckpoint(events[events.length - 1]);} catch (error) {// Don't checkpoint on error - events will be reprocessedconsole.error("Processing failed:", error);}},processError: async (err, context) => {if (err.name === "MessagingError") {// Transient error - SDK will retryconsole.warn("Transient error:", err.message);} else {// Fatal errorconsole.error("Fatal error:", err);}},});
Best Practices
- Use checkpointing - Checkpoint only after durable processing; delivery can repeat, so make handlers idempotent
- Batch sends - Use
createBatch()for efficient sending - Partition keys - Use partition keys to ensure ordering for related events
- Consumer groups - Use separate consumer groups for different processing pipelines
- Handle errors gracefully - Don't checkpoint on processing failures
- Close clients - Always close producer/consumer when done
- Monitor lag - Track
lastEnqueuedSequenceNumbervs processed sequence
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Checkpointing records progress; it does not make external side effects exactly once or guarantee an immediate retry when an error is swallowed. Use stable event IDs, durable deduplication and an explicit retry/dead-letter design. Inspect retryability rather than treating every MessagingError as transient. Examples are fragments; supply imports/handlers and redact event bodies. Official SDK guide.