Peek-lock receive mode is the receiver setting that tells Service Bus not to delete a message as soon as an app receives it. The message is locked first, then the app decides what happens after processing. Complete removes it, abandon makes it available again, dead-letter isolates it, and defer postpones it. This mode is usually chosen when losing a message is worse than processing it twice. It demands disciplined code, because duplicates, lock expiration, and settlement failures are normal design concerns.
Service Bus PeekLock mode, PeekLock receive mode, ReceiveMode.PeekLock, at-least-once receive mode, locked receive mode
Difficulty
intermediate
CLI mappings
5
Last verified
2026-05-17
Microsoft Learn
Peek-lock receive mode is the Azure Service Bus client receive mode that locks a message instead of deleting it when received. The receiver must settle the message with complete, abandon, defer, or dead-letter actions, so failures can lead to redelivery rather than silent loss.
In Azure architecture, peek-lock receive mode belongs to the Service Bus client, trigger, or worker that consumes queues and topic subscriptions. It is different from receive-and-delete mode, where receipt removes the message immediately. Entity settings such as lockDuration and maxDeliveryCount define how the broker behaves, but the receive mode is chosen by the receiver implementation or framework. The mode interacts with SDK settlement APIs, Azure Functions trigger options, sessions, prefetch, transactions, lock renewal, retry policies, and dead-letter handling.
Why it matters
Peek-lock receive mode matters because it defines the reliability contract between the broker and the application. With this mode, receiving a message is not the same as finishing the work. That separation lets a crashed worker, failed dependency, or rejected payload be handled intentionally. It also means application teams must build idempotent handlers, settle only after durable success, and monitor redelivery. Choosing receive-and-delete for important work can lose messages during crashes. Choosing peek-lock without understanding settlement can flood a system with duplicates or dead-letter noise. The mode is a small client setting with large operational consequences. Choose this mode deliberately. Review it deliberately.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
In SDK configuration or worker code, receive mode appears as PeekLock, ReceiveMode.PeekLock, or an equivalent default on Service Bus receivers and processors. during reviews. artifacts and checks.
Signal 02
In Azure Functions Service Bus trigger settings, auto-complete, lock renewal, and handler logs reveal whether peek-lock settlement is controlled by framework or code. during incidents. workbooks and logs.
Signal 03
In queue and subscription diagnostics, repeated deliveries, lock-lost events, and dead-letter movement show how peek-lock receive mode behaves under failures. during duplicate retry storm analysis. during consumer health and retry investigations.
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Consume important queue or subscription messages that must not disappear until processing succeeds.
Use manual settlement when the handler needs to complete, abandon, defer, or dead-letter based on business validation.
Review application code to distinguish peek-lock receive mode from receive-and-delete mode before production release.
Tune lock renewal, prefetch, and concurrency for handlers that perform slow or failure-prone downstream work.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
Wildfire alert fan-out safety
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
CinderWatch operated alerting workflows for county emergency managers. A receiver crash during a dry-run deleted several test messages because one worker had been configured for receive-and-delete mode.
🎯Business/Technical Objectives
Prevent alert delivery jobs from disappearing after receipt.
Ensure failed provider calls can retry without duplicate public alerts.
Make receiver mode visible in code review and release evidence.
Keep emergency drills auditable for county stakeholders.
✅Solution Using Peek-lock receive mode
The engineering team changed all critical alert receivers to peek-lock receive mode and required explicit settlement. A delivery job completed only after the alert provider accepted the send request and the platform recorded a delivery ledger entry. Provider timeouts caused abandon and retry, while invalid county templates were dead-lettered for review. The team used Azure CLI to document queue lock duration, max delivery count, and authorization rules, then added static checks that flagged receive-and-delete configuration in critical workers. Idempotency keys tied each delivery attempt to one alert version so redelivery could not publish duplicate public alerts.
📈Results & Business Impact
Critical alert job loss was eliminated in three quarterly emergency drills.
Duplicate public-alert attempts were blocked by idempotency checks in every retry test.
Release reviews gained a receive-mode evidence step completed in under 12 minutes.
County audit packets included settlement logs and queue configuration for each drill.
💡Key Takeaway for Glossary Readers
Peek-lock receive mode makes receiver configuration part of reliability governance, not just an SDK detail.
Case study 02
Subscription entitlement fulfillment
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
LatticeCart processed paid invoices into product-entitlement updates through Service Bus topic subscriptions. Auto-complete behavior hid downstream failures because functions returned before every entitlement write was durable.
🎯Business/Technical Objectives
Complete messages only after entitlement records are committed.
Avoid duplicate plan upgrades during message redelivery.
Expose receive-mode and settlement behavior in operations dashboards.
Reduce billing-support escalations after payment spikes.
✅Solution Using Peek-lock receive mode
Developers kept peek-lock receive mode but disabled automatic completion for the entitlement function. The handler validated the invoice, wrote entitlement changes with an idempotency key, published an audit event, and then completed the message. If the entitlement store was unavailable, the handler abandoned the message so Service Bus could retry. Invalid invoice payloads were dead-lettered with invoice and customer references. Azure CLI exported subscription lockDuration and maxDeliveryCount settings for release approval. Application Insights dashboards tracked settlement outcome, delivery count, lock-renewal events, and entitlement write latency so billing support could see whether a payment was pending retry or rejected.
📈Results & Business Impact
Post-payment entitlement delays over 15 minutes dropped by 69%.
Duplicate plan-upgrade tickets fell from 27 per month to four.
Support could identify retrying versus dead-lettered invoices without engineering escalation.
No entitlement message completed before durable storage during chaos tests.
💡Key Takeaway for Glossary Readers
Peek-lock receive mode delivers value only when application settlement matches the real business completion point.
Case study 03
Robotics command queue hardening
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
VectorWorks Lab sent movement calibration commands from a cloud controller to indoor robotics rigs. During firmware testing, receiver processes restarted frequently and sometimes dropped commands before rigs acknowledged execution.
🎯Business/Technical Objectives
Keep calibration commands available after receiver restarts.
Prevent duplicate movement commands from causing unsafe repeated actions.
Tune lock duration for realistic controller execution time.
Create diagnostics for lab technicians during firmware tests.
✅Solution Using Peek-lock receive mode
The command receiver was configured for peek-lock receive mode with manual settlement. A command completed only after the rig returned an execution receipt and the controller stored the command state. Redelivered commands were checked against a commandId ledger so duplicate movement did not execute twice. Slow calibration routines renewed locks, while invalid command payloads were dead-lettered for technician review. Azure CLI showed queue lockDuration and maxDeliveryCount values before each firmware test. Metrics and logs tracked active message age, delivery count, lock-lost events, and command receipt latency, letting technicians separate device problems from message-processing problems.
📈Results & Business Impact
Command loss during controller restarts fell to zero across six firmware test cycles.
Duplicate movement execution was prevented in 100% of redelivery simulations.
Lock-lost events dropped by 54% after duration and renewal tuning.
Technician triage time fell from 50 minutes to 14 minutes using settlement dashboards.
💡Key Takeaway for Glossary Readers
Peek-lock receive mode is a safety tool when command messages must survive restarts but still avoid uncontrolled duplicate execution.
Why use Azure CLI for this?
Azure CLI is useful around peek-lock receive mode even though the mode itself is normally set in client code. CLI commands can show lock duration, max delivery count, dead-letter settings, and access policies that determine how the broker supports locked receives. Operators use that evidence to validate application choices and incident fixes.
CLI use cases
Inspect queue or subscription settings before confirming that application receive-mode choices have safe broker support.
Update lock duration after measuring handler P95 and proving that lock loss is not caused by code defects.
List authorization rules or role assignments to confirm which clients are allowed to receive and settle messages.
Export message-count and dead-letter metrics to compare behavior before and after receive-mode or concurrency changes.
Before you run CLI
Confirm tenant, subscription, resource group, namespace, queue or topic subscription, region, and output format.
Review application configuration first, because receive mode may be in SDK code, host settings, or trigger options.
Check whether changing lock duration or delivery count could create duplicates, longer retries, or dead-letter delays.
Validate permissions, private endpoint connectivity, Service Bus SKU, and provider registration before troubleshooting settings.
What output tells you
Entity settings show whether lock duration and delivery limits support the receiver’s expected processing time.
Authorization fields reveal which identities or SAS rules could receive messages and perform settlement actions.
Metrics show whether receive-mode changes reduced dead-letter movement, lock loss, duplicate delivery, or backlog age.
Status and resource IDs confirm that evidence came from the intended queue or subscription, not a similarly named environment.
Mapped Azure CLI commands
Service Bus receive-mode support commands
validate
az servicebus queue show --resource-group <resource-group> --namespace-name <namespace> --name <queue> --query "{lockDuration:lockDuration,maxDeliveryCount:maxDeliveryCount,status:status,messageCount:messageCount}" --output json
az servicebus queuediscoverIntegration
az servicebus topic subscription show --resource-group <resource-group> --namespace-name <namespace> --topic-name <topic> --name <subscription> --query "{lockDuration:lockDuration,maxDeliveryCount:maxDeliveryCount,status:status,count:messageCount}" --output json
az servicebus topic subscriptiondiscoverIntegration
az servicebus namespace authorization-rule list --resource-group <resource-group> --namespace-name <namespace> --output json
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 receive mode belongs to the Service Bus client, trigger, or worker that consumes queues and topic subscriptions. It is different from receive-and-delete mode, where receipt removes the message immediately. Entity settings such as lockDuration and maxDeliveryCount define how the broker behaves, but the receive mode is chosen by the receiver implementation or framework. The mode interacts with SDK settlement APIs, Azure Functions trigger options, sessions, prefetch, transactions, lock renewal, retry policies, and dead-letter handling.
Security
Security impact is direct in access control and indirect in message exposure. Any identity that can receive in peek-lock mode can read payloads and influence settlement. Least-privilege Listen permissions, private endpoints, network controls, encrypted connections, and careful SAS policy scope are important. Because locked messages remain in the broker until settlement, operators must protect tools that inspect active or dead-letter messages. Application logs should not leak payloads, lock tokens, or customer data. Teams should also review auto-complete behavior in frameworks so compromised or buggy handlers cannot complete sensitive work before validation and authorization checks finish. Review receiver identities and logs regularly. Restrict replay and inspection tools.
Cost
Cost impact is indirect. Peek-lock receive mode can increase transaction volume because redeliveries, lock renewals, abandons, dead-letter operations, and replay attempts all count as work. It can also increase compute time when duplicate processing is not controlled. However, it often lowers business risk and support cost by preventing silent message loss. A team should compare the cost of extra transactions and handler safeguards with the cost of missing orders, commands, or workflow steps. Premium Service Bus capacity, longer-running workers, and observability retention may be justified when the workload requires reliable settlement evidence. Track duplicate work during retry-heavy incidents and replays. Measure duplicates before scaling workers.
Reliability
Reliability impact is direct because this receive mode enables at-least-once delivery. If a worker fails before completing the message, the lock can expire and another worker can try again. That is safer than immediate deletion, but it creates duplicate-delivery obligations. Reliable receivers use idempotency, durable progress records, appropriate lock renewal, bounded retries, and clear dead-letter rules. The chosen mode should match business criticality: telemetry samples may tolerate loss, while orders, commands, claims, and workflow steps usually need peek-lock. Operators should validate receive mode during code reviews, trigger configuration reviews, and incident postmortems. Test crash paths before every production release cycle. Practice failure recovery with realistic crashes.
Performance
Performance impact is direct for consumers. Peek-lock receive mode adds settlement steps and lock timing to the processing path. Throughput depends on handler duration, concurrency, prefetch, lock renewal, dependency latency, and how often messages are abandoned or retried. Auto-complete can improve simple workflows but can be dangerous when durable work continues after a function returns. Manual settlement offers more control but requires careful coding. Operators should test with real message sizes and failure rates, then compare active message age, delivery count, handler P95, lock-lost events, and dead-letter rate before tuning concurrency or lock duration. Measure before changing concurrency or prefetch. Tune against production-like handler and dependency latency.
Operations
Operators cannot usually set receive mode with Azure CLI because it lives in application code, SDK configuration, or framework settings. They can still inspect the Service Bus entities that support the mode: lockDuration, maxDeliveryCount, dead-letter settings, message counts, status, and authorization rules. Operations work also includes reviewing handler logs for complete, abandon, defer, dead-letter, and lock-renewal outcomes. Runbooks should identify which consumers use peek-lock, whether auto-complete is enabled, how long normal processing takes, and what evidence proves a message was settled correctly. Configuration drift often appears as duplicate messages or unexpected loss. Keep receiver-mode ownership documented in runbooks and tickets. Document the effective code and trigger settings.
Common mistakes
Assuming receive mode is configured on the queue when it is actually selected by the client or trigger.
Using receive-and-delete for critical commands, then losing messages when a worker crashes after receipt.
Disabling auto-complete without adding explicit settlement logic for every successful, failed, and rejected path.
Increasing lock duration to hide slow handlers instead of fixing dependency latency, concurrency, or idempotency problems.