aws-cdk-lib/aws-lambda-nodejs: add VERBOSE log level to esbuild bundling

[dreamorosi]

Describe the feature

The NodejsFunction constructs allows customers to bundle code using esbuild. The construct already has a bundling.logLevel property that allows to set the log level for the esbuild CLI.

Currently CDK exposes only some of the log levels (i.e. INFO, ERROR, WARNING, and SILENT), however esbuild offers more, namely VERBOSE.

I propose to add the VERBOSE log level to the existing ones, so that CDK customers can use it to troubleshoot or inspect issues with the bundling process.

Use Case

When bundling functions sometimes it's useful to see the full log output, this is especially helpful when debugging module resolution issues and to understand how a certain module ends up (or doesn't) in the final bundle.

For example, when enabled, the verbose output gives info similar to this (for each module resolved):

⬥ [VERBOSE] Resolving import "@aws-lambda-powertools/commons" in directory "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/logger/lib/esm" of type "import-statement"

  Checking for package alias matches
    Failed to find any package alias matches
  Checking "@aws-lambda-powertools/commons" against the external pattern "@aws-sdk/*"
  Read 14 entries for directory "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/logger/lib/esm"
  Searching for "@aws-lambda-powertools/commons" in "node_modules" directories starting from "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/logger/lib/esm"
    Parsed package name "@aws-lambda-powertools/commons" and package subpath "."
    Checking for a package in the directory "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons"
    Read 2 entries for directory "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools"
    The file "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons/package.json" exists
    Read 3 entries for directory "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons"
    Looking for "." in "exports" map in "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons/package.json"
      Using the entry for "."
      Checking condition map for one of ["default", "import", "module", "node"]
        The key "require" does not apply
        The key "import" applies
        Checking condition map for one of ["default", "import", "module", "node"]
          The key "types" does not apply
          The key "default" applies
          Checking path "" against target "./lib/esm/index.js"
            Joined "" to "./lib/esm/index.js" to get "./lib/esm/index.js"
      The resolved path "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons/lib/esm/index.js" is exact
      Read 3 entries for directory "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons"
      Read 17 entries for directory "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons/lib"
      The file "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons/lib/esm/package.json" exists
      Read 19 entries for directory "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons/lib/esm"
      Resolved to "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons/lib/esm/index.js"
  Read 19 entries for directory "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons/lib/esm"
  Primary path is "/Users/johndoe/Codes/temp-ts/node_modules/@aws-lambda-powertools/commons/lib/esm/index.js" in namespace "file"

Proposed Solution

Add the extra log levels to the , which is defined here.

The change would look like this:

export enum LogLevel {
++  /** Show everything **/
++  VERBOSE = 'verbose';
--  /** Show everything **/
++  /** Show warnings, errors, and summary (default) */
  INFO = 'info',
  /** Show warnings and errors */
  WARNING = 'warning',
  /** Show errors only */
  ERROR = 'error',
  /** Show nothing */
  SILENT = 'silent',
}

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.102.0

Environment details (OS name and version, etc.)

macOS

[msambol]

@dreamorosi I'm taking a look at this. To me, the LogLevel enum is a little confusing because it's used as a parameter for yarn, pnpm, and npm (see here)? I think it should be three enums, one for each package manager? I'm new to esbuild though, so my understanding could be wrong. Happy to implement this request once we decide on a direction.

[dreamorosi]

Hi @msambol thanks for looking into this & for the response.

I actually didn't notice that the same enum was used elsewhere, including package managers.

The usage that I was referring to is at this line:

...this.props.logLevel ? [`--log-level=${this.props.logLevel}`] : [],

This is part of the esbuildCommand object, which if I understand correctly, contains all the flags that are passed to the esbuild CLI.

I'm not sure whether adding a VERBOSE level will have an impact on the package managers, but I agree that at least the one for esbuild and the package manager one should be separate.

[msambol]

@peterwoodworth Could you weigh in for the CDK team here? Do we want to define separate enums for each package manager? I could see YarnLogLevel, NpmLogLevel, and PnpmLogLevel and then make these two lines [1, 2] smarter, instead of silent or default. Happy to take this on, once we decide on a direction. I will also add VERBOSE in the original enum.

[1]

aws-cdk/packages/aws-cdk-lib/aws-lambda-nodejs/lib/package-manager.ts

Line 36 in 9c0de51

installCommand: logLevel && logLevel !== LogLevel.INFO ? ['yarn', 'install', '--no-immutable', '--silent'] : ['yarn', 'install', '--no-immutable'],

[2]

aws-cdk/packages/aws-cdk-lib/aws-lambda-nodejs/lib/package-manager.ts

Line 42 in 9c0de51

installCommand: logLevel && logLevel !== LogLevel.INFO ? ['pnpm', 'install', '--reporter', 'silent', '--config.node-linker=hoisted', '--config.package-import-method=clone-or-copy', '--no-prefer-frozen-lockfile'] : ['pnpm', 'install', '--config.node-linker=hoisted', '--config.package-import-method=clone-or-copy', '--no-prefer-frozen-lockfile'],

[dreamorosi]

Since npm does have a verbose log level (see docs here), and the other two don't use it at all, I think we could already add the VERBOSE option to the enum, and then later on in a separate PR, make further changes to create dedicated enums for the install commands, if we want to go in that direction.

[indrora]

This should be an option, you're right! I could easily see the enum having all these levels but a helper function that "clamps" it at a maximum level (since one tool doesn't know VERBOSE, it would be clamped somehow).

I've added this to our weekly review session.

[msambol]

Let me know the result of the discussion, I'd be happy to implement.

[msambol]

@indrora / @dreamorosi I created #27657 to track the enhancement. I will also add VERBOSE for now to unblock you @dreamorosi since that is a legitimate esbuild log level and won't break anything.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.