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 Three 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 rotate logs:
25 Uses a sequence of rotate log files of limited size. As a log file
26 is filled up, it is rotated and then compressed. There is one ac‐
27 tive log file and upto the configured number of compressed log
28 files. Only externally formatted logs are supported. It follows the
29 same naming convention as the handler logger_std_h for Logger. For
30 more details about the naming convention check the file parameter
31 for open/1.
32 It follows the same naming convention as that for the compressed
34 files for Linux's logrotate and BSD's newsyslog.
35 For efficiency reasons, items are always written to files as binaries.
37 Two formats of the log files are supported:
39 internal format:
41 Supports automatic repair of log files that are not properly closed
42 and enables efficient reading of logged items in chunks using a set
43 of functions defined in this module. This is the only way to read
44 internally formatted logs. An item logged to an internally format‐
45 ted log must not occupy more than 4 GB of disk space (the size must
46 fit in 4 bytes).
47 external format:
49 Leaves it up to the user to read and interpret the logged data. The
50 disk_log module cannot repair externally formatted logs.
51 For each open disk log, one process handles requests made to the disk
53 log. This process is created when open/1 is called, provided there ex‐
54 ists no process handling the disk log. A process that opens a disk log
55 can be an owner or an anonymous user of the disk log. Each owner is
56 linked to the disk log process, and an owner can close the disk log ei‐
57 ther explicitly (by calling close/1) or by terminating.
58 Owners can subscribe to notifications, messages of the form {disk_log,
60 Node, Log, Info}, which are sent from the disk log process when certain
61 events occur, see the functions and in particular the open/1 option no‐
62 tify. A log can have many owners, but a process cannot own a log more
63 than once. However, the same process can open the log as a user more
64 than once.
65 For a disk log process to close its file properly and terminate, it
67 must be closed by its owners and once by some non-owner process for
68 each time the log was used anonymously. The users are counted and there
69 must not be any users left when the disk log process terminates.
70 Items can be logged synchronously by using functions log/2, blog/2,
72 log_terms/2, and blog_terms/2. For each of these functions, the caller
73 is put on hold until the items are logged (but not necessarily written,
74 use sync/1 to ensure that). By adding an a to each of the mentioned
75 function names, we get functions that log items asynchronously. Asyn‐
76 chronous functions do not wait for the disk log process to write the
77 items to the file, but return the control to the caller more or less
78 immediately.
79 When using the internal format for logs, use functions log/2,
81 log_terms/2, alog/2, and alog_terms/2. These functions log one or more
82 Erlang terms. By prefixing each of the functions with a b (for "bi‐
83 nary"), we get the corresponding blog() functions for the external for‐
84 mat. These functions log one or more chunks of bytes. For example, to
85 log the string "hello" in ASCII format, you can use disk_log:blog(Log,
86 "hello"), or disk_log:blog(Log, list_to_binary("hello")). The two al‐
87 ternatives are equally efficient.
88 The blog() functions can also be used for internally formatted logs,
90 but in this case they must be called with binaries constructed with
91 calls to term_to_binary/1. There is no check to ensure this, it is en‐
92 tirely the responsibility of the caller. If these functions are called
93 with binaries that do not correspond to Erlang terms, the chunk/2,3 and
94 automatic repair functions fail. The corresponding terms (not the bina‐
95 ries) are returned when chunk/2,3 is called.
96 An open disk log is only accessible from the node where the disk log
98 process runs. All processes on the node where the disk log process runs
99 can log items or otherwise change, inspect, or close the log.
100 Errors are reported differently for asynchronous log attempts and other
102 uses of the disk_log module. When used synchronously, this module
103 replies with an error message, but when called asynchronously, this
104 module does not know where to send the error message. Instead, owners
105 subscribing to notifications receive an error_status message.
106 The disk_log module does not report errors to the error_logger module.
108 It is up to the caller to decide whether to employ the error logger.
109 Function format_error/1 can be used to produce readable messages from
110 error replies. However, information events are sent to the error logger
111 in two situations, namely when a log is repaired, or when a file is
112 missing while reading chunks.
113 Error message no_such_log means that the specified disk log is not
115 open. Nothing is said about whether the disk log files exist or not.
116 Note:
118 If an attempt to reopen or truncate a log fails (see reopen/2,3 and
119 truncate/1,2) the disk log process terminates immediately. Before the
120 process terminates, links to owners and blocking processes (see
121 block/1,2) are removed. The effect is that the links work in one direc‐
122 tion only. Any process using a disk log must check for error message
123 no_such_log if some other process truncates or reopens the log simulta‐
124 neously.
125
128 log() = term()
129 dlog_size() =
131 infinity |
132 integer() >= 1 |
133 {MaxNoBytes :: integer() >= 1, MaxNoFiles :: integer() >= 1}
134 dlog_format() = external | internal
136 dlog_head_opt() = none | term() | iodata()
138 dlog_mode() = read_only | read_write
140 dlog_type() = halt | wrap | rotate
142 continuation()
144 Chunk continuation returned by chunk/2,3, bchunk/2,3, or
146 chunk_step/3.
147 invalid_header() = term()
149 file_error() = term()
151 next_file_error_rsn() =
153 no_such_log | nonode |
154 {read_only_mode, log()} |
155 {blocked_log, log()} |
156 {halt_log, log()} |
157 {rotate_log, log()} |
158 {invalid_header, invalid_header()} |
159 {file_error, file:filename(), file_error()}
160
162 all() -> [Log]
163 Types:
165 Log = log()
167 Returns the names of the disk logs accessible on the current
169 node.
170 alog(Log, Term) -> notify_ret()
172 balog(Log, Bytes) -> notify_ret()
174 Types:
176 Log = log()
178 Term = term()
179 Bytes = iodata()
180 notify_ret() = ok | {error, no_such_log}
181 Asynchronously append an item to a disk log. alog/2 is used for
183 internally formatted logs and balog/2 for externally formatted
184 logs. balog/2 can also be used for internally formatted logs if
185 the binary is constructed with a call to term_to_binary/1.
186 Owners subscribing to notifications receive message read_only,
188 blocked_log, or format_external if the item cannot be written on
189 the log, and possibly one of the messages wrap, full, or er‐
190 ror_status if an item is written on the log. Message error_sta‐
191 tus is sent if something is wrong with the header function or if
192 a file error occurs.
193 alog_terms(Log, TermList) -> notify_ret()
195 balog_terms(Log, ByteList) -> notify_ret()
197 Types:
199 Log = log()
201 TermList = [term()]
202 ByteList = [iodata()]
203 notify_ret() = ok | {error, no_such_log}
204 Asynchronously append a list of items to a disk log.
206 alog_terms/2 is used for internally formatted logs and ba‐
207 log_terms/2 for externally formatted logs. balog_terms/2 can
208 also be used for internally formatted logs if the binaries are
209 constructed with calls to term_to_binary/1.
210 Owners subscribing to notifications receive message read_only,
212 blocked_log, or format_external if the items cannot be written
213 on the log, and possibly one or more of the messages wrap, full,
214 and error_status if items are written on the log. Message er‐
215 ror_status is sent if something is wrong with the header func‐
216 tion or if a file error occurs.
217 block(Log) -> ok | {error, block_error_rsn()}
219 block(Log, QueueLogRecords) -> ok | {error, block_error_rsn()}
221 Types:
223 Log = log()
225 QueueLogRecords = boolean()
226 block_error_rsn() = no_such_log | nonode | {blocked_log, log()}
227 With a call to block/1,2 a process can block a log. If the
229 blocking process is not an owner of the log, a temporary link is
230 created between the disk log process and the blocking process.
231 The link ensures that the disk log is unblocked if the blocking
232 process terminates without first closing or unblocking the log.
233 Any process can probe a blocked log with info/1 or close it with
235 close/1. The blocking process can also use functions chunk/2,3,
236 bchunk/2,3, chunk_step/3, and unblock/1 without being affected
237 by the block. Any other attempt than those mentioned so far to
238 update or read a blocked log suspends the calling process until
239 the log is unblocked or returns error message {blocked_log,
240 Log}, depending on whether the value of QueueLogRecords is true
241 or false. QueueLogRecords defaults to true, which is used by
242 block/1.
243 change_header(Log, Header) -> ok | {error, Reason}
245 Types:
247 Log = log()
249 Header =
250 {head, dlog_head_opt()} |
251 {head_func, MFA :: {atom(), atom(), list()}}
252 Reason =
253 no_such_log | nonode |
254 {read_only_mode, Log} |
255 {blocked_log, Log} |
256 {badarg, head}
257 Changes the value of option head or head_func for an owner of a
259 disk log.
260 change_notify(Log, Owner, Notify) -> ok | {error, Reason}
262 Types:
264 Log = log()
266 Owner = pid()
267 Notify = boolean()
268 Reason =
269 no_such_log | nonode |
270 {blocked_log, Log} |
271 {badarg, notify} |
272 {not_owner, Owner}
273 Changes the value of option notify for an owner of a disk log.
275 change_size(Log, Size) -> ok | {error, Reason}
277 Types:
279 Log = log()
281 Size = dlog_size()
282 Reason =
283 no_such_log | nonode |
284 {read_only_mode, Log} |
285 {blocked_log, Log} |
286 {new_size_too_small, Log, CurrentSize :: integer() >= 1}
287 |
288 {badarg, size} |
289 {file_error, file:filename(), file_error()}
290 Changes the size of an open log. For a halt log, the size can
292 always be increased, but it cannot be decreased to something
293 less than the current file size.
294 For a wrap or rotate log, both the size and the number of files
296 can always be increased, as long as the number of files does not
297 exceed 65000. For wrap logs, if the maximum number of files is
298 decreased, the change is not valid until the current file is
299 full and the log wraps to the next file. The redundant files are
300 removed the next time the log wraps around, that is, starts to
301 log to file number 1.
302 As an example, assume that the old maximum number of files is 10
304 and that the new maximum number of files is 6. If the current
305 file number is not greater than the new maximum number of files,
306 files 7-10 are removed when file 6 is full and the log starts to
307 write to file number 1 again. Otherwise, the files greater than
308 the current file are removed when the current file is full (for
309 example, if the current file is 8, files 9 and 10 are removed).
310 The files between the new maximum number of files and the cur‐
311 rent file (that is, files 7 and 8) are removed the next time
312 file 6 is full.
313 For rotate logs, if the maximum number of files is decreased,
315 the redundant files are deleted instantly.
316 If the size of the files is decreased, the change immediately
318 affects the current log. It does not change the size of log
319 files already full until the next time they are used.
320 If the log size is decreased, for example, to save space, func‐
322 tion next_file/1, can be used to force the log to wrap.
323 chunk(Log, Continuation) -> chunk_ret()
325 chunk(Log, Continuation, N) -> chunk_ret()
327 bchunk(Log, Continuation) -> bchunk_ret()
329 bchunk(Log, Continuation, N) -> bchunk_ret()
331 Types:
333 Log = log()
335 Continuation = start | continuation()
336 N = integer() >= 1 | infinity
337 chunk_ret() =
338 {Continuation2 :: continuation(), Terms :: [term()]} |
339 {Continuation2 :: continuation(),
340 Terms :: [term()],
341 Badbytes :: integer() >= 0} |
342 eof |
343 {error, Reason :: chunk_error_rsn()}
344 bchunk_ret() =
345 {Continuation2 :: continuation(), Binaries :: [binary()]} |
346 {Continuation2 :: continuation(),
347 Binaries :: [binary()],
348 Badbytes :: integer() >= 0} |
349 eof |
350 {error, Reason :: chunk_error_rsn()}
351 chunk_error_rsn() =
352 no_such_log |
353 {format_external, log()} |
354 {blocked_log, log()} |
355 {badarg, continuation} |
356 {not_internal_wrap, log()} |
357 {corrupt_log_file, FileName :: file:filename()} |
358 {file_error, file:filename(), file_error()}
359 Efficiently reads the terms that are appended to an internally
361 formatted log. It minimizes disk I/O by reading 64 kilobyte
362 chunks from the file. Functions bchunk/2,3 return the binaries
363 read from the file, they do not call binary_to_term(). Apart
364 from that, they work just like chunk/2,3.
365 The first time chunk() (or bchunk()) is called, an initial con‐
367 tinuation, the atom start, must be provided.
368 When chunk/3 is called, N controls the maximum number of terms
370 that are read from the log in each chunk. Defaults to infinity,
371 which means that all the terms contained in the 64 kilobyte
372 chunk are read. If less than N terms are returned, this does not
373 necessarily mean that the end of the file is reached.
374 chunk() returns a tuple {Continuation2, Terms}, where Terms is a
376 list of terms found in the log. Continuation2 is yet another
377 continuation, which must be passed on to any subsequent calls to
378 chunk(). With a series of calls to chunk(), all terms from a log
379 can be extracted.
380 chunk() returns a tuple {Continuation2, Terms, Badbytes} if the
382 log is opened in read-only mode and the read chunk is corrupt.
383 Badbytes is the number of bytes in the file found not to be Er‐
384 lang terms in the chunk. Notice that the log is not repaired.
385 When trying to read chunks from a log opened in read-write mode,
386 tuple {corrupt_log_file, FileName} is returned if the read chunk
387 is corrupt.
388 chunk() returns eof when the end of the log is reached, or {er‐
390 ror, Reason} if an error occurs. If a wrap log file is missing,
391 a message is output on the error log.
392 When chunk/2,3 is used with wrap logs, the returned continuation
394 might not be valid in the next call to chunk(). This is because
395 the log can wrap and delete the file into which the continuation
396 points. To prevent this, the log can be blocked during the
397 search.
398 chunk_info(Continuation) -> InfoList | {error, Reason}
400 Types:
402 Continuation = continuation()
404 InfoList = [{node, Node :: node()}, ...]
405 Reason = {no_continuation, Continuation}
406 Returns the pair {node, Node}, describing the chunk continuation
408 returned by chunk/2,3, bchunk/2,3, or chunk_step/3.
409 Terms are read from the disk log running on Node.
411 chunk_step(Log, Continuation, Step) ->
413 {ok, any()} | {error, Reason}
414 Types:
416 Log = log()
418 Continuation = start | continuation()
419 Step = integer()
420 Reason =
421 no_such_log | end_of_log |
422 {format_external, Log} |
423 {blocked_log, Log} |
424 {badarg, continuation} |
425 {file_error, file:filename(), file_error()}
426 Can be used with chunk/2,3 and bchunk/2,3 to search through an
428 internally formatted wrap log. It takes as argument a continua‐
429 tion as returned by chunk/2,3, bchunk/2,3, or chunk_step/3, and
430 steps forward (or backward) Step files in the wrap log. The con‐
431 tinuation returned, points to the first log item in the new cur‐
432 rent file.
433 If atom start is specified as continuation, the first file of
435 the wrap log is chosen as the new current file.
436 If the wrap log is not full because all files are not yet used,
438 {error, end_of_log} is returned if trying to step outside the
439 log.
440 close(Log) -> ok | {error, close_error_rsn()}
442 Types:
444 Log = log()
446 close_error_rsn() =
447 no_such_log | nonode |
448 {file_error, file:filename(), file_error()}
449 Closes a disk log properly. An internally formatted log must be
451 closed before the Erlang system is stopped. Otherwise, the log
452 is regarded as unclosed and the automatic repair procedure is
453 activated next time the log is opened.
454 The disk log process is not terminated as long as there are own‐
456 ers or users of the log. All owners must close the log, possibly
457 by terminating. Also, any other process, not only the processes
458 that have opened the log anonymously, can decrement the users
459 counter by closing the log. Attempts to close a log by a process
460 that is not an owner are ignored if there are no users.
461 If the log is blocked by the closing process, the log is also
463 unblocked.
464 format_error(Error) -> io_lib:chars()
466 Types:
468 Error = term()
470 Given the error returned by any function in this module, this
472 function returns a descriptive string of the error in English.
473 For file errors, function format_error/1 in module file is
474 called.
475 inc_wrap_file(Log) -> ok | {error, inc_wrap_error_rsn()}
477 Types:
479 Log = log()
481 inc_wrap_error_rsn() = next_file_error_rsn()
482 invalid_header() = term()
483 Forces the internally formatted disk log to start logging to the
485 next log file. It can be used, for example, with change_size/2
486 to reduce the amount of disk space allocated by the disk log.
487 Owners subscribing to notifications normally receive a wrap mes‐
489 sage, but if an error occurs with a reason tag of invalid_header
490 or file_error, an error_status message is sent.
491 info(Log) -> InfoList | {error, no_such_log}
493 Types:
495 Log = log()
497 InfoList = [dlog_info()]
498 dlog_info() =
499 {name, Log :: log()} |
500 {file, File :: file:filename()} |
501 {type, Type :: dlog_type()} |
502 {format, Format :: dlog_format()} |
503 {size, Size :: dlog_size()} |
504 {mode, Mode :: dlog_mode()} |
505 {owners, [{pid(), Notify :: boolean()}]} |
506 {users, Users :: integer() >= 0} |
507 {status,
508 Status :: ok | {blocked, QueueLogRecords :: boolean()}} |
509 {node, Node :: node()} |
510 {head,
511 Head ::
512 none |
513 {head, binary()} |
514 (MFA :: {atom(), atom(), list()})} |
515 {no_written_items, NoWrittenItems :: integer() >= 0} |
516 {full, Full :: boolean} |
517 {no_current_bytes, integer() >= 0} |
518 {no_current_items, integer() >= 0} |
519 {no_items, integer() >= 0} |
520 {current_file, integer() >= 1} |
521 {no_overflows,
522 {SinceLogWasOpened :: integer() >= 0,
523 SinceLastInfo :: integer() >= 0}}
524 Returns a list of {Tag, Value} pairs describing a log running on
526 the node.
527 The following pairs are returned for all logs:
529 {name, Log}:
531 Log is the log name as specified by the open/1 option name.
532 {file, File}:
534 For halt logs File is the filename, and for wrap logs File
535 is the base name.
536 {type, Type}:
538 Type is the log type as specified by the open/1 option type.
539 {format, Format}:
541 Format is the log format as specified by the open/1 option
542 format.
543 {size, Size}:
545 Size is the log size as specified by the open/1 option size,
546 or the size set by change_size/2. The value set by
547 change_size/2 is reflected immediately.
548 {mode, Mode}:
550 Mode is the log mode as specified by the open/1 option mode.
551 {owners, [{pid(), Notify}]}:
553 Notify is the value set by the open/1 option notify or func‐
554 tion change_notify/3 for the owners of the log.
555 {users, Users}:
557 Users is the number of anonymous users of the log, see the
558 open/1 option linkto.
559 {status, Status}:
561 Status is ok or {blocked, QueueLogRecords} as set by func‐
562 tions block/1,2 and unblock/1.
563 {node, Node}:
565 The information returned by the current invocation of func‐
566 tion info/1 is gathered from the disk log process running on
567 Node.
568 The following pairs are returned for all logs opened in
570 read_write mode:
571 {head, Head}:
573 Depending on the value of the open/1 options head and
574 head_func, or set by function change_header/2, the value of
575 Head is none (default), {head, H} (head option), or {M,F,A}
576 (head_func option).
577 {no_written_items, NoWrittenItems}:
579 NoWrittenItems is the number of items written to the log
580 since the disk log process was created.
581 The following pair is returned for halt logs opened in
583 read_write mode:
584 {full, Full}:
586 Full is true or false depending on whether the halt log is
587 full or not.
588 The following pairs are returned for wrap logs opened in
590 read_write mode:
591 {no_current_bytes, integer() >= 0}:
593 The number of bytes written to the current wrap log file.
594 {no_current_items, integer() >= 0}:
596 The number of items written to the current wrap log file,
597 header inclusive.
598 {no_items, integer() >= 0}:
600 The total number of items in all wrap log files.
601 {current_file, integer()}:
603 The ordinal for the current wrap log file in the range
604 1..MaxNoFiles, where MaxNoFiles is specified by the open/1
605 option size or set by change_size/2.
606 {no_overflows, {SinceLogWasOpened, SinceLastInfo}}:
608 SinceLogWasOpened (SinceLastInfo) is the number of times a
609 wrap log file has been filled up and a new one is opened or
610 inc_wrap_file/1 has been called since the disk log was last
611 opened (info/1 was last called). The first time info/2 is
612 called after a log was (re)opened or truncated, the two val‐
613 ues are equal.
614 Notice that functions chunk/2,3, bchunk/2,3, and chunk_step/3 do
616 not affect any value returned by info/1.
617 log(Log, Term) -> ok | {error, Reason :: log_error_rsn()}
619 blog(Log, Bytes) -> ok | {error, Reason :: log_error_rsn()}
621 Types:
623 Log = log()
625 Term = term()
626 Bytes = iodata()
627 log_error_rsn() =
628 no_such_log | nonode |
629 {read_only_mode, log()} |
630 {format_external, log()} |
631 {blocked_log, log()} |
632 {full, log()} |
633 {invalid_header, invalid_header()} |
634 {file_error, file:filename(), file_error()}
635 Synchronously appends a term to a disk log. Returns ok or {er‐
637 ror, Reason} when the term is written to disk. Terms are written
638 by the ordinary write() function of the operating system. Hence,
639 it is not guaranteed that the term is written to disk, it can
640 linger in the operating system kernel for a while. To ensure
641 that the item is written to disk, function sync/1 must be
642 called.
643 log/2 is used for internally formatted logs, and blog/2 for ex‐
645 ternally formatted logs. blog/2 can also be used for internally
646 formatted logs if the binary is constructed with a call to
647 term_to_binary/1.
648 Owners subscribing to notifications are notified of an error
650 with an error_status message if the error reason tag is in‐
651 valid_header or file_error.
652 log_terms(Log, TermList) ->
654 ok | {error, Reason :: log_error_rsn()}
655 blog_terms(Log, BytesList) ->
657 ok | {error, Reason :: log_error_rsn()}
658 Types:
660 Log = log()
662 TermList = [term()]
663 BytesList = [iodata()]
664 log_error_rsn() =
665 no_such_log | nonode |
666 {read_only_mode, log()} |
667 {format_external, log()} |
668 {blocked_log, log()} |
669 {full, log()} |
670 {invalid_header, invalid_header()} |
671 {file_error, file:filename(), file_error()}
672 Synchronously appends a list of items to the log. It is more ef‐
674 ficient to use these functions instead of functions log/2 and
675 blog/2. The specified list is split into as large sublists as
676 possible (limited by the size of wrap log files), and each sub‐
677 list is logged as one single item, which reduces the overhead.
678 log_terms/2 is used for internally formatted logs, and
680 blog_terms/2 for externally formatted logs. blog_terms/2 can
681 also be used for internally formatted logs if the binaries are
682 constructed with calls to term_to_binary/1.
683 Owners subscribing to notifications are notified of an error
685 with an error_status message if the error reason tag is in‐
686 valid_header or file_error.
687 next_file(Log) -> ok | {error, next_file_error_rsn()}
689 Types:
691 Log = log()
693 next_file_error_rsn() =
694 no_such_log | nonode |
695 {read_only_mode, log()} |
696 {blocked_log, log()} |
697 {halt_log, log()} |
698 {rotate_log, log()} |
699 {invalid_header, invalid_header()} |
700 {file_error, file:filename(), file_error()}
701 invalid_header() = term()
702 For wrap logs, it forces the disk log to start logging to the
704 next log file. It can be used, for example, with change_size/2
705 to reduce the amount of disk space allocated by the disk log.
706 Owners subscribing to notifications normally receive a wrap mes‐
708 sage, but if an error occurs with a reason tag of invalid_header
709 or file_error, an error_status message is sent.
710 For rotate logs, it forces rotation of the currently active log
712 file, compresses it and opens a new active file for logging.
713 open(ArgL) -> open_ret()
715 Types:
717 ArgL = dlog_options()
719 dlog_options() = [dlog_option()]
720 dlog_option() =
721 {name, Log :: log()} |
722 {file, FileName :: file:filename()} |
723 {linkto, LinkTo :: none | pid()} |
724 {repair, Repair :: true | false | truncate} |
725 {type, Type :: dlog_type()} |
726 {format, Format :: dlog_format()} |
727 {size, Size :: dlog_size()} |
728 {notify, boolean()} |
729 {head, Head :: dlog_head_opt()} |
730 {head_func, MFA :: {atom(), atom(), list()}} |
731 {quiet, boolean()} |
732 {mode, Mode :: dlog_mode()}
733 open_ret() =
734 {ok, Log :: log()} |
735 {repaired,
736 Log :: log(),
737 {recovered, Rec :: integer() >= 0},
738 {badbytes, Bad :: integer() >= 0}} |
739 {error, open_error_rsn()}
740 open_error_rsn() =
741 no_such_log |
742 {badarg, term()} |
743 {size_mismatch,
744 CurrentSize :: dlog_size(),
745 NewSize :: dlog_size()} |
746 {arg_mismatch,
747 OptionName :: dlog_optattr(),
748 CurrentValue :: term(),
749 Value :: term()} |
750 {name_already_open, Log :: log()} |
751 {open_read_write, Log :: log()} |
752 {open_read_only, Log :: log()} |
753 {need_repair, Log :: log()} |
754 {not_a_log_file, FileName :: file:filename()} |
755 {invalid_index_file, FileName :: file:filename()} |
756 {invalid_header, invalid_header()} |
757 {file_error, file:filename(), file_error()} |
758 {node_already_open, Log :: log()}
759 dlog_optattr() =
760 name | file | linkto | repair | type | format | size |
761 notify | head | head_func | mode
762 dlog_size() =
763 infinity |
764 integer() >= 1 |
765 {MaxNoBytes :: integer() >= 1, MaxNoFiles :: integer() >= 1}
766 Parameter ArgL is a list of the following options:
768 {name, Log}:
770 Specifies the log name. This name must be passed on as a pa‐
771 rameter in all subsequent logging operations. A name must
772 always be supplied.
773 {file, FileName}:
775 Specifies the name of the file to be used for logged terms.
776 If this value is omitted and the log name is an atom or a
777 string, the filename defaults to lists:concat([Log, ".LOG"])
778 for halt logs.
779 For wrap logs, this is the base name of the files. Each file
781 in a wrap log is called <FileName>.N, where N is an integer.
782 Each wrap log also has two files called <FileName>.idx and
783 <FileName>.siz.
784 For rotate logs, this is the name of the active log file.
786 The compressed files are named as <FileName>.N.gz, where N
787 is an integer and <FileName>.0.gz is the latest compressed
788 log file. All the compressed files are renamed at each rota‐
789 tion so that the latest files have the smallest index. The
790 maximum value for N is the value of MaxNoFiles minus 1.
791 {linkto, LinkTo}:
793 If LinkTo is a pid, it becomes an owner of the log. If
794 LinkTo is none, the log records that it is used anonymously
795 by some process by incrementing the users counter. By de‐
796 fault, the process that calls open/1 owns the log.
797 {repair, Repair}:
799 If Repair is true, the current log file is repaired, if
800 needed. As the restoration is initiated, a message is output
801 on the error log. If false is specified, no automatic repair
802 is attempted. Instead, the tuple {error, {need_repair, Log}}
803 is returned if an attempt is made to open a corrupt log
804 file. If truncate is specified, the log file becomes trun‐
805 cated, creating an empty log, regardless of previous con‐
806 tent. Defaults to true, which has no effect on logs opened
807 in read-only mode.
808 {type, Type}:
810 The log type. Defaults to halt.
811 {format, Format}:
813 Disk log format. Defaults to internal.
814 {size, Size}:
816 Log size.
817 When a halt log has reached its maximum size, all attempts
819 to log more items are rejected. Defaults to infinity, which
820 for halt implies that there is no maximum size.
821 For wrap and rotate logs, parameter Size can be a pair
823 {MaxNoBytes, MaxNoFiles}. For wrap logs it can also be in‐
824 finity. In the latter case, if the files of an existing wrap
825 log with the same name can be found, the size is read from
826 the existing wrap log, otherwise an error is returned.
827 Wrap logs write at most MaxNoBytes bytes on each file and
829 use MaxNoFiles files before starting all over with the first
830 wrap log file. Regardless of MaxNoBytes, at least the header
831 (if there is one) and one item are written on each wrap log
832 file before wrapping to the next file.
833 The first time an existing wrap log is opened, that is, when
835 the disk log process is created, the value of the option
836 size is allowed to differ from the current log size, and the
837 size of the disk log is changed as per change_size/2.
838 When opening an existing wrap log, it is not necessary to
840 supply a value for option size, but if the log is already
841 open, that is, the disk log process exists, the supplied
842 value must equal the current log size, otherwise the tuple
843 {error, {size_mismatch, CurrentSize, NewSize}} is returned.
844 Note:
846 Before Erlang/OTP 24.0, the supplied value of option size was
847 to be equal to the current log size when opening an existing
848 wrap log for the first time, that is, when creating the disk
849 log process.
850 Rotate logs write at most MaxNoBytes bytes on the active log
853 file and keep the latest MaxNoFiles compressed files. Re‐
854 gardless of MaxNoBytes, at least the header (if there is
855 one) and one item are written on each rotate log file before
856 rotation.
857 When opening an already open halt log, option size is ig‐
859 nored.
860 {notify, boolean()}:
862 If true, the log owners are notified when certain log events
863 occur. Defaults to false. The owners are sent one of the
864 following messages when an event occurs:
865 {disk_log, Node, Log, {wrap, NoLostItems}}:
867 Sent when a wrap log has filled up one of its files and a
868 new file is opened. NoLostItems is the number of previ‐
869 ously logged items that were lost when truncating existing
870 files.
871 {disk_log, Node, Log, {truncated, NoLostItems}}:
873 Sent when a log is truncated or reopened. For halt logs
874 NoLostItems is the number of items written on the log
875 since the disk log process was created. For wrap logs
876 NoLostItems is the number of items on all wrap log files.
877 {disk_log, Node, Log, {read_only, Items}}:
879 Sent when an asynchronous log attempt is made to a log
880 file opened in read-only mode. Items is the items from the
881 log attempt.
882 {disk_log, Node, Log, {blocked_log, Items}}:
884 Sent when an asynchronous log attempt is made to a blocked
885 log that does not queue log attempts. Items is the items
886 from the log attempt.
887 {disk_log, Node, Log, {format_external, Items}}:
889 Sent when function alog/2 or alog_terms/2 is used for in‐
890 ternally formatted logs. Items is the items from the log
891 attempt.
892 {disk_log, Node, Log, full}:
894 Sent when an attempt to log items to a wrap log would
895 write more bytes than the limit set by option size.
896 {disk_log, Node, Log, {error_status, Status}}:
898 Sent when the error status changes. The error status is
899 defined by the outcome of the last attempt to log items to
900 the log, or to truncate the log, or the last use of func‐
901 tion sync/1, inc_wrap_file/1, or change_size/2. Status is
902 either ok or {error, Error}, the former is the initial
903 value.
904 {head, Head}:
906 Specifies a header to be written first on the log file. If
907 the log is a wrap or rotate log, the item Head is written
908 first in each new file. Head is to be a term if the format
909 is internal, otherwise an iodata(). Defaults to none, which
910 means that no header is written first on the file.
911 {head_func, {M,F,A}}:
913 Specifies a function to be called each time a new log file
914 is opened. The call M:F(A) is assumed to return {ok, Head}.
915 The item Head is written first in each file. Head is to be a
916 term if the format is internal, otherwise an iodata().
917 {mode, Mode}:
919 Specifies if the log is to be opened in read-only or read-
920 write mode. Defaults to read_write.
921 {quiet, Boolean}:
923 Specifies if messages will be sent to error_logger on recov‐
924 erable errors with the log files. Defaults to false.
925 open/1 returns {ok, Log} if the log file is successfully opened.
927 If the file is successfully repaired, the tuple {repaired, Log,
928 {recovered, Rec}, {badbytes, Bad}} is returned, where Rec is the
929 number of whole Erlang terms found in the file and Bad is the
930 number of bytes in the file that are non-Erlang terms.
931 When a disk log is opened in read-write mode, any existing log
933 file is checked for. If there is none, a new empty log is cre‐
934 ated, otherwise the existing file is opened at the position af‐
935 ter the last logged item, and the logging of items starts from
936 there. If the format is internal and the existing file is not
937 recognized as an internally formatted log, a tuple {error,
938 {not_a_log_file, FileName}} is returned.
939 open/1 cannot be used for changing the values of options of an
941 open log. When there are prior owners or users of a log, all op‐
942 tion values except name, linkto, and notify are only checked
943 against the values supplied before as option values to function
944 open/1, change_header/2, change_notify/3, or change_size/2.
945 Thus, none of the options except name is mandatory. If some
946 specified value differs from the current value, a tuple {error,
947 {arg_mismatch, OptionName, CurrentValue, Value}} is returned.
948 Note:
950 If an owner attempts to open a log as owner once again, it is
951 acknowledged with the return value {ok, Log}, but the state of
952 the disk log is not affected.
953 A log file can be opened more than once by giving different val‐
956 ues to option name or by using the same file when opening a log
957 on different nodes. It is up to the user of module disk_log to
958 ensure that not more than one disk log process has write access
959 to any file, otherwise the file can be corrupted.
960 If an attempt to open a log file for the first time fails, the
962 disk log process terminates with the EXIT message {{failed,Rea‐
963 son},[{disk_log,open,1}]}. The function returns {error, Reason}
964 for all other errors.
965 pid2name(Pid) -> {ok, Log} | undefined
967 Types:
969 Pid = pid()
971 Log = log()
972 Returns the log name given the pid of a disk log process on the
974 current node, or undefined if the specified pid is not a disk
975 log process.
976 This function is meant to be used for debugging only.
978 reopen(Log, File) -> ok | {error, reopen_error_rsn()}
980 reopen(Log, File, Head) -> ok | {error, reopen_error_rsn()}
982 breopen(Log, File, BHead) -> ok | {error, reopen_error_rsn()}
984 Types:
986 Log = log()
988 File = file:filename()
989 Head = term()
990 BHead = iodata()
991 reopen_error_rsn() =
992 no_such_log | nonode |
993 {read_only_mode, log()} |
994 {blocked_log, log()} |
995 {same_file_name, log()} |
996 {invalid_index_file, file:filename()} |
997 {invalid_header, invalid_header()} |
998 {file_error, file:filename(), file_error()}
999 Renames the log file to File and then recreates a new log file.
1001 If a wrap/rotate log exists, File is used as the base name of
1002 the renamed files. By default the header given to open/1 is
1003 written first in the newly opened log file, but if argument Head
1004 or BHead is specified, this item is used instead. The header ar‐
1005 gument is used only once. Next time a wrap/rotate log file is
1006 opened, the header given to open/1 is used.
1007 reopen/2,3 are used for internally formatted logs, and breopen/3
1009 for externally formatted logs.
1010 Owners subscribing to notifications receive a truncate message.
1012 Upon failure to reopen the log, the disk log process terminates
1014 with the EXIT message {{failed,Error},[{disk_log,Fun,Arity}]}.
1015 Other processes having requests queued receive the message
1016 {disk_log, Node, {error, disk_log_stopped}}.
1017 sync(Log) -> ok | {error, sync_error_rsn()}
1019 Types:
1021 Log = log()
1023 sync_error_rsn() =
1024 no_such_log | nonode |
1025 {read_only_mode, log()} |
1026 {blocked_log, log()} |
1027 {file_error, file:filename(), file_error()}
1028 Ensures that the contents of the log are written to the disk.
1030 This is usually a rather expensive operation.
1031 truncate(Log) -> ok | {error, trunc_error_rsn()}
1033 truncate(Log, Head) -> ok | {error, trunc_error_rsn()}
1035 btruncate(Log, BHead) -> ok | {error, trunc_error_rsn()}
1037 Types:
1039 Log = log()
1041 Head = term()
1042 BHead = iodata()
1043 trunc_error_rsn() =
1044 no_such_log | nonode |
1045 {read_only_mode, log()} |
1046 {blocked_log, log()} |
1047 {invalid_header, invalid_header()} |
1048 {file_error, file:filename(), file_error()}
1049 Removes all items from a disk log. If argument Head or BHead is
1051 specified, this item is written first in the newly truncated
1052 log, otherwise the header given to open/1 is used. The header
1053 argument is used only once. Next time a wrap/rotate log file is
1054 opened, the header given to open/1 is used.
1055 truncate/1 is used for both internally and externally formatted
1057 logs.
1058 truncate/2 is used for internally formatted logs, and btrun‐
1060 cate/2 for externally formatted logs.
1061 Owners subscribing to notifications receive a truncate message.
1063 If the attempt to truncate the log fails, the disk log process
1065 terminates with the EXIT message {{failed,Rea‐
1066 son},[{disk_log,Fun,Arity}]}. Other processes having requests
1067 queued receive the message {disk_log, Node, {error,
1068 disk_log_stopped}}.
1069 unblock(Log) -> ok | {error, unblock_error_rsn()}
1071 Types:
1073 Log = log()
1075 unblock_error_rsn() =
1076 no_such_log | nonode |
1077 {not_blocked, log()} |
1078 {not_blocked_by_pid, log()}
1079 Unblocks a log. A log can only be unblocked by the blocking
1081 process.
1082
1084 file(3), wrap_log_reader(3)
1085Ericsson AB kernel 9.1 disk_log(3)