The Elastic APM Node.js agent is implemented in vanilla JavaScript, but includes TypeScript types. This document shows how to integrate the APM agent with your TypeScript project.

A small, complete example project can be found here.

Installationedit

Add elastic-apm-node as a dependency to your application, and possibly @types/node as a dev-dependency for type checking:

npm install --save elastic-apm-node
npm install --save-dev @types/node 

tsconfig compiler optionsedit

The TypeScript authors strongly recommend that you use the "esModuleInterop": true option in your "tsconfig.json". In case you do not, then the "default" import of the agent will not work, so instead of using import apm from 'elastic-apm-node/start' or similar, you will have to use:

import * as apm from 'elastic-apm-node/start' // if using esModuleInterop:false

Currently the Elastic APM Node.js agent does not support instrumenting ECMA Script modules (ESM), so for full APM support you will need to tell TypeScript to generate JavaScript using CommonJS modules via the "module": "commonjs" compiler option.

// tsconfig.json
{
  "compilerOptions": {
    "module": "commonjs",
    "esModuleInterop": true,
    "moduleResolution": "node"
    // ...
  }
}

The current TypeScript recommended tsconfigs for node use options that work with the APM agent.

Starting the agentedit

For the APM agent to be able to automatically instrument modules it must be started before you import other modules. This means that you should probably import and start the agent in your application’s main file (usually index.js, server.js or app.js). One way to do this is as follows.

import 'elastic-apm-node/start' 

// Application code starts here.
// ...

Pay special attention to the possible surprise gotcha where the TypeScript compiler can throw away your import in the generated JavaScript.

Next stepsedit

The APM agent will now trace your application, monitor performance, and record any uncaught exceptions. Refer to the following documentation to configure and use the APM agent.

If you can’t get the Node.js agent to work as expected, please follow the troubleshooting guide.