Coder Social home page Coder Social logo

aws-powertools / powertools-lambda-typescript Goto Github PK

View Code? Open in Web Editor NEW
1.5K 26.0 128.0 36.56 MB

Powertools is a developer toolkit to implement Serverless best practices and increase developer velocity.

Home Page: https://docs.powertools.aws.dev/lambda/typescript/latest/

License: MIT No Attribution

JavaScript 0.78% TypeScript 99.18% Dockerfile 0.04%
aws serverless lambda typescript nodejs powertools aws-lambda instrumentation aws-sdk

powertools-lambda-typescript's People

Contributors

alan-churley avatar am29d avatar bahrmichael avatar balabad avatar bpauwels avatar daschaa avatar dependabot[bot] avatar dreamorosi avatar flochaz avatar github-actions[bot] avatar haaleo avatar heitorlessa avatar hjgraca avatar ijemmy avatar jeffrey-baker-vg avatar karthikeyanjp avatar leandrodamascena avatar michaelbrewer avatar miguel-martinr avatar misterjoshua avatar muthuveerappanv avatar niko-achilles avatar nimmlor avatar okoskine avatar peim8 avatar saragerion avatar shdq avatar sthuber90 avatar sthulb avatar yamatatsu avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

powertools-lambda-typescript's Issues

Feature request: define more specific types for decorators

Description of the feature request

As discussed internally, we need to define more specific types for the method decorator that currently uses the any type:

// TODO: Revisit type below & make it more specific
// eslint-disable-next-line  @typescript-eslint/no-explicit-any
type MethodDecorator = (target: any, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<any>) => any;

Related issues, RFCs

#107

Docs: JSDoc for method decorators don't render properly

Description of the improvement

Summary of the proposal
Currently hovering on a decorator in VS Code shows an unindented code example with also additional characters (*) around the decorator name. This, aside from the fact that decorators are still experimental in TypeScript, is probably due to either the @ sigil conflicting with JSDocs (which uses the same symbol to delimit sections) and/or VS Code itself.

Discussion of the issue here.

TODO:

  • Create isolated code sample
  • Test if this is an issue in other IDEs (like the IntelliJ ones)
  • Open an issue on the TS or VS Code repos

How, where did you look for information
Hover on a decorator while on VS Code.

Missing or unclear documentation
N/A

Improvement
The code example should be indented & highlighted/rendered properly.

Related existing documentation

image

Related issues, RFCs

N/A

Maintenance: tracer fix linting

Description

Implement linting for tracer module following what done for logger in #247 ; should be implemented after #107 has been merged.

Expected Behavior

New configuration should be present & npm run lint should be successful.

Current Behavior

Linting fails which causes automated checks to fail as well.

Maintenance: Improve CI for PRs

Description of the improvement

Summary of the proposal

At the moment merging PRs requires maintainers to clone the branch locally, run tests, and then go back to GitHub to approve the PR.

To make it inclusive and accessible for contributors from different seniority, background and experience, this area should be be more detailed to make sure that ambiguity is reduced and most importantly, in case of PR's, expectations are communicated early on in the PR progress.

How, where did you look for information

Closed PRs, especially the ones from dependabot.

Missing or unclear documentation

N/A

Improvement

As discussed internally it would be beneficial to have an automation based on GitHub Actions that runs tests so that maintainers can see the results in the PR screen and make a decision.

Scripts like npm run lerna-ci to install the dependencies and npm run lerna-test in all the packages are already there.

Related existing documentation

NO

Related issues, RFCs

Docs: Logger documentation

Description of the feature request

Problem statement
N/A.

Summary of the feature
Documentation for the Logger library:
https://awslabs.github.io/aws-lambda-powertools-python/core/logger/

Code examples
https://github.com/awslabs/aws-lambda-powertools-python/tree/develop/docs
https://github.com/awslabs/aws-lambda-powertools-python/blob/develop/README.md

Benefits for you and the wider AWS community
Understand how to use the library and speed up their adoption.

Describe alternatives you've considered

N/A

Additional context

N/A

Related issues, RFCs

#24

Feature request: correlation ID's propagation

Description of the feature request

