[PATCH] examples: add script fcalls.d

[PATCH] examples: add script fcalls.d

[eugene.loh]

From: Ruud van der Pas <ruud.vanderpas@oracle.com>

This is a script to list and count function calls.

dtrace/ChangeLog
2025-08-01  Ruud van der Pas  <ruud.vanderpas@oracle.com>

	* examples/fcalls.d: List and count function calls.

Signed-off-by: Ruud van der Pas <ruud.vanderpas@oracle.com>
---
 examples/fcalls.d | 88 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100755 examples/fcalls.d

diff --git a/examples/fcalls.d b/examples/fcalls.d
new file mode 100755
index 000000000..8116ecc6f
--- /dev/null
+++ b/examples/fcalls.d
@@ -0,0 +1,88 @@
+#!/usr/sbin/dtrace -s
+
+/*
+ *  NAME
+ *    fcalls.d - list the functions executed by an application
+ *
+ *  SYNOPSIS
+ *    sudo ./fcalls.d -c "<name-of-application> [app options]"
+ *
+ *  DESCRIPTION
+ *    This program lists the functions executed by the target
+ *    application.  In addition to this, the number of calls to
+ *    each function is printed.  This information is given on a
+ *    per-thread basis, as well as aggregated over all threads.
+ *
+ *  NOTES
+ *    - Since a.out is used in the probe definitions, library calls
+ *    are excluded.  If a library like libc should be included,
+ *    duplicate the probe definitions and in the copied lines
+ *    replace a.out by libc.so.
+ *    For example:
+ *    pid$target:a.out::entry,pid$target:libc.so::entry
+ *      { ... }
+ *    - It is assumed that a function called main is executed.
+ *    If this is not the case, this is not a critical error.
+ *    The first probe is used to capture the name of the executable,
+ *    but this is not critical.  The probe and printf statement
+ *    can safely be removed, or replaced by a suitable alternative.
+ */
+
+/*
+ *  Suppress the default output from the dtrace command and
+ *  have printa() print the data sorted by the first field.
+ */
+#pragma D option quiet
+#pragma D option aggsortkey=1
+#pragma D option aggsortkeypos=0
+
+/*
+ *  Store the name of the target application.  The probe
+ *  is restricted to main only, because the exec name needs
+ *  to be captured only once.
+ */
+pid$target:a.out:main:entry
+{
+  executable_name = execname;
+}
+/*
+ *  Use 4 aggregations to store the total number of function
+ *  calls, the counts per function and per thread, both
+ *  seperately and differentiated by thread and function.
+ */
+pid$target:a.out::entry
+{
+  @total_call_counts                          = count();
+  @call_counts_per_function[probefunc]        = count();
+  @call_counts_per_thr[tid]                   = count();
+  @counts_per_thr_and_function[tid,probefunc] = count();
+}
+/*
+ *  Print the results.  Use format strings to create a
+ *  table lay-out.
+ */
+END {
+  printf("===========================================\n");
+  printf("      Function Call Count Statistics\n");
+  printf("===========================================\n");
+  printf("Name of the executable: %s\n" ,executable_name);
+  printa("Total function calls  : %@d\n",@total_call_counts);
+
+  printf("\n===========================================\n");
+  printf("      Aggregated Function Call Counts\n");
+  printf("===========================================\n");
+  printf("%-25s %12s\n\n","Function name","Count");
+  printa("%-25s %@12d\n",@call_counts_per_function);
+
+  printf("\n===========================================\n");
+  printf("      Function Call Counts Per Thread\n");
+  printf("===========================================\n");
+  printf("%-7s %12s\n\n", "TID","Count");
+  printa("%-7d %@12d\n",@call_counts_per_thr);
+
+  printf("\n===========================================\n");
+  printf("      Thread Level Function Call Counts\n");
+  printf("===========================================\n");
+  printf("%-7s  %-25s %8s\n\n","TID","Function name","Count");
+  printa("%-7d  %-25s %@8d\n",@counts_per_thr_and_function);
+}
-- 
2.43.5

Re: [PATCH] examples: add script fcalls.d

[Eugene Loh]

Reviewed-by: Eugene Loh <eugene.loh@oracle.com>

I wouldn't mind a blank line separating each clause from the comment 
block that follows it.

Incidentally, when git applies a patch with "git am", it squeaks when 
there is trailing white space.  In this case, "both" (at the end of a 
line) was followed by a space.  (That trailing space was removed for 
this patch, but might still be in the original.)

