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.

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¶

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¶

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
   

tsc index.ts

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"]

Running 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