osquery: the counter is not the row count

Counter moves when the query runs again

Each differential line can include a counter and an epoch. The counter climbs by one when that scheduled query executes again inside the same epoch. It is a tick for the query, not a tally of rows in the columns object.

A new epoch starts the tick over. Counter 1 in epoch 3 is not “the same as” counter 1 in epoch 2. Write the epoch beside the counter if you quote it.

The row is the line

One JSON line, with one columns object, is one result row. Five rows are five lines. A counter of 5 on a single line does not mean the columns describe five devices, five users, or five events.

If you need a population, count the lines that share the identifier, the query name, and the execution you care about. The counter is not that population.

What to file

File the counter and the epoch as the execution tick. File the row as the columns on that line. If the note says “five,” say five of what. Do not let the word sit next to a device or a user the line does not repeat five times.

Worked case: counter 5 and one disk

A disk_free line for host identifier b7e1c0aa-4400-4a10-9c10-lab000000004 shows epoch 2, counter 5, and one columns object for /dev/sdb1. A draft says five disks were low on space.

The note says counter 5 is the fifth execution in epoch 2. The line names one device. No other disk_free line from that execution was in the file that was reviewed. The finding cites one device, not five.

host identifier: b7e1c0aa-4400-4a10-9c10-lab000000004
epoch: 2  counter: 5
lines reviewed: 1
columns: device /dev/sdb1
write: fifth execution, one device
not: five disks