Lightrun tags overview🔗
Tags in Lightrun are user-defined labels assigned to one or more Lightrun agents, providing a structured way to organize, group, and manage agents across your application ecosystem. Tags act as metadata attached to the agent at startup. Agents can have multiple tags, and tags can be shared across multiple agents.
Using tags eliminates the need to target individual agents when applying Logs, Snapshots, or Metrics. Instead, you can operate on logical collections of agents—such as production servers, microservices, teams, or roles—making instrumentation easier to scale and maintain.
Why tags matter🔗
Tags are foundational to large-scale or dynamic debugging because they allow you to:
-
Apply actions to groups of agents
Instead of repeating the same actions on dozens (or hundreds) of servers, you can apply an action once to a tag. All agents with the matching tag receive the action automatically.
-
Support dynamic or ephemeral environments
In autoscaling, containerized, or serverless architectures where instances appear and disappear frequently, tags ensure actions follow the logical group rather than an individual process.
-
Simplify navigation and filtering
Tags make it easier to locate agents by type, environment, or purpose inside the Management Portal.
-
Enable consistent instrumentation
Teams can enforce stable tagging conventions, ensuring consistent observability and debugging practices across deployments.
Tags let you group agents under meaningful names based on shared functionality or deployment context. For example, you might use tags to identify an agent’s location or purpose—such as database, staging, or frontend. Agents can receive any combination of tags based on your organizational needs.
Tags commonly classify agents by:
- Environment (
prod,staging) - Service or microservice (
checkout-service) - Deployment type (
k8s,lambda) - Region (
us-east1) - Application role (
worker,frontend)
Using tags, you can also bind actions to agents before those agents are launched. Once an action is attached to a tag, it is automatically applied to all agents that have that tag, allowing you to instrument applications consistently across environments and services.
How tagging works🔗
Tags are metadata recognized by the Lightrun agent. This metadata is loaded when the agent starts and is used by Lightrun to classify, group, and target agents across your environment.
A running agent supports two types of metadata:
DisplayName
Identifies the specific application instance (for example:server-12,checkout-service,eu-prod-node). Display names are not necessarily unique and should not be relied on to uniquely identify or target actions.
Tags
A set of labels that group the agent according to its environment, role, or deployment context (for example:staging,production,database,QA).
Metadata can be supplied in several ways, such as through metadata files or environment variables. Some runtimes also support setting metadata programmatically. See the runtime-specific agent pages for detailed instructions.
Tags are static metadata. Once the agent starts, its tags remain fixed for the lifetime of the process. To add, remove, or modify tags, you must update the agent’s configuration and restart the application so the new metadata is loaded.
Regardless of the method, tags are treated as metadata by Lightrun and remain unchanged until the agent is restarted.
Assigning actions to tags from the plugin🔗
When adding a Lightrun action (Log, Snapshot, or Metric), you can choose whether to target a single agent or a tag.
Actions assigned to a tag behave as follows:
- Apply to all currently running agents that have the tag.
- Automatically apply to any future agents that start with the tag.
- Observe the action’s Time To Live (TTL), with tag-specific semantics.
TTL behavior
- For individually targeted agents, the TTL begins counting down from the moment the agent accepts the action—whether or not the action ever triggers.
- For tag-targeted actions, the TTL is applied per agent, starting when each agent accepts the action.
- As a result, a tag-targeted action with a 1-hour TTL does not expire one hour after it is created. Instead, the action continues to apply to all matching agents—both existing and newly launched—and each agent keeps the action active for its own one-hour TTL window.
This behavior makes tag-based actions ideal for production debugging, distributed systems, and dynamic or ephemeral workloads, where agents frequently start and stop or are created on demand.
Common use cases🔗
Debug serverless functions🔗
Serverless functions are stateless programmatical functions written for a single purpose. They are hosted on managed infrastructure by cloud computing companies who maintain the infrastructure and code base of the serverless function.
Serverless functions are short-running functions. Suppose a Lightrun action is added directly to an agent created when the serverless function is started. In that case, the action will be deleted when the serverless function disconnects, and you will have to insert the action again when the serverless function restarts.
You can solve this problem by attaching the Lightrun actions to tags instead. Lightrun actions attached to a tag outlive any individual agent. The action is implicitly attached to every agent created whenever the serverless function is started and persists even after the short-running function disconnects.
Debug multiple deployment environments🔗
Most systems include multiple deployment environments, such as Development, Staging, and Production. Tags make it easy to target actions to a specific environment.
Example configuration:
{
"registration": {
"displayName": "<display-name>",
"tags": [
{ "name": "MyComponent-DevEnv" },
{ "name": "MyComponent-Staging" },
{ "name": "MyComponent-Production" }
]
}
}
Suppose you are experiencing a problem in the Production environment but not in any other environment. In that case, you can target that environment with Lightrun actions by applying the actions to the Production tag. A good tagging system can help you target just the set of agents relevant to your investigation.
Get started🔗
To get started, select the tagging instructions relevant to your runtime environment: