Integration Event Hubs stream processing

Sequence number

A sequence number in Azure Event Hubs is the ordered number assigned to an event within a specific partition. It helps consumers identify position in the partition log, resume or replay processing from a known point, and diagnose gaps, duplicates, or lag alongside offsets and enqueued time.

Source: Microsoft Learn - Azure Event Hubs features and terminology Reviewed 2026-05-23

Exam trap: Assuming sequence numbers are globally ordered across all partitions instead of ordered only within a single Event Hubs partition.
Production check: Confirm the partition ID before comparing two sequence numbers, because values from different partitions do not establish global order.

Practice this topic Microsoft Learn

Article details and learning context

Aliases: Event Hubs sequence number, event sequence number, partition sequence number, stream sequence number
Difficulty: intermediate
CLI mappings: 4
Last verified: 2026-05-23
Review level: template-specs-five-use-cases
Article depth: template-specs-five-use-cases-three-case-studies

Related context No curated learning path mapped yet; use the category trail.

Compare related concepts Search related resources Browse the glossary

Understand the concept

In plain English

A sequence number is the position marker Event Hubs assigns to an event inside one partition. Think of each partition as its own ordered log. The sequence number tells consumers where an event sits in that log, but it is not a single global counter across the whole event hub. Operators use it when replaying messages, checking whether a consumer skipped ahead, explaining duplicates, or proving that events arrived in partition order. It is evidence for stream position, not a business transaction ID.

Why it matters

Sequence numbers matter because stream processing failures are usually about position. When a consumer restarts, a checkpoint is wrong, or downstream storage shows missing records, engineers need to know which partition and which event position are involved. Sequence numbers help reconstruct the timeline without confusing ingestion order across multiple partitions. They also make incident conversations precise: a team can say partition three processed through sequence number 918244, while partition seven lagged behind. That clarity shortens recovery, supports audit evidence, and prevents false assumptions that a multi-partition stream has one universal order. It prevents producer blame without partition evidence and gives replay work a precise anchor. It is the shared vocabulary between developers, operators, auditors, and replay automation.

Technical context

In Azure architecture, sequence numbers live in the Event Hubs data plane with offsets, partition IDs, enqueued time, consumer groups, and checkpoints. Producers send events to partitions, Event Hubs appends them to partition logs, and consumers read from positions. SDKs expose sequence numbers for received events and partition properties, while Azure CLI mainly inspects the namespace, event hub, consumer groups, retention, partition count, and metrics around the stream. Stream Analytics, Functions, and custom consumers use these positions to manage replay and progress.

Exam context

Compare with

Event Hubs Event Hub

Where it is used

Where you see it

In Event Hubs SDK receive logs, each event can include partition ID, offset, enqueued time, and sequence number for replay or diagnostics. during consumer troubleshooting reviews. during consumer troubleshooting and replay analysis
In checkpoint records or processor diagnostics, sequence numbers show the last processed event position for a consumer group within a specific partition. in replay discussions. during processor recovery reviews
In incident notebooks, engineers compare sequence numbers from failed downstream records against partition metrics, Capture files, and consumer restart points. after incident triage and recovery. after stream incidents and audits

Common situations

Replay one Event Hubs partition from a known position after a downstream database failure without reprocessing the entire stream.
Prove that an apparent missing telemetry record was delayed in a consumer group rather than lost at ingestion.
Diagnose duplicate processing by comparing stored checkpoint positions with sequence numbers written into downstream audit records.
Design partition-key strategy for workloads where business events must remain ordered for each account, device, or shipment.
Estimate partition-specific lag by comparing consumer progress against the latest observed sequence number in Event Hubs diagnostics.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Scenario 01 Energy telemetry replay avoids a false data-loss incident Scenario, objectives, solution, measured impact, and takeaway.

Scenario

A wind-farm monitoring platform showed missing turbine readings after a processor crash, and operations leaders believed Event Hubs had dropped telemetry.

Goals

Determine whether records were lost, delayed, or skipped by one consumer.
Replay only the affected partition range without duplicating all daily telemetry.
Restore dashboard completeness before the morning reliability review.
Create incident evidence clear enough for non-streaming stakeholders.

Approach using Sequence number

Engineers compared SDK logs containing partition IDs and sequence numbers with the checkpoint store used by the telemetry processor. Azure CLI confirmed the event hub retention period, partition count, and consumer group configuration. The team found that partition two had checkpointed past a failed database batch. They restored the previous checkpoint, replayed from the saved sequence number, and used idempotent turbine-reading keys to prevent duplicate writes. Metrics were exported to show that ingestion continued normally during the incident. Replay evidence was archived with the incident record. The drill record also captured the approved replay window.

Potential outcomes

Dashboard gaps for 14 turbines were filled within 47 minutes.
Replay processed 82,000 events instead of a full-day stream of 3.8 million events.
No duplicate turbine readings remained after idempotent merge validation.
The incident was reclassified from data loss to consumer checkpoint error.

