@appsignal/nodejs

@appsignal/nodejs

The core AppSignal for Node.js library.

See also the mono repo README for more information.

Installation

First, sign up for an AppSignal account and run our automated install tool, which will install @appsignal/nodejs and any relevant integrations to your project:

npx @appsignal/cli install

You can also skip the automated tool and add @appsignal/nodejs to your package.json on the command line with npm/yarn:

yarn add @appsignal/nodejs
npm install --save @appsignal/nodejs

Alternatively, you can manually add the @appsignal/nodejs package to your package.json. Then, run yarn install/npm install.

Installing the AppSignal for Node.js integration builds a native extension. In order to compile it, macOS users will need to install the Xcode Developer Tools. Linux users will need the dependencies outlined here. Windows is not supported.

You can then import and use the package in your bundle:

const { Appsignal } = require("@appsignal/nodejs");

const appsignal = new Appsignal({
  active: true,
  name: "<YOUR APPLICATION NAME>"
  pushApiKey: "<YOUR API KEY>"
});

// ...all the rest of your code goes here!

In order to auto-instrument modules, the Appsignal module must be both required and initialized before any other package.

Extension

This package also contains the C++ extension, and the install script for the agent. The native extension is a bridge between the Node.js runtime and our agent.

Changelog

2.4.0

Added

• 60d7980 minor - Add OpenTelemetry span processor for the mysql and mysql2 packages. These are experimental integrations and require additional set up to integrate with OpenTelemetry.

• 9cd1c8b patch - Add config options for disabling default instrumentation like HTTP, HTTPS, PostgreSQL (pg package) and Redis (node-redis package).

  The following configuration options have been added:

  • instrumentHttp
  • instrumentPg
  • instrumentRedis

  By default these configuration options are set to true, which means the instrumentation is active by default. If you want to disable one of these instrumentations, configure it by setting the configuration option to false.

  // appsignal.js
  // Brief example, see our docs for a full example
  
  const appsignal = new Appsignal({
    instrumentRedis: false // Disables the node-redis package instrumentation
  });
  

• 3959858 patch - Add OpenTelemetry node-redis and ioredis query sanitizers. We recommend using these sanitizers to ensure no sensitive data is sent in query statements. Add the sanitizer to the dbStatementSerializer config as demonstrated below.

  // tracing.js
  // Add the RedisDbStatementSerializer import
  const { RedisDbStatementSerializer } = require("@appsignal/nodejs");
  const { RedisInstrumentation } = require("@opentelemetry/instrumentation-redis");
  const sdk = new opentelemetry.NodeSDK({
    instrumentations: [
      new RedisInstrumentation({
        // Configure the AppSignal RedisDbStatementSerializer to sanitize queries
        dbStatementSerializer: RedisDbStatementSerializer
      })
    ]
  });
  

  The same can be done for the ioredis instrumentation:

  // tracing.js
  // Add the IORedisDbStatementSerializer import
  const { IORedisDbStatementSerializer } = require('@appsignal/nodejs');
  const { IORedisInstrumentation } = require('@opentelemetry/instrumentation-ioredis');
  const sdk = new opentelemetry.NodeSDK({
    instrumentations: [
      // Add the IORedisInstrumentation
      new IORedisInstrumentation({
        // Configure the AppSignal IORedisDbStatementSerializer to sanitize queries
        dbStatementSerializer: IORedisDbStatementSerializer
      })
    ]
  });
  

Changed

• ee1ea8b patch - Use the OpenTelemetry SpanProcessor interface to build our own SpanProcessor. We previously copied the SpanProcessor code into our package, but instead we now use the OpenTelemetry interface directly. This should make our processor match the expected type better.

• 4e58a73 patch - Bump agent to v-0b43802.

  • Add redis and ioredis OpenTelemetry instrumentation support.

• 01c25d3 patch - Bump agent to v-1a8ac46

  • Support OpenTelemetry root span import.
  • Support OpenTelemetry HTTP instrumentation.
  • Support OpenTelemetry Express instrumentation.

Fixed

• 8e45eba patch - Fix the ScopeManager.active() function returning closed spans.
• 6d2e2d5 patch - Do not transfer closed spans for new async contexts in the ScopeManager. Rather than relying on ScopeManager.active() and ScopeManager.root() to make sure the span is not already closed, also make sure it's not closed when transferring spans around between async contexts.