1disk_log(3) Erlang Module Definition disk_log(3)
2
6 disk_log - A disk-based term logging facility.
7
9 disk_log is a disk-based term logger that enables efficient logging of
10 items on files.
11 Two types of logs are supported:
13 halt logs:
15 Appends items to a single file, which size can be limited by the
16 disk_log module.
17 wrap logs:
19 Uses a sequence of wrap log files of limited size. As a wrap log
20 file is filled up, further items are logged on to the next file in
21 the sequence, starting all over with the first file when the last
22 file is filled up.
23 For efficiency reasons, items are always written to files as binaries.
25 Two formats of the log files are supported:
27 internal format:
29 Supports automatic repair of log files that are not properly closed
30 and enables efficient reading of logged items in chunks using a set
31 of functions defined in this module. This is the only way to read
32 internally formatted logs. An item logged to an internally format‐
33 ted log must not occupy more than 4 GB of disk space (the size must
34 fit in 4 bytes).
35 external format:
37 Leaves it up to the user to read and interpret the logged data. The
38 disk_log module cannot repair externally formatted logs.
39 For each open disk log, one process handles requests made to the disk
41 log. This process is created when open/1 is called, provided there ex‐
42 ists no process handling the disk log. A process that opens a disk log
43 can be an owner or an anonymous user of the disk log. Each owner is
44 linked to the disk log process, and an owner can close the disk log ei‐
45 ther explicitly (by calling close/1 or lclose/1,2) or by terminating.
46 Owners can subscribe to notifications, messages of the form {disk_log,
48 Node, Log, Info}, which are sent from the disk log process when certain
49 events occur, see the functions and in particular the open/1 option no‐
50 tify. A log can have many owners, but a process cannot own a log more
51 than once. However, the same process can open the log as a user more
52 than once.
53 For a disk log process to close its file properly and terminate, it
55 must be closed by its owners and once by some non-owner process for
56 each time the log was used anonymously. The users are counted and there
57 must not be any users left when the disk log process terminates.
58 Items can be logged synchronously by using functions log/2, blog/2,
60 log_terms/2, and blog_terms/2. For each of these functions, the caller
61 is put on hold until the items are logged (but not necessarily written,
62 use sync/1 to ensure that). By adding an a to each of the mentioned
63 function names, we get functions that log items asynchronously. Asyn‐
64 chronous functions do not wait for the disk log process to write the
65 items to the file, but return the control to the caller more or less
66 immediately.
67 When using the internal format for logs, use functions log/2,
69 log_terms/2, alog/2, and alog_terms/2. These functions log one or more
70 Erlang terms. By prefixing each of the functions with a b (for "bi‐
71 nary"), we get the corresponding blog() functions for the external for‐
72 mat. These functions log one or more chunks of bytes. For example, to
73 log the string "hello" in ASCII format, you can use disk_log:blog(Log,
74 "hello"), or disk_log:blog(Log, list_to_binary("hello")). The two al‐
75 ternatives are equally efficient.
76 The blog() functions can also be used for internally formatted logs,
78 but in this case they must be called with binaries constructed with
79 calls to term_to_binary/1. There is no check to ensure this, it is en‐
80 tirely the responsibility of the caller. If these functions are called
81 with binaries that do not correspond to Erlang terms, the chunk/2,3 and
82 automatic repair functions fail. The corresponding terms (not the bina‐
83 ries) are returned when chunk/2,3 is called.
84 An open disk log is only accessible from the node where the disk log
86 process runs. All processes on the node where the disk log process runs
87 can log items or otherwise change, inspect, or close the log.
88 Errors are reported differently for asynchronous log attempts and other
90 uses of the disk_log module. When used synchronously, this module
91 replies with an error message, but when called asynchronously, this
92 module does not know where to send the error message. Instead, owners
93 subscribing to notifications receive an error_status message.
94 The disk_log module does not report errors to the error_logger module.
96 It is up to the caller to decide whether to employ the error logger.
97 Function format_error/1 can be used to produce readable messages from
98 error replies. However, information events are sent to the error logger
99 in two situations, namely when a log is repaired, or when a file is
100 missing while reading chunks.
101 Error message no_such_log means that the specified disk log is not
103 open. Nothing is said about whether the disk log files exist or not.
104 Note:
106 If an attempt to reopen or truncate a log fails (see reopen/2,3 and
107 truncate/1,2) the disk log process terminates immediately. Before the
108 process terminates, links to owners and blocking processes (see
109 block/1,2) are removed. The effect is that the links work in one direc‐
110 tion only. Any process using a disk log must check for error message
111 no_such_log if some other process truncates or reopens the log simulta‐
112 neously.
113
116 log() = term()
117 dlog_size() =
119 infinity |
120 integer() >= 1 |
121 {MaxNoBytes :: integer() >= 1, MaxNoFiles :: integer() >= 1}
122 dlog_format() = external | internal
124 dlog_head_opt() = none | term() | iodata()
126 dlog_mode() = read_only | read_write
128 dlog_type() = halt | wrap
130 continuation()
132 Chunk continuation returned by chunk/2,3, bchunk/2,3, or
134 chunk_step/3.
135 invalid_header() = term()
137 file_error() = term()
139
141 all() -> [Log]
142 Types:
144 Log = log()
146 Returns the names of the disk logs accessible on the current
148 node.
149 accessible_logs() -> {[Log], []}
151 Types:
153 Log = log()
155 Returns the names of the disk logs accessible on the current
157 node. The first list contains the logs. The second list is al‐
158 ways empty (before Erlang/OTP 24.0 it used to contain so called
159 distributed disk logs).
160 Note:
162 This function is deprecated. Use all/0 instead.
163 alog(Log, Term) -> notify_ret()
166 balog(Log, Bytes) -> notify_ret()
168 Types:
170 Log = log()
172 Term = term()
173 Bytes = iodata()
174 notify_ret() = ok | {error, no_such_log}
175 Asynchronously append an item to a disk log. alog/2 is used for
177 internally formatted logs and balog/2 for externally formatted
178 logs. balog/2 can also be used for internally formatted logs if
179 the binary is constructed with a call to term_to_binary/1.
180 Owners subscribing to notifications receive message read_only,
182 blocked_log, or format_external if the item cannot be written on
183 the log, and possibly one of the messages wrap, full, or er‐
184 ror_status if an item is written on the log. Message error_sta‐
185 tus is sent if something is wrong with the header function or if
186 a file error occurs.
187 alog_terms(Log, TermList) -> notify_ret()
189 balog_terms(Log, ByteList) -> notify_ret()
191 Types:
193 Log = log()
195 TermList = [term()]
196 ByteList = [iodata()]
197 notify_ret() = ok | {error, no_such_log}
198 Asynchronously append a list of items to a disk log.
200 alog_terms/2 is used for internally formatted logs and ba‐
201 log_terms/2 for externally formatted logs. balog_terms/2 can
202 also be used for internally formatted logs if the binaries are
203 constructed with calls to term_to_binary/1.
204 Owners subscribing to notifications receive message read_only,
206 blocked_log, or format_external if the items cannot be written
207 on the log, and possibly one or more of the messages wrap, full,
208 and error_status if items are written on the log. Message er‐
209 ror_status is sent if something is wrong with the header func‐
210 tion or if a file error occurs.
211 block(Log) -> ok | {error, block_error_rsn()}
213 block(Log, QueueLogRecords) -> ok | {error, block_error_rsn()}
215 Types:
217 Log = log()
219 QueueLogRecords = boolean()
220 block_error_rsn() = no_such_log | nonode | {blocked_log, log()}
221 With a call to block/1,2 a process can block a log. If the
223 blocking process is not an owner of the log, a temporary link is
224 created between the disk log process and the blocking process.
225 The link ensures that the disk log is unblocked if the blocking
226 process terminates without first closing or unblocking the log.
227 Any process can probe a blocked log with info/1 or close it with
229 close/1. The blocking process can also use functions chunk/2,3,
230 bchunk/2,3, chunk_step/3, and unblock/1 without being affected
231 by the block. Any other attempt than those mentioned so far to
232 update or read a blocked log suspends the calling process until
233 the log is unblocked or returns error message {blocked_log,
234 Log}, depending on whether the value of QueueLogRecords is true
235 or false. QueueLogRecords defaults to true, which is used by
236 block/1.
237 change_header(Log, Header) -> ok | {error, Reason}
239 Types:
241 Log = log()
243 Header =
244 {head, dlog_head_opt()} |
245 {head_func, MFA :: {atom(), atom(), list()}}
246 Reason =
247 no_such_log | nonode |
248 {read_only_mode, Log} |
249 {blocked_log, Log} |
250 {badarg, head}
251 Changes the value of option head or head_func for an owner of a
253 disk log.
254 change_notify(Log, Owner, Notify) -> ok | {error, Reason}
256 Types:
258 Log = log()
260 Owner = pid()
261 Notify = boolean()
262 Reason =
263 no_such_log | nonode |
264 {blocked_log, Log} |
265 {badarg, notify} |
266 {not_owner, Owner}
267 Changes the value of option notify for an owner of a disk log.
269 change_size(Log, Size) -> ok | {error, Reason}
271 Types:
273 Log = log()
275 Size = dlog_size()
276 Reason =
277 no_such_log | nonode |
278 {read_only_mode, Log} |
279 {blocked_log, Log} |
280 {new_size_too_small, Log, CurrentSize :: integer() >= 1}
281 |
282 {badarg, size} |
283 {file_error, file:filename(), file_error()}
284 Changes the size of an open log. For a halt log, the size can
286 always be increased, but it cannot be decreased to something
287 less than the current file size.
288 For a wrap log, both the size and the number of files can always
290 be increased, as long as the number of files does not exceed
291 65000. If the maximum number of files is decreased, the change
292 is not valid until the current file is full and the log wraps to
293 the next file. The redundant files are removed the next time the
294 log wraps around, that is, starts to log to file number 1.
295 As an example, assume that the old maximum number of files is 10
297 and that the new maximum number of files is 6. If the current
298 file number is not greater than the new maximum number of files,
299 files 7-10 are removed when file 6 is full and the log starts to
300 write to file number 1 again. Otherwise, the files greater than
301 the current file are removed when the current file is full (for
302 example, if the current file is 8, files 9 and 10 are removed).
303 The files between the new maximum number of files and the cur‐
304 rent file (that is, files 7 and 8) are removed the next time
305 file 6 is full.
306 If the size of the files is decreased, the change immediately
308 affects the current log. It does not change the size of log
309 files already full until the next time they are used.
310 If the log size is decreased, for example, to save space, func‐
312 tion inc_wrap_file/1 can be used to force the log to wrap.
313 chunk(Log, Continuation) -> chunk_ret()
315 chunk(Log, Continuation, N) -> chunk_ret()
317 bchunk(Log, Continuation) -> bchunk_ret()
319 bchunk(Log, Continuation, N) -> bchunk_ret()
321 Types:
323 Log = log()
325 Continuation = start | continuation()
326 N = integer() >= 1 | infinity
327 chunk_ret() =
328 {Continuation2 :: continuation(), Terms :: [term()]} |
329 {Continuation2 :: continuation(),
330 Terms :: [term()],
331 Badbytes :: integer() >= 0} |
332 eof |
333 {error, Reason :: chunk_error_rsn()}
334 bchunk_ret() =
335 {Continuation2 :: continuation(), Binaries :: [binary()]} |
336 {Continuation2 :: continuation(),
337 Binaries :: [binary()],
338 Badbytes :: integer() >= 0} |
339 eof |
340 {error, Reason :: chunk_error_rsn()}
341 chunk_error_rsn() =
342 no_such_log |
343 {format_external, log()} |
344 {blocked_log, log()} |
345 {badarg, continuation} |
346 {not_internal_wrap, log()} |
347 {corrupt_log_file, FileName :: file:filename()} |
348 {file_error, file:filename(), file_error()}
349 Efficiently reads the terms that are appended to an internally
351 formatted log. It minimizes disk I/O by reading 64 kilobyte
352 chunks from the file. Functions bchunk/2,3 return the binaries
353 read from the file, they do not call binary_to_term(). Apart
354 from that, they work just like chunk/2,3.
355 The first time chunk() (or bchunk()) is called, an initial con‐
357 tinuation, the atom start, must be provided.
358 When chunk/3 is called, N controls the maximum number of terms
360 that are read from the log in each chunk. Defaults to infinity,
361 which means that all the terms contained in the 64 kilobyte
362 chunk are read. If less than N terms are returned, this does not
363 necessarily mean that the end of the file is reached.
364 chunk() returns a tuple {Continuation2, Terms}, where Terms is a
366 list of terms found in the log. Continuation2 is yet another
367 continuation, which must be passed on to any subsequent calls to
368 chunk(). With a series of calls to chunk(), all terms from a log
369 can be extracted.
370 chunk() returns a tuple {Continuation2, Terms, Badbytes} if the
372 log is opened in read-only mode and the read chunk is corrupt.
373 Badbytes is the number of bytes in the file found not to be Er‐
374 lang terms in the chunk. Notice that the log is not repaired.
375 When trying to read chunks from a log opened in read-write mode,
376 tuple {corrupt_log_file, FileName} is returned if the read chunk
377 is corrupt.
378 chunk() returns eof when the end of the log is reached, or {er‐
380 ror, Reason} if an error occurs. If a wrap log file is missing,
381 a message is output on the error log.
382 When chunk/2,3 is used with wrap logs, the returned continuation
384 might not be valid in the next call to chunk(). This is because
385 the log can wrap and delete the file into which the continuation
386 points. To prevent this, the log can be blocked during the
387 search.
388 chunk_info(Continuation) -> InfoList | {error, Reason}
390 Types:
392 Continuation = continuation()
394 InfoList = [{node, Node :: node()}, ...]
395 Reason = {no_continuation, Continuation}
396 Returns the pair {node, Node}, describing the chunk continuation
398 returned by chunk/2,3, bchunk/2,3, or chunk_step/3.
399 Terms are read from the disk log running on Node.
401 chunk_step(Log, Continuation, Step) ->
403 {ok, any()} | {error, Reason}
404 Types:
406 Log = log()
408 Continuation = start | continuation()
409 Step = integer()
410 Reason =
411 no_such_log | end_of_log |
412 {format_external, Log} |
413 {blocked_log, Log} |
414 {badarg, continuation} |
415 {file_error, file:filename(), file_error()}
416 Can be used with chunk/2,3 and bchunk/2,3 to search through an
418 internally formatted wrap log. It takes as argument a continua‐
419 tion as returned by chunk/2,3, bchunk/2,3, or chunk_step/3, and
420 steps forward (or backward) Step files in the wrap log. The con‐
421 tinuation returned, points to the first log item in the new cur‐
422 rent file.
423 If atom start is specified as continuation, the first file of
425 the wrap log is chosen as the new current file.
426 If the wrap log is not full because all files are not yet used,
428 {error, end_of_log} is returned if trying to step outside the
429 log.
430 close(Log) -> ok | {error, close_error_rsn()}
432 Types:
434 Log = log()
436 close_error_rsn() =
437 no_such_log | nonode |
438 {file_error, file:filename(), file_error()}
439 Closes a disk log properly. An internally formatted log must be
441 closed before the Erlang system is stopped. Otherwise, the log
442 is regarded as unclosed and the automatic repair procedure is
443 activated next time the log is opened.
444 The disk log process is not terminated as long as there are own‐
446 ers or users of the log. All owners must close the log, possibly
447 by terminating. Also, any other process, not only the processes
448 that have opened the log anonymously, can decrement the users
449 counter by closing the log. Attempts to close a log by a process
450 that is not an owner are ignored if there are no users.
451 If the log is blocked by the closing process, the log is also
453 unblocked.
454 format_error(Error) -> io_lib:chars()
456 Types:
458 Error = term()
460 Given the error returned by any function in this module, this
462 function returns a descriptive string of the error in English.
463 For file errors, function format_error/1 in module file is
464 called.
465 inc_wrap_file(Log) -> ok | {error, inc_wrap_error_rsn()}
467 Types:
469 Log = log()
471 inc_wrap_error_rsn() =
472 no_such_log | nonode |
473 {read_only_mode, log()} |
474 {blocked_log, log()} |
475 {halt_log, log()} |
476 {invalid_header, invalid_header()} |
477 {file_error, file:filename(), file_error()}
478 invalid_header() = term()
479 Forces the internally formatted disk log to start logging to the
481 next log file. It can be used, for example, with change_size/2
482 to reduce the amount of disk space allocated by the disk log.
483 Owners subscribing to notifications normally receive a wrap mes‐
485 sage, but if an error occurs with a reason tag of invalid_header
486 or file_error, an error_status message is sent.
487 info(Log) -> InfoList | {error, no_such_log}
489 Types:
491 Log = log()
493 InfoList = [dlog_info()]
494 dlog_info() =
495 {name, Log :: log()} |
496 {file, File :: file:filename()} |
497 {type, Type :: dlog_type()} |
498 {format, Format :: dlog_format()} |
499 {size, Size :: dlog_size()} |
500 {mode, Mode :: dlog_mode()} |
501 {owners, [{pid(), Notify :: boolean()}]} |
502 {users, Users :: integer() >= 0} |
503 {status,
504 Status :: ok | {blocked, QueueLogRecords :: boolean()}} |
505 {node, Node :: node()} |
506 {head,
507 Head ::
508 none |
509 {head, binary()} |
510 (MFA :: {atom(), atom(), list()})} |
511 {no_written_items, NoWrittenItems :: integer() >= 0} |
512 {full, Full :: boolean} |
513 {no_current_bytes, integer() >= 0} |
514 {no_current_items, integer() >= 0} |
515 {no_items, integer() >= 0} |
516 {current_file, integer() >= 1} |
517 {no_overflows,
518 {SinceLogWasOpened :: integer() >= 0,
519 SinceLastInfo :: integer() >= 0}}
520 Returns a list of {Tag, Value} pairs describing a log running on
522 the node.
523 The following pairs are returned for all logs:
525 {name, Log}:
527 Log is the log name as specified by the open/1 option name.
528 {file, File}:
530 For halt logs File is the filename, and for wrap logs File
531 is the base name.
532 {type, Type}:
534 Type is the log type as specified by the open/1 option type.
535 {format, Format}:
537 Format is the log format as specified by the open/1 option
538 format.
539 {size, Size}:
541 Size is the log size as specified by the open/1 option size,
542 or the size set by change_size/2. The value set by
543 change_size/2 is reflected immediately.
544 {mode, Mode}:
546 Mode is the log mode as specified by the open/1 option mode.
547 {owners, [{pid(), Notify}]}:
549 Notify is the value set by the open/1 option notify or func‐
550 tion change_notify/3 for the owners of the log.
551 {users, Users}:
553 Users is the number of anonymous users of the log, see the
554 open/1 option linkto.
555 {status, Status}:
557 Status is ok or {blocked, QueueLogRecords} as set by func‐
558 tions block/1,2 and unblock/1.
559 {node, Node}:
561 The information returned by the current invocation of func‐
562 tion info/1 is gathered from the disk log process running on
563 Node.
564 The following pairs are returned for all logs opened in
566 read_write mode:
567 {head, Head}:
569 Depending on the value of the open/1 options head and
570 head_func, or set by function change_header/2, the value of
571 Head is none (default), {head, H} (head option), or {M,F,A}
572 (head_func option).
573 {no_written_items, NoWrittenItems}:
575 NoWrittenItems is the number of items written to the log
576 since the disk log process was created.
577 The following pair is returned for halt logs opened in
579 read_write mode:
580 {full, Full}:
582 Full is true or false depending on whether the halt log is
583 full or not.
584 The following pairs are returned for wrap logs opened in
586 read_write mode:
587 {no_current_bytes, integer() >= 0}:
589 The number of bytes written to the current wrap log file.
590 {no_current_items, integer() >= 0}:
592 The number of items written to the current wrap log file,
593 header inclusive.
594 {no_items, integer() >= 0}:
596 The total number of items in all wrap log files.
597 {current_file, integer()}:
599 The ordinal for the current wrap log file in the range
600 1..MaxNoFiles, where MaxNoFiles is specified by the open/1
601 option size or set by change_size/2.
602 {no_overflows, {SinceLogWasOpened, SinceLastInfo}}:
604 SinceLogWasOpened (SinceLastInfo) is the number of times a
605 wrap log file has been filled up and a new one is opened or
606 inc_wrap_file/1 has been called since the disk log was last
607 opened (info/1 was last called). The first time info/2 is
608 called after a log was (re)opened or truncated, the two val‐
609 ues are equal.
610 Notice that functions chunk/2,3, bchunk/2,3, and chunk_step/3 do
612 not affect any value returned by info/1.
613 lclose(Log) -> ok | {error, lclose_error_rsn()}
615 lclose(Log, Node) -> ok | {error, lclose_error_rsn()}
617 Types:
619 Log = log()
621 Node = node()
622 lclose_error_rsn() =
623 no_such_log | {file_error, file:filename(), file_error()}
624 lclose/1 closes a disk log on the current node.
626 lclose/2 closes a disk log on the current node if Node is the
628 current node.
629 lclose(Log) is equivalent to lclose(Log, node()). See also
631 close/1.
632 If no log with the specified name exist on the current node,
634 no_such_log is returned.
635 Note:
637 These functions are deprecated. Use close/1 instead.
638 log(Log, Term) -> ok | {error, Reason :: log_error_rsn()}
641 blog(Log, Bytes) -> ok | {error, Reason :: log_error_rsn()}
643 Types:
645 Log = log()
647 Term = term()
648 Bytes = iodata()
649 log_error_rsn() =
650 no_such_log | nonode |
651 {read_only_mode, log()} |
652 {format_external, log()} |
653 {blocked_log, log()} |
654 {full, log()} |
655 {invalid_header, invalid_header()} |
656 {file_error, file:filename(), file_error()}
657 Synchronously appends a term to a disk log. Returns ok or {er‐
659 ror, Reason} when the term is written to disk. Terms are written
660 by the ordinary write() function of the operating system. Hence,
661 it is not guaranteed that the term is written to disk, it can
662 linger in the operating system kernel for a while. To ensure
663 that the item is written to disk, function sync/1 must be
664 called.
665 log/2 is used for internally formatted logs, and blog/2 for ex‐
667 ternally formatted logs. blog/2 can also be used for internally
668 formatted logs if the binary is constructed with a call to
669 term_to_binary/1.
670 Owners subscribing to notifications are notified of an error
672 with an error_status message if the error reason tag is in‐
673 valid_header or file_error.
674 log_terms(Log, TermList) ->
676 ok | {error, Reason :: log_error_rsn()}
677 blog_terms(Log, BytesList) ->
679 ok | {error, Reason :: log_error_rsn()}
680 Types:
682 Log = log()
684 TermList = [term()]
685 BytesList = [iodata()]
686 log_error_rsn() =
687 no_such_log | nonode |
688 {read_only_mode, log()} |
689 {format_external, log()} |
690 {blocked_log, log()} |
691 {full, log()} |
692 {invalid_header, invalid_header()} |
693 {file_error, file:filename(), file_error()}
694 Synchronously appends a list of items to the log. It is more ef‐
696 ficient to use these functions instead of functions log/2 and
697 blog/2. The specified list is split into as large sublists as
698 possible (limited by the size of wrap log files), and each sub‐
699 list is logged as one single item, which reduces the overhead.
700 log_terms/2 is used for internally formatted logs, and
702 blog_terms/2 for externally formatted logs. blog_terms/2 can
703 also be used for internally formatted logs if the binaries are
704 constructed with calls to term_to_binary/1.
705 Owners subscribing to notifications are notified of an error
707 with an error_status message if the error reason tag is in‐
708 valid_header or file_error.
709 open(ArgL) -> open_ret()
711 Types:
713 ArgL = dlog_options()
715 dlog_options() = [dlog_option()]
716 dlog_option() =
717 {name, Log :: log()} |
718 {file, FileName :: file:filename()} |
719 {linkto, LinkTo :: none | pid()} |
720 {repair, Repair :: true | false | truncate} |
721 {type, Type :: dlog_type()} |
722 {format, Format :: dlog_format()} |
723 {size, Size :: dlog_size()} |
724 {notify, boolean()} |
725 {head, Head :: dlog_head_opt()} |
726 {head_func, MFA :: {atom(), atom(), list()}} |
727 {quiet, boolean()} |
728 {mode, Mode :: dlog_mode()}
729 open_ret() =
730 {ok, Log :: log()} |
731 {repaired,
732 Log :: log(),
733 {recovered, Rec :: integer() >= 0},
734 {badbytes, Bad :: integer() >= 0}} |
735 {error, open_error_rsn()}
736 open_error_rsn() =
737 no_such_log |
738 {badarg, term()} |
739 {size_mismatch,
740 CurrentSize :: dlog_size(),
741 NewSize :: dlog_size()} |
742 {arg_mismatch,
743 OptionName :: dlog_optattr(),
744 CurrentValue :: term(),
745 Value :: term()} |
746 {name_already_open, Log :: log()} |
747 {open_read_write, Log :: log()} |
748 {open_read_only, Log :: log()} |
749 {need_repair, Log :: log()} |
750 {not_a_log_file, FileName :: file:filename()} |
751 {invalid_index_file, FileName :: file:filename()} |
752 {invalid_header, invalid_header()} |
753 {file_error, file:filename(), file_error()} |
754 {node_already_open, Log :: log()}
755 dlog_optattr() =
756 name | file | linkto | repair | type | format | size |
757 notify | head | head_func | mode
758 dlog_size() =
759 infinity |
760 integer() >= 1 |
761 {MaxNoBytes :: integer() >= 1, MaxNoFiles :: integer() >= 1}
762 Parameter ArgL is a list of the following options:
764 {name, Log}:
766 Specifies the log name. This name must be passed on as a pa‐
767 rameter in all subsequent logging operations. A name must
768 always be supplied.
769 {file, FileName}:
771 Specifies the name of the file to be used for logged terms.
772 If this value is omitted and the log name is an atom or a
773 string, the filename defaults to lists:concat([Log, ".LOG"])
774 for halt logs.
775 For wrap logs, this is the base name of the files. Each file
777 in a wrap log is called <base_name>.N, where N is an inte‐
778 ger. Each wrap log also has two files called <base_name>.idx
779 and <base_name>.siz.
780 {linkto, LinkTo}:
782 If LinkTo is a pid, it becomes an owner of the log. If
783 LinkTo is none, the log records that it is used anonymously
784 by some process by incrementing the users counter. By de‐
785 fault, the process that calls open/1 owns the log.
786 {repair, Repair}:
788 If Repair is true, the current log file is repaired, if
789 needed. As the restoration is initiated, a message is output
790 on the error log. If false is specified, no automatic repair
791 is attempted. Instead, the tuple {error, {need_repair, Log}}
792 is returned if an attempt is made to open a corrupt log
793 file. If truncate is specified, the log file becomes trun‐
794 cated, creating an empty log. Defaults to true, which has no
795 effect on logs opened in read-only mode.
796 {type, Type}:
798 The log type. Defaults to halt.
799 {format, Format}:
801 Disk log format. Defaults to internal.
802 {size, Size}:
804 Log size.
805 When a halt log has reached its maximum size, all attempts
807 to log more items are rejected. Defaults to infinity, which
808 for halt implies that there is no maximum size.
809 For wrap logs, parameter Size can be a pair {MaxNoBytes,
811 MaxNoFiles} or infinity. In the latter case, if the files of
812 an existing wrap log with the same name can be found, the
813 size is read from the existing wrap log, otherwise an error
814 is returned.
815 Wrap logs write at most MaxNoBytes bytes on each file and
817 use MaxNoFiles files before starting all over with the first
818 wrap log file. Regardless of MaxNoBytes, at least the header
819 (if there is one) and one item are written on each wrap log
820 file before wrapping to the next file.
821 The first time an existing wrap log is opened, that is, when
823 the disk log process is created, the value of the option
824 size is allowed to differ from the current log size, and the
825 size of the disk log is changed as per change_size/2.
826 When opening an existing wrap log, it is not necessary to
828 supply a value for option size, but if the log is already
829 open, that is, the disk log process exists, the supplied
830 value must equal the current log size, otherwise the tuple
831 {error, {size_mismatch, CurrentSize, NewSize}} is returned.
832 Note:
834 Before Erlang/OTP 24.0, the supplied value of option size was
835 to be equal to the current log size when opening an existing
836 wrap log for the first time, that is, when creating the disk
837 log process.
838 When opening an already open halt log, option size is ig‐
841 nored.
842 {notify, boolean()}:
844 If true, the log owners are notified when certain log events
845 occur. Defaults to false. The owners are sent one of the
846 following messages when an event occurs:
847 {disk_log, Node, Log, {wrap, NoLostItems}}:
849 Sent when a wrap log has filled up one of its files and a
850 new file is opened. NoLostItems is the number of previ‐
851 ously logged items that were lost when truncating existing
852 files.
853 {disk_log, Node, Log, {truncated, NoLostItems}}:
855 Sent when a log is truncated or reopened. For halt logs
856 NoLostItems is the number of items written on the log
857 since the disk log process was created. For wrap logs
858 NoLostItems is the number of items on all wrap log files.
859 {disk_log, Node, Log, {read_only, Items}}:
861 Sent when an asynchronous log attempt is made to a log
862 file opened in read-only mode. Items is the items from the
863 log attempt.
864 {disk_log, Node, Log, {blocked_log, Items}}:
866 Sent when an asynchronous log attempt is made to a blocked
867 log that does not queue log attempts. Items is the items
868 from the log attempt.
869 {disk_log, Node, Log, {format_external, Items}}:
871 Sent when function alog/2 or alog_terms/2 is used for in‐
872 ternally formatted logs. Items is the items from the log
873 attempt.
874 {disk_log, Node, Log, full}:
876 Sent when an attempt to log items to a wrap log would
877 write more bytes than the limit set by option size.
878 {disk_log, Node, Log, {error_status, Status}}:
880 Sent when the error status changes. The error status is
881 defined by the outcome of the last attempt to log items to
882 the log, or to truncate the log, or the last use of func‐
883 tion sync/1, inc_wrap_file/1, or change_size/2. Status is
884 either ok or {error, Error}, the former is the initial
885 value.
886 {head, Head}:
888 Specifies a header to be written first on the log file. If
889 the log is a wrap log, the item Head is written first in
890 each new file. Head is to be a term if the format is inter‐
891 nal, otherwise an iodata(). Defaults to none, which means
892 that no header is written first on the file.
893 {head_func, {M,F,A}}:
895 Specifies a function to be called each time a new log file
896 is opened. The call M:F(A) is assumed to return {ok, Head}.
897 The item Head is written first in each file. Head is to be a
898 term if the format is internal, otherwise an iodata().
899 {mode, Mode}:
901 Specifies if the log is to be opened in read-only or read-
902 write mode. Defaults to read_write.
903 {quiet, Boolean}:
905 Specifies if messages will be sent to error_logger on recov‐
906 erable errors with the log files. Defaults to false.
907 open/1 returns {ok, Log} if the log file is successfully opened.
909 If the file is successfully repaired, the tuple {repaired, Log,
910 {recovered, Rec}, {badbytes, Bad}} is returned, where Rec is the
911 number of whole Erlang terms found in the file and Bad is the
912 number of bytes in the file that are non-Erlang terms.
913 When a disk log is opened in read-write mode, any existing log
915 file is checked for. If there is none, a new empty log is cre‐
916 ated, otherwise the existing file is opened at the position af‐
917 ter the last logged item, and the logging of items starts from
918 there. If the format is internal and the existing file is not
919 recognized as an internally formatted log, a tuple {error,
920 {not_a_log_file, FileName}} is returned.
921 open/1 cannot be used for changing the values of options of an
923 open log. When there are prior owners or users of a log, all op‐
924 tion values except name, linkto, and notify are only checked
925 against the values supplied before as option values to function
926 open/1, change_header/2, change_notify/3, or change_size/2.
927 Thus, none of the options except name is mandatory. If some
928 specified value differs from the current value, a tuple {error,
929 {arg_mismatch, OptionName, CurrentValue, Value}} is returned.
930 Note:
932 If an owner attempts to open a log as owner once again, it is
933 acknowledged with the return value {ok, Log}, but the state of
934 the disk log is not affected.
935 A log file can be opened more than once by giving different val‐
938 ues to option name or by using the same file when opening a log
939 on different nodes. It is up to the user of module disk_log to
940 ensure that not more than one disk log process has write access
941 to any file, otherwise the file can be corrupted.
942 If an attempt to open a log file for the first time fails, the
944 disk log process terminates with the EXIT message {{failed,Rea‐
945 son},[{disk_log,open,1}]}. The function returns {error, Reason}
946 for all other errors.
947 pid2name(Pid) -> {ok, Log} | undefined
949 Types:
951 Pid = pid()
953 Log = log()
954 Returns the log name given the pid of a disk log process on the
956 current node, or undefined if the specified pid is not a disk
957 log process.
958 This function is meant to be used for debugging only.
960 reopen(Log, File) -> ok | {error, reopen_error_rsn()}
962 reopen(Log, File, Head) -> ok | {error, reopen_error_rsn()}
964 breopen(Log, File, BHead) -> ok | {error, reopen_error_rsn()}
966 Types:
968 Log = log()
970 File = file:filename()
971 Head = term()
972 BHead = iodata()
973 reopen_error_rsn() =
974 no_such_log | nonode |
975 {read_only_mode, log()} |
976 {blocked_log, log()} |
977 {same_file_name, log()} |
978 {invalid_index_file, file:filename()} |
979 {invalid_header, invalid_header()} |
980 {file_error, file:filename(), file_error()}
981 Renames the log file to File and then recreates a new log file.
983 If a wrap log exists, File is used as the base name of the re‐
984 named files. By default the header given to open/1 is written
985 first in the newly opened log file, but if argument Head or
986 BHead is specified, this item is used instead. The header argu‐
987 ment is used only once. Next time a wrap log file is opened, the
988 header given to open/1 is used.
989 reopen/2,3 are used for internally formatted logs, and breopen/3
991 for externally formatted logs.
992 Owners subscribing to notifications receive a truncate message.
994 Upon failure to reopen the log, the disk log process terminates
996 with the EXIT message {{failed,Error},[{disk_log,Fun,Arity}]}.
997 Other processes having requests queued receive the message
998 {disk_log, Node, {error, disk_log_stopped}}.
999 sync(Log) -> ok | {error, sync_error_rsn()}
1001 Types:
1003 Log = log()
1005 sync_error_rsn() =
1006 no_such_log | nonode |
1007 {read_only_mode, log()} |
1008 {blocked_log, log()} |
1009 {file_error, file:filename(), file_error()}
1010 Ensures that the contents of the log are written to the disk.
1012 This is usually a rather expensive operation.
1013 truncate(Log) -> ok | {error, trunc_error_rsn()}
1015 truncate(Log, Head) -> ok | {error, trunc_error_rsn()}
1017 btruncate(Log, BHead) -> ok | {error, trunc_error_rsn()}
1019 Types:
1021 Log = log()
1023 Head = term()
1024 BHead = iodata()
1025 trunc_error_rsn() =
1026 no_such_log | nonode |
1027 {read_only_mode, log()} |
1028 {blocked_log, log()} |
1029 {invalid_header, invalid_header()} |
1030 {file_error, file:filename(), file_error()}
1031 Removes all items from a disk log. If argument Head or BHead is
1033 specified, this item is written first in the newly truncated
1034 log, otherwise the header given to open/1 is used. The header
1035 argument is used only once. Next time a wrap log file is opened,
1036 the header given to open/1 is used.
1037 truncate/1 is used for both internally and externally formatted
1039 logs.
1040 truncate/2 is used for internally formatted logs, and btrun‐
1042 cate/2 for externally formatted logs.
1043 Owners subscribing to notifications receive a truncate message.
1045 If the attempt to truncate the log fails, the disk log process
1047 terminates with the EXIT message {{failed,Rea‐
1048 son},[{disk_log,Fun,Arity}]}. Other processes having requests
1049 queued receive the message {disk_log, Node, {error,
1050 disk_log_stopped}}.
1051 unblock(Log) -> ok | {error, unblock_error_rsn()}
1053 Types:
1055 Log = log()
1057 unblock_error_rsn() =
1058 no_such_log | nonode |
1059 {not_blocked, log()} |
1060 {not_blocked_by_pid, log()}
1061 Unblocks a log. A log can only be unblocked by the blocking
1063 process.
1064
1066 file(3), wrap_log_reader(3)
1067Ericsson AB kernel 8.3.2 disk_log(3)