Skip to content

Latest commit

 

History

History
80 lines (58 loc) · 3.17 KB

CONTRIBUTING.md

File metadata and controls

80 lines (58 loc) · 3.17 KB
Raw

Contributing to the Lumigo OpenTelemetry Distro for JS

Please note that to ensure compatibility with all supported Node.js versions, the lowest supported Node.js version must be used for any actions that update the package-lock.json file.

For this reason we have included the nvm configuration file .nvmrc set to the lowest supported version, if you're using nvm then just type nvm use to switch to it.

If you don't have nvm installed, make sure you're running the version of Node.js specified in the .nvmrc file before installing the npm dependencies.

Tests

Unit tests are run with:

npm run test:unit

Instrumentation tests are run with:

npm run test:instrumentations

Scope

You can scope the tests to run to specific instrumentations as follows:

INSTRUMENTATION_UNDER_TEST="<instrumentation_name>" npm run test:instrumentations

The instrumentation names are the folder names in test/instrumentations.

You can scope the tests to run a specific version of that specific instrumentation as follows:

INSTRUMENTATION_UNDER_TEST="<instrumentation_name>" VERSION_UNDER_TEST="<instrumentation_version>" npm run test:instrumentations

Supported version files

For local testing, you can disable the post-test update of the tested versions file as follows:

DISABLE_SUPPORTED_VERSIONS_UPDATE="true" npm run test:instrumentations

Contributing an Instrumentation

The js-distro activates numerous opentelemetry instrumentations. The distro validates minor & major versions of packages to ensure stability.

Follow these steps to add an instrumentation from the contrib:

  • add the instrumentation to package.json
  • create a test app
    • under test/instrumentations directory, create a new directory for the instrumentation
    • under test/instrumentations/<your_instrumentation> create an app directory
      • could be something like <your_instrumentation>_app.js and package.json files
        • you can copy the contents of another instrumentation tests and change the fields
    • under test/instrumentations/<your_instrumentation> create a test file: <your_instrumentation>.test.ts
    • under src/instrumentations directory, create a new directory for the instrumentation
      • add tested_versions directory with matching runtimes directories
      • add an arbitrary version to be tested initially
  • run the tests, make sure they are failing (because we haven't activated the instrumentation yet)
  • add the instrumentation to the distro
    • add a file for your instrumentation: <Name>Instrumentation.ts
    • import the instrumentation and activate it
    • run the script: scripts/init_tested_versions.sh to create the directories for the various versions testing
  • run: npm run build
  • run the tests again, this time they should pass
  • add the package to the README.md Supported packages table
    • leave the tested versions columns empty
  • open a pull-request 🙌

pull-request for example