Depending on where we want to go with this, it'd be nice to have tests 
for examples, so that if an example is going to break that we'll know 
about it.  There is currently a test/demo directory with a similar 
purpose but antiquated tests.  Maybe there could be a test/examples 
directory.  The trigger code could possibly be something we already 
have.  E.g., in test/triggers/* -- something that terminates by itself 
(or not) and has nontrivial call stack (for this example) or even 
multithreaded!  And predictable (checkable) behavior.  Possibilities 
include:
     test/triggers/futex
     test/triggers/libproc-dlmadopen (multithreaded)
     test/triggers/ustack-tst-basic
but one could argue that's beyond the scope of this patch.

On 8/4/25 19:42, eugene.loh@oracle.com wrote:
> From: Ruud van der Pas <ruud.vanderpas@oracle.com>
>
> This is a script to list and count function calls.
>
> dtrace/ChangeLog
> 2025-08-01  Ruud van der Pas  <ruud.vanderpas@oracle.com>
>
> 	* examples/fcalls.d: List and count function calls.
>
> Signed-off-by: Ruud van der Pas <ruud.vanderpas@oracle.com>
> ---
>   examples/fcalls.d | 88 +++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 88 insertions(+)
>   create mode 100755 examples/fcalls.d
>
> diff --git a/examples/fcalls.d b/examples/fcalls.d
> new file mode 100755
> index 000000000..8116ecc6f
> --- /dev/null
> +++ b/examples/fcalls.d
> @@ -0,0 +1,88 @@
> +#!/usr/sbin/dtrace -s
> +
> +/*
> + *  NAME
> + *    fcalls.d - list the functions executed by an application
> + *
> + *  SYNOPSIS
> + *    sudo ./fcalls.d -c "<name-of-application> [app options]"
> + *
> + *  DESCRIPTION
> + *    This program lists the functions executed by the target
> + *    application.  In addition to this, the number of calls to
> + *    each function is printed.  This information is given on a
> + *    per-thread basis, as well as aggregated over all threads.
> + *
> + *  NOTES
> + *    - Since a.out is used in the probe definitions, library calls
> + *    are excluded.  If a library like libc should be included,
> + *    duplicate the probe definitions and in the copied lines
> + *    replace a.out by libc.so.
> + *    For example:
> + *    pid$target:a.out::entry,pid$target:libc.so::entry
> + *      { ... }
> + *    - It is assumed that a function called main is executed.
> + *    If this is not the case, this is not a critical error.
> + *    The first probe is used to capture the name of the executable,
> + *    but this is not critical.  The probe and printf statement
> + *    can safely be removed, or replaced by a suitable alternative.
> + */
> +
> +/*
> + *  Suppress the default output from the dtrace command and
> + *  have printa() print the data sorted by the first field.
> + */
> +#pragma D option quiet
> +#pragma D option aggsortkey=1
> +#pragma D option aggsortkeypos=0
> +
> +/*
> + *  Store the name of the target application.  The probe
> + *  is restricted to main only, because the exec name needs
> + *  to be captured only once.
> + */
> +pid$target:a.out:main:entry
> +{
> +  executable_name = execname;
> +}
> +/*
> + *  Use 4 aggregations to store the total number of function
> + *  calls, the counts per function and per thread, both
> + *  seperately and differentiated by thread and function.
> + */
> +pid$target:a.out::entry
> +{
> +  @total_call_counts                          = count();
> +  @call_counts_per_function[probefunc]        = count();
> +  @call_counts_per_thr[tid]                   = count();
> +  @counts_per_thr_and_function[tid,probefunc] = count();
> +}
> +/*
> + *  Print the results.  Use format strings to create a
> + *  table lay-out.
> + */
> +END {
> +  printf("===========================================\n");
> +  printf("      Function Call Count Statistics\n");
> +  printf("===========================================\n");
> +  printf("Name of the executable: %s\n" ,executable_name);
> +  printa("Total function calls  : %@d\n",@total_call_counts);
> +
> +  printf("\n===========================================\n");
> +  printf("      Aggregated Function Call Counts\n");
> +  printf("===========================================\n");
> +  printf("%-25s %12s\n\n","Function name","Count");
> +  printa("%-25s %@12d\n",@call_counts_per_function);
> +
> +  printf("\n===========================================\n");
> +  printf("      Function Call Counts Per Thread\n");
> +  printf("===========================================\n");
> +  printf("%-7s %12s\n\n", "TID","Count");
> +  printa("%-7d %@12d\n",@call_counts_per_thr);
> +
> +  printf("\n===========================================\n");
> +  printf("      Thread Level Function Call Counts\n");
> +  printf("===========================================\n");
> +  printf("%-7s  %-25s %8s\n\n","TID","Function name","Count");
> +  printa("%-7d  %-25s %@8d\n",@counts_per_thr_and_function);
> +}

Re: [PATCH] examples: add script fcalls.d

[Kris Van Hees]

On Mon, Aug 04, 2025 at 08:06:59PM -0400, Eugene Loh wrote:
> Reviewed-by: Eugene Loh <eugene.loh@oracle.com>

I am confused... is this a R-b that means that the patch can go in as-is, or
are you expecting changes?  I also see discussion about a README.  Is that a
prerequisite or companion patch that is expected to go in with this one, or
is this one separete and could potentially go in on its own before a README?

