Skip to content

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.

Version Support

Supported Node versions: 18, 20, 22. Limited support for EOL version: 16. If you require support for earlier versions, please reach out and let us know!

System requirements

Please check the Node.js agent system requirements here.

Lightrun can be installed both directly and inside of 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.
  3. Open your application file (for example, app.js) and add the following code at the beginning of the file.

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

    Getting Company Details

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

    Note

    The metadata block with the filename parameter is optional; the agent runs perfectly well without them. Using metadata nevertheless provides substantial benefits when managing your agents. See here for details, with examples, on constructing the metadata file.

  4. Enter the parameter values for lightrunSecret and (optionally) the metadata_file.

  5. Save and close the application file.

  6. From a terminal, enter the command to run your application (for example, node index.js or npm start).

Alternative method - Providing agent credentials as environment variables

Note

This method works only for Linux and MacOS.

Info

Although using this method allows you to avoid hard-coding your credentials into the source code, you must enter them in the run command every time your application is launched with the agent.

Instructions

  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.

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

     require('lightrun').start();
    
  4. Save and close the application file.

  5. From a terminal, enter the command to run your application, with the environment variables declared before the node command.

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

Running the agent in TypeScript applications

Important

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

It's essential to note that when utilizing Lightrun for TypeScript in a production setting, you must include sourcemap files on the server where your production software is deployed. This step is crucial for seamless debugging and troubleshooting.

Instructions

  1. 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>
    });
    

    Info

    The filename parameter is optional. See here for details on constructing the metadata file.

  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
    

Important

Unless you are working within a TypeScript framework, such as Express or Koa, for the above procedure, you must compile the TypeScript application file.

tsc index.ts

Following compilation, another file is created that has the same name as your TypeScript application, but with the .js extension.

Tip

You can choose to provide the agent's credentials as environment variables, when running your application from the command line, instead of inserting them in the application file, as explained above (note this does not work in MS Windows).

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, we suggest you 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 dummy 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"]

Important

Installing Lightrun in this fashion does not absolve you of the need to require Lightrun in your application. Please make sure to add Lightrun as an require to your application file.

Running the agent with Express or Koa

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


Last update: December 4, 2024