Provide default instances of Powertools

[bilalq]

Porting the discussion over from #777.

Relevant quotes from the issue:

@bilalq:

Are the Logger/Tracer/Metrics classes computationally expensive to instantiate? It seems really awkward to force consumers to essentially build their own wrapper export around them for instance access. Why not instead export default instances that are ready to be used? Consumers can then have a consistent way to import these instances across all their files/modules. This can be done without forcing singleton usage. The majority of users will be best served using the default instances and the minority with more specialized requirements can still create separate instances as needed. This is the pattern today used by the popular lambda-log library.

If default instances are expensive to instantiate, then they can be published under a separate file that gets imported only by those who want them. Unless that import comes up in the handler path, bundlers will just exclude the code that instantiates default instances. Best of both worlds. Here's an example of what such default imports could look like:

// Easy imports for most use-cases
import { logger } from '@aws-lambda-powertools/logger/defaults'
import { metrics } from '@aws-lambda-powertools/metrics/defaults'
import { tracer } from '@aws-lambda-powertools/tracer/defaults'

// If a hypothetical single wrapper package for all of these existed:
import { logger, metrics, tracer } from '@aws-lambda-powertools/powertools/defaults'

@dreamorosi:

The classes for the utilities that we support at the moment are not expensive to instantiate, the only logic that is run at init time is configuring the instances according to the options/params that can be passed by env variables or constructor.

At the moment we don't provide instances of the utilities instantiated with default because we wanted to give developers the ability to initialise the classes and customise their behaviour directly. Even using the method you propose you'd be essentially be saving one line but you'd be losing the chance to configure the class via constructor parameters.

We simply don't have enough feedback from the community yet to determine whether the default settings would be fine for most use cases like you suggest, but if that's the case we can consider providing these already-instantiated utils. I'd like to defer the decision to a later date after more members from the community and users have also given their opinion. Would you be so kind to open a dedicated discussion essentially porting the content of your comment, so that we can have a period of time to gather more opinions? If after that we see enough interest we'll definitely consider this.

---

My take on this is that nothing is lost by vending default instances. You wouldn't be "losing the chance to configure the class via constructor parameters", because that option would remain available if you wanted it. However, the default setup becomes a lot easier to use. The added convenience is not just "saving one line". With default instances, the following advantages exist:

• It's easy to set a convention of specifying Powertools configuration via Lambda ENV variables. This in turn makes it easy to create L3 AWS CDK constructs that enforce these patterns for a consumer's use.
• Dependency injection of logger/tracer/metrics instances can be made optional rather than a must in utility packages we create that get reused across lambdas. These internal lambda utility packages can just use the default logger if a specific implementation is not injected as a function parameter.
• No need to create a separate wrapper powertools.ts file per lambda. This does not just save one line of code, but dozens of lines of highly repetitive code per lambda that could better be expressed as configuration elsewhere. As an anecdotal point, we run many distinct lambda functions, so this amounts to literally hundreds of lines of code we could avoid.

If we look at other libraries attempting to solve similar problems, they all vend default implementations that are ready to go. Notable examples include the popular lambda-log library and the DAZN Lambda PowerTools that this library is inspired by.

For advanced usage, the option of instantiating a specially configured instance is always there. But I would conjecture that vending default instances serves the vast majority and essentially comes out as a way to use this library with sane defaults rather than forcing them to go through an architectural decision point of either building their own conventions around ad-hoc singletons or setting up dependency injection just to get logging/tracing/metrics working.

[dreamorosi]

Thanks for opening the discussion, I appreciate the effort you put in laying out the use cases.

As I mentioned in my original post the team is keen to gather some additional datapoints before making a decision. If anyone reads this and is interested in this type of feature please leave a 👍 to the original post, or leave a comment below if you want to share your point of view / use case.

[moltar]

Perhaps instead of doing this, which IMO is an anti-pattern.

// Easy imports for most use-cases
import { logger } from '@aws-lambda-powertools/logger/defaults'
import { metrics } from '@aws-lambda-powertools/metrics/defaults'
import { tracer } from '@aws-lambda-powertools/tracer/defaults'

We could release separate packages that offer ready-to-go instances:

// Easy imports for most use-cases
import logger from '@aws-lambda-powertools/logger-instance'
import metrics from '@aws-lambda-powertools/metrics-instance'
import tracer from '@aws-lambda-powertools/tracer-instance'

[bilalq]

Personally, I don't think that'd be a good idea. My contention is that there are no advantages to this separation, but there are clear disadvantages.

Because of the way module loading works (both with ES modules and CommonJS bundling), un-imported modules within a package will not be included in published artifacts. There is no extra cost in the final bundle size or runtime behavior by including them in the main package, so long as they are in their own module (i.e., file).

Having them in separate packages, however, makes maintenance and consumption more difficult. For the maintainers, they need to model the peer dependency properly and ensure version ranges are accurate. If API changes are made, the secondary packages would need updating after the fact and require peer dep version bumps. For consumers, they may get false positive peer dep warnings/errors if the package maintainers have not kept dependency version ranges up to date. This isn't an insurmountable issue or anything, but it's an added maintenance cost that comes at no benefit.

Could you elaborate on what about this you see as an anti-pattern?

[moltar]

Could you elaborate on what about this you see as an anti-pattern?

Arguably it is reaching inside the internals. This can, of course, be a documented feature, at which point it is an "interface" that is supported, and no longer considered to be internal.

This also limits your ability to refactor later. If you export from the root, you can still move files around, while maintaining exported symbol names.

Also most TS projects would put sources in ./src and transpiled .js files into ./lib. The paths then would be:

import { logger } from '@aws-lambda-powertools/lib/logger/defaults'
import { metrics } from '@aws-lambda-powertools/lib/metrics/defaults'
import { tracer } from '@aws-lambda-powertools/lib/tracer/defaults'

Or the project would need to deviate from the norms and adjust config in some obscure and unintuitive way to support this pattern (without the lib dir).

[mikebroberts]

(I got here via @saragerion 's tweet - thanks Sara! - https://twitter.com/Sarutule/status/1549732065242923009)

Weird / possibly ignorant question on my part - what does "vend" mean? :) E.g. I think if I use the word "provide" instead of "vend" here it all makes sense to me, but I wonder if I'm missing meaning? Thanks!

[dreamorosi]

Not ignorant at all, I agree that the term is maybe not the most widely used and might be confusing for some (i.e. non-native English speakers like me).

In this case we are referring to whether or not the project/library should provide something, in this case the default instances.

The ver to vend kinda relates to the actions of an automatic vending machine:

I have however renamed the discussion to clarify the ambiguity, thanks for the feedback!

[mikebroberts]

Thanks! This sparked some conversation in a Slack I'm on. I get the feeling this is a term used more in AWS? (E.g. "vended logs")? Or has this come from somewhere in the Node community? Definitely interesting language evolution though. I pretty much can only think (as an actual native English speaker!) of "vend as verb" used in the context of a vending machine - I think pretty much everywhere else it would be "selling" or "giving".

Anyway, thanks for the tangent. I guess I should give a technical opinion on this while I'm here to avoid completely derailing. :) I think providing default instances is fine, as long as they are clearly named that they are not the "canonical" behavior. E.g. I wouldn't personally use them since they are dangerously close to Singletons (IMO), however that's a design choice on my part, and I think for folks wanting to get started quickly it probably makes sense.