H5Pset_fapl_log
(
hid_t fapl_id
,
const char *logfile
,
unsigned long long flags
,
size_t buf_size
)
H5FD_LOG
) for use.
H5Pset_fapl_log
modifies the
file access property list to use the logging driver,
H5FD_LOG
.
The logging virtual file driver (VFD) is a clone of the
standard SEC2 (H5FD_SEC2
) driver with additional
facilities for logging VFD metrics and activity to a file.
logfile
is the name of the file in which the
logging entries are to be recorded.
The actions to be logged are specified in the parameter flags
using the pre-defined constants described in the following table.
Multiple flags can be set through the use of a logical OR contained
in parentheses. For example, logging read and write locations would
be specified as (H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE)
.
Table 1: Logging flags |
||
Flag | Description | |
H5FD_LOG_LOC_READ
|
Track the location and length of every read, write, or seek operation. | |
H5FD_LOG_LOC_WRITE
| ||
H5FD_LOG_LOC_SEEK
| ||
H5FD_LOG_LOC_IO
|
Track all I/O locations and lengths. The logical equivalent of the following: | |
|
(H5FD_LOG_LOC_READ | H5FD_LOG_LOC_WRITE |
H5FD_LOG_LOC_SEEK)
| |
H5FD_LOG_FILE_READ
|
Track the number of times each byte is read or written. | |
H5FD_LOG_FILE_WRITE
| ||
H5FD_LOG_FILE_IO
|
Track the number of times each byte is read and written. The logical equivalent of the following: | |
|
(H5FD_LOG_FILE_READ | H5FD_LOG_FILE_WRITE)
| |
H5FD_LOG_FLAVOR
|
Track the type, or flavor, of information stored at each byte. | |
H5FD_LOG_NUM_READ
|
Track the total number of read, write, seek, or truncate operations that occur. | |
H5FD_LOG_NUM_WRITE
| ||
H5FD_LOG_NUM_SEEK
| ||
H5FD_LOG_NUM_TRUNCATE
|
||
H5FD_LOG_NUM_IO
|
Track the total number of all types of I/O operations. The logical equivalent of the following: | |
|
(H5FD_LOG_NUM_READ | H5FD_LOG_NUM_WRITE | H5FD_LOG_NUM_SEEK
| H5FD_LOG_NUM_TRUNCATE)
| |
H5FD_LOG_TIME_OPEN
|
Track the time spent in open, stat, read, write, seek, or close operations. | |
H5FD_LOG_TIME_STAT
| ||
H5FD_LOG_TIME_READ
| ||
H5FD_LOG_TIME_WRITE
| ||
H5FD_LOG_TIME_SEEK
| ||
H5FD_LOG_TIME_CLOSE
|
||
H5FD_LOG_TIME_IO
|
Track the time spent in each of the above operations. The logical equivalent of the following: | |
|
(H5FD_LOG_TIME_OPEN | H5FD_LOG_TIME_STAT |
H5FD_LOG_TIME_READ | H5FD_LOG_TIME_WRITE |
H5FD_LOG_TIME_SEEK | H5FD_LOG_TIME_CLOSE)
| |
H5FD_LOG_ALLOC
|
Track the allocation of space in the file. | |
H5FD_LOG_ALL
|
Track everything. The logical equivalent of the following: | |
|
(H5FD_LOG_ALLOC | H5FD_LOG_TIME_IO | H5FD_LOG_NUM_IO |
H5FD_LOG_FLAVOR | H5FD_LOG_FILE_IO | H5FD_LOG_LOC_IO)
|
The logging driver can track the number of times each byte in the file
is read from or written to (using H5FD_LOG_FILE_READ
and
H5FD_LOG_FILE_WRITE
) and what kind of data is at that
location (e.g., metadata, raw data; using H5FD_LOG_FLAVOR
).
This information is tracked in internal buffers of size
buf_size
, which must be at least the maximum size in bytes
of the file to be logged while the log driver is in use.
One buffer of size buf_size
will be created for each of
H5FD_LOG_FILE_READ
, H5FD_LOG_FILE_WRITE
and
H5FD_LOG_FLAVOR
when those flags are set;
these buffers will not grow as the file increases in size.
hid_t fapl_id |
IN: File access property list identifier. |
char *logfile |
IN: Name of the log file. |
unsigned long long flags |
IN: Flags specifying the types of logging activity. |
size_t buf_size |
IN: The size of the logging buffers, in bytes (see description). |
The table, immediately below, describes output of the various logging driver flags and function calls; error output is in red italic. A list of valid flavor values, describing the type of data stored, follows the table.
Table 2: Logging output |
||
Flag (H5FD_LOG_) | VFD Call | Output and Comments |
LOC_READ |
Read() |
%10a-%10a (%10Zu bytes) (%s) Read
Start position
Adds |
LOC_READ |
Read() Error |
Error! Reading: %10a-%10a (%10Zu bytes)
Same parameters as non-error entry. |
LOC_WRITE |
Write() |
%10a-%10a (%10Zu bytes) (%s) Written
Start position
Adds |
LOC_WRITE |
Write() Error |
Error! Writing: %10a-%10a (%10Zu bytes)
Same parameters as non-error entry. |
LOC_SEEK |
Read()
|
Seek: From %10a-%10a
Start position
Adds |
FILE_READ |
Close() |
Begins with:
Dumping read I/O information
Then, for each range of identical values, there is this line:
Start address
Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read. |
FILE_WRITE |
Close() |
Begins with:
Dumping write I/O information
Then, for each range of identical values, there is this line:
Start address
Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read. |
FLAVOR |
Close() |
Begins with:
Dumping I/O flavor information
Then, for each range of identical values, there is this line:
Start address
Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read. |
NUM_READ |
Close() |
Total number of read operations: %11u
|
NUM_WRITE |
Close() |
Total number of write operations: %11u
|
NUM_SEEK |
Close() |
Total number of seek operations: %11u
|
NUM_TRUNCATE |
Close() |
Total number of truncate operations: %11u
|
TIME_OPEN |
Open() |
Open took: (%f s)
|
TIME_READ |
Close() |
Total time in read operations: %f s
See also: |
TIME_WRITE |
Close() |
Total time in write operations: %f s
See also: |
TIME_SEEK |
Close()
|
Total time in seek operations: %f s
See also: |
TIME_CLOSE |
Close() |
Close took: (%f s)
|
TIME_STAT |
Open() |
Stat took: (%f s)
|
ALLOC |
Alloc() |
%10-%10 (%10Hu bytes) (%s) Allocated
Start of address space
|
Flavors:
Table 3: Flavors of logged data |
||
Flavor | Description | |
H5FD_MEM_NOLIST |
Error value | |
H5FD_MEM_DEFAULT |
Value not yet set.
May also be a datatype set in a larger allocation that will be suballocated by the library. |
|
H5FD_MEM_SUPER |
Superblock data | |
H5FD_MEM_BTREE |
B-tree data | |
H5FD_MEM_DRAW |
Raw data (for example, contents of a dataset) | |
H5FD_MEM_GHEAP |
Global heap data | |
H5FD_MEM_LHEAP |
Local heap data | |
H5FD_MEM_OHDR |
Object header data |
Release | C |
1.8.7 |
The flags parameter has been changed from
unsigned int to unsigned long long.
The implementation of the H5FD_LOG_TIME_OPEN ,
H5FD_LOG_TIME_READ ,
H5FD_LOG_TIME_WRITE , and
H5FD_LOG_TIME_SEEK flags has been finished.
New flags were added: H5FD_LOG_NUM_TRUNCATE and
H5FD_LOG_TIME_STAT . |
1.6.0 |
The verbosity parameter has been removed.Two new parameters have been added: flags of type unsigned
and buf_size of type size_t.
|
1.4.0 | Function introduced in this release. |