Manage the Node.js agent metadata and tagging¶

Overview¶

Metadata and tags allow you to locate agents more easily; for instance, agents performing the same type of task or running on the same server, or company site. Tags also allow you to group agents with labels for bulk actions across multiple applications (running on the same server, or even on different servers).

Running agents with Node.js allows for two types of metadata to be specified, which can be included in either the metadata file or the application file, or entered as environment variables from the command line.

• displayName - identifies the application instance (for example, server name, company site)
• tags - groups the agents according to context (for example, staging, production, server, QA)

Agent tags¶

Tags are a powerful feature of the Lightrun agent. Applying tags enables you to group agents together with meaningful labels, typically based on common functionality.

For example, you can use tags to identify the location and purpose of each agent: database servers, staging, QA, and so on. You can apply multiple tags to each agent, in any combination. Similarly, adding a single tag to multiple deployments of the same application allows you to add a log action to all of the instances at once.

By applying multiple tags, you can bind actions to an agent even before the agent is launched, and you can apply actions to multiple applications regardless of where they are running. Once an action is bound to a tag, it is implicitly added to all agents that possess that tag.

Out-of-the-box, agents include a single Production tag. You can:

• Create and manage tags

• View all tags

• View tags and their details from the CLI

Managing tags¶

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

Specifying agent metadata and tags within the code¶

The metadata properties can be declared in the start method, as follows.

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

Specifying agent tags using environment variable¶

You can use the LIGHTRUN_TAGS environment variable to set agent's tags dynamically.

For example,

LIGHTRUN_TAGS=Production,Main,EastUS

Specifying agent metadata and tags within a JSON file¶

1. From the relevant server where the agent is installed, go to the agent.metadata.json file (see a typical example here) and open it.

2. Insert the following JSON (replace the dummy parameters and values as required):

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

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>'
        }
   });
   

5. Restart the application.

   Important

   Changes to the agent.metadata.json file do not take effect until the application is restarted.

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

Example¶

The following JSON provides to the displayName parameter a value that indicates a pilot site deployment. Tag labels are included for Production, main, and East US.

{
    "registration": {
      "displayName": "Pilot site",
      "tags": [
        {
          "name": "Production"
        },
        {
          "name": "Main"
        },
        {
          "name": "EastUS"
        }
      ]
    }
}

Additional metadata configuration examples can be found here.

Viewing tags¶

Tags assigned to agents can be viewed from the Management Portal.

To view tag details from the Management Portal¶

Log in to your Lightrun account and navigate to Entities->Tags. The Tags screen appears, similar to the following:

The following details are displayed: