Java Agent: Manage metadata and tags🔗

The Lightrun Java 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, Java agents are assigned a single Production tag.

Agent metadata🔗

The Lightrun Java 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>. In Java, agent metadata is typically defined using an agent.metadata.json file or JVM command-line arguments.

From the relevant server where the agent is installed, go to the agent.metadata.json file and open it.

Insert tag names within the tags object (which should be nested in the registration object).

{
  "registration": {
    "tags": [
      {
        "name": "Tag1"
      },
      {
        "name": "Tag2"
      },
      {
        "name": "Tag3"
      }
    ]
  }
}

For example, the following JSON applies the tags MyComponent-DevEnv, MyComponent-Staging, and MyComponent-Production to the relevant agent.

{
  "registration": {
    "displayName": "<DISPLAY_NAME>",
    "tags": [
      {
        "name": "MyComponent-DevEnv"
      },
      {
        "name": "MyComponent-Staging"
      },
      {
        "name": "MyComponent-Production"
      }
    ]
  }
}

Alternatively, you can apply tags using a command-line argument when running the agent with your application.

Multiple tags can be specified using commas. For example, you can set them like this:

java -Dlightrun.registration.tags=myTag1,myTag2,myOtherTag

Save the changes and close the file.
Restart the application.

Important

Changes to this file are not detected until the application is restarted.

Sample use case: Debugging integration tests with tags🔗

Define a tag named MyComponent-IntegrationTest in your metadata file.
Add this tag to agents used for running integration tests.
When an integration test fails, target actions using the MyComponent-IntegrationTest tag to debug the issue.
List actions associated with this tag using the Lightrun CLI:
```
java -jar lightrunc.jar list-actions tag:MyComponent-IntegrationTest
```
The command returns all agents and actions related to integration testing for that component.

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.

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

View tag details in the Lightrun Management Portal🔗

Log in to your Lightrun Management Portal.
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

View tags from the CLI🔗

Install the Lightrun CLI tool.
Run the command java -jar lightrunc.jar list-tags:

For more information, see the CLI reference.

Last update: January 4, 2026

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