> I wouldn't mind a blank line separating each clause from the comment block
> that follows it.
> 
> Incidentally, when git applies a patch with "git am", it squeaks when there
> is trailing white space.  In this case, "both" (at the end of a line) was
> followed by a space.  (That trailing space was removed for this patch, but
> might still be in the original.)
> 
> Depending on where we want to go with this, it'd be nice to have tests for
> examples, so that if an example is going to break that we'll know about it. 
> There is currently a test/demo directory with a similar purpose but
> antiquated tests.  Maybe there could be a test/examples directory.  The
> trigger code could possibly be something we already have.  E.g., in
> test/triggers/* -- something that terminates by itself (or not) and has
> nontrivial call stack (for this example) or even multithreaded!  And
> predictable (checkable) behavior.  Possibilities include:
>     test/triggers/futex
>     test/triggers/libproc-dlmadopen (multithreaded)
>     test/triggers/ustack-tst-basic
> but one could argue that's beyond the scope of this patch.
> 
> On 8/4/25 19:42, eugene.loh@oracle.com wrote:
> > From: Ruud van der Pas <ruud.vanderpas@oracle.com>
> > 
> > This is a script to list and count function calls.
> > 
> > dtrace/ChangeLog
> > 2025-08-01  Ruud van der Pas  <ruud.vanderpas@oracle.com>
> > 
> > 	* examples/fcalls.d: List and count function calls.
> > 
> > Signed-off-by: Ruud van der Pas <ruud.vanderpas@oracle.com>
> > ---
> >   examples/fcalls.d | 88 +++++++++++++++++++++++++++++++++++++++++++++++
> >   1 file changed, 88 insertions(+)
> >   create mode 100755 examples/fcalls.d
> > 
> > diff --git a/examples/fcalls.d b/examples/fcalls.d
> > new file mode 100755
> > index 000000000..8116ecc6f
> > --- /dev/null
> > +++ b/examples/fcalls.d
> > @@ -0,0 +1,88 @@
> > +#!/usr/sbin/dtrace -s
> > +
> > +/*
> > + *  NAME
> > + *    fcalls.d - list the functions executed by an application
> > + *
> > + *  SYNOPSIS
> > + *    sudo ./fcalls.d -c "<name-of-application> [app options]"
> > + *
> > + *  DESCRIPTION
> > + *    This program lists the functions executed by the target
> > + *    application.  In addition to this, the number of calls to
> > + *    each function is printed.  This information is given on a
> > + *    per-thread basis, as well as aggregated over all threads.
> > + *
> > + *  NOTES
> > + *    - Since a.out is used in the probe definitions, library calls
> > + *    are excluded.  If a library like libc should be included,
> > + *    duplicate the probe definitions and in the copied lines
> > + *    replace a.out by libc.so.
> > + *    For example:
> > + *    pid$target:a.out::entry,pid$target:libc.so::entry
> > + *      { ... }
> > + *    - It is assumed that a function called main is executed.
> > + *    If this is not the case, this is not a critical error.
> > + *    The first probe is used to capture the name of the executable,
> > + *    but this is not critical.  The probe and printf statement
> > + *    can safely be removed, or replaced by a suitable alternative.
> > + */
> > +
> > +/*
> > + *  Suppress the default output from the dtrace command and
> > + *  have printa() print the data sorted by the first field.
> > + */
> > +#pragma D option quiet
> > +#pragma D option aggsortkey=1
> > +#pragma D option aggsortkeypos=0
> > +
> > +/*
> > + *  Store the name of the target application.  The probe
> > + *  is restricted to main only, because the exec name needs
> > + *  to be captured only once.
> > + */
> > +pid$target:a.out:main:entry
> > +{
> > +  executable_name = execname;
> > +}
> > +/*
> > + *  Use 4 aggregations to store the total number of function
> > + *  calls, the counts per function and per thread, both
> > + *  seperately and differentiated by thread and function.
> > + */
> > +pid$target:a.out::entry
> > +{
> > +  @total_call_counts                          = count();
> > +  @call_counts_per_function[probefunc]        = count();
> > +  @call_counts_per_thr[tid]                   = count();
> > +  @counts_per_thr_and_function[tid,probefunc] = count();
> > +}
> > +/*
> > + *  Print the results.  Use format strings to create a
> > + *  table lay-out.
> > + */
> > +END {
> > +  printf("===========================================\n");
> > +  printf("      Function Call Count Statistics\n");
> > +  printf("===========================================\n");
> > +  printf("Name of the executable: %s\n" ,executable_name);
> > +  printa("Total function calls  : %@d\n",@total_call_counts);
> > +
> > +  printf("\n===========================================\n");
> > +  printf("      Aggregated Function Call Counts\n");
> > +  printf("===========================================\n");
> > +  printf("%-25s %12s\n\n","Function name","Count");
> > +  printa("%-25s %@12d\n",@call_counts_per_function);
> > +
> > +  printf("\n===========================================\n");
> > +  printf("      Function Call Counts Per Thread\n");
> > +  printf("===========================================\n");
> > +  printf("%-7s %12s\n\n", "TID","Count");
> > +  printa("%-7d %@12d\n",@call_counts_per_thr);
> > +
> > +  printf("\n===========================================\n");
> > +  printf("      Thread Level Function Call Counts\n");
> > +  printf("===========================================\n");
> > +  printf("%-7s  %-25s %8s\n\n","TID","Function name","Count");
> > +  printa("%-7d  %-25s %@8d\n",@counts_per_thr_and_function);
> > +}