Create tagging rules#
Use the Tagging rules tab to create and manage the rules that generate
custom tags for each query. Routing rules can then match these tags. Tagging
rules are active only when gateway.routing.type=AUTO_TAGS is set. See
Routing and Set the routing method for more
information.
Rule properties#
Each tagging rule has the following properties:
Name: a unique label for the rule. The name has at most 255 characters, and it cannot start with
system..Description: optional text, up to 2,048 characters.
Tag key: the key of the tag that the rule produces. The key has at most 255 characters, and it cannot start with
system.. See Reserved names.Condition: when the rule applies. A condition can check any system tag, and any custom tag that a tagging rule higher in the list produces. Starburst control plane does not check the tag names in a condition. A name that no tag has, for example a typo, saves without an error, and the rule never matches. See Condition syntax.
Action: how control plane produces the tag value. Use one of the following:
Fixed value: the tag value is a literal string that you specify. The value cannot be empty.
Regular expression extraction: control plane extracts the tag value from an existing tag by using a regular expression with a capturing group. The captured group becomes the tag value.
Condition syntax#
A condition is a list of groups. A query matches if it satisfies any group, which is a logical OR. Within a group, all expressions must match, which is a logical AND.
Each expression compares a tag against a value, by an exact string match or by a regular expression.
You can compare these tags:
The system tags
system.request.source,system.request.clientTag,system.identity.user,system.identity.group, andsystem.identity.role.A custom tag that a tagging rule higher in the list produces.
Create a tagging rule#
On the Tagging rules tab, click Create tagging rule.
Enter a name and an optional description.
Build the condition. Click Add condition group to add an OR branch. Within each group, click Add condition to add AND clauses. Select the tag to compare, the operator, and the value.
Enter the Tag key, which is the name of the tag that this rule produces.
Select the action:
Choose Fixed value, and enter the tag value.
Choose Regular expression extraction, select the source tag, and enter a regular expression with a capturing group.
Click Save.
Control plane adds the new rule at the end of the list. To change the order, see Reorder tagging rules.
Reorder tagging rules#
You can reorder tagging rules in the Tagging rules tab. In the sidebar, under Admin, click Routing rules, and then click the Tagging rules tab. Click more_vert options > Re-order rules. Drag and drop the rules in the grid. If another administrator changed the rules after you opened the pane, control plane refuses your reordering. Reload the pane, and reorder again.
Reserved names#
The prefix system. is reserved for system tags. Control plane rejects a rule
name or a tag key that starts with system., in any letter case. For example,
it rejects System.team. Choose another key, for example team.
The system tags are system.request.source, system.request.clientTag,
system.identity.user, system.identity.group, and system.identity.role.
Note
The upgrade to 2026.6.0 renames the system tags source, clientTag,
user, group, and role to the names above, and it rewrites your routing
rules and tagging rules. If a tagging rule produces a tag key that starts with
system., the upgrade stops with an error that lists the rules by ID and name.
Change those rules, and run the upgrade again.
Troubleshooting#
Message |
Fix |
|---|---|
|
Choose a name or a key that does not start with |
|
Choose a name that no other tagging rule uses. |
|
Put the part of the value that you want to extract in parentheses. |