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, and system.identity.role.

  • A custom tag that a tagging rule higher in the list produces.

Create a tagging rule#

  1. On the Tagging rules tab, click Create tagging rule.

  2. Enter a name and an optional description.

  3. 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.

  4. Enter the Tag key, which is the name of the tag that this rule produces.

  5. 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.

  6. 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

Rule name must not start with reserved prefix 'system.' or Tag key must not start with reserved prefix 'system.'

Choose a name or a key that does not start with system..

Rule with name '<name>' already exists

Choose a name that no other tagging rule uses.

Match pattern expression must contain at least one capturing group

Put the part of the value that you want to extract in parentheses.