Peek-lock is the safer way to receive a Service Bus message when the app needs time to process it. Service Bus shows the message to one receiver and locks it so another receiver does not process it at the same time. If processing succeeds, the app completes the message and it is removed. If the app fails, abandons it, or the lock expires, the message can be delivered again. That protects against losing work, but the app must handle possible duplicates.
peek lock, peek-lock processing, message lock, Service Bus lock, at-least-once receive
Difficulty
intermediate
CLI mappings
5
Last verified
2026-05-17
Microsoft Learn
In Azure Service Bus, peek-lock is a receive pattern where the broker locks a message, returns it to one receiver, and waits for settlement. The receiver then completes, abandons, defers, dead-letters, or lets the lock expire, enabling at-least-once processing instead of immediate deletion.
In Azure architecture, peek-lock sits in the messaging data plane for Service Bus queues and topic subscriptions. It works with lock duration, delivery count, max delivery count, dead-letter queues, transactions, sessions, client SDK settlement APIs, and Azure Functions triggers. The receive operation creates a temporary lock, and settlement calls decide the final message state. Operators configure the entity’s lock duration and delivery behavior on the control plane, while application code performs complete, abandon, defer, dead-letter, and lock-renewal actions.
Why it matters
Peek-lock matters because many integration workloads cannot afford silent message loss. Payment steps, shipping labels, device commands, document imports, and workflow transitions often need a receiver to finish work before the broker removes the message. Peek-lock provides that control, but it changes the engineering contract: handlers must be idempotent, settle messages correctly, renew locks for long work, and decide when failures should dead-letter. Without those practices, teams see duplicate processing, stuck messages, lock-lost errors, and confused incident timelines. Correct peek-lock design turns a queue into a reliable handoff point instead of a fragile notification pipe. This prevents fragile integration handoffs. Design settlement intentionally every time.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
In Service Bus queue or subscription settings, lock duration and max delivery count describe how peek-lock messages are protected and eventually dead-lettered. and replay policies. during configuration reviews.
Signal 02
In SDK code or Azure Functions logs, settlement calls such as Complete, Abandon, Defer, DeadLetter, and RenewLock show peek-lock behavior during processing. for incident review. during incident and replay investigations.
Signal 03
In Azure Monitor metrics, rising active messages, delivery count, lock-lost errors, or dead-letter counts often reveal handlers struggling with peek-lock processing. during failed processing reviews. during alerts, dashboards, and capacity reviews.
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Process business messages that should not be removed until downstream work completes successfully.
Redeliver messages after receiver crashes, transient dependency failures, or explicit abandon operations.
Dead-letter malformed or repeatedly failing messages after max delivery count is reached.
Tune lock duration, handler concurrency, idempotency, and retry behavior for reliable queue processing.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
Parcel sorter retry safety
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
SortNest Robotics routed parcels through conveyor lanes using messages from Service Bus queues. Brief scanner outages caused handlers to crash after reading routing commands, and the team needed a safer handoff model.
🎯Business/Technical Objectives
Prevent routing commands from disappearing during handler crashes.
Keep conveyor recovery under five minutes after scanner outages.
Avoid duplicate label printing when messages are redelivered.
Give operators clear dead-letter evidence for malformed commands.
✅Solution Using Peek-lock
The integration team standardized receivers on peek-lock processing. Each handler read a routing command, wrote the lane decision to a durable store, printed the label, and completed the message only after both steps succeeded. If scanner validation failed, the handler abandoned the message for retry; malformed commands were dead-lettered with a reason code. Queue lock duration was increased after timing real scanner recovery, and handlers used idempotency keys to prevent duplicate label printing. Azure CLI exported queue lockDuration and maxDeliveryCount settings during change approval, while Azure Monitor tracked active messages, dead-letter counts, and handler latency.
📈Results & Business Impact
No routing command was lost during the next five scanner outages.
Median conveyor recovery time dropped from 11 minutes to 3.6 minutes.
Duplicate label incidents fell by 88% after idempotency checks were added.
Malformed command triage time fell from 40 minutes to 9 minutes with dead-letter reasons.
💡Key Takeaway for Glossary Readers
Peek-lock protects work when a receiver needs to prove processing succeeded before the broker removes the message.
Case study 02
Market reconciliation settlement control
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
Cobalt Ledger processed trade-confirmation messages for institutional clients. A downstream reconciliation API occasionally timed out after the message was received, creating uncertainty about whether confirmations were complete.
🎯Business/Technical Objectives
Avoid losing trade confirmations during downstream API failures.
Prevent duplicate reconciliation updates when messages retry.
Separate malformed messages from transient dependency failures.
Create incident evidence for client operations teams.
✅Solution Using Peek-lock
Engineers changed the receiver so Service Bus messages remained locked until reconciliation writes were confirmed with an idempotency token. Successful writes completed the message. Transient API errors caused abandon with exponential retry, while invalid payloads were dead-lettered with a structured reason and the client reference. Lock duration matched the 95th percentile reconciliation time plus buffer, and long-running edge cases renewed locks through the SDK. Azure CLI captured queue settings and authorization rules before rollout. Dashboards correlated delivery count, dead-letter reasons, reconciliation latency, and dependency errors so operators could distinguish downstream outages from message-quality issues.
📈Results & Business Impact
Confirmation loss incidents fell to zero during the first two monthly close cycles.
Duplicate reconciliation updates dropped by 73% after idempotency enforcement.
Client incident reports included message state and settlement evidence within 30 minutes.
Dead-letter review identified one malformed upstream payload contract before wider rollout.
💡Key Takeaway for Glossary Readers
Peek-lock is most valuable when settlement is tied to durable business confirmation, not merely to message receipt.
Case study 03
Donation receipt workflow recovery
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
BrightHarbor Giving sent donation receipt jobs through Service Bus after payment authorization. Receipt generation sometimes failed when the email provider throttled, and support feared retries might duplicate donor actions.
🎯Business/Technical Objectives
Retry receipt jobs without losing authorized donations.
Avoid duplicate payment capture or duplicate donor acknowledgments.
Move bad email templates to dead-letter review.
Give support staff a safe replay process.
✅Solution Using Peek-lock
The payment system separated payment capture from receipt generation and sent receipt jobs to a Service Bus queue. Receipt workers used peek-lock and completed a message only after the receipt record was stored and the email send was accepted. Payment capture IDs acted as idempotency keys so a redelivered receipt job could not charge a donor again. Provider throttling caused abandon and retry, while invalid templates were dead-lettered with the campaign ID. Queue settings were reviewed with Azure CLI, and support used a controlled replay runbook for dead-lettered receipt jobs after template fixes. Application Insights tracked settlement outcome by campaign and provider response.
📈Results & Business Impact
Receipt job loss dropped to zero during two high-volume fundraising events.
No duplicate donor charges occurred from redelivered receipt jobs.
Template-related failures were isolated in the dead-letter queue within minutes.
Support replay time for corrected receipts fell from four hours to 35 minutes.
💡Key Takeaway for Glossary Readers
Peek-lock helps teams retry nonpayment workflow steps safely when work must be completed exactly once in business terms.
Why use Azure CLI for this?
Azure CLI does not complete or abandon individual Service Bus messages, but it is still useful around peek-lock operations. CLI commands can inspect queues and subscriptions, verify lock duration and max delivery count, review authorization rules, and update entity settings. This gives operators repeatable evidence before changing receiver code or retry policy.
CLI use cases
Show a queue or subscription to verify lockDuration, maxDeliveryCount, dead-letter settings, and message counts.
Update lock duration in a controlled change after proving handlers legitimately need more processing time.
List authorization rules and role assignments to confirm which identities can receive and settle messages.
Export entity configuration during an incident before changing concurrency, retry, or settlement behavior.
Before you run CLI
Confirm tenant, subscription, resource group, namespace, queue or topic subscription, region, and output format.
Check whether the command is read-only or changes lock duration, delivery count, status, or authorization settings.
Verify Service Bus provider registration, SKU, private endpoint access, and permissions for queue or subscription management.
Coordinate with application owners because lock changes can affect duplicate processing, backlog age, and dead-letter behavior.
What output tells you
Lock duration shows how long a receiver has to process and settle a message before redelivery can occur.
Max delivery count explains when repeated peek-lock failures will move a message to the dead-letter queue.
Message count and status fields show whether backlog, disabled receiving, or dead-letter growth is affecting operations.
Authorization output reveals which identities or SAS policies can receive, complete, abandon, or dead-letter messages.
Mapped Azure CLI commands
Service Bus peek-lock configuration commands
operate
az servicebus queue show --resource-group <resource-group> --namespace-name <namespace> --name <queue> --query "{lockDuration:lockDuration,maxDeliveryCount:maxDeliveryCount,count:messageCount,status:status}" --output json
az servicebus topic subscription show --resource-group <resource-group> --namespace-name <namespace> --topic-name <topic> --name <subscription> --output json
az servicebus topic subscriptiondiscoverIntegration
az servicebus namespace authorization-rule list --resource-group <resource-group> --namespace-name <namespace> --output table
az servicebus namespace authorization-rulediscoverIntegration
az monitor metrics list --resource <service-bus-entity-resource-id> --metric ActiveMessages,DeadletteredMessages --interval PT5M --output table
az monitor metricsdiscoverIntegration
Architecture context
In Azure architecture, peek-lock sits in the messaging data plane for Service Bus queues and topic subscriptions. It works with lock duration, delivery count, max delivery count, dead-letter queues, transactions, sessions, client SDK settlement APIs, and Azure Functions triggers. The receive operation creates a temporary lock, and settlement calls decide the final message state. Operators configure the entity’s lock duration and delivery behavior on the control plane, while application code performs complete, abandon, defer, dead-letter, and lock-renewal actions.
Security
Security impact is direct around who can receive and settle messages, and indirect around payload exposure. Receivers need appropriate Service Bus Listen rights through Microsoft Entra roles or SAS policies. A compromised receiver can read locked messages and may complete, abandon, or dead-letter work it should not control. Message payloads can contain customer or operational data, so encryption, private endpoints, network restrictions, least-privilege identities, and log hygiene matter. Operators should avoid broad namespace keys, review authorization rules, protect dead-letter inspection tools, and ensure settlement actions are audited through application telemetry and Service Bus diagnostics. Review receiver identities after every rotation. Limit replay privileges to trusted operators.
Cost
Cost impact is indirect. Peek-lock itself is a receive behavior, but poor handling can increase operations through repeated deliveries, dead-letter growth, retries, duplicate downstream calls, and extended incident work. A workload that frequently loses locks may need longer lock duration, better concurrency control, Premium messaging capacity, or faster downstream dependencies. Those choices can increase spend but may be cheaper than failed business processes. Cost reviews should connect Service Bus transactions, active backlog, duplicate processing, dead-letter storage, handler compute time, and support effort. The goal is not fewer locks; it is fewer unnecessary redeliveries and cleaner settlement. Measure replay overhead regularly. Review retry storms first.
Reliability
Reliability impact is direct because peek-lock implements at-least-once processing. If a handler crashes after receiving a message, Service Bus can redeliver it when the lock expires. If the handler completes too early, work can be lost after downstream failure. If lock duration is too short, valid processing may redeliver and create duplicates. If max delivery is too low, recoverable messages may dead-letter prematurely. Reliable designs use idempotency keys, transactional settlement where appropriate, lock renewal for long operations, clear dead-letter policies, and monitoring for lock-lost events, delivery count growth, active message backlog, and handler latency. Test crash recovery under load regularly. Test crash recovery before each major consumer release.
Performance
Performance impact is direct for message-processing throughput. Lock duration, handler time, prefetch settings, concurrency, downstream latency, and settlement timing all affect how quickly messages leave the queue. Too little concurrency creates backlog; too much concurrency can overload dependencies and cause lock loss. Long lock durations hide failed work for longer before redelivery, while short durations create duplicate processing during normal slow work. Operators should compare processing latency, lock-lost count, delivery count, active message age, and dead-letter rate. Tuning peek-lock requires testing real handler behavior, not only increasing queue capacity. Tune only after measuring handler behavior under production-like failure load first. Tune with realistic handler duration and downstream latency measurements.
Operations
Operators manage peek-lock by reviewing queue and subscription settings, inspecting lock duration, checking active and dead-letter counts, and correlating handler logs with settlement outcomes. Azure CLI cannot process individual messages, but it can show entity configuration, update lock duration, inspect authorization rules, and export evidence during incidents. Service Bus Explorer, SDK tools, and application logs complete the operational picture by showing message details and settlement errors. Runbooks should define when to abandon, defer, dead-letter, replay, or purge messages, and how to verify that handlers do not complete messages before durable work succeeds. Record settlement evidence for every replay decision made. Document replay ownership, poison-message review, and rollback steps clearly.
Common mistakes
Completing the message before downstream work is durable, which can lose work after a later failure.
Ignoring duplicate delivery and building non-idempotent handlers that run the same business action twice.
Setting lock duration shorter than normal processing time and then blaming Service Bus for duplicate messages.
Leaving dead-letter queues unmonitored, causing poisoned or malformed messages to accumulate silently.