summaryrefslogtreecommitdiffstats
path: root/src/H5FDlog.h
blob: 969c09131ccc2c8427e7b1d08c0ae032b675cb3e (plain)
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
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * Copyright by the Board of Trustees of the University of Illinois.         *
 * 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.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 * Programmer:  Quincey Koziol
 *              Monday, April 17, 2000
 *
 * Purpose:	The public header file for the log driver.
 */
#ifndef H5FDlog_H
#define H5FDlog_H

#define H5FD_LOG (H5FD_log_init())

/* 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)}.
 *
 * <table>
 * <caption>Table1: Logging Flags</caption>
 * <tr>
 * <td>
 * #H5FD_LOG_LOC_READ
 * </td>
 * <td rowspan="3">
 * Track the location and length of every read, write, or seek operation.
 * </td>
 * </tr>
 * <tr><td>#H5FD_LOG_LOC_WRITE</td></tr>
 * <tr><td>#H5FD_LOG_LOC_SEEK</td></tr>
 * <tr>
 * <td>
 * #H5FD_LOG_LOC_IO
 * </td>
 * <td>
 * 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)}
 * </td>
 * </tr>
 * <tr>
 * <td>
 * #H5FD_LOG_FILE_READ
 * </td>
 * <td rowspan="2">
 * Track the number of times each byte is read or written.
 * </td>
 * </tr>
 * <tr><td>#H5FD_LOG_FILE_WRITE</td></tr>
 * <tr>
 * <td>
 * #H5FD_LOG_FILE_IO
 * </td>
 * <td>
 * 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)}
 * </td>
 * </tr>
 * <tr>
 * <td>
 * #H5FD_LOG_FLAVOR
 * </td>
 * <td>
 * Track the type, or flavor, of information stored at each byte.
 * </td>
 * </tr>
 * <tr>
 * <td>
 * #H5FD_LOG_NUM_READ
 * </td>
 * <td rowspan="4">
 * Track the total number of read, write, seek, or truncate operations that occur.
 * </td>
 * </tr>
 * <tr><td>#H5FD_LOG_NUM_WRITE</td></tr>
 * <tr><td>#H5FD_LOG_NUM_SEEK</td></tr>
 * <tr><td>#H5FD_LOG_NUM_TRUNCATE</td></tr>
 * <tr>
 * <td>
 * #H5FD_LOG_NUM_IO
 * </td>
 * <td>
 * 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)}
 * </td>
 * </tr>
 * <tr>
 * <td>
 * #H5FD_LOG_TIME_OPEN
 * </td>
 * <td rowspan="6">
 * Track the time spent in open, stat, read, write, seek, or close operations.
 * </td>
 * </tr>
 * <tr><td>#H5FD_LOG_TIME_STAT</td></tr>
 * <tr><td>#H5FD_LOG_TIME_READ</td></tr>
 * <tr><td>#H5FD_LOG_TIME_WRITE</td></tr>
 * <tr><td>#H5FD_LOG_TIME_SEEK</td></tr>
 * <tr><td>#H5FD_LOG_TIME_CLOSE</td></tr>
 * <tr>
 * <td>
 * #H5FD_LOG_TIME_IO
 * </td>
 * <td>
 * 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)}
 * </td>
 * </tr>
 * <tr>
 * <td>
 * #H5FD_LOG_ALLOC
 * </td>
 * <td>
 * Track the allocation of space in the file.
 * </td>
 * </tr>
 * <tr>
 * <td>
 * #H5FD_LOG_ALL
 * </td>
 * <td>
 * 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)}
 * </td>
 * </tr>
 * </table>
 * 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.
 * <table>
 * <caption>Table2: Logging Output</caption>
 * <tr>
 * <th>Flag</th><th>VFD Call</th><th>Output and Comments</th>
 * </th>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_LOC_READ</td>
 * <td>Read</td>
 * <td>
 * \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.
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_LOC_READ</td>
 * <td>Read Error</td>
 * <td>
 * \Code{Error! Reading: %10a-%10a (%10Zu bytes)}\n\n
 * Same parameters as non-error entry.
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_LOC_WRITE</td>
 * <td>Write</td>
 * <td>
 * \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.
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_LOC_WRITE</td>
 * <td>Write Error</td>
 * <td>
 * \Code{Error! Writing: %10a-%10a (%10Zu bytes)}\n\n
 * Same parameters as non-error entry.
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_LOC_SEEK</td>
 * <td>Read, Write</td>
 * <td>
 * \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.
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_FILE_READ</td>
 * <td>Close</td>
 * <td>
 * 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.
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_FILE_WRITE</td>
 * <td>Close</td>
 * <td>
 * 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.
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_FLAVOR</td>
 * <td>Close</td>
 * <td>
 * 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.
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_NUM_READ</td>
 * <td>Close</td>
 * <td>
 * Total number of read operations: \Code{%11u}
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_NUM_WRITE</td>
 * <td>Close</td>
 * <td>
 * Total number of write operations: \Code{%11u}
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_NUM_SEEK</td>
 * <td>Close</td>
 * <td>
 * Total number of seek operations: \Code{%11u}
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_NUM_TRUNCATE</td>
 * <td>Close</td>
 * <td>
 * Total number of truncate operations: \Code{%11u}
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_TIME_OPEN</td>
 * <td>Open</td>
 * <td>
 * Open took: \Code{(\%f s)}
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_TIME_READ</td>
 * <td>Close, Read</td>
 * <td>
 * Total time in read operations: \Code{\%f s}\n\n
 * See also: #H5FD_LOG_LOC_READ
 * </td>
 * </tr>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_TIME_WRITE</td>
 * <td>Close, Write</td>
 * <td>
 * Total time in write operations: \Code{\%f s}\n\n
 * See also: #H5FD_LOG_LOC_WRITE
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_TIME_SEEK</td>
 * <td>Close, Read, Write</td>
 * <td>
 * Total time in write operations: \Code{\%f s}\n\n
 * See also: #H5FD_LOG_LOC_SEEK or #H5FD_LOG_LOC_WRITE
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_TIME_CLOSE</td>
 * <td>Close</td>
 * <td>
 * Close took: \Code{(\%f s)}
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_TIME_STAT</td>
 * <td>Open</td>
 * <td>
 * Stat took: \Code{(\%f s)}
 * </td>
 * </tr>
 * <tr>
 * <td>#H5FD_LOG_ALLOC</td>
 * <td>Alloc</td>
 * <td>
 * \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
 * </td>
 * </tr>
 * </table>
 *
 * \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.
 * <table>
 * <caption>Table3: Flavors of logged data</caption>
 * <tr>
 * <th>Flavor</th><th>Description</th>
 * </th>
 * </tr>
 * <tr>
 * <td>#H5FD_MEM_NOLIST</td>
 * <td>Error value</td>
 * </tr>
 * <tr>
 * <td>#H5FD_MEM_DEFAULT</td>
 * <td>Value not yet set.\n
 *     May also be a datatype set in a larger allocation that will be
 *     suballocated by the library.</td>
 * </tr>
 * <tr>
 * <td>#H5FD_MEM_SUPER</td>
 * <td>Superblock data</td>
 * </tr>
 * <tr>
 * <td>#H5FD_MEM_BTREE</td>
 * <td>B-tree data</td>
 * </tr>
 * <tr>
 * <td>#H5FD_MEM_DRAW</td>
 * <td>Raw data (for example, contents of a dataset)</td>
 * </tr>
 * <tr>
 * <td>#H5FD_MEM_GHEAP</td>
 * <td>Global heap data</td>
 * </tr>
 * <tr>
 * <td>#H5FD_MEM_LHEAP</td>
 * <td>Local heap data</td>
 * </tr>
 * <tr>
 * <td>#H5FD_MEM_OHDR</td>
 * <td>Object header data</td>
 * </tr>
 * </table>
 *
 * \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