CloudWatch DescribeLogGroups documentation is missing the "showSubscriptionDestinations" flag

[mdbouchard]

Describe the issue

Findings

The @aws-sdk (v3) > DescribeLogGroupsCommand library docs and the API Reference > DescribeLogGroups API docs both do not mention that showSubscriptionDestinations is supported by the describe log groups API.

I also noticed the flag is missing from the TypeScript API objects as well. See the DescribeLogGroupsRequest interface.

For example, this call:

import { CloudWatchLogsClient, DescribeLogGroupsCommand } from "@aws-sdk/client-cloudwatch-logs";

const command = new DescribeLogGroupsCommand({
    showSubscriptionDestinations: true
});
const logGroups = await cloudWatchLogs.send(command);

Produces results containing a list subscriptions ARNs per log group:

{
    "logGroups": [
        {
            "arn": "arn:aws:logs:XXX:XXX:log-group:XXX:*",
            "creationTime": 9999999999999,
            "logGroupArn": "arn:aws:logs:XXX:XXX:log-group:XXX",
            "logGroupClass": "STANDARD",
            "logGroupName": "/aws/lambda/XXX",
            "metricFilterCount": 0,
            "retentionInDays": 14,
            "storedBytes": 0,
            "subscriptions": [
                "arn:aws:lambda:XXX:XXX:function:XXX"
            ]
        },
        // ...
    ],
     "nextToken": "/aws/lambda/XXX"
}

I discovered that this behavior exists when inspecting the AWS CloudWatch console backend AJAX calls:

And I saw results coming back with subscriptions ARNs per log group.

Why is this important?

When a developer only needs the subscriptions list of ARNs and nothing else, adding the showSubscriptionDestinations: true flag removes the need to additionally call describeSubscriptionFilters() per log group returned. This also minimizes the chance of experiencing throttling by the API.

For my specific use case, we have a lambda which runs frequently checking to see which CloudWatch log groups don't have a subscription for our log shipper. If any are found, the lambda executes a pubSubscriptionFilter() call to add the subscription automatically. We have over 1,000 log groups in one of our AWS accounts, so we were previously experiencing throttling by the describeSubscriptionFilters() call (which must be executed per log group).

Links

https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/DescribeLogGroupsCommand/

https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_DescribeLogGroups.html

[aBurmeseDev]

Hi @mdbouchard - thanks for raising this to our attention.

Both models and SDK API reference docs are generated upstream by service teams and we barely make any changes to them. This may be something you may want to reach out to service team directly with your support plan via AWS Support. However, I'd be happy to forward this if you can't reach them for any reason. Let us know!

[mdbouchard]

@aBurmeseDev Thanks for the reply! I'll see if I can forward this to them when I have some time.

[aBurmeseDev]

Since this change needs to happen in the upstream by service team and there's no action item for SDK team here, I'll close this issue. Please feel free to reach out anytime. Thank you!

[github-actions[bot]]

This issue is now closed. Comments on closed issues are hard for our team to see. If you need more assistance, please open a new issue that references this one.

[github-actions[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs and link to relevant comments in this thread.