Install the Lightrun Node.js agent¶

The Lightrun agent is at the core of the Lightrun platform. It's the component that communicates requests for runtime observability to your running code, and gathers and relays the requested data back to the Lightrun Server, and eventually the developer's IDE.

Before running the agent, it must be installed on the system where your code to be monitored is running, and its credentials must be declared either inside the application code, as environment variables, or in an agent.config file.

System requirements¶

Supported Node.js versions: 18, 20, 22. Limited support for EOL version: 16. For more information, see the Node.js agent system requirements.

Step 1: Install the Lightrun Node.js agent¶

Lightrun supports installing the Lightrun Node.js agent using one of the following methods:

• A direct installation
• Within a Docker container

Direct installation¶

1. Open a terminal and change to the working directory where your project is located.
2. Install the Node agent by entering npm install lightrun.

Docker installation¶

Docker containers are ephemeral.

If you were to create a shell into a Docker container (by docker exec -it <container-id>, for example) and add the Lightrun files there, they would disappear the next time the container would spin up due to the ephemeral nature of that container.

Instead, install Lightrun by adding it to the underlying Docker image directly, i.e. by "baking" the agent into the image.

This is an example Dockerfile that installs Lightrun with a simple sample application.

FROM node:17.5.0
RUN npm install lightrun
COPY prime_main.js /app/prime_main.js
CMD ["node", "prime_main.js"]

If you prefer passing the credentials via the command line, here's how to do it inside a Dockerfile.

FROM node:17.5.0
RUN npm install lightrun
COPY prime_main.js /app/prime_main.js
CMD ["LIGHTRUN_SECRET=<LIGHTRUN_SECRET>", "node", "--require", "lightrun/start", "prime_main.js"]

Step 2: Add the Lightrun agent to your application¶

1. Open your application file (for example, app.js) and add the following code to the beginning of the file.

       require('lightrun').start({
        lightrunSecret: '<LIGHTRUN_SECRET>',
        metadata: {
         filename: <FULL_PATH_TO_METADATA_FILE>
       }
     });    
   

2. The lightrunSecret parameter is used for authenticating the agent with the Lightrun server.

   To get your <LIGHTRUN_SECRET>, log into the Management Portal, and inspect the Set Up An Agent section, under Getting Started and copy the key.

   If you wish to avoid setting the Lightrun credentials in the application source code you can use environment variable. For more information, see Set credentials via environment variables.

3. [Optional] The metadata block is intended for adding metadata such as display name. Using metadata provides substantial benefits when managing your agents. For more information, see Manage the Node.js agent metadata and tagging for details and examples on constructing the metadata file.

4. Save and close the application file.

Set credentials using environment variables¶

If you wish to avoid hard-coding the Lightrun credentials in the application source code, you can pass them as environment variables when running the application.

1. Verify that the Lightrun agent initialization code at the beginning of your application does not include the lightrunSecret property. Modify the Lightrun agent initialization in your application to exclude the secret key:

   require('lightrun').start();
   

2. Set the LIGHTRUN_SECRET environment variable before starting the application when running your Node.js application, define the LIGHTRUN_SECRET environment variable in the command line before executing the application. For example:

   LIGHTRUN_SECRET=<LIGHTRUN_SECRET> node --require lightrun/start app.js

Run the agent with Express or Koa¶

If you are using Express or Koa frameworks in your application, refer to the instructions linked below:

• Express
• Koa

Additional prerequisites for using the Lightrun Node.js agent¶

Set up Source Maps for TypeScript/JavaScript applications¶

When building and packaging your JavaScript or TypeScript application, the original source code is often processed and transformed. Common transformations include:

• Minification: Reducing code size by removing whitespace, renaming variables, and simplifying expressions (e.g., using UglifyJS or Terser).

• Bundling: Combining multiple files into a single module using a bundler (e.g., Webpack, Rollup).

• Transpiling: Converting modern JavaScript or TypeScript code into an older version for compatibility (e.g., using Babel or TypeScript).

To enable the Lightrun Node.js agent to work with transformed JavaScript code:

