doc/dlog_doc.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_SYSTEM_DLOG_DOC_H__
  18 #define __TIZEN_SYSTEM_DLOG_DOC_H__
  19
  20 /**
  21  * @defgroup CAPI_SYSTEM_DLOG Dlog
  22  * @brief The Dlog API provides functions for sending log output.
  23  * @ingroup CAPI_SYSTEM_FRAMEWORK
  24  * @section CAPI_SYSTEM_DLOG_HEADER Required Header
  25  *   \#include <dlog.h>
  26  *
  27  * @section CAPI_SYSTEM_DLOG_OVERVIEW Overview
  28  *
  29 Sending log message to circular buffer. Dlog APIs include Priority and Tag. By using priority and Tag, we can easily filtered messages what we want to see.
  30 <h2 class="pg">priority</h2>
  31 priority level indicates the urgency of log message
  32
  33 <table>
  34 <tr>
  35         <th>Priority</th>
  36         <th>Description</th>
  37 </tr>
  38 <tr>
  39         <td>DLOG_DEBUG</td>
  40         <td>Debug message. - Log message which developer want to check.</td>
  41 </tr>
  42 <tr>
  43         <td>DLOG_INFO</td>
  44         <td>Information message - Normal operational messages. above of this priority will always be logged.</td>
  45 </tr>
  46 <tr>
  47         <td>DLOG_WARN</td>
  48         <td>Warning messages - Not an error, but indication that an error will occur if action is not taken.</td>
  49 </tr>
  50 <tr>
  51         <td>DLOG_ERROR</td>
  52         <td>Error message - Indicate error.</td>
  53 </tr>
  54 </table>
  55
  56 <h2 class="pg">Macro example for useful usage</h2>
  57 The Dlog APIs can be used by defining own macros. The macros can be defined like below examples.
  58 Thus, developers can use appropriate method as a matter of convenience.
  59
  60 @code
  61 #undef LOG_TAG
  62 #define LOG_TAG "APP_TAG"
  63
  64 #define LOGI(fmt, arg...) \
  65         ({ do { \
  66                 dlog_print(DLOG_INFO, LOG_TAG, "%s: %s(%d) > " fmt, __MODULE__, __func__, __LINE__, ##arg); \
  67         } while (0); })
  68 #define LOGW(fmt, arg...) \
  69         ({ do { \
  70                 dlog_print(DLOG_WARN, LOG_TAG, "%s: %s(%d) > " fmt, __MODULE__, __func__, __LINE__, ##arg); \
  71         } while (0); })
  72 #define LOGE(fmt, arg...) \
  73         ({ do { \
  74                 dlog_print(DLOG_ERROR, LOG_TAG, "%s: %s(%d) > " fmt, __MODULE__, __func__, __LINE__, ##arg); \
  75         } while (0); })
  76 @endcode
  77
  78 <h2>Signal</h2>
  79
  80 For technical reasons, libdlog blocks the SIGPIPE signal on initialization. If you need to receive it, feel free to reenable it,
  81 but note that you may receive the SIGPIPE signal spuriously when writing logs.
  82
  83 @section CAPI_SYSTEM_DLOG_UTIL dlogutil CLI
  84
  85 dlogutil is a utility that can be utilized to read stored logs.
  86
  87 The most rudimentary way to use it is to run it with no parameters; it then prints all stored logs to the standard output and awaits more.
  88
  89 Parameters exist to change behaviour:
  90
  91 <table>
  92 <tr><th>PARAM          </th><th>DESCRIPTION</th></tr>
  93 <tr><td>-s             </td><td>Set default filter to *:s (see later for details)</td></tr>
  94 <tr><td>-f filename    </td><td>Output to given file instead of stdout</td></tr>
  95 <tr><td>-r kbytes      </td><td>Rotate log file every this many kilobytes.</td></tr>
  96 <tr><td>-n files       </td><td>Keep this many old rotations</td></tr>
  97 <tr><td>-v             </td><td>Set log output format.</td></tr>
  98 <tr><td>-b buffer      </td><td>Select another buffer</td></tr>
  99 <tr><td>-c             </td><td>Clear the selected buffers</td></tr>
 100 <tr><td>-d             </td><td>Exit when no more logs are currently available</td></tr>
 101 <tr><td>-t count       </td><td>Similar to -d, except only print this many logs from the end</td></tr>
 102 <tr><td>-g             </td><td>Get the size of selected buffers instead of printing logs</td></tr>
 103 <tr><td>-h, --help     </td><td>Show help info</td></tr>
 104 </table>
 105
 106 Additionally, you can specify filters. Filters go behind the parameters and are used to decide which logs are shown.
 107 <br/>
 108 Each log line has priority and a tag. Filters are specified in the format TAG[:PRIO]. Only logs with given tags and priorities are shown.
 109 <br/>
 110 You can specify * as the tag to match anything. Beware: only a single asterisk works that way, asterisk is not otherwise expanded. For example, "T*G" filter will NOT match "TAG", only literal "T*G".
 111 <br/>
 112 If you don't specify any filter, it defaults to *:I<br/>
 113 If you specify just * as the tag, without priority, its priority defaults to D<br/>
 114 If you specify any other tag without priority, the priority defaults to V<br/>
 115
 116 dlogutil allows you to specify buffers. These are:
 117 <table>
 118 <tr><th>NAME</th><th>REMARKS</th></tr>
 119 <tr><td>main</td><td>the default, for general platform logging</td></tr>
 120 <tr><td>system</td><td>for system logs</td></tr>
 121 <tr><td>radio</td><td>for radio logs</td></tr>
 122 <tr><td>apps</td><td>for applications</td></tr>
 123 <tr><td>kmsg</td><td>a copy of kernel messages (dmesg)</td></tr>
 124 </table>
 125
 126 There are also priorities to be specified. These are one letter abbreviations of the following levels:
 127
 128 <table>
 129 <tr><th>LEVEL</th><th>DESCRIPTION</th></tr>
 130 <tr><td>V    </td><td>verbose</td></tr>
 131 <tr><td>D    </td><td>debug</td></tr>
 132 <tr><td>I    </td><td>info</td></tr>
 133 <tr><td>W    </td><td>warning</td></tr>
 134 <tr><td>E    </td><td>error</td></tr>
 135 <tr><td>F    </td><td>fatal</td></tr>
 136 <tr><td>S    </td><td>silent</td></tr>
 137 </table>
 138
 139 Depending on products, some of priorities (e.g., V and D) can be disabled by default to prevent too many logs.
 140
 141 Formats, and what they look like:
 142
 143 <table>
 144 <tr><th>NAME</th>      <th>SPECIFICATION</th>                               <th>EXAMPLE</th></tr>
 145 <tr><td>brief</td>     <td>PRI/TAG(PID): MSG</td>                           <td>E/TEST_APP(123): FOO</td></tr>
 146 <tr><td>process</td>   <td>PRI(PID) MSG (TAG)</td>                          <td>E(123) FOO (TEST_APP)</td></tr>
 147 <tr><td>tag</td>       <td>PRI/TAG: MSG</td>                                <td>E/TEST_APP: FOO</td></tr>
 148 <tr><td>thread</td>    <td>PRI('P'PID, 'T'TID) MSG</td>                     <td>E(P123, T456) FOO</td></tr>
 149 <tr><td>raw</td>        <td>MSG</td>                                         <td>FOO</td></tr>
 150 <tr><td>time</td>      <td>REALTIME PRI/TAG(PID): MSG</td>                  <td>12-31 23:59:59.999 +0200 E/TEST_APP(123): FOO</td></tr>
 151 <tr><td>threadtime</td><td>REALTIME PRI/TAG('P'PID, 'T'TID): MSG</td>       <td>12-31 23:59:59.999 +0200 E/TEST_APP(P123, T456): FOO</td></tr>
 152 <tr><td>kerneltime</td><td>BOOTTIME PRI/TAG('P'PID, 'T'TID): MSG</td>       <td>0.123 E/TEST_APP(P123, T456): FOO</td></tr>
 153 <tr><td>long</td>      <td>[REALTIME PRI/TAG 'P'PID, 'T'TID]<br>MSG<br></td><td>[12-31 23:59:59.999 +0200 E/TEST_APP P123, T456]<br>FOO<br></td></tr>
 154 </table>
 155
 156 */
 157
 158 #endif /* __TIZEN_SYSTEM_DLOG_DOC_H__ */