The section header carries three small controls to the right of the title rule:

Rows are added by Add Watch (header ＋, Ctrl+Shift+W, the Watch-tree context menu, the editor context menu, or double-clicking the empty area below the last row), edited inline via double-click or F2, removed via Delete / Backspace or the － button, and reordered by drag. The tree supports Ctrl / Shift-click to extend the selection so a bulk delete removes every selected top-level row in one shot. The right-click context menu offers Add Watch; on a watch root also Duplicate Watch (Ctrl+Shift+D), Edit Watch (F2), Copy Value (Ctrl+Shift+C), Remove (Delete), and Remove All Watches (Ctrl+Shift+K); on a sub-row only Add Watch and Copy Value. Committing an empty spec removes the row. The Value column is always read-only.

The Wireshark-specific behaviors:

Expansion state is kept only for the current session; watches open collapsed the next time you start Wireshark.

The chapter intro called out that a Watch row whose contents look like a plain variable path gets the path-watch fast path — selection sync with the Variables tree, sharper error chrome, cheaper re-resolution, and so on. This subsection nails down what "plain variable path" means.

A path watch is one identifier followed by any number of .name or [key] segments, optionally qualified by a section prefix. Anything else — method calls, arithmetic, function calls, comparisons, table constructors — is routed to the expression watcher (see Section 14.6.3, “Expression patterns”) automatically; there is no error and no UI toggle.

Examples.

-- A local in the current frame (a parameter of printer.dissector):
Locals.pinfo

-- A field on that local userdata:
pinfo.src

-- An upvalue table indexed by an integer key (printer.lua's
-- per-frame cache):
Upvalues.sessions[1]

-- A nested field reachable through the same path:
Upvalues.sessions[1].src

