6.3 The stats Command

6.3 The stats Command

Quick Answer: | stats <function>(field) [BY field] aggregates events into summary rows. Learn count, dc/distinct_count, sum, avg, min, max, values, and list, plus BY grouping. Use stats for general math; use top/rare when you specifically need most/least common value rankings with percents.

Topic 5.3 The stats command completes Domain 5.0. If top/rare are specialized frequency tools, stats is the Swiss Army knife: count events, sum bytes, average durations, find min/max, list distinct values, and group those calculations with BY.

Why stats dominates real User work

After you can find events, you usually need answers, not pages of _raw:

• How many errors per host?
• What is average response time by URI?
• How many distinct users hit an app today?
• What is the max queue depth observed?

Those questions map cleanly to stats aggregations. Exam items often show four similar pipelines and ask which function matches the business ask.

Transforming behavior (same family)

stats is a transforming command:

• Consumes incoming events/results
• Emits aggregated rows on the Statistics tab
• With no BY clause, returns one row for the whole set
• With BY, returns one row per distinct group

Core syntax at User level

... | stats <agg> [AS <name>] [, <agg> ...] [BY <field-list>]

Examples:

index=web
| stats count

index=web
| stats count BY status

index=web
| stats avg(bytes) AS avg_bytes, max(bytes) AS max_bytes BY host

AS renames output columns for readability—useful when multiple functions would otherwise produce long default names.

Aggregations you must recognize

Focus on the functions named in the User transforming-commands scope. You do not need every statistical function in the SPL reference for this exam domain.

count vs distinct_count

index=auth
| stats count AS events, dc(user) AS unique_users

• count → how many auth events matched
• dc(user) → how many different usernames appeared

Exam trap: “How many users logged in?” is usually dc(user), not raw count, unless the stem clearly means event volume.

values vs list

Both produce multivalue-style outputs useful for inspection:

• values — unique values (think “set”)
• list — values as encountered (can repeat)

If a question emphasizes unique members of a field across the set, prefer values or dc depending on whether they want the members or only the count of members.

BY grouping patterns

index=web
| stats count, avg(bytes) BY host, status

Grouping fields appear as columns; metrics fill the rest. Each distinct (host, status) pair gets its own aggregation row.

Wildcards in BY field names are not how you “BY all hosts like web*”—you specify concrete field names. Filter earlier (host=web*) then BY host.

Contrast: stats vs top vs rare

Keep this comparison cold for the exam:

You can approximate frequencies with stats count BY field, then sort—but User exam answers for “most/least common with percent” usually point to top/rare. Use stats when the stem mentions sum/avg/min/max/distinct or multiple named metrics.

Worked examples

Total errors and unique failing hosts

index=web status>=500
| stats count AS errors, dc(host) AS failing_hosts

Average and max bytes by status

index=web
| stats avg(bytes) AS avg_bytes, max(bytes) AS max_bytes BY status

Which methods appeared (unique)

index=web
| stats values(method) AS methods_seen

Busy hosts by event volume (stats style)

index=web
| stats count BY host
| sort - count

That last pattern is valid, but if the question explicitly wants the top command’s percent column, | top host is the tighter answer.

Related reporting (not Domain 5 focus)

Commands such as chart and timechart also aggregate and are popular when building visualizations over categories or _time. For Domain 5.0, stay centered on top, rare, and stats. Treat chart/timechart as “related later when creating chart reports,” not as substitutes you must master inside topic 5.3.

Common traps

1. count vs dc. Event volume ≠ unique values.
2. Forgetting BY yields one row. Surprise “single total” results usually mean you omitted grouping.
3. Using top for averages. Average bytes is stats avg(bytes), never top.
4. Numeric functions on non-numeric fields. sum(status) is usually wrong; filter/convert appropriately in real life—exam stems pick sensible numeric fields (bytes, durations).
5. Power User sprawl. Field aliases, data models, tstats, and CIM are outside Core User Domain 5—do not drag them into these answers.

Quick selection checklist

1. Stem says most/least common (+ percent)? → top / rare
2. Stem says count/sum/avg/min/max/distinct/values/list? → stats
3. Need split by category? → add BY
4. Need several metrics at once? → comma-separate stats functions

Domain 5 rewards precise matching of intent → command → function. Memorize the eight functions in the table, the BY rule, and the top/rare contrast, and this 15% domain becomes high-confidence points.