Skip to content

Metadata and Tags


Running agents with Python 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 deployment 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 application 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.


  • Define a tag in the metadata file named Integration.
  • Add that tag to relevant agents where you're running your application for integration testing.
  • Set integration tests to execute with the Integration tag in order to debug an integration test failure.
  • List actions by tag from the CLI with java -jar lightrunc.jar list-actions tag:Integration.

‚Äč The output lists all actions you inserted for integration testing across all of your agents.

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

Managing tags

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

Specifying agent metadata and tags within a JSON file

  1. From the relevant server where the agent is installed, create a file named agent.metadata.json file 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" 
    !!! info With no entered value, displayName will show the hostname of the machine running the application and the application's process identifier.

  3. Open your application file (for example,,

  4. Within the enable() function, include a reference to the metadata JSON file.

     import lightrun
     lightrun.enable(agent_config="/path/to/agent.config" , agent_regmetadata_file="/path/to/agent.metadata.json")
    except ImportError as e:
      print("Error importing Lightrun: ", e)
  5. Restart the application.


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


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"

When running your Python application from the command line, you can pass the metadata file as an environment variable using either:

python -m lightrun --server_url=https://<COMPANY_SERVER_URI> --company=<COMPANY_NAME> --company_key=<COMPANY_SECRET> --agent_regmetadata_file=agent.metadata.json --


python -m lightrun --com_lightrun_server=https://<SERVER_DOMAIN>/<COMPANY_NAME> --company_key=<COMPANY_SECRET> --agent_regmetadata_file=agent.metadata.json --

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:

Manage tags

The following details are displayed:

Column Description
Name The name of the tag.
Actions The list of actions currently attached to this tag.
Agents The list of agents to which this tag has been associated.

Last update: November 24, 2021