Skip to content

Commit e0e11f1

Browse files
docs: add debug logs info
1 parent a609a45 commit e0e11f1

1 file changed

Lines changed: 74 additions & 0 deletions

File tree

docs/core/logger.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ The Durable Execution SDK automatically enriches your logs with execution contex
1414
- [Integration with Powertools for AWS Lambda (Python)](#integration-with-powertools-for-aws-lambda-python)
1515
- [Replay behavior and log deduplication](#replay-behavior-and-log-deduplication)
1616
- [Best practices](#best-practices)
17+
- [Enabling debug logging](#enabling-debug-logging)
1718
- [FAQ](#faq)
1819
- [Testing logger integration](#testing-logger-integration)
1920
- [See also](#see-also)
@@ -485,6 +486,79 @@ context.logger.info("User authenticated", extra={"password": password})
485486

486487
[↑ Back to top](#table-of-contents)
487488

489+
## Enabling debug logging
490+
491+
The SDK logs internally using Python's standard `logging` module. To see these logs, set `ApplicationLogLevel: DEBUG` in [Advanced logging controls](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs-advanced.html).
492+
493+
Advanced logging controls filters logs before they reach CloudWatch. If you set DEBUG level in code but leave Advanced logging controls at INFO, your debug logs will be dropped. You must configure the level in Advanced logging controls - it auto-patches all loggers, so you don't need to configure log levels in code.
494+
495+
```mermaid
496+
flowchart LR
497+
A[Logger emits DEBUG] --> B{Advanced Logging Controls}
498+
B -->|ApplicationLogLevel = DEBUG| C[CloudWatch ✓]
499+
B -->|ApplicationLogLevel = INFO| D[Dropped ✗]
500+
```
501+
502+
**Important:** DEBUG level applies to all libraries including botocore. Since the SDK uses boto3 internally, this will flood your logs with HTTP request/response details. Silence botocore in your code:
503+
504+
```python
505+
import logging
506+
507+
# Silence botocore/urllib3 noise
508+
logging.getLogger("botocore").setLevel(logging.WARNING)
509+
logging.getLogger("urllib3").setLevel(logging.WARNING)
510+
```
511+
512+
Configure ALC via SAM/CloudFormation:
513+
514+
```yaml
515+
# SAM template
516+
Resources:
517+
MyFunction:
518+
Type: AWS::Serverless::Function
519+
Properties:
520+
LoggingConfig:
521+
LogFormat: JSON
522+
ApplicationLogLevel: DEBUG
523+
```
524+
525+
Or in the Lambda console under Configuration → Monitoring and operations tools → Logging configuration.
526+
527+
### Selective logging
528+
529+
Python loggers are hierarchical. Silencing `aws_durable_execution_sdk_python` silences all SDK modules. To keep some modules at DEBUG while silencing others:
530+
531+
```python
532+
import logging
533+
534+
# Silence all SDK logs
535+
logging.getLogger("aws_durable_execution_sdk_python").setLevel(logging.WARNING)
536+
537+
# Or silence specific modules only
538+
logging.getLogger("aws_durable_execution_sdk_python.state").setLevel(logging.WARNING)
539+
logging.getLogger("aws_durable_execution_sdk_python.concurrency").setLevel(logging.WARNING)
540+
```
541+
542+
SDK logger namespaces:
543+
544+
| Namespace | Description |
545+
|-----------|-------------|
546+
| `aws_durable_execution_sdk_python` | Root - silences all SDK logs |
547+
| `aws_durable_execution_sdk_python.state` | Checkpoint and replay state management |
548+
| `aws_durable_execution_sdk_python.execution` | Durable execution lifecycle |
549+
| `aws_durable_execution_sdk_python.context` | DurableContext operations |
550+
| `aws_durable_execution_sdk_python.lambda_service` | Lambda API calls |
551+
| `aws_durable_execution_sdk_python.serdes` | Serialization/deserialization |
552+
| `aws_durable_execution_sdk_python.concurrency` | Parallel and map execution |
553+
| `aws_durable_execution_sdk_python.operation.step` | Step operations |
554+
| `aws_durable_execution_sdk_python.operation.wait` | Wait operations |
555+
| `aws_durable_execution_sdk_python.operation.invoke` | Invoke operations |
556+
| `aws_durable_execution_sdk_python.operation.child` | Child context operations |
557+
| `aws_durable_execution_sdk_python.operation.parallel` | Parallel operations |
558+
| `aws_durable_execution_sdk_python.operation.map` | Map operations |
559+
560+
[↑ Back to top](#table-of-contents)
561+
488562
## FAQ
489563

490564
**Q: Does logging work during replays?**

0 commit comments

Comments
 (0)