chore(tracer): quality of life improvements

[dreamorosi]

Description of your changes

This PR includes the following changes, all related to the Tracer module:

• Introduced usage of @aws-lambda-powertools-typescript/commons package in tests (examples will be updated in separate PR related to Maintenance: delete examples in packages folder #332).
• Updated README.md file of the package to include only intro + link to main docs as discussed in standup.
• Exposed tracer.addResponseAsMetadata as public API, changed middleware to use it, updated tests & docs (Feature request: feature parity for manual instrumentation tracer #334).
• Exposed tracer.addErrorAsMetadata as public API, changed middleware to use it, updated tests & docs (Feature request: feature parity for manual instrumentation tracer #334).
• Exposed tracer.annotateColdStart as public API, changed middleware to use it, updated tests & docs (Feature request: feature parity for manual instrumentation tracer #334).
• Changed behaviour of tracer.annotateColdStart so that annotation is always added to main segment even when it's not a cold start, this is a change mentioned here Feature request: tracer feature improvements #275.
• Added public API tracer.addServiceNameAnnotation to allow Customers to add the annotation to the main segment, changed middleware & decorator to use it, updated tests & docs; this is a change mentioned here Feature request: tracer feature improvements #275.

How to verify this change

Verify that all tests are passing & coverage hasn't decreased.

Related issues, RFCs

#332
#334
#275
#851 (Python)
#861 (Python)

PR status

Is this ready for review?: YES
Is it a breaking change?: YES

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• The code coverage hasn't decreased
• I have added tests that prove my change is effective and works
• New and existing unit tests pass locally and in Github Actions
• Any dependent changes have been merged and published in downstream module
• The PR title follows the conventional commit semantics

Breaking change checklist

• I have documented the migration process
• I have added, implemented necessary warnings (if it can live side by side)

This is a breaking change in the sense that generated traces will now all have ColdStart (sometimes true, sometimes false) and ServiceName annotations.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[dreamorosi]

I revisited the implementation of the Tracer middleware because while testing it on an actual Lambda function I was running in an issue similar to the one described here. The integration and API haven't changed but the implementation now correctly handles the segments, the key was in calling setSegment with the facade segment (the main one) at the end so that each execution in the same execution environment is represented correctly in X-Ray.

[ijemmy]

LGTM overall. I have only a few nits for you to double check.

[ijemmy]

(nit) Should it have "##"?

[dreamorosi]

Don't have a strong feeling about this, followed Python's implementation that puts ## in subsegments (see img below - taken from docs here or Python implementation here)
.

[saragerion]

The python tracer library is opinionated on the syntax of the subsegments' labels (as it is with the format of the structure logs, for example).
I say that for consistency and feature parity we should leave it as it is, but allow customers to control the annotation labels if they want to in the future (but this we can do after the beta).

[saragerion]

Added a couple of comments (minor). Thanks @dreamorosi! 🎉

[saragerion]

Looks great, I just left a minor nit (I would find/replace in the codebase for captureLambdaHanlder), but for me it's already good to merge :chefskiss: