[PATCH 2/3] doc: Add trunc() documentation to User Guide

eugene.loh
2025-12-11T19:00:17Z

doc/userguide/index.md | 1 +
doc/userguide/reference/dtrace_functions.md | 4 ++
doc/userguide/reference/function_clear.md | 11 +++-
doc/userguide/reference/function_trunc.md | 53 +++++++++++++++++++
.../reference/unimplemented_functions.md | 7 ++-
5 files changed, 70 insertions(+), 6 deletions(-)
create mode 100644 doc/userguide/reference/function_trunc.md

diff --git a/doc/userguide/index.md b/doc/userguide/index.md
index 7d6b1caec..3bf731c67 100644
--- a/doc/userguide/index.md
+++ b/doc/userguide/index.md
@@ -179,6 +179,7 @@
- [system](reference/function_system.md)
- [trace](reference/function_trace.md)
- [tracemem](reference/function_tracemem.md)
+ - [trunc](reference/function_trunc.md)
- [uaddr](reference/function_uaddr.md)
- [ufunc](reference/function_ufunc.md)
- [umod](reference/function_umod.md)
diff --git a/doc/userguide/reference/dtrace_functions.md b/doc/userguide/reference/dtrace_functions.md
index 9a4f01363..7bf37794d 100644
--- a/doc/userguide/reference/dtrace_functions.md
+++ b/doc/userguide/reference/dtrace_functions.md
@@ -57,6 +57,8 @@ Functions can be grouped according to their general use case and might appear in

- [`printa`](function_printa.md): Displays and controls the formatting of an aggregation

+ - [`trunc`](function_trunc.md): Truncates (eliminates keys from) an aggregation
+
- **Speculation Functions**

Speculation functions create or operate on speculative buffers. Speculation is used to trace quantities into speculation buffers that can either be committed to the primary buffer or discarded at a later point, when other important information is known.
@@ -392,6 +394,8 @@ Returns a string translation of a hardware address.
Traces the result of an expression to the directed buffer.
- **[tracemem](../reference/function_tracemem.md)**
Copies the specified number of bytes of data from an address in memory to the current buffer.
+- **[trunc](../reference/function_trunc.md)**
+ Truncates keys from an aggregation.
- **[uaddr](../reference/function_uaddr.md)**
Prints the symbol for a specified address.
- **[ufunc](../reference/function_ufunc.md)**
diff --git a/doc/userguide/reference/function_clear.md b/doc/userguide/reference/function_clear.md
index a36a14ff8..de620b650 100644
--- a/doc/userguide/reference/function_clear.md
+++ b/doc/userguide/reference/function_clear.md
@@ -7,7 +7,9 @@ Clears the values from an aggregation while retaining aggregation keys.
void clear(@ *aggr*)
```

-The `clear` function takes an aggregation as its only parameter. The `clear` function clears only the aggregation's values, while the aggregation's keys are retained. If the key is referenced after the `clear` function is run, it has a zero value.
+The `clear` function takes an aggregation as its only parameter.
+The `clear` function clears only the aggregation's values, while the aggregation's keys are retained.
+If the key is referenced after the `clear` function is run, it has a zero value.

## How to use clear to show the system call rate only for the most recent ten-second period

@@ -35,5 +37,10 @@ tick-10sec
}
```

-**Parent topic:**[DTrace Function Reference](../reference/dtrace_functions.md)
+Each 10 seconds, the counts are cleared.
+Since the keys are retained, however, keys will persist in later
+time intervals, even if their corresponding functions never reoccur.
+More and more keys will be reported with counts of 0.
+Thus, you may want to use [`trunc`](function_trunc.md) instead.

+**Parent topic:**[DTrace Function Reference](../reference/dtrace_functions.md)
diff --git a/doc/userguide/reference/function_trunc.md b/doc/userguide/reference/function_trunc.md
new file mode 100644
index 000000000..b15cf3fe5
--- /dev/null
+++ b/doc/userguide/reference/function_trunc.md
@@ -0,0 +1,53 @@
+
+# trunc
+
+Truncates an aggregation, meaning discarding aggregation keys.
+
+```nocopybutton
+void trunc(@ *aggr*, [int64_t *number*])
+```
+
+The `trunc` function takes an aggregation as its first parameter.
+While the `clear` function clears only the aggregation's values, retaining the aggregation's keys,
+the `trunc` function removes the aggregation's keys.
+
+The optional second argument indicates how many keys to keep.
+By default, no keys are kept.
+
+## How to use trunc to show the system call rate only for the most recent ten-second period
+
+The `trunc` function is used inside the `tick-10sec` probe to clear the keys inside the `@func` aggregation.
+
+```
+#pragma D option quiet
+
+syscall:::entry
+{
+ @func[execname] = count();
+}
+
+tick-10sec
+{
+ printa(@func);
+ trunc(@func);
+}
+```
+
+Contrast this behavior with [`clear`](function_clear.md), which
+retains keys and simply clears their values.
+
+If the reported aggregations have too many keys, you can use the optional,
+second argument to indicate how many keys to retain.
+For example, you could limit the reporting to the 5 most common
+functions by changing the `tick` probe to:
+
+```
+tick-10sec
+{
+ trunc(@func, 5);
+ printa(@func);
+ trunc(@func);
+}
+```
+
+**Parent topic:**[DTrace Function Reference](../reference/dtrace_functions.md)
diff --git a/doc/userguide/reference/unimplemented_functions.md b/doc/userguide/reference/unimplemented_functions.md
index 942e16cf0..f69600b56 100644
--- a/doc/userguide/reference/unimplemented_functions.md
+++ b/doc/userguide/reference/unimplemented_functions.md
@@ -1,7 +1,9 @@

# Unimplemented Functions

-DTrace implementations have varied in functionality, and some functions aren't relevant to Linux and might never be implemented. The following functions aren't currently implemented:
+DTrace implementations have varied in functionality,
+and some functions are not relevant to Linux and might never be implemented.
+The following functions are not currently implemented:

- `breakpoint`

@@ -24,8 +26,5 @@ DTrace implementations have varied in functionality, and some functions aren't r

- `stop`

-- `trunc`