Node.js Agent: Manage metadata and tags🔗

The Lightrun Node.js agent allows you to attach metadata—such as a display name and tags—to each running agent instance for identification and targeting purposes. Metadata and tags help you locate agents more easily and group them for bulk actions across multiple applications and environments. For information on Lightrun tags, see Lightrun tags overview.

By default, Node.js agents are assigned a single Production tag.

Agent metadata🔗

The Lightrun Node.js agent supports two metadata properties:

• displayName: Identifies the application instance (for example, server name, company site).
• tags: User-defined labels that group agents by deployment context (for example, production, staging, QA).

Metadata is loaded when the agent starts and remains fixed for the lifetime of the process.

Methods for adding metadata🔗

For consistency and easier targeting, Lightrun recommends using structured tags that include the component and context, such as <Component>-<Environment> or <Component>-<Purpose>.

Metadata and tags are specified within the code or in the agent.metadata.json file.

Add agent metadata and tags within the code🔗

You can define metadata directly when starting the Lightrun agent in your application:

require('lightrun').start({
    company: '<COMPANY_NAME>',
    lightrunSecret: '<LIGHTRUN_SECRET>',
    metadata: {
        registration: {
            displayName: "Pilot site",
            tags: ['MyComponent-Production', 'Main', 'EastUS']
        }
    }
});

Add agent tags using environment variables🔗

You can dynamically assign tags using the LIGHTRUN_TAGS environment variable.

For example,

LIGHTRUN_TAGS=Production,Main,EastUS

Add agent metadata using an agent.metadata.json file🔗

1. On the server where the agent is installed, open the agent.metadata.json file (see a typical example here).

2. Define the metadata in the following format.

    {
      "registration": {
        "displayName": "<DISPLAY_NAME>",
        "tags": [
          {
            "name": "<Tag1>"
          },
          {
            "name": "<Tag2>"
          },
          {
            "name": "<Tag3>"
          }
        ]
      }
    }
   

   For example, the following JSON applies the tags MyComponent-DevEnv, MyComponent-Staging, and MyComponent-Production:

   { "registration": { "displayName": "Pilot site", "tags": [ { "name": "MyComponent-DevEnv" }, { "name": "MyComponent-Staging" }, { "name": "MyComponent-Production" } ] } }

3. Open your application file (for example, app.js).

4. At the top of the file, within the start method, include a reference to the metadata JSON file.

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

   Alternatively, you can use the environment variable LIGHTRUN_METADATA_FILE to pass the path for the metadata JSON file.

5. Restart the application.

   Important

   Changes to the agent.metadata.json file are not detected until the application is restarted.

Sample use case: Debugging integration tests with tags🔗

1. Define a tag named MyComponent-IntegrationTest in your metadata configuration.

2. Add this tag to agents used for running integration tests.

3. When an integration test fails, target actions using the MyComponent-IntegrationTest tag to debug the issue.

4. Filter agents or list actions associated with this tag using the Lightrun plugins or CLI.

This approach allows you to debug integration test failures across multiple agents consistently.

Tag management🔗

Once tags are defined and associated with agents, you can manage and monitor them from the Lightrun plugins and Lightrun Management Portal.

Manage unused tags🔗

You can manually delete unused tags from the Lightrun plugin UI or from the Lightrun Management Portal.

A tag cannot be deleted if it is currently associated with an agent or an action.

Starting with version 1.74, the Auto-cleanup unused tags parameter was introduced and is enabled by default. When enabled, unused tags are automatically removed after 1 day to keep the tags list clean in large deployments. Tags are automatically regenerated when the agents reconnect.

Modify the cleanup interval🔗

You can modify the cleanup interval or disable the parameter.

1. Log in to the Lightrun Management Portal.
2. Navigate to Settings → Compliance → Service Configuration.
3. Under Other, adjust the Auto-cleanup unused tags interval (for example, 1 week), or disable the feature.
4. Click Save Changes.

View tag details in the Management Portal🔗

1. Log in to your Lightrun Management Portal.

2. Navigate to Entities > Tags.

   

   The Tags page displays the following information:

   Parameter	Description
   Name	Tag name
   Actions	Actions currently attached to the tag
   Agent Number	Number of agents associated with the tag