/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * * distribution tree, or in https://www.hdfgroup.org/licenses. * * If you do not have access to either file, you may request a copy from * * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* * Purpose: The public header file for the log driver. */ #ifndef H5FDlog_H #define H5FDlog_H #define H5FD_LOG (H5FDperform_init(H5FD_log_init)) #define H5FD_LOG_VALUE H5_VFD_LOG /* Flags for H5Pset_fapl_log() */ /* Flags for tracking 'meta' operations (truncate) */ #define H5FD_LOG_TRUNCATE 0x00000001 #define H5FD_LOG_META_IO (H5FD_LOG_TRUNCATE) /* Flags for tracking where reads/writes/seeks occur */ #define H5FD_LOG_LOC_READ 0x00000002 #define H5FD_LOG_LOC_WRITE 0x00000004 #define H5FD_LOG_LOC_SEEK 0x00000008 #define H5FD_LOG_LOC_IO (H5FD_LOG_LOC_READ | H5FD_LOG_LOC_WRITE | H5FD_LOG_LOC_SEEK) /* Flags for tracking number of times each byte is read/written */ #define H5FD_LOG_FILE_READ 0x00000010 #define H5FD_LOG_FILE_WRITE 0x00000020 #define H5FD_LOG_FILE_IO (H5FD_LOG_FILE_READ | H5FD_LOG_FILE_WRITE) /* Flag for tracking "flavor" (type) of information stored at each byte */ #define H5FD_LOG_FLAVOR 0x00000040 /* Flags for tracking total number of reads/writes/seeks/truncates */ #define H5FD_LOG_NUM_READ 0x00000080 #define H5FD_LOG_NUM_WRITE 0x00000100 #define H5FD_LOG_NUM_SEEK 0x00000200 #define H5FD_LOG_NUM_TRUNCATE 0x00000400 #define H5FD_LOG_NUM_IO (H5FD_LOG_NUM_READ | H5FD_LOG_NUM_WRITE | H5FD_LOG_NUM_SEEK | H5FD_LOG_NUM_TRUNCATE) /* Flags for tracking time spent in open/stat/read/write/seek/truncate/close */ #define H5FD_LOG_TIME_OPEN 0x00000800 #define H5FD_LOG_TIME_STAT 0x00001000 #define H5FD_LOG_TIME_READ 0x00002000 #define H5FD_LOG_TIME_WRITE 0x00004000 #define H5FD_LOG_TIME_SEEK 0x00008000 #define H5FD_LOG_TIME_TRUNCATE 0x00010000 #define H5FD_LOG_TIME_CLOSE 0x00020000 #define H5FD_LOG_TIME_IO \ (H5FD_LOG_TIME_OPEN | H5FD_LOG_TIME_STAT | H5FD_LOG_TIME_READ | H5FD_LOG_TIME_WRITE | \ H5FD_LOG_TIME_SEEK | H5FD_LOG_TIME_TRUNCATE | H5FD_LOG_TIME_CLOSE) /* Flags for tracking allocation/release of space in file */ #define H5FD_LOG_ALLOC 0x00040000 #define H5FD_LOG_FREE 0x00080000 #define H5FD_LOG_ALL \ (H5FD_LOG_FREE | H5FD_LOG_ALLOC | H5FD_LOG_TIME_IO | H5FD_LOG_NUM_IO | H5FD_LOG_FLAVOR | \ H5FD_LOG_FILE_IO | H5FD_LOG_LOC_IO | H5FD_LOG_META_IO) #ifdef __cplusplus extern "C" { #endif H5_DLL hid_t H5FD_log_init(void); /** * \ingroup FAPL * * \brief Sets up the logging virtual file driver (#H5FD_LOG) for use * * \fapl_id * \param[in] logfile Name of the log file * \param[in] flags Flags specifying the types of logging activity * \param[in] buf_size The size of the logging buffers, in bytes (see description) * \returns \herr_t * * \details 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. * * \p 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 \p flags * using the pre-defined constants described in the following * table. Multiple flags can be set through the use of a logical \c OR * contained in parentheses. For example, logging read and write * locations would be specified as * \Code{(H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE)}. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Table1: Logging Flags
* #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: * \Code{(#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: * \Code{(#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: * \Code{(#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: * \Code{(#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: * \Code{(#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.\n * 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. * * \par Output: * This section describes the logging driver (LOG VFD) output.\n * The table, immediately below, describes output of the various logging driver * flags and function calls. A list of valid flavor values, describing the type * of data stored, follows the table. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Table2: Logging Output
FlagVFD CallOutput and Comments
#H5FD_LOG_LOC_READRead * \Code{%10a-%10a (%10Zu bytes) (%s) Read}\n\n * Start position\n * End position\n * Number of bytes\n * Flavor of read\n\n * Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. *
#H5FD_LOG_LOC_READRead Error * \Code{Error! Reading: %10a-%10a (%10Zu bytes)}\n\n * Same parameters as non-error entry. *
#H5FD_LOG_LOC_WRITEWrite * \Code{%10a-%10a (%10Zu bytes) (%s) Written}\n\n * Start position\n * End position\n * Number of bytes\n * Flavor of write\n\n * Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. *
#H5FD_LOG_LOC_WRITEWrite Error * \Code{Error! Writing: %10a-%10a (%10Zu bytes)}\n\n * Same parameters as non-error entry. *
#H5FD_LOG_LOC_SEEKRead, Write * \Code{Seek: From %10a-%10a}\n\n * Start position\n * End position\n\n * Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. *
#H5FD_LOG_FILE_READClose * Begins with:\n * Dumping read I/O information\n\n * Then, for each range of identical values, there is this line:\n * \Code{Addr %10-%10 (%10lu bytes) read from %3d times}\n\n * Start address\n * End address\n * Number of bytes\n * Number of times read\n\n * 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. *
#H5FD_LOG_FILE_WRITEClose * Begins with:\n * Dumping read I/O information\n\n * Then, for each range of identical values, there is this line:\n * \Code{Addr %10-%10 (%10lu bytes) written to %3d times}\n\n * Start address\n * End address\n * Number of bytes\n * Number of times written\n\n * 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. *
#H5FD_LOG_FLAVORClose * Begins with:\n * Dumping I/O flavor information\n\n * Then, for each range of identical values, there is this line:\n * \Code{Addr %10-%10 (%10lu bytes) flavor is %s}\n\n * Start address\n * End address\n * Number of bytes\n * Flavor\n\n * 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. *
#H5FD_LOG_NUM_READClose * Total number of read operations: \Code{%11u} *
#H5FD_LOG_NUM_WRITEClose * Total number of write operations: \Code{%11u} *
#H5FD_LOG_NUM_SEEKClose * Total number of seek operations: \Code{%11u} *
#H5FD_LOG_NUM_TRUNCATEClose * Total number of truncate operations: \Code{%11u} *
#H5FD_LOG_TIME_OPENOpen * Open took: \Code{(\%f s)} *
#H5FD_LOG_TIME_READClose, Read * Total time in read operations: \Code{\%f s}\n\n * See also: #H5FD_LOG_LOC_READ *
#H5FD_LOG_TIME_WRITEClose, Write * Total time in write operations: \Code{\%f s}\n\n * See also: #H5FD_LOG_LOC_WRITE *
#H5FD_LOG_TIME_SEEKClose, Read, Write * Total time in write operations: \Code{\%f s}\n\n * See also: #H5FD_LOG_LOC_SEEK or #H5FD_LOG_LOC_WRITE *
#H5FD_LOG_TIME_CLOSEClose * Close took: \Code{(\%f s)} *
#H5FD_LOG_TIME_STATOpen * Stat took: \Code{(\%f s)} *
#H5FD_LOG_ALLOCAlloc * \Code{%10-%10 (%10Hu bytes) (\%s) Allocated}\n\n * Start of address space\n * End of address space\n * Total size allocation\n * Flavor of allocation *
* * \par Flavors: * The \Emph{flavor} describes the type of stored information. The following * table lists the flavors that appear in log output and briefly describes each. * These terms are provided here to aid in the construction of log message * parsers; a full description is beyond the scope of this document. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Table3: Flavors of logged data
FlavorDescription
#H5FD_MEM_NOLISTError value
#H5FD_MEM_DEFAULTValue not yet set.\n * May also be a datatype set in a larger allocation that will be * suballocated by the library.
#H5FD_MEM_SUPERSuperblock data
#H5FD_MEM_BTREEB-tree data
#H5FD_MEM_DRAWRaw data (for example, contents of a dataset)
#H5FD_MEM_GHEAPGlobal heap data
#H5FD_MEM_LHEAPLocal heap data
#H5FD_MEM_OHDRObject header data
* * \version 1.8.7 The flags parameter has been changed from \Code{unsigned int} * to \Code{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. * \version 1.6.0 The \c verbosity parameter has been removed. * Two new parameters have been added: \p flags of type \Code{unsigned} and * \p buf_size of type \Code{size_t}. * \since 1.4.0 * */ H5_DLL herr_t H5Pset_fapl_log(hid_t fapl_id, const char *logfile, unsigned long long flags, size_t buf_size); #ifdef __cplusplus } #endif #endif