observability-node

observability-node

Node.JS Observability Library (Telemetry Wrapper)

• structured logging
• application performance monitoring and tracing, currently provided through NewRelic
• metrics reporting, currently provided through hot-shots

Installation

Install the package

npm install --save @procore/observability-node

WIP

Once this is installed

• emitted logs will be structured according to Procore's spec
• requests will generate a canonical log message and metrics
• unhandled errors will automatically be captured and reported

Usage

WIP

Configuration

@procore/observability-node can be configured by

• providing a custom config object when calling observability.Logging()
• providing a custom config object when calling observability.Metrics()
• providing a service name string when calling observability.setupTracing()

The following settings are available

// Logging Config
observability.Logging({
  // Update to change verbosity
  // Default info
  LOG_LEVEL: "error" | "warn" | "info" | "debug",

  // If set to pretty, logs will be pretty printed over multiple lines
  LOG_FORMAT: "pretty" | "default"

  // If set to none, structured logs will omit static service metadata.
  LOG_METADATA: "none" | "default",
})

// Metrics Config
observability.Metrics({
  // If set to `datadog`, metrics will be reported to datadog
  // Otherwise metrics will be printed to the logs (at DEBUG level)
  METRICS_HANDLER: "datadog" | "logs",

  // Required if METRICS_HANDLER=datadog, otherwise ignored
  DATADOG_AGENT_HOST: ""
})

// Traces Config
observability.setupTracing('Application-Name')

Development

Note: For more information about contributing to this template, see CONTRIBUTING

To work on this repo, clone it down and then run

$ ./bin/setup

To report coverage run

$ npm run test:cov

When developing, we recommend re-running specs for changed files

$ npm run test:watch

Committing Changes

Conventional Commits

This repo makes use of the Conventional Commits spec to achieve an auto-generated CHANGELOG, to support automatic semantic versioning, and to maintain a more easily readable commit history. Commits are linted using Commitlint in a pre-commit hook, which will fail commits that do not follow the configured rules.

The current rule configuration is set using @commitlint/config-conventional; please refer to the library's #Rules section for details.

Generating Commits

You may want to use a wizard for generating your commits. This repo includes commitizen which will walk you through generating a Conventional Commit. You can invoke this tool by running npx cz. If you set PREPARE_COMMIT_MSG to true in your environment, commitizen will run automatically each time you git commit. This can cause odd behavior when doing things like amending or rebasing commits. You can always quit the wizard with Ctrl-C.

Publishing

We strongly recommend using the script npm run cm which will help determine version and provide proper formatting.

We use semantic-release to manage releases and publishing to NPM. Semantic Release relies on the project commit history to create release notes and determine the next version. Merges into the main branch will run semantic-release, but semantic-release will publish a release only for certain commit types.

Specifically, the following commit types do not trigger a release:

• doc (documentation changes)
• build(deps-dev) (development dependency changes, typically version bumps by dependabot)
• chore (misc changes tools and libraries that don't effect user-facing library code)
• test (changes to specs/testing resources)
• no-release (Or commits otherwise labeled to not release with [skip release] or [release skip])

The specific steps that run can be found in this section of the library's documentation.

Details about how commit types are mapped to versioning can be found in the commit analyzer documentation.

When a PR is merged, each of its commits that is releasable will be added to the release notes automatically. The release version will be determined by the commit whose type represents the highest SemVer value.

E.g. in a PR with 3 commits of type fix, chore, and feat, the release version resulting from a rebase merge will be a minor version bump (due to feat). The fix commit will be listed under bugfixes, and chore will be ignored.

If the PR is squash-merged, the fix commit will be absent from the changelog.

Pre-releases

When making a pre-release, merge your changes into the alpha branch. When the pre-release is finalized and you are ready to publish a full release, merge alpha into main.