Aws-xray-sdk-node: Node SDK release V3.0.0

[yogiraj07]

Hello,
This issue tracks next major version release changes : V3.0.0

1) Using cls-hooked library for trace context

Currently, master branch uses continuation-local-storage library for thread local storage. cls-hooked library is used as thread local storage for async operations in the expermental-hooks branch. The next major version will merge branch expermental-hooks into master and cls-hooked library will be used for synchronous and asynchronous operations. expermental-hooks branch will be deprecated.

When running Nodejs version >= 8.2.1, cls-hooked module uses the newer async_hooks API which is considered Experimental by Nodejs : reference.

This change is included as per community feedback.

Action required for update

It is unlikely this change will cause any existing code to break. If you'd like to be safe, test your application with the experimental-hooks branch of the SDK. Installation instructions can be found here. The only difference between the 2.x and experimental-hooks branches is the use of cls-hooked, so this would be the best way to detect if the change causes any issues in your application.

2) Dropping support for Node V4, V6, V8

Currently the SDK supports Node versions 4, 6, and 8. Since these versions have met end of life : reference, the major version will drop support for these versions.

Action required for update

Ensure your application uses Node 10 or above.

3) Removal of winston

We will merge #190 to remove the dependency on the winston logging library. This will reduce the size of our bundle, a big customer ask (see #113). winston is an overly complex and cumbersome library given our simple use case, and it will be replaced with a lightweight, native console logger. All logs emitted from the SDK will be formatted the same way as

 [timestamp] [log level] [message] [optional metadata]

The setLogger() API will be unchanged, so you can still replace the default logger with any logger object of your choice as long as it implements the debug, info, warn, and error methods.

Action required for update

If you programmatically consume logs, be prepared for the new format described above. If you have been using the getLogger() API, there is a possibility your code can break. Since winston will no longer be the default logging library, usages such as

AWSXRay.getLogger().add(winston.transports.File);

will no longer work by default. You'll have to create your own winston logger object and pass it to the SDK using the setLogger() API.

4) Separation of aws-sdk

This SDK will be restructured so that aws-xray-sdk-core no longer depends on aws-sdk. This has also been a long time customer ask (see #113) and will be the last change to make this package fully lightweight, especially in Lambda environments.

We will be changing all requests made by the X-Ray SDK using the AWS SDK calls to native HTTP calls to their corresponding API calls. This will be a simple change, however a consequence of removing the dependency on the aws-sdk is that we will no longer have access to its types.

Action required for update

This change should not affect the functionality of the SDK whatsoever. However, if you use TypeScript, types defined in aws_p.d.ts will transition from PatchedAWS and PatchedAWSClient to the original AWS and AWS.Service. This should not impact usage since all methods & fields on the original AWS types were copied over.

---

Please see the below comment for a schedule of the release process.

We welcome any further suggestions.

Thanks,
Yogi

[parisholley]

just want to drop my two cents in case it wasn't considered.

for performance (and architectural reasons), I prefer to rely on manual segmentation vs having it automatically wired up. activating hooks and other "magic" will increase CPU time (latency), so I want to ensure that all the magic can be opted-out :)

even in the case of AWS SDK, I actually prefer to either
a) segment around my service layer instead (what I do now)
b) append custom segment ids to each call
c) create a client per root segment (eg: web request)

[willarmiros]

The 3.0.0 release process will be done in phases. First, we will release a 3.0.0-alpha.1 version of the SDK that includes the deprecation of node 4 and 6, mainlining the use of cls-hooked, and removing winston. This is being done to give our customers the new features of 3.x as soon as possible. We will also release the separation of the aws-sdk dependency as a breaking change in 3.0.0-alpha.2. This change will be clearly documented in this issue and the release notes. Caution should be exercised while using the SDK’s 3.x alpha version, since it is unlikely but possible that updates will cause backwards incompatibility in unexpected ways. Once all new features for 3.x are integrated, the alpha tag will be removed and subsequent updates will no longer contain breaking changes.

We will leave the 2.x and experimental-hooks branches in tact for customers who do not wish to upgrade, but still want to see the 2.x source code or documentation.

In summary, the schedule for the entire release process is as follows:


1. Merge #190 (the removal of winston) into master. DONE
2. Merge other outstanding PRs to 2.x and make a final 2.x release of the SDK as 2.5.0. Barring any major issues, the recently made PR #207 to add TypeScript definitions will be included in this release. DONE
3. Merge all changes from 2.x to master. DONE
4. Merge experimental-hooks into master. This will change the package to depend on cls-hooked instead of cls. DONE
5. Make appropriate changes to remove support for node 4 and 6 on master. DONE
6. Release 3.0.0-alpha.1 from the master branch. DONE
7. Release the removal of the aws-sdk dependency from the SDK as a 3.0.0-alpha.2 release. This will likely be a breaking change. DONE
8. Once the release is stable and immediate bugs are fixed, remove the alpha tag from the 3.x version of the SDK, and deprecate official support (except security patches) for the 2.x and experimental releases of the SDK. These versions will still be publicly available to view on GitHub and download from npm for legacy purposes. DONE

[LosD]

@willarmiros Any idea around the release timeline? We're currently not using aws-xray-sdk-core in our Lambda functions as it makes function size double (or more), but we'd sure like to.

[willarmiros]

Hi @LosD,
You can expect much more progress to be made here in the coming weeks. I'll continue to update the above comment to track progress. Steps 7 and 8 will unfortunately take a little while longer since we have not started work on the separation of the aws-sdk yet.

[LosD]

@willarmiros that's great, thanks for the update.

[awssandra]

3.0.0-alpha-1 has been released! Mainline now reflects the latest, previous 2.x version is snapshotted on a separate branch. Changelog can be found here.

[willarmiros]

3.0.0-alpha.2 has been released! This should be the last alpha version before v3 is made GA, please install it and try it out so we can iron out any bugs before the proper release.

npm i --save aws-xray-sdk@alpha

[kbradl16]

@Willarmiros what’s the timeline for v3.0 release?

[willarmiros]

Hi @kbradl16,
I cannot provide you with an official date, but as stated the plan is to make the next release of this SDK the v3 stable release.

[kbradl16]

@Willarmiros Just curious but why not? An official release date isn’t need, I’d be happy with a best guess. What are you/we waiting for? Just trying to gauge if/when I should start seriously testing. If it’s months out then it’s not worth it at the moment.

[willarmiros]

It's the policy of AWS to not provide any release dates (estimations or otherwise) on open source software. To be honest, most of what we're waiting for now is the process to update the public docs and hopefully get some customer feedback on alpha.2.

I can tell you that apart from the recent decision to additionally deprecate support for node 8 (see #265), the v3 release should be pretty much identical to the current 3.0.0-alpha.2 version. So we'd much appreciate testing now to get bugfixes in before the stable release.

[kbradl16]

Ok, thanks that’s helpful. I’ll give it a try

[willarmiros]

V3 of the SDK has been released to NPM! Upgrade today and let us know what you think :)

Also, feel free to experiment with or contribute to the new Express sample app.

[jplock]

Thank you for the well coordinated release @willarmiros!