Problem statement
The use of correlation ID's can be extremely helpful for debugging purposes and help developers understanding the lifecycle of user transactions as they are being handled by different microservices within a platform.
It would be good to help developers understand how they can use correlation ID's effectively and following the best practices, potentially allowing them to bring their own custom correlation ID's, and most importantly propagate correlation ID's through the different utilities to external dependencies of a service. This can be achieved through the implementation of a new dedicated utilities, new features within all utilities, adding examples and/or documentation.

For the scope of this Issue, we can identify 2 types of correlation ID's:

  1. Unique transaction ID that are set by AWS (for example X-Ray Trace Id, AWS Request Id)
  2. User-defined correlation ID's that can be stored and passed along between microservices:

Summary of the feature
All utilities would be able to fetch out of the box correlation ID's coming from each different AWS service (Lambda Trigger), and propagate them to logs, metrics, traces, ....
Note that this feature and functionality should not necessarily be enabled by default, but it should be possible to enable it and turn it on if developers need it.
It should be also possible to define your own custom correlation ID's and be able to propagate them and use them in different utilities accordingly.

Implement this logic in all utilities. Research is needed to understand the best implementation strategy, how to not do code repetition.

Code examples

TBC. Happy to receive suggestions on this one.

Benefits for you and the wider AWS community
As discussed in a past meeting with @gsingh1 @loujaybee and @simontabor, the functionality of fetching and propagating correlation ID's, including custom user-defined ones, can be useful and especially relevant for developers who operate at scale and within big organisations, where you have a high number of teams responsible for microservices communicating to each other.

Describe alternatives you've considered

None that comes into mind apart from writing the code by yourself.

Additional context
See here a brief definition of a correlation ID.

Related issues, RFCs

Not at the moment.

Feature request: tracer feature improvements

Description of the feature request

Problem statement
While an initial implementation of the Tracer core package has been done there are a handful of features that are missing when compared with the Python version. Some of these features were implemented recently while others, due to the language difference, need to be implemented differently and for this reason where left out in the initial implementation.

Summary of the feature

  • Cold start annotation present for every invocation (#851). At the moment Tracer annotates only ColdStart = true during the first invocation.
  • Service name is added as an annotation (#861). At the moment Tracer uses the service name only as default namespace when adding metadata to traces.
  • Automatic traces for HTTP requests (Python version captures all libraries). At the moment Tracer (supports this) only via explicit opt-in using the escape hatch mechanism.
  • Reusing tracer across your code (Python version implements Singleton pattern). At the moment every new Tracer() returns a completely new instance, JS/TS could implement it like so.
    โฌ†๏ธ We are opting to not introduce this feature in order to not force this pattern on every customer. See this comment.

Code examples
N/A

Benefits for you and the wider AWS community
Same behaviour as other Powertools libraries & better DX

Describe alternatives you've considered
N/A

Additional context

Related issues, RFCs

Maintenance: Use correct license

Bug description

Right now the repo is referencing the wrong license.
This one should be used instead (also important for consistency):
https://github.com/awslabs/aws-lambda-powertools-python/blob/develop/LICENSE

Expected Behavior

Licenses are consistent across languages

Current Behavior

A wrong license is referenced.

Possible Solution

Steps to Reproduce

Go to: https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/LICENSE

Environment

  • Powertools version used:
  • Packaging format (Layers, npm):
  • AWS Lambda function runtime:
  • Debugging logs:

Related issues, RFCs

Bug: metrics not flushing on throw

Bug description

If using the decorator on handler and any execution flow endup throwing an exception, the metrics won't be flushed.

Expected Behavior

Metrics should be flushed whatever is happening in the customer code.

Current Behavior

If exception thrown, no metrics sent to cloudwatch.

Possible Solution

Option 1: Flush in a finally statement here: https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/packages/metrics/src/Metrics.ts#L93

Option 2: Leverage official lib https://github.com/awslabs/aws-embedded-metrics-node that handle this properly

Steps to Reproduce

Add this test to unit tests:

test('Using decorator should log even if exception thrown', async () => {
      const metrics = new Metrics({ namespace: 'test' });
      class LambdaFunction implements LambdaInterface {
        @metrics.logMetrics()
        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
        // @ts-ignore
        public handler<TEvent, TResult>(
          _event: TEvent,
          _context: Context,
          _callback: Callback<TResult>
        ): void | Promise<TResult> {
          metrics.addMetric('test_name_1', MetricUnits.Count, 1);
          throw new Error('Test Error');
        }
      }

      try {
        await new LambdaFunction().handler(dummyEvent, dummyContext, () => console.log('Lambda invoked!'));
      } catch (error) {
        // DO NOTHING
      }
      
      expect(console.log).toBeCalledTimes(1);
    });

Should pass after fix

Environment

  • Powertools version used: v0.0.1-alpha.3
  • Packaging format (Layers, npm): npm
  • AWS Lambda function runtime: nodejs
  • Debugging logs: N/A

Related issues, RFCs

N/A

Docs: add tracer documentation

Description of the feature request

Problem statement
N/A.

Summary of the feature
Documentation for the Tracer library:
https://awslabs.github.io/aws-lambda-powertools-python/core/tracer/

Code examples
https://github.com/awslabs/aws-lambda-powertools-python/tree/develop/docs
https://github.com/awslabs/aws-lambda-powertools-python/blob/develop/README.md

Benefits for you and the wider AWS community
Understand how to use the library and speed up their adoption.

Describe alternatives you've considered

N/A

Additional context

N/A

Related issues, RFCs

#91
#152

Maintenance: Refactoring shared events/contexts

Description of the feature request

Problem statement
At the moment we have some resources like dummy events that are referenced in examples and tests across modules.

This complicates the project structure and makes it harder to reason about & work in isolation.

This issue aims at capturing the unit of work needed to propose a solution to this as discussed here.

Summary of the feature
TBD

Code examples
N/A

Benefits for you and the wider AWS community
Customers will be able to copy paste examples without needed to understand our package structure.

Describe alternatives you've considered
N/A

Additional context
N/A

Related issues, RFCs

See linked discussions above.

Feature request: feature parity for manual instrumentation tracer

Description of the feature request

This feature request is to expose some of the currently private APIs to annotate cold start, add error as metadata, and so on.

Problem statement

At the moment instrumenting tracing for a function manually is a bit clunky and requires reverse-engineering the decorator/middleware implementations.

Summary of the feature

  • Public method tracer.annotateColdStart()
  • Public method tracer.addErrorAsMetadata()
  • Public method tracer.addResponseAsMetadata()

Code examples

N/A

Benefits for you and the wider AWS community

Better DX

Describe alternatives you've considered
N/A

Additional context
N/A

Related issues, RFCs

N/A

Maintenance: `undefined` environment variable returning empty string from `EnvironmentVariablesService`

Description of the feature request

Problem statement
Currently the EnvironmentVariablesService returns an empty string if an env var is not set, rather than undefined.

Ticket to discuss the pros and cons of this approach and consider changing the logic to use undefined

Summary of the feature

Code examples

Benefits for you and the wider AWS community

Describe alternatives you've considered

Additional context

Related issues, RFCs

This issue should be addressed after:
#484

Maintenance: Enable auto-merge for dependabot

Description of the feature request

Problem statement

Today dependabot PRs require manual approval, which consists of checking if the PR builds succeeded and then merging the changes.

Summary of the feature

By enabling auto-merge for a dependabot pull requests we can reduce the required maintenance time, and focus our time on more creative tasks.

To auto-merge your pull requests, we can use GitHub's auto-merge functionality. This enables the pull request to be merged when all required tests and approvals are successfully met.

The auto-merge functionality lets us configure under which conditions we want to enable auto-merge. This lets us start with a list of trusted dependencies (e.g. aws-sdk) and a certain version type (e.g. patch). The example below limits auto-merge to patches of aws-sdk.

      - name: Enable auto-merge for Dependabot PRs
        if: ${{contains(steps.metadata.outputs.dependency-names, 'aws-sdk') && steps.metadata.outputs.update-type == 'version-update:semver-patch'}}
        run: gh pr merge --auto --merge "$PR_URL"
        env:
          PR_URL: ${{github.event.pull_request.html_url}}

Auto-merge requires permissions to write to PRs, as shown below:

permissions:
  pull-requests: write
  contents: write

Code examples

Below is an example that I copied from the Github docs and switched the trusted library to aws-sdk. I did not dive deep into the step Dependabot metadata yet.

name: Dependabot auto-merge
on: pull_request_target

permissions:
  pull-requests: write
  contents: write

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: ${{ github.actor == 'dependabot[bot]' }}
    steps:
      - name: Dependabot metadata
        id: metadata
        uses: dependabot/[email protected]
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"
      - name: Enable auto-merge for Dependabot PRs
        if: ${{contains(steps.metadata.outputs.dependency-names, 'aws-sdk') && steps.metadata.outputs.update-type == 'version-update:semver-patch'}}
        run: gh pr merge --auto --merge "$PR_URL"
        env:
          PR_URL: ${{github.event.pull_request.html_url}}
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Benefits for you and the wider AWS community

Maintainers spend less time on chores, and have more time to engage with the community.

Describe alternatives you've considered

I have not yet investigated alternatives, as this seems to be the recommended approach for Github.

With this issue I am not suggesting that we should enable the auto-merge feature through the GitHub UI.

Additional context

None yet.

Related issues, RFCs

None yet.

Maintenance: README files, beta release warnings

Description of the feature request

  • Add readme files with minimal content for each package (including root)
  • Add installation guide
  • Add notice about beta

Problem statement

N/A

Summary of the feature

N/A

Code examples

N/A

Benefits for you and the wider AWS community

N/A

Describe alternatives you've considered

N/A

Additional context

N/A

Related issues, RFCs

N/A

Maintenance: revisit automation for Issues and PR's

Note, the body of this issue was edited to reflect the new scope:

  • If possible, when a new issue is created we should add it to the GitHub project (note, this is not a Project (classic) in GH nomenclature)
  • Review & make sure that when a new PR is opened, this job runs and if the PR body doesn't contain a string that matches this regex, which should be Issue number: #digits, the proper labels and comments are added to the PR.
  • Review & make sure that when this workflow runs and labels an issue as status/pending-release, it also removes the current status/* label as well as help-wanted (if present).
  • If possible, implement this workflow in this repo, with the difference that in our case it: 1/ queries all issues marked as status/pending-release (which should be all closed), 2/ removes the label, 3/ adds a label status/completed, 4/ leaves a comment that says the thing has been released (this last point is optional & not a must)
  • If possible, extend this workflow to label PRs with the correct areas based on title suffix and with the areas being the utilities only (i.e. area/logger, area/parameters, etc. - full list here)
  • If possible, implement a boring cyborg workflow that does this for Issues and this for PRs.
  • Consider renaming this workflow to remove V2 notation

Older issue body below, hidden for clarify/brevity and to reflect the new focus.

Description of the feature request

Problem statement

To keep up with our collaboration, for clarity, and make sure our efforts are tracked, there are 2 Github projects:
https://github.com/awslabs/aws-lambda-powertools-typescript/projects

  1. AWS Lambda Powertools Typescript - Issues https://github.com/awslabs/aws-lambda-powertools-typescript/projects/2
  2. AWS Lambda Powertools Typescript - Pull Requests https://github.com/awslabs/aws-lambda-powertools-typescript/projects/3
    All explanations of each column are added in the boards.
    While this structure is helpful, there is margin of improvement for how we can limit the manual effort to keep things tidy so that we understand what's going on.

Summary of the feature

Github related automation so that:

  • Newly created issues SHOULD be added to the Issues board;
  • Newly created issues / Issues that are in the "Needs clarification" column SHOULD NOT have assignees (because assignees = responsible to implement it);
  • Newly created issues SHOULD be created with the relevant labels, no assignees, correct projects assigned;
  • Issues that are in done done state should be automatically added in form of excerpt and references to the Changelog file and releases descriptions;

This can be achieved through relevant files/setup/configuration via Github actions or files in the .github folder.

Code examples

TBD.

Benefits for you and the wider AWS community

Automation of these tasks will allow maintainers and contributors to focus on the implementation of features rather than administration of tasks. Additionally, shifting the effort from human intervention to automation will reduce the rate of human errors.

Describe alternatives you've considered

Not at the moment.

Additional context

N/A.

Related issues, RFCs

Docs: create metrics documentation

Description of the feature request

Problem statement
N/A.

Summary of the feature
Documentation for the Metrics library:
https://awslabs.github.io/aws-lambda-powertools-python/core/metrics/

Code examples
https://github.com/awslabs/aws-lambda-powertools-python/tree/develop/docs
https://github.com/awslabs/aws-lambda-powertools-python/blob/develop/README.md

Benefits for you and the wider AWS community
Understand how to use the library and speed up their adoption.

Describe alternatives you've considered

N/A

Additional context

N/A

Related issues, RFCs

#25
#152

RFC: naming convention of core utilities

Description of the proposal

We need to come to an agreement about the naming convention of the core utilities, to keep them consistent within the wider TypeScript tools.

Name of the core utility (and consequently the folders that contain the libraries):

  • packages/logger, packages/tracer, packages/meter
    OR
  • packages/logs, packages/traces, packages/metrics
    OR
  • packages/logging, packages/tracing, packages/metrics (?)

Name of Class that is used in the code to call the library:

  • const logger = new Logger();, const tracer = new Tracer();, const meter = new Meter();
    OR
  • const logs = new Logs();, const traces = new Traces();, const metrics = new Metrics();
    OR
  • const logging = new Logging();, const tracing = new Tracing();, const metrics = new Metrics(); (?)

Related issues, RFCs

TODO: this needs to be created/moved in the official RFC repo: https://github.com/awslabs/aws-lambda-powertools-rfcs.
Adding this issue here for visibility and to open the conversation.

Feature request: Logger utility

Description of the feature request

Core utility: Logger

Beta release launch checklist:

  • Business logic is created and reviewed by peers
  • All functionalities available via decorators are also available via Middy middleware
  • Unit tests are created and passing in Github Actions, with 100% coverage
  • Examples related to this utility are created in the examples folder, and up-to-date
  • Docs related to this utility are created, up-to-date, and accessible in the Docs webpage
  • The library is published to a private NPM registry via verdaccio and working correctly when imported for internal testing
  • The library is published to the public NPM registry are completed
  • The library is published to the official NPM registry and working correctly when imported and run on Lambda's

Related issues, RFCs

#130

N/A

Bug: tracer unable to create service map Lambda -> SQS -> Lambda

Description of the feature request

Problem statement

SQS currently don't propagate properly traces when chaining Lambda. See aws/aws-xray-sdk-node#208 for more details.

Summary of the feature

  1. Implement a mechanism to detect when event coming from SQS and contains XRay trace id.
  2. Rebuild segments to be part of the main trace

Code examples

I did a first implem here : https://github.com/flochaz/x-ray-lambda-sqs-lambda/blob/main/lib/lambda/consumer-function/index.js

Benefits for you and the wider AWS community

The issue on xray sdk has been open for 2 years, people are getting really frustrated, 84 ๐Ÿ‘ and tens of comments ....

Describe alternatives you've considered

Wait for service team to fix it :)

Maintenance: Publish documentation

Description of the improvement

Summary of the proposal

Publish first version of documentation for beta release

How, where did you look for information

N/A

Missing or unclear documentation

N/A

Improvement

  • Documentation Homepage #250
  • Documentation for Logger #130
  • Documentation for Metrics #151
  • Documentation for Tracer #153
  • Automate publishing on GitHub Pages โš ๏ธ Issue missing โš ๏ธ

Related existing documentation

https://awslabs.github.io/aws-lambda-powertools-python/

Related issues, RFCs

#130
#152
#153

Feature request: main implementation, randomization, middy middleware, correlation ID's, optional: object merging

Description of the feature request

Problem statement

There are some areas that should be revisited or implemented.

Summary of the feature

  1. We should update the implementation of randomisation of sampling - currently implemented like this:
  private setLogsSampled(): void {
    const sampleRateValue = this.getSampleRateValue();
    // TODO: revisit Math.random() as it's not a real randomization
    this.logsSampled = sampleRateValue !== undefined && (sampleRateValue === 1 || Math.random() < sampleRateValue);
  }

Not optimal.

  1. Implementation of middy-compatible middleware logic to match the one of the decorator which is already existing.

  2. Correlation ID's propagation - see #129

  3. Optional: replace lodash library with in-house custom code

Code examples

Benefits for you and the wider AWS community

Describe alternatives you've considered

Additional context

Related issues, RFCs

#129

Docs: wrong documentation for tracer manual mode

Bug description

Using #326 global examples and especially https://github.com/awslabs/aws-lambda-powertools-typescript/blob/examples/cdk/examples/cdk/lib/example-stack.MyFunction.ts#L43

Subsegment does not seems to be created in xray:

Screenshot 2021-12-16 at 09 44 26

And inline doc is not correct (importing Segment and using Subsegment ... ):

Expected Behavior

To have a subsegment called MySubSegment showing up in xray.

Current Behavior

Just basic segment showing

Possible Solution

Steps to Reproduce

  1. branch example/cdk
  2. deploy example
  3. check xray

Environment

  • Powertools version used: 0.1.0-beta-9
  • Packaging format (Layers, npm): npm
  • AWS Lambda function runtime: NODEJS_14
  • Debugging logs: NA

Bug: tracer capturing an error causes ERR_UNHANDLED_REJECTION or catching Customer's error

Bug description

The Tracer utility has a feature that allows Customers to annotate a segment by adding error data when an error is thrown while capturing the Lambda handler.

This feature comes from the x-ray sdk for node and is implemented also in the Python version albeit in a slightly different way due to the differences in the underlying SDK.

The current Typescript implementation uses a try/catch block to detect the error.

If the library's code allows the error to bubble up, then an ERR_UNHANDLED_REJECTION is thrown.

If instead the library's code catches the error (current implementation) the library is essentially catching an error thrown in the Customer's code.

I'd be inclined at not catching a Customer's error, but allowing it to bubble up dirties the stack trace by making it seem that the error was actually thrown by Powertools.

Would like to have a discussion to agree on expected behaviour.

Steps to Reproduce

Reproduction steps in this unit test.

Related issues, RFCs

#107

Feature request: Metrics utility

Description of the feature request

Core utility: Metrics

Beta release launch checklist:

  • Business logic is created and reviewed by peers
  • All functionalities available via decorators are also available via Middy middleware
  • Unit tests are created and passing in Github Actions, with 100% coverage
  • Examples related to this utility are created in the examples folder, and up-to-date
  • Docs related to this utility are created, up-to-date, and accessible in the Docs webpage
  • The library is published to a private NPM registry, for example via via verdaccio and working correctly when imported for internal testing
  • The library has been vetted and approved from a security perspective
  • The library is published to the official NPM registry and working correctly when imported and run on Lambda's

Related issues, RFCs

N/A

Maintenance: private publishing on npm

Description of the feature request

Problem statement

Before the beta launch, it would be good to setup tests of the code running on real Lambda functions. This can catch and mitigate errors when it comes to publishing, missing files, and build steps for example.

Summary of the feature

Proposals:

  • Private NPM registry such as Verdaccio;
  • NPM dependency locally hosted, see here
  • Lambda layer(s)

Code examples

Benefits for you and the wider AWS community

Describe alternatives you've considered

Additional context

Related issues, RFCs

Feature request: logger review PowertoolLogFormatter.formatError() message field

Description of the feature request

Problem statement

We have observed a potential issue related to how node generates error messages that might affect the PowertoolLogFormatter.formatError() and that made unit tests fail.

An hot fix has been applied (here) but we need to make sure that all errors are formatted properly and that there are sufficient unit test cases.

RFC: utilities packages structure

Description of the feature request

We need to come to an agreement on how to structure the utilities packages like parameters, parsers, etc. for this project.

Problem statement

The Python version of Powertools groups all the modules/classes under an utilities umbrella module. This is in line with how package management is done in Python and with the way the AWS SDK (boto3) is distributed.

The Typescript version seem to be going in the monorepo direction with each utility having its own published package and its own dependencies. This choice makes sense also in the context of the newer AWS SDK v3 for Javascript that also has a modular architecture.

Describe alternatives you've considered

On one hand, favouring consistency with the Python utility all the utilities (parsers, parameters, etc.) should be under the same utility package. On the other hand splitting each utility in its own package would bring the following benefits:

  • Being in line with the other Typescript/Javascript AWS-related projects like AWS SDK v3 and CDK
  • Allowing Customers to have closer control over the deployment package size by importing only the dependencies that they need. I.e. If a Customer needs the parsers utility but not the parameters one there would be no reason to bring dependencies like @aws-sdk/client-secrets-manager, @aws-sdk/client-ssm, @aws-sdk/client-dynamodb, etc. which are not needed for the parsers util.

Feature request: rename raiseOnEmptyMetrics to throwOnEmptyMetrics

Description of the feature request

Currently the metrics Class has a class propriety shouldRaiseOnEmptyMetrics and middleware/decorator parameter raiseOnEmptyMetrics that when set to true, will cause the library to throw an error when no metrics are created.
As flagged by @dreamorosi in this PR, throw is a more intuitive and accurate way to describe the behaviour in the Node.js runtime.
The name is currently ported as it is from the Python library.

Problem statement

Based on above, the name of the parameters can be confusing for developers using the Node.js runtime.

Summary of the feature

  • Rename both the middleware/decorator parameters, the class propriety and the types (from raise to throw)
  • Update the documentations and examples

Code examples

const handlerWithMiddleware = middy(lambdaHandler)
  .use(logMetrics(metrics, { throwOnEmptyMetrics: true }));

Benefits for you and the wider AWS community

Better clarity of the feature, less confusion.

Describe alternatives you've considered

N/A

Additional context

Related issues, RFCs

Feature request: Tracing utility

Description of the feature request

Core utility: Tracing

Beta release launch checklist:

  • Business logic is created and reviewed by peers
  • All functionalities available via decorators are also available via Middy middleware
  • Unit tests are created and passing in Github Actions, with 100% coverage
  • Examples related to this utility are created in the examples folder, and up-to-date
  • Docs related to this utility are created, up-to-date, and accessible in the Docs webpage - #153
  • The library is published to a private NPM registry, for example via via verdaccio and working correctly when imported for internal testing
  • The library has been vetted and approved from a security perspective
  • The library is published to the official NPM registry and working correctly when imported and run on Lambda's

Related issues, RFCs

N/A

Docs: document all supported environment variables settings

Description of the feature request

The library's utilities allow the configuration of settings via env variables or constructor.
It would be helpful to create a documentation section with a table for each utility to describe what variables can be used, and if they overlap with other TS utilities or not (for example: POWERTOOLS_SERVICE_NAME, POWERTOOLS_TRACE_ENABLED, ...)

Problem statement

Developers can figure it out by looking at the source code, but the variables are undocumented.

Summary of the feature

N/A

Code examples

N/A

Benefits for you and the wider AWS community

N/A

Describe alternatives you've considered

N/A

Additional context

N/A

Related issues, RFCs

N/A

Docs: cdk examples + e2e tests

Description of the feature request

Similarly to what is done for Tracer and Metrics utilities, it would be helpful for developers to add these functionalities.

Problem statement

Summary of the feature

  • Add logger related examples in root folder
  • Add e2e tests in the package folder/scope

Code examples
N/A

Benefits for you and the wider AWS community
Better understand how to use the library, better testing coverage

Describe alternatives you've considered
N/A

Additional context
N/A

Related issues, RFCs

N/A

Maintenance: labels strategy & automation for Issues and PRs

Description of the feature request

Minor feature but useful for governance of external contributions by the AWS community.
It would be good to review labels used for Github Issues and PR's.

  • Review the existing labels and add, edit, delete labels also based on other runtimes
  • When applicable, automate the assignment of labels based on specific criteria
  • Nice to have: make sure that there is consistency and labels convention (uppercase vs lower case, spaces, characters used, ...)

Problem statement

Inspired by this PR: aws-powertools/powertools-lambda-python#894
Without proper labelling the runtime maintainers and the AWS community can be confused about the current status of the item (issue or PR).

Summary of the feature

N/A

Code examples

See other runtimes:
https://github.com/awslabs/aws-lambda-powertools-python/labels
https://github.com/awslabs/aws-lambda-powertools-java/labels

Benefits for you and the wider AWS community

Improved transparency and governance.

Describe alternatives you've considered

N/A

Additional context

N/A

Related issues, RFCs

N/A

Maintenance: use npm-shrinkwrap instead of package-lock

Bug description

The package uses package-lock.json instead of npm-shirinkwrap.json.

I didn't spot this in the PR review.

Expected Behavior

Use npm-shrinkwrap.json.

Current Behavior

Using package-lock.json.

Possible Solution

Run npm shrinkwrap in the package folder, delete the old file, commit the new one.

Steps to Reproduce

N/A

Docs: improve the "Contributing" section documentation

Description of the improvement

Summary of the proposal

Right now the contributing docs are very bare.
To make it inclusive and accessible for contributors from different seniority, background and experience, this area should be be more detailed to make sure that ambiguity is reduced and most importantly, in case of PR's, expectations are communicated early on in the PR progress.

How, where did you look for information

In the current Contributing doc.

Missing or unclear documentation

Contributions may be related to:

  • Design (UX, accessibility)
  • Research to scope requirements or understand priorities
  • Improve the documentation
  • Add or improve examples
  • Writing tutorials
  • Implementation of new features via Pull Requests's
  • Bux fixes
  • Share ideas & proposals
  • Organising Github issues, labels, projects
  • Review code and Pull Requests

Improvement

Rather than 1 single cluttered CONTRIBUITING.md file, a folder with organized files/sections might be easier to read and browse.

Related existing documentation

Contributing file

Related issues, RFCs

#426
#422

Maintenance: delete examples in packages folder

Description of the feature request

Problem statement

Redundant examples in the logger folder.

Summary of the feature

The scope of this Issue is to delete this folder:
https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/logger/examples
Nobody is using this folder, and it's just redundant at this point.

Code examples

Benefits for you and the wider AWS community

Describe alternatives you've considered

Additional context

Related issues, RFCs

Maintenance: release process

Description of the feature request

Problem statement

For the scope of our first beta release, and consequent ones, when one or more features are merged to main and ready to be published, a release process needs to be in place in order to make the NPM library available to the wider public.
Ideally, this process should be as automated as possible to reduce the operational burden of maintainers and contributors who can instead focus on the core business logic of this library.

Summary of the feature

Tasks related to this process can include:

  • Github workflow triggered any time a change is pushed to the main branch - that will validate, through different tests, that the code is production ready. Why similar automated tests might already have been performed in the PR branches, I would advice that we protect the main branch again any changes added.
  • Before the code is released, release notes should be added in the Changelog file(s). See this website for reference. It would be nice to have but not paramount for the beta release if we could automate this to avoid losing so much time understanding what is gonna be released and what is still not merged. This can be achieved by looking for example at the issues placed in the "Done but not yet released" column of our Github Project:

Screenshot 2021-07-26 at 15 32 24

- Github workflow triggered any time a new [release](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#release) is created. Release steps may include (but not limited to): compile, lint, audit, test, publish the code.

Note that the above should probably be split in multiple issues and/or PR's to reduce the amount of code reviewed at once.

Code examples

Benefits for you and the wider AWS community

Describe alternatives you've considered

Additional context

Related issues, RFCs

Feature request: enable tracing only when running on AWS Lambda

Description of the feature request

Customers have raised a pain point around the Tracer utility throwing errors when when not running inside the Lambda execution environment. While both the Tracer and the underlying aws-x-ray packages provide ways to both change missing context strategy and disable tracing altogether, it would make sense to have Tracer to be enabled by default only when running inside a Lambda function and disabled elsewhere instead of the current behaviour that sees the utility always being enabled by default unless explicitly disabled.

Problem statement

Tracer throws an error when trying to interact with a segment outside of a context and/or without the existence of a root segment (aka facade). Customers have to explicitly disable the Tracer utility when running outside of Lambda (i.e. testing, CI, etc.) which can be cumbersome.

Summary of the feature

  • Change wording/names of the parameter and variable used to enable/disable tracing to avoid double negation (i.e. currently reading like tracing disabled, change to tracing enabled).
  • Add logic to detect whether Tracer is being initialised in a Lambda function or not which would check the existence of one between AWS_LAMBDA_FUNCTION_NAME or AWS_EXECUTION_ENV environment variables that are present by default in Lambda.
  • Change protected property Tracer.tracingDisabled to Tracer.tracingEnabled.
  • Change all conditional behaviour and references related to Tracer.tracingDisabled to account for change.
  • Update all unit tests.

Code examples

  • Current environment variable used to disable tracing is POWERTOOLS_TRACE_DISABLED, would change to POWERTOOLS_TRACE_ENABLED.
  • Currently, to disable the tracer Customers have to do this const tracer: Tracer = new Tracer({ disabled: true });, it would change to const tracer: Tracer = new Tracer({ enabled: true });

Benefits for you and the wider AWS community

Better Developer Experience, less boilerplate code (-1 extra line) needed to instrument tests.

Describe alternatives you've considered

Clearer documentation around how to either disable tracing and/or changing X-Ray underlying SDK behaviour to ignore missing segments/context.

Additional context

Related issues, RFCs

#515
#572

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.