Tagging & auto-tagging

Tags are how you make a large estate navigable. In WatchTower15 every tag lives in a tag group (its key or category), and tags can be applied to servers, domains, services, log sources, custom metrics, metric sources and databases — then used to filter dashboards and lists, scope log searches, and target alarms. The agent can also tag hosts automatically from the metadata they already carry, so a freshly-provisioned fleet arrives correctly labelled with no manual work.

Tag groups and tags

A tag is always a value inside a group. The group is the key; the tag is the value. For example, the group Environment might contain the tags production, staging and qa.

Every organisation is seeded with seven system groups that cannot be renamed or deleted:

System group	Scope	Applies to
Organisation-wide	none	any resource type
Server	server	servers only
Domain	domain	domains only
Service	service	services only
Log-Source	log_source	log sources only
Custom-Metric	custom_metric	custom metrics and metric sources
Database	database_instance	databases only

You can create any number of your own groups; custom groups default to the none scope, meaning their tags can be applied to any resource type. A group’s scope is what enforces sensible assignment — a tag in a Domain-scoped group can’t be stuck on a server.

Note

Tag names are unique within a group, so Region:eu and Zone:eu happily coexist. There is no per-tag colour concept — organisation is by group, not by colour.

Naming rule

Group and tag names use only letters, digits, - and _, up to 100 characters:

• a group name starts with a letter, and cannot have the form of a uuid (8-4-4-4-12 hexadecimal characters): Environment, WT15_APP_NAME, team-owner;
• a tag name starts with a letter or a digit: production, 2024, 10-0-1.

A name that breaks the rule is refused under the field with Use only letters, digits, - and _, starting with a letter (up to 100 characters). (for a tag, …starting with a letter or a digit…). Use - or _ where you would put a space: Web-Tier, not Web Tier.

Names created before the rule keep working: they stay as they are, show as they are, and can still be applied to resources. Renaming one, even saving it unchanged, needs a name that follows the rule. Two system groups were renamed to follow it: Log Source is now Log-Source, and Custom Metric is now Custom-Metric. Their tags and everything that uses them are unchanged.

Tags at install

The install command can tag the server it installs: --tag=<group>=<tag>, repeatable up to 20, or WT15_TAGS in a container (see Tags at install). A person chose them, so they are always applied when the server enrols: the profile’s server-led tagging and its include/exclude filter do not touch them. They follow the naming rule, a group or tag that does not exist yet is created, and a tag of another resource type’s group (Domain, Service, Log-Source, Custom-Metric, Database) is refused before anything is installed. They apply at the first enrollment only; removing one later keeps it removed, until the host is installed again with the same command.

Auto-tagging (server-led tagging)

When enabled on a profile, the agent reads identity metadata from the host at enrollment and reports it as tags. The backend find-or-creates the matching groups and tags, so the tag key becomes the group name and the tag value becomes the tag — an AWS instance tag Environment=production becomes group Environment → tag production.

Sources the agent reads

Source	Detected when	Read from
AWS EC2 instance tags	instance metadata is reachable	IMDSv2 (token-authenticated) — the instance tags exposed at /latest/meta-data/tags/instance/
Docker environment	/.dockerenv exists	only the variables of PID 1's environment named WT15_TAG_<Name>, with the prefix removed: WT15_TAG_Teams=Platform becomes the tag Teams: Platform
Kubernetes pod labels	KUBERNETES_SERVICE_HOST is set	the Downward API labels file at /etc/podinfo/labels

All three sources are merged into one flat set of key/value pairs. Where the same key appears in more than one source, the later collector wins — in practice Kubernetes labels take precedence over Docker, which takes precedence over AWS. Metadata lookups are best-effort and time-boxed (a couple of hundred milliseconds for cloud metadata), so a source that isn’t present or is slow is silently skipped and never delays enrollment.

The agent never sends any other container environment variable — not its own settings such as WT15_ORG_TOKEN, and not your application’s. A container’s environment often holds credentials, so only the variables you mark with the prefix are read.

Migrating container tags (agent 1.1.29)

Agents before 1.1.29 turned every variable of PID 1’s environment into a tag. If you relied on that, rename each variable you want as a tag: Teams=Platform becomes WT15_TAG_Teams=Platform. Tags already on your servers stay until you remove them, from (change) on the Tags card of each server’s Info tab.

Keys and values never stored as tags

Whatever source reports them (AWS, Docker or Kubernetes), WatchTower15 never stores a reported tag:

