Python Agent: Manage metadata and tags🔗

The Lightrun Python 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 more information on Lightrun tags, see Lightrun tags overview.

By default, Python agents are assigned a single Production tag.

Agent metadata🔗

The Lightrun Python agent supports two metadata properties:

• displayName — Identifies the deployment instance (for example, server name, company site).
• tags — User-defined labels that group agents by deployment context or purpose (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 Python, agent metadata can be defined in application code, in an agent.metadata.json file, or using environment variables.

Add agent metadata and tags within the code🔗

You can define agent tags programmatically by passing the metadata_registration_tags argument to the lightrun.enable() call:

lightrun.enable(
    company_key="<COMPANY_SECRET>",
    metadata_registration_tags='[{"name": "MyComponent-Production"}, {"name": "EastUS"}]'
)

Add agent tags using environment variables🔗

You can dynamically assign tags using the LIGHTRUN_TAGS environment variable.

For example:

LIGHTRUN_TAGS=MyComponent-Production,Main,EastUS

This method is useful for CI pipelines or environment-based deployments.

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

1. On the server where the agent is installed, create and open a file named agent.metadata.json.

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

   Note that if no displayName value is provided, Lightrun automatically uses the hostname of the machine and the application’s process identifier.

3. In your application file (for example, main.py or app.py), reference the metadata file when enabling the agent:

   try:
       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)
   

4. 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 consistently across multiple Python agents.

Tag management🔗

Once tags are defined and associated with agents, you can manage and monitor them from the Lightrun plugins and the 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 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 agents reconnect.

Modify the cleanup interval🔗

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