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

[Kris Van Hees <kris.van.hees@oracle.com>]

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`
> -
>  
>  **Parent topic:**[DTrace Function Reference](../reference/dtrace_functions.md)
> -
> -- 
> 2.47.3
>