AppSignals Functionality - add AlwaysRecordSampler and Utility files, add pr-build workflow

.github/workflows/pr_build.yml

@@ -0,0 +1,59 @@
+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 Contrib Repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - 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: Install
+        run: npm ci
+      - name: Build
+        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

.markdownlint-cli2.jsonc

@@ -0,0 +1,17 @@
+// 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" },
+    "MD012": false // no-multiple-blanks; disabled because common in CHANGELOG.md files
+  },
+  "gitignore": true,
+  "noBanner": true,
+  "noProgress": true
+}

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.

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,61 @@ 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
 ```
+
 ### 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.
 
 

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 \

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",

aws-distro-opentelemetry-node-autoinstrumentation/src/aws-attribute-keys.ts

@@ -1,6 +1,7 @@
 // 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',
@@ -16,7 +17,7 @@ export const AWS_ATTRIBUTE_KEYS: { [key: string]: string } = {
   AWS_REMOTE_DB_USER: 'aws.remote.db.user',
 
   // Used for JavaScript workaround - attribute for pre-calculated value of isLocalRoot
-  APPSIGNALS_IS_LOCAL_ROOT: 'appsignals.is.local.root',
+  AWS_IS_LOCAL_ROOT: 'aws.is.local.root',
 
   // Divergence from Java/Python
   // TODO: Audit this: These will most definitely be different in JavaScript.

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 {

aws-distro-opentelemetry-node-autoinstrumentation/src/aws-span-processing-util.ts

@@ -70,7 +70,8 @@ export class AwsSpanProcessingUtil {
    * @param httpTarget http request target string value. Eg, /payment/1234
    * @return the first part from the http target. Eg, /payment
    */
-  static extractAPIPathValue(httpTarget: string): string {
+  static extractAPIPathValue(httpTarget: string | undefined | null): string {
+    // In TypeScript, `httpTarget == null` checks both null and undefined
     if (httpTarget == null || httpTarget === '') {
       return '/';
     }
@@ -140,10 +141,10 @@ export class AwsSpanProcessingUtil {
   // parent context and returns true if it is a local root.
   static isLocalRoot(spanData: ReadableSpan): boolean {
     // Workaround implemented for this function as parent span context is not obtainable.
-    // This isLocalRoot value is precalculated in AttributePropagatingSpanProcessor, which is assumed
-    // to start before the other processors (e.g. AwsSpanMetricsProcessor)
+    // This isLocalRoot value is precalculated in AttributePropagatingSpanProcessor, which
+    // is started before the other processors (e.g. AwsSpanMetricsProcessor)
     // Thus this function is implemented differently than in Java/Python
-    const isLocalRoot: AttributeValue | undefined = spanData.attributes[AWS_ATTRIBUTE_KEYS.APPSIGNALS_IS_LOCAL_ROOT];
+    const isLocalRoot: AttributeValue | undefined = spanData.attributes[AWS_ATTRIBUTE_KEYS.AWS_IS_LOCAL_ROOT];
     if (isLocalRoot === undefined) {
       // isLocalRoot should be precalculated, this code block should not be entered
       diag.debug('isLocalRoot for span has not been precalculated. Assuming span is Local Root Span.');
@@ -239,6 +240,6 @@ export class AwsSpanProcessingUtil {
     const isParentSpanRemote: boolean = parentSpanContext !== undefined && parentSpanContext.isRemote === true;
 
     const isLocalRoot: boolean = span.parentSpanId === undefined || !isParentSpanContextValid || isParentSpanRemote;
-    span.setAttribute(AWS_ATTRIBUTE_KEYS.APPSIGNALS_IS_LOCAL_ROOT, isLocalRoot);
+    span.setAttribute(AWS_ATTRIBUTE_KEYS.AWS_IS_LOCAL_ROOT, isLocalRoot);
   }
 }

aws-distro-opentelemetry-node-autoinstrumentation/src/register.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 { DiagConsoleLogger, diag } from '@opentelemetry/api';
 import * as opentelemetry from '@opentelemetry/sdk-node';

aws-distro-opentelemetry-node-autoinstrumentation/test/always-record-sampler.test.ts

@@ -0,0 +1,79 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Attributes, SpanKind, TraceState, context, createTraceState } from '@opentelemetry/api';
+import {
+  AlwaysOffSampler,
+  RandomIdGenerator,
+  Sampler,
+  SamplingDecision,
+  SamplingResult,
+} from '@opentelemetry/sdk-trace-base';
+import { expect } from 'expect';
+import { AlwaysRecordSampler } from '../src/always-record-sampler';
+
+let mockedSampler: Sampler;
+let sampler: AlwaysRecordSampler;
+
+describe('AlwaysRecordSamplerTest', () => {
+  beforeEach(() => {
+    mockedSampler = new AlwaysOffSampler();
+    sampler = AlwaysRecordSampler.create(mockedSampler);
+  });
+
+  it('testGetDescription', () => {
+    mockedSampler.toString = () => 'mockDescription';
+    expect(sampler.toString()).toEqual('AlwaysRecordSampler{mockDescription}');
+  });
+
+  it('testRecordAndSampleSamplingDecision', () => {
+    validateShouldSample(SamplingDecision.RECORD_AND_SAMPLED, SamplingDecision.RECORD_AND_SAMPLED);
+  });
+
+  it('testRecordOnlySamplingDecision', () => {
+    validateShouldSample(SamplingDecision.RECORD, SamplingDecision.RECORD);
+  });
+
+  it('testDropSamplingDecision', () => {
+    validateShouldSample(SamplingDecision.NOT_RECORD, SamplingDecision.RECORD);
+  });
+});
+
+function validateShouldSample(rootDecision: SamplingDecision, expectedDecision: SamplingDecision): void {
+  const rootResult: SamplingResult = buildRootSamplingResult(rootDecision);
+  mockedSampler.shouldSample = () => {
+    return rootResult;
+  };
+
+  const actualResult: SamplingResult = sampler.shouldSample(
+    context.active(),
+    new RandomIdGenerator().generateTraceId(),
+    'spanName',
+    SpanKind.CLIENT,
+    {},
+    []
+  );
+
+  if (rootDecision === expectedDecision) {
+    expect(actualResult).toBe(rootResult);
+    expect(actualResult.decision).toBe(rootDecision);
+  } else {
+    expect(actualResult).not.toBe(rootResult);
+    expect(actualResult.decision).toBe(expectedDecision);
+  }
+
+  expect(actualResult.attributes).toEqual(rootResult.attributes);
+  expect(actualResult.traceState).toEqual(rootResult.traceState);
+}
+
+function buildRootSamplingResult(samplingDecision: SamplingDecision): SamplingResult {
+  const samplingAttr: Attributes = { key: SamplingDecision[samplingDecision] };
+  const samplingTraceState: TraceState = createTraceState();
+  samplingTraceState.set('key', SamplingDecision[samplingDecision]);
+  const samplingResult: SamplingResult = {
+    decision: samplingDecision,
+    attributes: samplingAttr,
+    traceState: samplingTraceState,
+  };
+  return samplingResult;
+}