Tagging Your JVMs
A tag is a user-defined key-value pair associated with a JVM. Unlike instance IDs, tags are not unique: you can add the same tag to several JVMs, and several tags to one JVM. You set the tags of a JVM on the Agent.
Tag Format
Tag keys must begin with a letter. Both keys and values may contain lower and upper case letters, and numbers. These additional characters are also allowed:
ALLOWED_KEY_EXTRA_CHARS = "-_."
ALLOWED_VALUE_EXTRA_CHARS = "-_. :/@" <-- Includes space
Separate the tags with semicolons, and the key and value of each tag with =.
Setting Tags
You can set tags in an environment variable and with a system property on the command line of your application. When you use both, the tags are combined, and when both set the same key, the system property wins. We recommend the environment variable, because it lets the Agent options stay the same for each JVM.
An Admin can also set tags on a Forwarder in the web interface. A machine shows the tags its JVMs declared, overlaid by the tags of the Forwarder that delivered its newest observation, and when both set the same key, the Forwarder’s tag wins. A machine that moves to another Forwarder takes that Forwarder’s tags and drops the old one’s. Keep keys that you set on the Agent distinct from the keys you set on Forwarders, unless you want the Forwarder to override them. See Tagging a Forwarder.
# With an environment variable
export CRS_TAGS="env.tag-1=value:1; env_Tag_2=value 2"
# With a system property
-Dcom.azul.crs.instance.tags="system-prop.tag_1=system prop/value@1; system_prop_tag.2=system prop:value/2"
For example, with the system property on the command line:
java -Dcom.azul.crs.instance.tags="location=west-coast" \
-javaagent:${AGENT_DIR}/ic-agent.jar=api.url=https://<FORWARDER_HOST>:<PORT> \
-jar <MY_APP>.jar
See Installing the Agent for the recommended Agent options.
Recommended Tagging Practice
Tagging should reflect the way you categorize your Java applications. For example, you can use west-coast, east-coast, and so on to distinguish between different availability zones or locations.
We also recommend the AppEnv tag, which identifies the application that a JVM runs and the environment it runs in, such as its staging level and region. Set it, and your other tags, when you first deploy the Agent. You configure the Agent once and rarely change its options later, so tags set from the start describe all the data your JVMs report.
Choosing the AppEnv Format
Choose a format that you can search by its beginning. Put the stable, human-readable parts first and the dynamic, less readable parts last. Then a short prefix such as OrderService. is enough to find every deployment of a service.
Use this order:
-
Static, meaningful parts: application name, staging level, region or data center.
-
Dynamic parts, at the end: build or version identifier, deploy timestamp, commit hash.
<app>.<stagingLevel>.<region>.<buildId>.<deployTimeUTC>
| Format | Example |
|---|---|
Not recommended |
|
Recommended |
|
With the recommended format, each prefix narrows the results:
-
OrderService.finds all deployments of the service. -
OrderService.prod.finds all production deployments of the service. -
OrderService.prod.region1.a1b2c3d4.finds one specific build.
Follow these guidelines:
- Separator
-
Use one that never appears inside a field, for example
.between fields. You can still use-inside names. - Empty fields
-
Keep the field count constant by using a placeholder such as
default,empty, orundefinedinstead of leaving a field empty. - Timestamp
-
Use UTC in a compact format (
yyyyMMddTHHmmssZ), and always make it the last field. - Build identifier
-
A short hash or version of 8 to 12 characters is enough.
- Separate tags
-
Send the static parts (application name, staging level, region) as their own tags too. Then you can filter across services, for example to list all
proddeployments.