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

Kris Van Hees
2025-12-19T06:05:37Z

On Thu, Dec 11, 2025 at 02:00:02PM -0500, eugene.loh@oracle.com wrote:
> From: Eugene Loh <eugene.loh@oracle.com>
>
> Signed-off-by: Eugene Loh <eugene.loh@oracle.com>

Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
> 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`