• Generate and include Source Maps with your application.

  Source Maps are JSON-based files that map processed code back to the original source, allowing debugging tools to provide accurate stack traces and source references. For instructions on generating Source Maps, refer to the documentation of the tool, such as Webpack, Babel, or TypeScript.

Lightrun support for minified JavaScript code in Node.js¶

In some cases, when building and packaging JavaScript applications their source code is minified/uglified - reducing code size by removing whitespace, renaming variables, and simplifying expressions.

When code is minified, variable names are shortened or replaced, and their original names no longer exist in the minified version. Minification applies to all variables, regardless of scope (e.g., local or global). Minification is usually performed by tools such as Terser and UglifyJS.

In this scenario, the Lightrun Node.js agent operates on the minified code and therefore can only access variables by their minified names. As a result, Lightrun Snapshots display minified variable names along with their values, and Lightrun Logs cannot reference variables by their original names because those names are no longer present in the minified code. To allow logs to reference variables correctly, variable name minification, also known as mangling, must be disabled.

Disable variable name minification for Lightrun Logs¶

Since the Lightrun agent is connected to the runtime environment, it operates on the minified version of JavaScript code, where original variable names are replaced. To ensure Lightrun Logs can reference variables correctly, variable name minification (mangling) must be disabled.

• If using UglifyJS, set the mangle parameter to false.

• If using Terser, disable mangling by adjusting the configuration. The following example shows how to configure Webpack to disable mangling with Terser:

  const TerserPlugin = require('terser-webpack-plugin');
  
  module.exports = {
  optimization: {
      minimize: true,
      minimizer: [
      new TerserPlugin({
          terserOptions: {
          mangle: false, // Do not change variable names
          },
      }),
      ],
  },
  };
  

Running the agent in TypeScript applications¶

As part of Lightrun’s commitment to align with industry standards, we strongly advise using the TypeScript Compiler (tsc) rather than ts-node in production environments. This choice not only ensures a more efficient memory usage and footprint but also avoids generating unnecessary type information.

It's essential to note that when using Lightrun with TypeScript in a production environment, ensure that sourcemap files are packaged with your application and accessible to the Lightrun agent. This step is crucial for seamless debugging and troubleshooting.

1. To start, insert the following code at the start of your application file (for example, index.ts or app.ts).

   import * as lightrun from 'lightrun';
   
   lightrun.start({
   lightrunSecret: '<LIGHTRUN_SECRET>',
   filename: <full_path_to_metadata_file>
   });
   

   The filename parameter is optional. For more information, see Manage the Node.js agent metadata and tagging.

2. In the compilerOptions section of the tsconfig.json file, set the parameter sourceMap to true.

3. From a terminal, run the application.

   node index.js

tsc index.ts

Using the Lightrun Agent in bundled JavaScript applications (ESM / .mjs)¶

If you are using a bundler such as Rollup to generate an ECMAScript Module (.mjs) build, special configuration is required to ensure the Lightrun agent functions correctly. Below are the necessary steps to integrate Lightrun into a bundled JavaScript application:

1. Exclude Lightrun from bundling.

   To prevent issues with the Lightrun agent, configure your Rollup build to treat Lightrun as an external dependency. This ensures that the agent is not bundled into the final output. Modify your Rollup configuration (rollup.config.js) to exclude Lightrun from bundling, for example:

   export default {
   input: "src/index.ts",
   output: {
       dir: "dist",
       format: "esm",
       sourcemap: true,
   },
   external: ['lightrun'], // Do not bundle 'lightrun'
   plugins: [
       nodeResolve(),
       typescript({ module: "ESNext" }), 
       terser({
       mangle: false,
       }),
   ],
   };
   

2. Ensure source maps are generated. Enabling source maps in your Rollup configuration helps maintain visibility into the original source code during debugging. The sourcemap: true option in the output configuration ensures this.

3. Use Default Import for Lightrun Instead of using a package export, import Lightrun as a default module.

   import lightrun from "lightrun";
   

   This approach ensures compatibility with ECMAScript Modules (.mjs) and avoids issues related to package exports.