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

[eugene.loh at oracle.com]

From: Eugene Loh <eugene.loh at oracle.com>

Signed-off-by: Eugene Loh <eugene.loh at 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