AppSignals Functionality - add AlwaysRecordSampler and Utility files,…

… add pr-build workflow (#9) *Issue #, if available:* *Description of changes:* Implement the following files in TypeScript ``` always-record-sampler.ts aws-attribute-keys.ts aws-span-processing-util.ts configuration/sql_dialect_keywords.json sqs-url-parser.ts ``` - [Java Comparison](https://github.com/aws-observability/aws-otel-java-instrumentation/tree/main/awsagentprovider/src/main/java/software/amazon/opentelemetry/javaagent/providers) - [Python Comparison](https://github.com/aws-observability/aws-otel-python-instrumentation/tree/main/aws-opentelemetry-distro/src/amazon/opentelemetry/distro) By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.
aws-observability · Aug 2, 2024 · 9aa8086 · 9aa8086
1 parent a25c3d4
commit 9aa8086
Show file tree

Hide file tree

Showing 21 changed files with 2,171 additions and 26 deletions.
diff --git a/.github/workflows/pr-build.yml b/.github/workflows/pr-build.yml
@@ -0,0 +1,60 @@
+name: JavaScript Instrumentation PR Build
+on:
+  pull_request:
+    branches:
+      - main
+      - "release/v*"
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false # ensures the entire test matrix is run, even if one permutation fails
+      matrix:
+        node: ["14", "16", "18", "20", "22"]
+    env:
+      NPM_CONFIG_UNSAFE_PERM: true
+    steps:
+      - name: Checkout Repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Update npm to a version that supports workspaces (v7 or later)
+        if: ${{ matrix.node < 16 }}
+        run: npm install -g npm@9 # npm@9 supports node >=14.17.0
+      - name: NPM Clean Install
+        # https://docs.npmjs.com/cli/v10/commands/npm-ci
+        run: npm ci
+      - name: Compile all NPM projects
+        run: npm run compile
+      - name: Unit tests (Full)
+        if: matrix.code-coverage
+        run: npm run test
+      - name: Report Coverage
+        if: ${{ matrix.code-coverage && !cancelled()}}
+        uses: codecov/codecov-action@v4
+        with:
+          verbose: true
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: 'npm'
+      - run: npm ci
+      - name: Lint
+        run: |
+          npm run lint
+          npm run lint:markdown
+          npm run lint:readme
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -0,0 +1,18 @@
+// https://github.com/open-telemetry/opentelemetry-js-contrib/blob/d52d4218235528dcecc706867425b86bac49b1f0/.markdownlint-cli2.jsonc
+{
+  "config": {
+    // https://github.com/DavidAnson/markdownlint/blob/main/README.md#rules--aliases
+    "MD013": false,
+    "MD024": false,
+    "MD033": false,
+    "MD041": false,
+    // MD004/ul-style. We prefer dash, but generated CHANGELOG.md files use
+    // asterisk. The default "consistent" is a good compromise.
+    "MD004": { "style": "consistent" },
+    // This setting is for a future potential CHANGELOG.md file, which doesn't exist yet
+    "MD012": false // no-multiple-blanks; disabled because common in CHANGELOG.md files
+  },
+  "gitignore": true,
+  "noBanner": true,
+  "noProgress": true
+}
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -1,4 +1,5 @@
 ## Code of Conduct
+
 This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
 For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
-[email protected] with any additional questions or comments.
+<[email protected]> with any additional questions or comments.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -21,6 +21,7 @@ reported the issue. Please try to include as much information as you can. Detail
 
 
 ## Contributing via Pull Requests
+
 Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
 
 1. You are working against the latest source on the *main* branch.
@@ -47,52 +48,67 @@ The following are useful commands that can be run within the `root` directory of
 Use `npm install` within the root directory to initialize all package directories before running any of the following commands.
 
 ### Build TypeScript into JavaScript
-```
+
+```shell
 npm run compile
 ```
 
 ### Lint
-```
+
+```shell
 npm run lint
 ```
 
 ### Lint automatic fixing
-```
+
+```shell
 npm run lint:fix
 ```
+
+### Run unit tests
+
+```shell
+npm run tests
+```
+
 ### Test the local ADOT JS package with your own local NodeJS project
 
 In the `./aws-distro-opentelemetry-node-autoinstrumentation` directory, run:
-```
+
+```shell
 npm install
 npm run compile
 npm link
 ```
 
 In the target local NodeJS project to be instrumented, run
 
-```
+```shell
 npm install
 npm link @aws/aws-distro-opentelemetry-node-autoinstrumentation
 ```
 
 Your NodeJS project can now be run with your local copy of the ADOT NodeJS code with:
-```
+
+```shell
 node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js.js
 ```
 
 
 ## Finding contributions to work on
+
 Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
 
 
 ## Code of Conduct
+
 This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
 For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
-[email protected] with any additional questions or comments.
+<[email protected]> with any additional questions or comments.
 
 
 ## 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.
 
 

diff --git a/aws-distro-opentelemetry-node-autoinstrumentation/README.md b/aws-distro-opentelemetry-node-autoinstrumentation/README.md
@@ -1,18 +1,20 @@
 # AWS Distro for OpenTelemetry (ADOT) NodeJS Auto-Instrumentation
 
 Install this package into your NodeJS project with:
-```
+
+```shell
 npm install --save @aws/aws-distro-opentelemetry-node-autoinstrumentation
 ```
 
 Run your application with ADOT NodeJS with:
-```
+
+```shell
 node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
 ```
 
 ## Sample Environment Variables for Application Signals
 
-```
+```shell
 export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
 export OTEL_PROPAGATORS=xray,tracecontext,b3,b3multi \
 export OTEL_TRACES_EXPORTER=console,otlp \

diff --git a/aws-distro-opentelemetry-node-autoinstrumentation/package.json b/aws-distro-opentelemetry-node-autoinstrumentation/package.json
@@ -45,7 +45,8 @@
     "rimraf": "5.0.5",
     "sinon": "15.2.0",
     "ts-mocha": "10.0.0",
-    "typescript": "4.4.4"
+    "typescript": "4.4.4",
+    "expect": "29.2.0"
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",

diff --git a/aws-distro-opentelemetry-node-autoinstrumentation/src/always-record-sampler.ts b/aws-distro-opentelemetry-node-autoinstrumentation/src/always-record-sampler.ts
@@ -0,0 +1,67 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Context, Link, SpanAttributes, SpanKind } from '@opentelemetry/api';
+import { Sampler, SamplingDecision, SamplingResult } from '@opentelemetry/sdk-trace-base';
+
+/**
+ * This sampler will return the sampling result of the provided {@link #rootSampler}, unless the
+ * sampling result contains the sampling decision {@link SamplingDecision.NOT_RECORD}, in which case, a
+ * new sampling result will be returned that is functionally equivalent to the original, except that
+ * it contains the sampling decision {@link SamplingDecision.RECORD}. This ensures that all
+ * spans are recorded, with no change to sampling.
+ *
+ * <p>The intended use case of this sampler is to provide a means of sending all spans to a
+ * processor without having an impact on the sampling rate. This may be desirable if a user wishes
+ * to count or otherwise measure all spans produced in a service, without incurring the cost of 100%
+ * sampling.
+ */
+export class AlwaysRecordSampler implements Sampler {
+  private rootSampler: Sampler;
+
+  public static create(rootSampler: Sampler): AlwaysRecordSampler {
+    return new AlwaysRecordSampler(rootSampler);
+  }
+
+  private constructor(rootSampler: Sampler) {
+    if (rootSampler === null) {
+      throw new Error('rootSampler is null. It must be provided');
+    }
+    this.rootSampler = rootSampler;
+  }
+
+  shouldSample(
+    context: Context,
+    traceId: string,
+    spanName: string,
+    spanKind: SpanKind,
+    attributes: SpanAttributes,
+    links: Link[]
+  ): SamplingResult {
+    const rootSamplerSamplingResult: SamplingResult = this.rootSampler.shouldSample(
+      context,
+      traceId,
+      spanName,
+      spanKind,
+      attributes,
+      links
+    );
+    if (rootSamplerSamplingResult.decision === SamplingDecision.NOT_RECORD) {
+      return this.wrapResultWithRecordOnlyResult(rootSamplerSamplingResult);
+    }
+    return rootSamplerSamplingResult;
+  }
+
+  toString(): string {
+    return `AlwaysRecordSampler{${this.rootSampler.toString()}}`;
+  }
+
+  wrapResultWithRecordOnlyResult(result: SamplingResult) {
+    const wrappedResult: SamplingResult = {
+      decision: SamplingDecision.RECORD,
+      attributes: result.attributes,
+      traceState: result.traceState,
+    };
+    return wrappedResult;
+  }
+}
diff --git a/aws-distro-opentelemetry-node-autoinstrumentation/src/aws-attribute-keys.ts b/aws-distro-opentelemetry-node-autoinstrumentation/src/aws-attribute-keys.ts
@@ -0,0 +1,32 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// Utility class holding attribute keys with special meaning to AWS components
+export const AWS_ATTRIBUTE_KEYS: { [key: string]: string } = {
+  AWS_SPAN_KIND: 'aws.span.kind',
+  AWS_LOCAL_SERVICE: 'aws.local.service',
+  AWS_LOCAL_OPERATION: 'aws.local.operation',
+  AWS_REMOTE_SERVICE: 'aws.remote.service',
+  AWS_REMOTE_OPERATION: 'aws.remote.operation',
+  AWS_REMOTE_RESOURCE_TYPE: 'aws.remote.resource.type',
+  AWS_REMOTE_RESOURCE_IDENTIFIER: 'aws.remote.resource.identifier',
+  AWS_SDK_DESCENDANT: 'aws.sdk.descendant',
+  AWS_CONSUMER_PARENT_SPAN_KIND: 'aws.consumer.parent.span.kind',
+
+  AWS_REMOTE_TARGET: 'aws.remote.target',
+  AWS_REMOTE_DB_USER: 'aws.remote.db.user',
+
+  // Used for JavaScript workaround - attribute for pre-calculated value of isLocalRoot
+  AWS_IS_LOCAL_ROOT: 'aws.is.local.root',
+
+  // Divergence from Java/Python
+  // TODO: Audit this: These will most definitely be different in JavaScript.
+  //   For example:
+  //     - `messaging.url` for AWS_QUEUE_URL
+  //     - `aws.dynamodb.table_names` for AWS_TABLE_NAME
+  AWS_BUCKET_NAME: 'aws.bucket.name',
+  AWS_QUEUE_URL: 'aws.queue.url',
+  AWS_QUEUE_NAME: 'aws.queue.name',
+  AWS_STREAM_NAME: 'aws.stream.name',
+  AWS_TABLE_NAME: 'aws.table.name',
+};
diff --git a/aws-distro-opentelemetry-node-autoinstrumentation/src/aws-opentelemetry-configurator.ts b/aws-distro-opentelemetry-node-autoinstrumentation/src/aws-opentelemetry-configurator.ts
@@ -1,5 +1,5 @@
-//Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-//SPDX-License-Identifier: Apache-2.0
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 import { diag } from '@opentelemetry/api';
 import {