1<?xml version="1.0" encoding="utf-8" ?> 2<!DOCTYPE erlref SYSTEM "erlref.dtd"> 3 4<erlref> 5 <header> 6 <copyright> 7 <year>2017</year><year>2020</year> 8 <holder>Ericsson AB. All Rights Reserved.</holder> 9 </copyright> 10 <legalnotice> 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 23 </legalnotice> 24 25 <title>logger_std_h</title> 26 <prepared></prepared> 27 <responsible></responsible> 28 <docno></docno> 29 <approved></approved> 30 <checked></checked> 31 <date></date> 32 <rev>A</rev> 33 <file>logger_std_h.xml</file> 34 </header> 35 <module since="OTP 21.0">logger_std_h</module> 36 <modulesummary>Standard handler for Logger.</modulesummary> 37 38 <description> 39 <p>This is the standard handler for Logger. 40 Multiple instances of this handler can be added to 41 Logger, and each instance prints logs to <c>standard_io</c>, 42 <c>standard_error</c>, or to file.</p> 43 <p>The handler has an overload protection mechanism that keeps the handler 44 process and the Kernel application alive during high loads of log 45 events. How overload protection works, and how to configure it, is 46 described in the 47 <seealso marker="logger_chapter#overload_protection"><c>User's Guide</c> 48 </seealso>.</p> 49 <p>To add a new instance of the standard handler, use 50 <seealso marker="logger#add_handler-3"><c>logger:add_handler/3</c> 51 </seealso>. The handler configuration argument is a map which can contain 52 general configuration parameters, as documented in the 53 <seealso marker="logger_chapter#handler_configuration"><c>User's Guide</c> 54 </seealso>, and handler specific parameters. The specific data 55 is stored in a sub map with the key <c>config</c>, and can contain the 56 following parameters:</p> 57 <taglist> 58 <tag><marker id="type"/><c>type = standard_io | standard_error | file</c></tag> 59 <item> 60 <p>Specifies the log destination.</p> 61 <p>The value is set when the handler is added, and it cannot 62 be changed in runtime.</p> 63 <p>Defaults to <c>standard_io</c>, unless 64 parameter <seealso marker="#file"><c>file</c></seealso> is 65 given, in which case it defaults to <c>file</c>.</p> 66 </item> 67 <tag><marker id="file"/><c>file = </c><seealso marker="file#type-filename"><c>file:filename()</c></seealso></tag> 68 <item> 69 <p>This specifies the name of the log file when the handler is 70 of type <c>file</c>.</p> 71 <p>The value is set when the handler is added, and it cannot 72 be changed in runtime.</p> 73 <p>Defaults to the same name as the handler identity, in the 74 current directory.</p> 75 </item> 76 <tag><marker id="modes"/><c>modes = [</c><seealso marker="file#type-mode"><c>file:mode()</c></seealso><c>]</c></tag> 77 <item> 78 <p>This specifies the file modes to use when opening the log 79 file, 80 see <seealso marker="file#open-2"><c>file:open/2</c></seealso>. 81 If <c>modes</c> are not specified, the default list used 82 is <c>[raw,append,delayed_write]</c>. If <c>modes</c> are 83 specified, the list replaces the default modes list with the 84 following adjustments:</p> 85 <list> 86 <item> 87 If <c>raw</c> is not found in the list, it is added. 88 </item> 89 <item> 90 If none of <c>write</c>, <c>append</c> or <c>exclusive</c> is 91 found in the list, <c>append</c> is added.</item> 92 <item>If none of <c>delayed_write</c> 93 or <c>{delayed_write,Size,Delay}</c> is found in the 94 list, <c>delayed_write</c> is added.</item> 95 </list> 96 <p>Log files are always UTF-8 encoded. The encoding cannot be 97 changed by setting the mode <c>{encoding,Encoding}</c>.</p> 98 <p>The value is set when the handler is added, and it cannot 99 be changed in runtime.</p> 100 <p>Defaults to <c>[raw,append,delayed_write]</c>.</p> 101 </item> 102 <tag><marker id="max_no_bytes"/><c>max_no_bytes = pos_integer() | infinity</c></tag> 103 <item> 104 <p>This parameter specifies if the log file should be rotated 105 or not. The value <c>infinity</c> means the log file will 106 grow indefinitely, while an integer value specifies at which 107 file size (bytes) the file is rotated.</p> 108 <p>Defaults to <c>infinity</c>.</p> 109 </item> 110 <tag><marker id="max_no_files"/><c>max_no_files = non_neg_integer()</c></tag> 111 <item> 112 <p>This parameter specifies the number of rotated log file 113 archives to keep. This has meaning only 114 if <seealso marker="#max_no_bytes"><c>max_no_bytes</c></seealso> 115 is set to an integer value.</p> 116 <p>The log archives are 117 named <c>FileName.0</c>, <c>FileName.1</c>, 118 ... <c>FileName.N</c>, where <c>FileName</c> is the name of 119 the current log file. <c>FileName.0</c> is the newest of the 120 archives. The maximum value for <c>N</c> is the value 121 of <c>max_no_files</c> minus 1.</p> 122 <p>Notice that setting this value to <c>0</c> does not turn of 123 rotation. It only specifies that no archives are kept.</p> 124 <p>Defaults to <c>0</c>.</p> 125 </item> 126 <tag><marker id="compress_on_rotate"/><c>compress_on_rotate = boolean()</c></tag> 127 <item> 128 <p>This parameter specifies if the rotated log file archives 129 shall be compressed or not. If set to <c>true</c>, all 130 archives are compressed with <c>gzip</c>, and renamed 131 to <c>FileName.N.gz</c></p> 132 <p><c>compress_on_rotate</c> has no meaning if <seealso 133 marker="#max_no_bytes"><c>max_no_bytes</c></seealso> has the 134 value <c>infinity</c>.</p> 135 <p>Defaults to <c>false</c>.</p> 136 </item> 137 <tag><marker id="file_check"/><c>file_check = non_neg_integer()</c></tag> 138 <item> 139 <p>When <c>logger_std_h</c> logs to a file, it reads the file 140 information of the log file prior to each write 141 operation. This is to make sure the file still exists and 142 has the same inode as when it was opened. This implies some 143 performance loss, but ensures that no log events are lost in 144 the case when the file has been removed or renamed by an 145 external actor.</p> 146 <p>In order to allow minimizing the performance loss, the 147 <c>file_check</c> parameter can be set to a positive integer 148 value, <c>N</c>. The handler will then skip reading the file 149 information prior to writing, as long as no more 150 than <c>N</c> milliseconds have passed since it was last 151 read.</p> 152 <p>Notice that the risk of loosing log events grows when 153 the <c>file_check</c> value grows.</p> 154 <p>Defaults to 0.</p> 155 </item> 156 <tag><c>filesync_repeat_interval = pos_integer() | no_repeat</c></tag> 157 <item> 158 <p>This value, in milliseconds, specifies how often the handler does 159 a file sync operation to write buffered data to disk. The handler attempts 160 the operation repeatedly, but only performs a new sync if something has 161 actually been logged.</p> 162 <p>If <c>no_repeat</c> is set as value, the repeated file sync operation 163 is disabled, and it is the operating system settings that determine 164 how quickly or slowly data is written to disk. The user can also call 165 the <seealso marker="logger_std_h#filesync-1"><c>filesync/1</c></seealso> 166 function to perform a file sync.</p> 167 <p>Defaults to <c>5000</c> milliseconds.</p> 168 </item> 169 </taglist> 170 <p>Other configuration parameters exist, to be used for customizing 171 the overload protection behaviour. The same parameters are used both in the 172 standard handler and the disk_log handler, and are documented in the 173 <seealso marker="logger_chapter#overload_protection"><c>User's Guide</c> 174 </seealso>.</p> 175 <p>Notice that if changing the configuration of the handler in 176 runtime, the <c>type</c>, <c>file</c>, or <c>modes</c> parameters 177 must not be modified.</p> 178 <p>Example of adding a standard handler:</p> 179 <code type="none"> 180logger:add_handler(my_standard_h, logger_std_h, 181 #{config => #{file => "./system_info.log", 182 filesync_repeat_interval => 1000}}). 183 </code> 184 <p>To set the default handler, that starts initially with 185 the Kernel application, to log to file instead of <c>standard_io</c>, 186 change the Kernel default logger configuration. Example:</p> 187 <code type="none"> 188erl -kernel logger '[{handler,default,logger_std_h, 189 #{config => #{file => "./log.log"}}}]' 190 </code> 191 <p>An example of how to replace the standard handler with a disk_log handler 192 at startup is found in the 193 <seealso marker="logger_disk_log_h"><c>logger_disk_log_h</c></seealso> 194 manual.</p> 195 </description> 196 197 <funcs> 198 199 <func> 200 <name name="filesync" arity="1" clause_i="1" since="OTP 21.0"/> 201 <fsummary>Writes buffered data to disk.</fsummary> 202 <desc> 203 <p>Write buffered data to disk.</p> 204 </desc> 205 </func> 206 207 </funcs> 208 209 <section> 210 <title>See Also</title> 211 <p><seealso marker="logger"><c>logger(3)</c></seealso>, 212 <seealso marker="logger_disk_log_h"> 213 <c>logger_disk_log_h(3)</c></seealso></p> 214 </section> 215</erlref> 216 217 218