feat(aws-apigatewayv2-alpha): Add properties for specifing access and data logs to HttpApi and WebSocketApi classes

[dathomae]

Describe the feature

Access (and in the case of web socket apis, data trace) logs are critical for debugging problems with api gateways. There are no options on the HttpStage and WebSocketStage classes to enable access and data logs. They should be added.

Use Case

When debugging problems with contacting/using Http and WebSocket apis.

Proposed Solution

For both Http and WebSocket stages (which both have access logs), the idea would be to add an accessLogEnabled flag and a accessLogFormat field (which has a default, unlike the raw setting in CfnStage). An Http api instantiation might look like this:

const httpApi = new apigw.HttpApi(this, 'HttpApi', { createDefaultStage: false });

new apigw.HttpStage(this, 'HttpDev', {
httpApi,
stageName: 'dev',
autoDeploy: true,
accessLogEnabled: true,
});

using the default value for the access log format. Alternatively, it would be possible to supply a format like this:

const accessLogFormat = JSON.stringify({
apigw: {
api_id: '$context.apiId',
stage: '$context.stage',
},
request: {
request_id: '$context.requestId',
extended_request_id: '$context.extendedRequestId',
},
errors: {
message: '$context.error.message',
}
http: {
method: '$context.httpMethod'
}
});

new apigw.HttpStage(this, 'HttpDevStageWithExternalLogGroup', {
httpApi: httpApiWithExternalLogGroup,
stageName: 'dev',
autoDeploy: true,
accessLogEnabled: true,
accessLogFormat: accessLogFormat,
});

Web sockets would also support the accessLogEnabled and accessLogFormat properties in exactly the same way.

Web socket apis (but not http apis) support data logging, which would be controlled by a new property dataTraceLoggingLevel, with supported levels of INFO, ERROR and OFF, like this:
const websocketApi = new apigw.WebSocketApi(this, 'WebSocketApi');

new apigw.WebSocketStage(this, 'WebSocketDev', {
webSocketApi,
stageName: 'dev',
autoDeploy: true,
dataTraceLoggingLevel: 'INFO',
});

The CfnStage has a property to enable data trace logging and a separate log level property, but that seems redundant. If the log level is OFF, then the data trace enabled flag is false.

Finally, while metrics aren't logging, to flesh out the possibilities surfaced by the defaultRouteSettings support for turning on detailed metrics should be surfaced in HttpStage (this is something that's not supported by web socket apis), like this:

new HttpStage(stack, 'DefaultStage', {
httpApi: api,
stageName: 'dev',
detailedMetricsEnabled: true,
});

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

CDK version used

2.40.0

Environment details (OS name and version, etc.)

Windows, Linux and Mac OS

[dathomae]

The PR that implements these changes is #21993

[rationull]

It looks like this issue and the attached PR enables setting up access logs when explicitly creating a stage, but not for the implicit $default stage. This older issue proposes also "Add logging prop to HttpApi which enables logging for all routes" which would be very useful.

Can we update this to provide a simple path to hook up logging for an API's default stage (or all stages) consistent with the explicit stage creation settings added here?

[dathomae]

It doesn't look to be too hard. I think that the right thing to do would be to add the three new access log attributes that are defined in common/stage (accessLogEnabled, accessLogGroup and accessLogFormat) and include them at the api level where, if present, they'd be used to set the appropriate properties on the default stage. Thus, to set up access logs for the default stage all you'd need to do is specify accessLogEnabled:true, and a log group would be created that used the default accessLogFormat (which consists of those fields that are common to both http and websocket gateways, more or less). If the user wanted to create their own log group instead they'd include a value for accessLogGroup and if they wanted to control the fields that showed up in log entries they'd specify accessLogFormat (those settings are orthoganol to each other, either or both can be specfied).

By using the same properties as the stages for controlling the access logging we'll make the interface regular and consistent. That's not quite the same as the suggestion in the issue you point to, but it gets us to the same place and covers all of the use cases.

Taking the access log settings off of the stages and having each stage that gets added taking it's settings from the api level settings may be possible (or taking it's settings from the api level if they're not specfied at the stage level), but it's definitely a more radical step, since the access logs are associated with stages in the L1 model and we'd be changing that association from the point of view of the user. I'd recommend sticking with the current access log/stage association and then when that's in the bag looking at specifying access log settings at both levels, with the stage level settings taking precedence if they're specified at both the api and stage levels.

What do you think?

[dathomae]

It turns out that the existing code will serve to add logging for the default HttpApi stage as is, provided that the automatic creation of the stage by HttpApi is inhibited, thus:

const httpApi = new apigwv2.HttpApi(this, 'HttpApi', { createDefaultStage: false });
new apigwv2.HttpStage(this, 'HttpDefaultStage', {
httpApi,
stageName: '$default',
autoDeploy: true,
accessLogEnabled: true,
});

I've added that example (with explanatory text) to the README file. I think that the idea of specifying the access log settings once on the HttpApi and then having all of the stages pick that up automatically is an interesting one, but there are details to be worked out that I think don't belong in this particular modification.

[dathomae]

The existing capability works for defining the $default stage, as long as the autocreation of the stage is turned off when instantiating HttpApi. I've added an example of that to the README file.