What to learn

Sequence numbers give teams the partition-level evidence needed to recover stream processors without panicked full replays.

Scenario 02 Ticketing platform proves order for seat inventory updates Scenario, objectives, solution, measured impact, and takeaway.

Scenario

A live-event ticketing platform had seat inventory mismatches whenever payment, reservation, and release events arrived close together during high-demand onsales.

Goals

Keep events ordered for each seat block without forcing a single global stream.
Detect whether inventory mismatches came from producer order or consumer lag.
Reduce manual reconciliation before venue settlement.
Preserve enough evidence for dispute review with partners.

Approach using Sequence number

The architecture team changed producers to use a stable seat-block partition key and logged partition ID, sequence number, and order ID into downstream records. Azure CLI scripts exported partition count, consumer group, and retention settings before the onsale. When mismatches appeared, engineers compared sequence numbers inside the same partition and found that one consumer retried a stale release event after a payment success. Checkpoint handling was corrected, and downstream writes became idempotent by order event type. Auditors received the partition evidence package and replay note. The runbook assigned replay approval to the operations lead.

Potential outcomes

Manual reconciliation workload dropped from 620 seat blocks to 74 after the next onsale.
Inventory mismatch rate fell from 1.8 percent to 0.2 percent.
Partner dispute packets included partition and sequence evidence instead of manual timelines.
Processor rollback time decreased from two hours to under twenty minutes.

What to learn

Sequence numbers make ordering debates concrete when producers, consumers, and downstream stores all preserve partition position.

Scenario 03 Cold-chain logistics team isolates one lagging partition Scenario, objectives, solution, measured impact, and takeaway.

Scenario

A logistics company streamed temperature readings from refrigerated containers and saw late alerts for one shipping lane during a storm-related traffic surge.

Goals

Identify whether alert delay came from ingestion, partition imbalance, or the rules engine.
Protect compliance evidence for food-safety audits.
Avoid broad replay that could create duplicate customer notifications.
Tune processing before the next seasonal peak.

Approach using Sequence number

The platform team recorded sequence numbers at receive time and when alerts were written to Cosmos DB. Azure CLI pulled Event Hubs metrics and confirmed that only one partition showed rising outgoing-message lag. The partition key tied several high-volume routes to the same partition, so the team replayed a bounded sequence-number range, suppressed duplicate notifications, and adjusted producer partitioning for new container groups. The compliance dashboard stored sequence range, processing delay, and alert decision for audit review. Support could quote exact stream positions during vendor reviews, refunds, and escalations. The audit package included screenshots of the exact partition checkpoint.

Potential outcomes

Late alert volume on the affected lane dropped 63 percent after partition-key tuning.
Replay was limited to 31,500 events and avoided duplicate customer alerts.
Audit evidence showed all temperature breaches were processed within retention.
Peak-season processor capacity planning gained a partition-level lag threshold.

What to learn

Sequence numbers help streaming teams recover precisely and tune partition design before lag turns into business risk.

Azure CLI

I use Azure CLI around sequence-number investigations even though the exact event sequence number usually comes from SDK logs, Capture files, or consumer diagnostics. The CLI proves the platform shape: namespace, event hub, partition count, retention, consumer groups, authorization, and throughput-related metrics. After years of production streaming incidents, I do not troubleshoot positions without confirming the event hub being inspected is the same one the application uses. CLI output also makes it easy to compare environments, export resource IDs, pull metrics, and document whether lag came from configuration, traffic, or consumer code. CLI supplies the namespace and retention context around that event evidence. Without that context, a sequence number alone is just a number from the wrong layer.

Useful for

Show the event hub partition count, retention period, status, and resource ID before planning replay.
List consumer groups to confirm the checkpoint namespace being investigated matches the affected application.
Pull Event Hubs metrics around incoming and outgoing messages to correlate sequence-number lag with traffic spikes.
Export namespace and event hub configuration for incident evidence when SDK logs show problematic positions.
Compare dev and production event hub settings before changing partition count assumptions in consumer code.

Before you run a command

Confirm tenant, subscription, namespace, event hub name, consumer group, resource group, and whether the issue affects one partition or the whole stream.
Treat connection strings, SAS keys, managed identities, checkpoint stores, and Capture storage as sensitive because replay access can expose payload data.
Check retention before replay work; if the needed sequence-number range has aged out, CLI inspection cannot recover expired events.

What the output tells you

Event hub output shows partition count, retention, status, message size limits, and resource IDs that frame what replay and ordering are possible.
Consumer group output identifies which applications have independent checkpoints, helping avoid a restart against the wrong processing position.
Metric output shows ingestion and egress patterns, which helps connect sequence-number lag to producer bursts, slow consumers, or downstream bottlenecks.

Mapped commands

Event Hubs sequence-number investigation helpers

adjacent

az eventhubs namespace show --name <namespace> --resource-group <resource-group> --output json

