Add support for JSON Structured Logging

[sebsto]

This PR adds support for Structured Logging, as per the design document

[Copilot]

Pull request overview

This PR implements JSON structured logging support for AWS Lambda functions, aligning with AWS Lambda's advanced logging controls. The implementation adds the ability to emit logs in JSON format when AWS_LAMBDA_LOG_FORMAT=JSON is set, while maintaining full backward compatibility with existing text-based logging.

Changes:

• Introduces LoggingConfiguration to handle environment variable parsing and logger factory logic with proper precedence rules for AWS_LAMBDA_LOG_LEVEL vs LOG_LEVEL
• Adds JSONLogHandler to format logs as JSON with Lambda-specific metadata (requestId, traceId)
• Updates LambdaRuntime and LambdaManagedRuntime to use the new logging configuration and create per-request loggers
• Provides comprehensive JSONLogging example with deployment templates and documentation
• Updates design proposal and other documentation

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
Sources/AWSLambdaRuntime/Logging/LoggingConfiguration.swift	New file implementing logging configuration with environment variable parsing and logger factory methods
Sources/AWSLambdaRuntime/Logging/JSONLogHandler.swift	New file implementing JSON log handler with structured output to stderr
Sources/AWSLambdaRuntime/Runtime/LambdaRuntime.swift	Updated to initialize and use LoggingConfiguration, create per-request loggers
Sources/AWSLambdaRuntime/ManagedRuntime/LambdaManagedRuntime.swift	Updated to initialize and use LoggingConfiguration, create per-request loggers
Sources/AWSLambdaRuntime/Lambda.swift	Updated runLoop to create per-request loggers, deprecated old runLoop signature
Tests/AWSLambdaRuntimeTests/LambdaRunLoopTests.swift	Updated tests to use new runLoop signature with LoggingConfiguration
Sources/AWSLambdaRuntime/Docs.docc/Proposals/0002-logging.md	New design document describing the structured logging feature
Sources/AWSLambdaRuntime/Docs.docc/managed-instances.md	Header level adjustments for consistency
Sources/AWSLambdaRuntime/Docs.docc/Deployment.md	Header level adjustment for consistency
Examples/JSONLogging/*	Complete example demonstrating JSON logging with SAM templates and README

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sebsto]

More feedback received on slack. Adding it here for transparency

I read over the PR and I think it overall looks solid. I also temporarily deployed your revision in my live AWS environment for a service we have not released yet and I verified that (after changing my log settings to JSON), I do see the proper structured JSON logs in cloudwatch. Overall PR looks solid, well thought out and tested.

• One thing I was wondering is that the logs I do not think have millisecond precision, is that something worth adding?
• In your function parseLogLevel, I thought it might be good to add some sort of log indicating to the user if a fallback is used.
• In the JSONLogHandler a bit of the information gets discarded. I personally have found the file/function/line very helpful for debugging in the various more manual CloudWatch logging solutions I have created for us in the past.

[sebsto]

@benrosen78 Here are a couple of changes

One thing I was wondering is that the logs I do not think have millisecond precision, is that something worth adding?

See c19febc

{"timestamp":"2026-02-24T18:16:24.465Z","requestId":"5B9EEA11-C217-4872-B4B1-E8EE371C3B61","traceId":"Root=1-699deaf8-d3ea5e248a06d154c6518cbb;Sampled=1","level":"INFO","message":"Processing request for error"}

In your function parseLogLevel, I thought it might be good to add some sort of log indicating to the user if a fallback is used.

See 47feea9

In the JSONLogHandler a bit of the information gets discarded. I personally have found the file/function/line very helpful for debugging in the various more manual CloudWatch logging solutions I have created for us in the past.

My bad. I forgot to pass these parameters.

See 184fc62

{"message":"Server started and listening","requestId":"N\/A","level":"INFO","timestamp":"2026-02-24T18:43:11.688Z","metadata":{"port":"7000","host":"\"127.0.0.1\""},"traceId":"N\/A","file":"AWSLambdaRuntime\/Lambda+LocalServer.swift","function":"withLocalServer(host:port:invocationEndpoint:eventLoopGroup:logger:_:)","line":168}

[manojmahapatra]

Question: Probably not required but do we need to map "NOTICE" to .info?

[sebsto]

here it is 9a6694d

[manojmahapatra]

LGTM

[manojmahapatra]

🚢