/usr/share/doc/eztrace/example/README is in eztrace 1.1-2-1ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 | --- Writing a plugin module for eztrace ---
I - Introduction
================
This is an example of plugin module for eztrace.
This directory contains 2 sub-directories:
libexample_orig
---------------
This is an example library with functions that we want to trace using
eztrace. This library implements two simple functions
(example_function1 and example_function2).
This directory also includes a simple program that uses this library.
libexample_eztrace
------------------
This directory contains an example plugin for eztrace. This plugin
allows to trace the libexample functions with eztrace.
II - Files required for an eztrace module
=========================================
Writing an eztrace module requires 2 steps:
a. Recording events when a particular function is called. This step
happens during the application execution.
b. Interpreting the recorded events and generating a trace. This step
happens after the application execution, when eztrace_convert is run.
It is thus required to create two dynamic libraries that are loaded by
eztrace and eztrace_convert.
II.1 - Recording events
-----------------------
(see libexample_eztrace/example.c)
For recording events, eztrace relies on functions that redefines the
functions that have to be traced (MPI_Send, pthread_create, etc.)
Writing a plugin module for eztrace thus boils down to redefining all
the needed functions (for example example_function1 and
example_function2). Each redefined function f has to record an event
and to call the original f function. Usually such a function looks
like this:
int f(int arg1, double arg2)
{
EZTRACE_EVENT2(F_START, arg1, arg2);
int ret = f_orig(arg1, arg2);
EZTRACE_EVENT1(F_STOP, ret);
return ret;
}
This function records an event (which code is F_START), calls the
original f function, and records another after f (which code is F_STOP).
In order to call the original f function, the constructor of the
library should invoke the INTERCEPT macro:
INTERCEPT("f", f_orig);
This macro replace the original f function with the one defined in the
current module. It copies the address of the original function in the
f_orig variable.
II.2 - Interpreting the recorded events
---------------------------------------
(see libexample_eztrace/eztrace_convert_example.c)
The interpretation plugin has to register to eztrace at startup. This can
be done by using a constructor (see the libinit function). During the registration,
the plugin defines a set of callbacks as well as general information on the plugin:
int (*init)():
The initialization function. This function is called once all the plugins are loaded
and the trace is started. This function usually declared StateTypes, LinkTypes, etc.
int (*handle)(eztrace_event_t* ev):
The function that interprets events. It is called for each event in the Fxt trace.
int (*handle_stats)(eztrace_event_t* ev):
The function called for handling an event when eztrace_stats is called
void (*print_stats)():
Print the results of statistics.
uint8_t module_prefix:
Plugin identifier.
char* name:
Name of the plugin. It is used for selecting the list of plugins to use (ie. EZTRACE_TRACE)
char* description:
Description of the plugin (printed by eztrace_avail)
|