1fi_hook(7)                   Libfabric v1.12.0rc1                   fi_hook(7)
2
3
4

NAME

6       fi_hook - The Hook Fabric Provider Utility
7

OVERVIEW

9       The  hooking provider is a utility function that can intercept calls to
10       any provider.  The hook provider is always available, but has zero  im‐
11       pact  on  calls unless enabled.  It is useful for providing performance
12       data on selected calls or debugging information.
13

SUPPORTED FEATURES

15       Hooking support is enabled through the  FI_HOOK  environment  variable.
16       To  enable  hooking,  FI_HOOK must be set to the name of one or more of
17       the available hooking providers.  When multiple  hooks  are  specified,
18       the names must be separated by a semi-colon.  To obtain a list of hook‐
19       ing providers available on the current system, one can use the  fi_info
20       utility  with  the  '--env' command line option.  Hooking providers are
21       usually identified by 'hook' appearing in the provider name.
22
23       Known hooking providers include the following:
24
25       ofi_hook_perf
26              This hooks 'fast path' data operation calls.   Performance  data
27              is  captured  on  call entrance and exit, in order to provide an
28              average of how long each call takes to complete.  See  the  PER‐
29              FORMANCE HOOKS section for available performance data.
30

PERFORMANCE HOOKS

32       The hook provider allows capturing inline performance data by accessing
33       the CPU Performance Management Unit (PMU).  PMU data is only  available
34       on  Linux  systems.  Additionally, access to PMU data may be restricted
35       to privileged (super-user) applications.
36
37       Performance data is captured for critical data transfer calls:  fi_msg,
38       fi_rma,  fi_tagged,  fi_cq, and fi_cntr.  Captured data is displayed as
39       logged data using the FI_LOG_LEVEL trace level.   Performance  data  is
40       logged when the associated fabric is destroyed.
41
42       The environment variable FI_PERF_CNTR is used to identify which perfor‐
43       mance counter is tracked.  The following counters are available:
44
45       cpu_cycles
46              Counts the number of CPU cycles each function takes to complete.
47
48       cpu_instr
49              Counts the number of CPU instructions  each  function  takes  to
50              complete.   This  is  the default performance counter if none is
51              specified.
52

LIMITATIONS

54       Hooking functionality is not available for providers  built  using  the
55       FI_FABRIC_DIRECT feature.  That is, directly linking to a provider pre‐
56       vents hooking.
57
58       The hooking provider does not work with triggered operations.  Applica‐
59       tion  that  use  FI_TRIGGER  operations that attempt to hook calls will
60       likely crash.
61

SEE ALSO

63       fabric(7), fi_provider(7)
64

AUTHORS

66       OpenFabrics.
67
68
69
70Libfabric Programmer's Manual     2019-07-19                        fi_hook(7)