• whose key contains a whole word such as PASSWORD, PASS, PWD, TOKEN, KEY, SECRET, CREDENTIAL, AUTH or DSN (for example DB_PASSWORD, ssh-key-name, api-key; KeyName and Author are fine);
• whose key is one of the agent’s own WT15_* settings, such as WT15_ORG_TOKEN or WT15_PROXY (other WT15_* keys, such as WT15_APP_NAME, are kept);
• whose value holds a URL with a password, such as mysql://user:pass@host/db or postgres://host/db?password=…;
• whose key or value is longer than 100 characters.

Such keys and values are usually credentials, so they are dropped on arrival; the rest of the server’s tags are stored as usual. Tags already stored are not changed.

How reported names are stored

Host metadata rarely follows the naming rule: Kubernetes labels carry dots and slashes, AWS tags colons and spaces. So a reported key or value that breaks the rule is rewritten to fit, not refused. Every run of other characters becomes one -, and - and _ are trimmed from both ends; the case is kept. A key or value that already follows the rule is stored as reported.

Reported by the agent	Stored as
app.kubernetes.io/name = billing-api	group app-kubernetes-io-name, tag billing-api
aws:autoscaling:groupName = web-asg	group aws-autoscaling-groupName, tag web-asg
team:owner = Platform Team	group team-owner, tag Platform-Team
version = 10.0.1	group version, tag 10-0-1
2024 = x	not stored: a group name cannot start with a digit
a.b = 1 and a-b = 2 in one report	a-b : 2 only: both become a-b, and the key that sorts first is kept
Environment = prod and environment = test in one report	Environment : prod only: names are compared without case
x = é	not stored: nothing of the value is left
ModelType with no value	skipped, as an unset AWS tag always was

The checks for keys and values never stored run before and after the rewrite, so a key such as DB+PASSWORD is dropped once it reads DB-PASSWORD.

Groups and tags that agents created before the rule

A group an agent created with a name that breaks the rule, such as app.kubernetes.io/name, stops receiving values: they now arrive in its rewritten twin, app-kubernetes-io-name, which is created beside it. To tidy up:

• before the twin exists, rename the old group to the rewritten name: it keeps its tags and receives the new values;
• once the twin exists, delete the old group.

Deleting the old group before the twin exists keeps that key out, as deleting any group does: the agent does not bring it back under the new name.

Values split the same way. A server that had version : 10.0.1 gains version : 10-0-1 beside it on its next tag report, and a dashboard widget, alarm or custom metric tag rule that uses the old tag does not see the new one. Delete the old tag and point those at the new one. As with groups, deleting the old tag 10.0.1 before 10-0-1 exists keeps that value out; once 10-0-1 exists, it keeps receiving the value.

Keeping tags in sync

Auto-tagging isn’t a one-shot at install. On the system-information cadence the agent re-collects metadata, computes a delta, and reports only new keys or changed values. Updates are additive — the agent adds and updates tags but never removes them from a running host, so a transient metadata blip can’t strip a server’s identity.

A safeguard you should know about

To stop host metadata from polluting the rest of your taxonomy, a server-reported tag whose key names a group of any scope other than server or none (such as Domain, Service, Log-Source, Custom-Metric or Database, or one of your own domain-scoped groups) is ignored, at enrollment and on every heartbeat. It never fails the enrollment: the server’s other tags are stored as usual. Server metadata can only ever create or fill server-appropriate groups.

Putting tags to work

Once resources are tagged you can:

• Filter any list or dashboard by one or more tags: on a list page, pick them in its Tags filter.
• Scope log searches to “every host tagged web-tier” without listing UUIDs (see log search).
• Target alarms and notification policies at a tag rather than at individual resources, so new matching resources are covered automatically.
• Pass a metric source’s tag change down to its metrics. When you change a source’s tags, you are asked whether to apply the change to the metrics it owns, and shown what it would do; only the tags you added or removed change on them (see tagging a source).
• Choose which servers show a custom metric. A metric’s (or its source’s) Servers tagged with all of and Servers tagged with any of lists chart it on every server that carries all of the first tags and at least one of the second, including servers tagged later (see showing a metric on your servers).

Deleting a tag used to show metrics

Deleting a tag removes it from every custom metric’s and metric source’s tag lists. An all of list then asks for fewer tags, so the metric can show on more servers than before; a list left empty adds no condition. Each metric’s or source’s Audit tab records the change.

Related

• Advanced tagging — include/exclude filter rules per profile.
• Fleet & profiles — where server-led tagging is switched on.