-- Hex and boolean keys (printer.lua's lookup tables):
Upvalues.opcode_names[0x10]
Upvalues.handshake[true]

-- An explicit Globals path (a Lua-side global function):
Globals.get_version

-- Unqualified — tried in locals, then upvalues, then globals:
sessions                  -- finds the upvalue
get_version               -- finds the global

-- _G aliases:
_G.get_version            -- same as Globals.get_version
_G                        -- same as Globals (whole section)

Prefixes. A Watch spec may start with one of the three debugger section prefixes:

The exact tokens Locals, Upvalues, and Globals (with no trailing .) are also accepted and select the whole section’s contents. _G is aliased to Globals and _G. to Globals.. A bare path with no prefix (including a lone identifier) is resolved in Locals, then Upvalues, then Globals, in that order, and the UI rewrites the tooltip with the section that actually matched.

A common confusion: a file-scope local like printer.lua’s `local sessions = {} is an upvalue of any function defined in the same chunk, not a global. So the path is Upvalues.sessions, not Globals.sessions. Globals are names that were assigned without local (or that come from the standard library, such as print, tostring, Field, or get_version).

What’s allowed inside [ ]. Bracket subscripts mirror Lua’s own short-literal syntax and accept:

The decoded key is looked up exactly the way Lua itself indexes a table, so any key type that a Lua table can carry is reachable. For userdata (Wireshark class instances, e.g. Proto, Field), a bracket key must be a string and is looked up as an attribute name, the same as ud.name.

Anything that doesn’t match the grammar above is routed to the expression watcher. See When the path-watch fast path doesn’t apply in Section 14.6.3, “Expression patterns” for the full list of shapes that go that way.

watch   := section "." body
         | section
         | body
section := "Locals" | "Upvalues" | "Globals"
body    := ident ( "." ident | "[" key "]" )*
ident   := [A-Za-z_] [A-Za-z0-9_]*
key     := integer | boolean | string
integer := "-"? ( decimal-digits | ("0x" | "0X") hex-digits )
boolean := "true" | "false"
string  := '"' ( char-except-"\"\\ | escape )* '"'
         | "'" ( char-except-'\\ | escape )* "'"

The mini-blocks below are the cheat sheet for what kinds of Lua a Watch row accepts when the spec isn’t a plain path. Each is paste-and-run — drop a line into the Watch column and the row updates on every pause. Names like pinfo, tvb, and tree refer to whatever locals the current dissector exposes; substitute as needed.

Format a value the way columns do.

-- Address as the canonical column string:
tostring(pinfo.src)

-- Endpoints in one row:
tostring(pinfo.src) .. " -> " .. tostring(pinfo.dst)

-- TCP/UDP port pair:
string.format("%d -> %d", pinfo.src_port, pinfo.dst_port)

-- A flag byte rendered like Wireshark does:
string.format("0x%02x", tvb:range(13,1):uint())

Use tostring() and string.format() exactly as you would in a dissector callback. Wireshark’s userdata classes (Address, Pinfo, Tvb, …) expose conversion via the standard __tostring metamethod, so tostring(pinfo.src) is the canonical form — they do not offer a :tostring() method. The :method syntax still works on string locals (name:upper()).

Compute a derived number or boolean.

-- Bytes left to consume:
tvb:len() - offset

-- "Beyond frame N":
pinfo.number > 100

-- "Targets HTTP":
pinfo.dst_port == 80

-- First-pass dissection?
not pinfo.visited

-- Seconds since the previous captured frame, negated:
-pinfo.delta_ts

Inspect a derived value without expanding the underlying userdata or table. Standard arithmetic, comparison, and unary operators all work. Note that there is no __len metamethod on Tvb / TvbRange, so use tvb:len() rather than #tvb.

Pick out a bit field.

-- (Offset 13 here is illustrative; substitute whatever byte
--  position is meaningful for the protocol you're inspecting.)

-- High bit of that byte:
tvb:range(13, 1):uint() & 0x80

-- Upper nibble of the same byte:
(tvb:range(13, 1):uint() >> 4) & 0x0F

Lua 5.3+ bitwise operators on integers (Wireshark’s floor). The bundled bit library is also available if you prefer the named-function form (bit.band(tvb:range(13, 1):uint(), 0x80)).

Read a previously-constructed Field.

-- printer.lua defines `ip_src_F` and `tcp_flags_F` at file scope:
ip_src_F()
(tcp_flags_F()).value

Calling a Field returns the most recent FieldInfo for the current packet — handy when the local you want isn’t in scope but the protocol field is. If the field is not present in the current packet (e.g. tcp_flags_F() on a non-TCP frame) the call returns nil, so (tcp_flags_F()).value errors with attempt to index a nil value; guard with tcp_flags_F() and (tcp_flags_F()).value when the protocol may be missing. Field.new(…​) itself cannot be called from a watch: extractors can only be constructed at script load, before any dissector or tap callback runs (the watch evaluates inside that callback). Define the Field once at file scope, the way printer.lua does, and reference it by name in the watch.

Index a table by a non-path key.

-- Hyphenated key in _G (no such global by default; the watcher
-- just returns nil):
_G["my-shared-state"]

-- A subtable indexed by the current frame number:
sessions[pinfo.number]

-- A userdata stringified for use as a stable table key:
last_seen[tostring(pinfo.src)]

-- Non-integer / boolean keys:
sessions[1.5]
handshake[true]

Path watches accept identifiers and short integer / boolean / string keys; expressions accept anything Lua tables accept, including hyphenated names, non-integer numbers, booleans (including false), or a long-literal [[...]] string (e.g. state[ [[multi-line key]] ]).

Userdata as a table key. Lua hashes table keys by raw identity for userdata, ignoring __eq. Wireshark attribute getters like pinfo.src and pinfo.dst return a fresh userdata wrapper on each access, so t[pinfo.src] = … followed by t[pinfo.src] always misses on the second read. Key by a stable representation instead — tostring(pinfo.src) for an Address, pinfo.number for per-frame uniqueness — which is why last_seen above keys by tostring(pinfo.src).

Build an ad-hoc table.

-- A tuple of locals, expandable in the Watch tree:
{pinfo.src, pinfo.dst, pinfo.dst_port}

-- All return values of a multi-valued function:
{ string.find(tostring(pinfo.src), "(%d+)%.(%d+)") }

Expandable in the Watch tree without polluting the dissector with a temporary local. The second form captures every return value of a multi-valued function — see Capture all return values below.

Inspect type or metatable.

-- "userdata", "table", "string", ...:
type(pinfo.src)

-- Class-ish name on a Wireshark userdata
-- (Address, Pinfo, Tvb, ...):
getmetatable(pinfo.src).__name

-- Full metatable contents when something behaves unexpectedly:
getmetatable(tree)

Useful before assuming what a value is, especially when a row reports an unexpected attempt to index a nil value. Note that Wireshark userdata raise an error when indexed with an unknown attribute — pinfo.src.__name does not fall back to nil, so go through getmetatable(…​) for the class name.

Predicates and "tell me when X changes".

-- Is this the first dissection of this frame?
not pinfo.visited

-- "Seen" or "first time" — flips colour as soon as it changes:
pinfo.visited and "seen" or "first time"

-- Fail loudly the moment an invariant breaks:
assert(tvb:len() >= 20, "short IP header")

-- "Frame is more than 30 s after the previous one":
pinfo.delta_ts > 30

A failing assert (or a bare error("…​")) turns the row red with the user-supplied message in the Value column — a lightweight alternative to a conditional breakpoint for "tell me when X changes". The row stays normal as long as the predicate holds. The synthetic watch:1: prefix Lua adds to the message is stripped from the cell text, so a failing assert(..., "short IP header") reads simply short IP header; the full prefixed message is preserved in the row’s tooltip.

Conditional / fallback.

-- "Frame number where this source was last seen, or 'never'":
last_seen[tostring(pinfo.src)] or "never"

-- A two-state badge:
pinfo.visited and "seen" or "first time"

"Show this if available, otherwise that." The first branch evaluates Lua-truthy, so a boolean like pinfo.visited works as expected.

Capture all return values.

-- string.find returns (start, end, capture1, capture2, ...);
-- a bare watch only shows `start`, so wrap to capture them all:
{ string.find(tostring(pinfo.src), "(%d+)%.(%d+)") }

A bare string.find(…​) watch shows only the first return value. Wrap with { …​ } to get them as a sequence you can expand.

When the path-watch fast path doesn’t apply. The shapes below cannot be expressed as a plain variable path, so a row that uses any of them is automatically routed to the expression watcher and gives up the path-watch extras (selection sync, stack-frame nudge, sharper error chrome, cheaper re-resolution).

In short: keep specs as plain paths whenever you can, and reach for the expression watcher only for the cases above (or when one of the patterns earlier in this subsection is what you actually want).

What to watch out for.