In k6, how does exec.vu.tags set a metric tag mid-iteration, and which values does it accept?

## The object In k6 v2, `k6/execution` exposes four namespaces — `instance`, `scenario`, `test` and `vu` — and `exec.vu.tags` is a live view of the tag set the currently running VU stamps onto everything it emits. It is not a snapshot you pass somewhere; assigning to a property of it changes the VU's tag set immediately. ```javascript import exec from 'k6/execution'; import http from 'k6/http'; export default function () { exec.vu.tags.flow = 'checkout'; http.get('https://shop.test/cart'); // tagged flow=checkout http.get('https://shop.test/pay'); // tagged flow=checkout delete exec.vu.tags.flow; http.get('https://shop.test/health'); // no flow tag } ``` The same object is also reachable as `exec.vu.metrics.tags`, with a sibling `exec.vu.metrics.metadata` for non-indexed values. Reading works too: `exec.vu.tags['scenario']` returns the current scenario name, because system tags live in the same set. ## Why it exists The per-call tag arguments — a `tags` object in an HTTP params argument, the third argument to `check()`, the second argument to a custom metric's `.add()` — each tag exactly one thing. When a dimension has to span a stretch of an iteration, repeating it at every call site is both noisy and easy to get wrong. `exec.vu.tags` is the mechanism for a value that: - is only known at runtime, such as which of several data-driven paths this iteration took; - has to cover several calls, including calls made inside helper functions you did not want to thread a tags argument through; - has to cover nested `group()` calls, so that a container dimension survives the group path changing underneath it. ## The value rule k6 accepts **string, boolean and number** values and stores their string form. Anything else throws immediately: ```javascript exec.vu.tags.team = { id: 7 }; // TypeError: invalid value for metric tag 'team': only String, Boolean and // Number types are accepted as a metric tag values ``` This is the same rule that governs `tags` in an HTTP params object and the tag argument to `check()` and `.add()` — one shared conversion path, one shared error. There is no JSON serialisation fallback, so a nested object has to be flattened into separate tags yourself. ## The lifetime trap This is the part that separates people who have used it from people who have read about it. **k6 rebuilds a VU's tag set when the VU is activated for a scenario, not at the start of every iteration.** On activation, k6 seeds the tag set from the test-wide run tags plus any scenario-level tags and clears the metadata. Between iterations of that same activation it only refreshes the `iter` value. The consequence: a tag you assign in one iteration is **still set in the next iteration** of the same VU. A conditional assignment like `if (isNewUser) exec.vu.tags.cohort = 'new';` leaks `cohort=new` into every subsequent iteration that VU runs, including the ones for returning users. The fix is to delete it, or to assign on both branches: | Pattern | Result | | --- | --- | | Assign, never delete | tag persists for every later iteration of that VU | | Assign on one branch only | earlier value leaks into later iterations | | Assign, then `delete` before the iteration ends | scoped to the stretch you intended | | Assign unconditionally on every branch | overwritten each iteration, no leak | ## Interaction with groups and system tags - Setting a key that is also a system tag overwrites it for that VU. `exec.vu.tags.name = 'X'` behaves like a manual `name` tag; it is legal and occasionally useful, but surprising to a reader. - Do not assign to `group` by hand. `group()` reads the current `group` tag, appends `::name`, and restores the old value when the callback returns; a hand-set value gets folded into the path. - A tag set from code is an ordinary indexed tag, so a sub-metric selector of the form `metric{key:value}` matches it exactly as it would a system tag. That is usually the whole reason for setting one. ## Practical rules 1. Assign and `delete` in the same function, so the scope is visible in one screen. 2. Prefer a per-call `tags` argument when the dimension covers one call — it cannot leak. 3. Keep the value set small; a tag set per iteration from unbounded data is the fastest way to push a run past k6's 100,000-time-series warning. 4. Remember it is per VU: two VUs running the same code hold independent tag sets.