az eventhubs namespacediscoverIntegration

az eventhubs eventhub show --name <event-hub> --namespace-name <namespace> --resource-group <resource-group> --output json

az eventhubs eventhubdiscoverIntegration

az eventhubs eventhub consumer-group list --eventhub-name <event-hub> --namespace-name <namespace> --resource-group <resource-group> --output table

az eventhubs eventhub consumer-groupdiscoverIntegration

az monitor metrics list --resource <event-hub-resource-id> --metric IncomingMessages,OutgoingMessages --interval PT1M --output json

az monitor metricsdiscoverIntegration

Architecture context

Architecturally, sequence number is part of the ordering contract for each Event Hubs partition. If a workload needs strict order, the producer must choose partitioning carefully, often by using a stable partition key for a business entity. Consumers then checkpoint per partition and resume from a precise position. Architects should not promise global ordering across partitions. They should design idempotent processing, duplicate detection, replay windows, and poison-event handling around partition-local order. Sequence numbers become especially useful when Event Hubs feeds Functions, Stream Analytics, Databricks, or custom processors that must recover safely after interruption. Make ordering guarantees explicit in producer, partition-key, and consumer-group design. Design reviews should explicitly name the ordering boundary, checkpoint owner, and replay authority.

Security: Security impact is indirect because sequence numbers are not credentials or permissions. The risk appears in diagnostic access and replay capability. Anyone who can read the event hub, inspect Capture output, or control consumer checkpoints may expose event payloads or replay sensitive data. Operators should protect connection strings, SAS policies, managed identities, and storage accounts used for checkpoints or Capture. Diagnostic logs that include sequence numbers are usually safe alone, but when combined with payloads, partitions, and timestamps, they can reveal business activity patterns that deserve access control and retention limits. Restrict exported stream positions because they can reveal operational timing and customer activity. The safest evidence package proves position without exposing unnecessary business payloads.
Cost: Sequence numbers have no direct billing line, but they influence operational cost by determining how efficiently teams replay and diagnose streams. Poor checkpointing can force large replay jobs, extra Event Hubs throughput, downstream writes, Databricks processing, or storage reads from Capture. If retention is too short, teams may need expensive backfills from source systems. If retention is too long, storage and namespace costs rise. FinOps owners should review retention, Capture, consumer group count, and replay frequency with engineering so recovery capability is funded intentionally instead of improvised during outages. Size retention and checkpoint storage from recovery objectives, not vague hopes about later replay. A clear sequence range prevents broad, expensive reprocessing during incident recovery.
Reliability: Reliability impact is direct for stream recovery. Sequence numbers help consumers resume from a known partition position, verify whether replay covered the intended range, and determine whether downstream gaps are missing events or delayed processing. Reliable designs store checkpoints durably, tolerate duplicate processing, and avoid assuming sequence numbers are continuous across partitions. Operators should watch consumer lag, checkpoint age, retention windows, and partition-specific failures. If retention expires before a consumer replays the missing range, sequence numbers can prove where the gap occurred but cannot recover data that aged out. Practice replay, duplicate handling, checkpoint repair, and rollback messaging before incidents start. Recovery drills should prove the team can replay a range without corrupting downstream state.
Performance: Performance impact is indirect. Sequence numbers do not make Event Hubs faster, but they help measure and tune stream progress. Consumers can compare last processed sequence numbers with partition properties to estimate lag and identify slow partitions. High-throughput workloads should avoid excessive per-event logging, because logging every sequence number can overwhelm diagnostics. Performance tuning usually focuses on partition count, batch size, prefetch, checkpoint frequency, and downstream write throughput. Sequence numbers provide the position evidence needed to prove whether a bottleneck is ingestion, consumer code, checkpointing, or output storage. Track per-partition lag, hot keys, and consumer speed so bottlenecks appear early. Hot partition alerts should include the partition and checkpoint position, not only aggregate throughput.
Operations: Operators use sequence numbers during incident review, replay planning, and consumer-lag analysis. They collect partition ID, offset, sequence number, enqueued time, consumer group, checkpoint timestamp, and downstream write time. CLI helps inventory the event hub configuration and metrics, while SDK logs or processor checkpoints provide the actual positions. Runbooks should explain how to map a failed downstream record back to its partition position, how to restart from a safe checkpoint, and how to avoid replaying beyond the retention window. Good notes prevent duplicate-processing confusion. Include partition scope, offset, consumer group, checkpoint timestamp, and owner approval in every replay ticket for audit. Runbooks should include ownership of the checkpoint store and replay approval path.

Common mistakes

Assuming sequence numbers are globally ordered across all partitions instead of ordered only within a single Event Hubs partition.
Using sequence numbers as business identifiers, then being surprised when different partitions contain overlapping or unrelated positions.
Deleting or overwriting checkpoints during troubleshooting without preserving the last known partition sequence numbers for rollback or replay evidence.

On this page