Update readmes, documentation, comments, and scripts (#23)

*Issue #, if available:*

*Description of changes:*
Root files `CONTRIBUTING.md` and `README.md` are now more aligned with
[ADOT
Python](https://github.com/aws-observability/aws-otel-python-instrumentation).

Update install scripts and related instructions to use `npm install`
instead of `npm link` as it is recommended from NPM for testing
(https://docs.npmjs.com/creating-and-publishing-scoped-public-packages#testing-your-package).

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

---------

Co-authored-by: Ping Xiang <[email protected]>

.github/workflows/main-build.yml

@@ -79,3 +79,22 @@ jobs:
         with:
           name: ${{ steps.staging_tarball_output.outputs.STAGING_TARBALL}}
           path: aws-distro-opentelemetry-node-autoinstrumentation/${{ steps.staging_tarball_output.outputs.STAGING_TARBALL}}
+      # TODO - implement contract tests in NodeJS
+      # - name: Set up and run contract tests with pytest
+      #   run: |
+      #     bash scripts/set-up-contract-tests.sh
+      #     pip install pytest
+      #     pytest contract-tests/tests
+
+  # TODO - implement E2E tests in NodeJS
+  # application-signals-e2e-test:
+  #   name: "Application Signals E2E Test"
+  #   needs: [ build ]
+  #   uses: ./.github/workflows/application-signals-e2e-test.yml
+  #   secrets: inherit
+  #   permissions:
+  #     id-token: write
+  #     contents: read
+  #   with:
+  #     staging-wheel-name: ${{ needs.build.outputs.staging_wheel_file }}
+  #     adot-image-name: ${{ needs.build.outputs.staging_registry }}/aws-observability/adot-autoinstrumentation-python-staging:${{ needs.build.outputs.python_image_tag }}

.gitignore

@@ -1,6 +1,8 @@
-# Generated directories (e.g. through `npm run compile`)
+# Generated directories (e.g. through `npm run ...`)
 build/
 node_modules/
+aws-distro-opentelemetry-node-autoinstrumentation/coverage/
+aws-distro-opentelemetry-node-autoinstrumentation/src/version.ts
 
 # Other
 .git/

CONTRIBUTING.md

@@ -27,6 +27,9 @@ Contributions via pull requests are much appreciated. Before sending us a pull r
 1. You are working against the latest source on the *main* branch.
 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
 3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
+4. You are not mixing substantial refactoring changes in with functional changes.
+   1. If refactoring is desirable, publish a separate refactoring PR first, followed by a functional change PR. This will ensure safe and efficient reviews.
+   2. PRs that do not meet these expectations will be rejected.
 
 To send us a pull request, please:
 
@@ -36,10 +39,12 @@ To send us a pull request, please:
 4. Commit to your fork using clear commit messages.
 5. Send us a pull request, answering any default questions in the pull request interface.
 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
+7. Please do not squash commits between revisions, this makes review challenging, as the diff between revisions is harder to find and review.
 
 GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
 [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
 
+The following sections provide some guidance that will help you make contributions.
 
 ## NPM Commands for ADOT JS Development
 
@@ -73,19 +78,17 @@ npm run test
 
 ### Test the local ADOT JS package with your own local NodeJS project
 
-In the `./aws-distro-opentelemetry-node-autoinstrumentation` directory, run:
+In the root directory of `aws-otel-js-instrumentation`, run:
 
 ```shell
-npm install
-npm run compile
-npm link
+./scripts/build_and_install_distro.sh
 ```
 
 In the target local NodeJS project to be instrumented, run
 
 ```shell
 npm install
-npm link @aws/aws-distro-opentelemetry-node-autoinstrumentation
+npm install /<PATH>/<TO>/aws-distro-opentelemetry-node-autoinstrumentation
 ```
 
 Your NodeJS project can now be run with your local copy of the ADOT NodeJS code with:

README.md

@@ -1,17 +1,46 @@
-## My Project
+# AWS Distro for OpenTelemetry - Instrumentation for JavaScript
 
-TODO: Fill this README out!
+## Introduction
 
-Be sure to:
+This project is a redistribution of the [OpenTelemetry Auto-Instrumentation for NodeJS](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node),
+preconfigured for use with AWS services. Please check out that project too to get a better
+understanding of the underlying internals. You won't see much code in this repository since we only
+apply some small configuration changes, and our OpenTelemetry friends takes care of the rest. The
+exception to this is support for Application Signals.
 
-* Change the title in this README
-* Edit your repository description on GitHub
+We provided a NodeJS agent that can be attached to any application using a supported NodeJS version and dynamically injects
+bytecode to capture telemetry from a number of popular libraries and frameworks. The telemetry data
+can be exported in a variety of formats. In addition, the agent and exporter can be configured via
+command line arguments or environment variables. The net result is the ability to gather telemetry
+data from a NodeJS application without any code changes.
 
-## Security
+## Getting Started
 
-See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+The official AWS Documentation for getting started with ADOT JS Auto-Instrumentation is under construction.
+Meanwhile, check out the [getting started documentation for manual instrumentation](https://aws-otel.github.io/docs/getting-started/javascript-sdk).
+
+## Supported NodeJS libraries and frameworks
+
+For the complete list of supported frameworks, please refer to the [OpenTelemetry for JavaScript documentation](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations).
+
+## Support
+
+Please note that as per policy, we're providing support via GitHub on a best effort basis. However, if you have AWS Enterprise Support you can create a ticket and we will provide direct support within the respective SLAs.
+
+## Security issue notifications
+
+If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
 
 ## License
 
 This project is licensed under the Apache-2.0 License.
 
+## Notices
+
+### NodeJS Version Support
+
+This project ensures compatibility with the following supported NodeJS versions: 14, 16, 18, 20, 22
+
+### Note on Amazon CloudWatch Application Signals
+
+[Amazon CloudWatch Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html) components are designed to seamlessly work with all library instrumentations offered by [OpenTelemetry NodeJS auto-instrumentation](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/metapackages/auto-instrumentations-node/README.md). While upstream OpenTelemetry NodeJS instrumentations are in beta, Application Signals components are stable, production ready and have also been tested for popular libraries/frameworks such as `ExpressJS, AWS SDK for JavaScript V3, and others`. We will prioritize backward compatibility for Application Signals components, striving to ensure that they remain functional even in the face of potential breaking changes introduced by OpenTelemetry upstream libraries. Please [raise an issue](https://github.com/aws-observability/aws-otel-js-instrumentation/blob/main/CONTRIBUTING.md#reporting-bugsfeature-requests) if you notice Application Signals doesn't work for a particular OpenTelemetry supported library.

sample-applications/simple-express-server/README.md

@@ -34,7 +34,7 @@ node --require '@opentelemetry/auto-instrumentations-node/register' sample-app-e
 To startup the Express Sample App with local AWS Distro OTel auto-instrumentation, go to the `root` directory and run the following command to install the sample app with ADOT JS instrumentation:
 
 ```shell
-./scripts/install_and_link_simple_express_app_with_instrumentation.sh
+./scripts/install_simple_express_app_with_adot_instrumentation.sh
 ```
 
 Then start the app in this directory with:

scripts/build_and_install_distro.sh

@@ -17,9 +17,3 @@ fi
 npm install
 npm run compile
 
-cd ./aws-distro-opentelemetry-node-autoinstrumentation
-# This is handy for installing a local copy of the instrumentation for your own NodeJS project. After running this command,
-# run `npm link @aws/aws-distro-opentelemetry-node-autoinstrumentation` in your NodeJS project directory to create a symbolic link
-# from the globally-installed `@aws/aws-distro-opentelemetry-node-autoinstrumentation` to `node_modules/` of your NodeJS project folder
-# See - https://docs.npmjs.com/cli/v10/commands/npm-link
-npm link

scripts/install_and_link_simple_express_app_with_instrumentation.sh → scripts/install_simple_express_app_with_adot_instrumentation.sh

@@ -20,6 +20,5 @@ fi
 cd ./sample-applications/simple-express-server/
 npm install
 
-# create a symbolic link from the globally-installed `@aws/aws-distro-opentelemetry-node-autoinstrumentation``
-# to the `node_modules/` of the simple express server application
-npm link @aws/aws-distro-opentelemetry-node-autoinstrumentation
+# Install the locally compiled `@aws/aws-distro-opentelemetry-node-autoinstrumentation` project
+npm install ./../../aws-distro-opentelemetry-node-autoinstrumentation