doc/dlogutil_doc.h

   1 /*
   2  * Copyright (c) 2019-2020 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_DLOGUTIL_DOC_H__
  18 #define __TIZEN_SYSTEM_DLOGUTIL_DOC_H__
  19
  20 /**
  21  * @defgroup CAPI_SYSTEM_DLOGUTIL libdlogutil
  22  * @brief The libdlogutil API provides functions for receiving logs programatically
  23  * @ingroup CAPI_SYSTEM_FRAMEWORK
  24  * @section CAPI_SYSTEM_DLOGUTIL_HEADER Required Header
  25  *   \#include <dlogutil.h>
  26  *
  27  * @section CAPI_SYSTEM_DLOGUTIL_OVERVIEW Overview
  28  *
  29 This API can be used to do everything that the dlogutil CLI can (see @ref CAPI_SYSTEM_DLOG_UTIL). The most important use, however, is to receive the logs of the working Tizen system.
  30
  31 ## Permissions
  32
  33 We used to require libdlogutil user to either have the CAP_SYSLOG capability, or be in the log group. We still require this for some control operations, however it is not needed to have it in order to get logs, which is the most common operation. However, user without CAP_SYSLOG/log group will with high probability only see part of the logs; therefore, we suggest to operate with CAP_SYSLOG/log group.
  34
  35 ## Receiving logs
  36
  37 In order to receive logs, you have to use the dlogutil_get_log() function repeatedly. In order to call it, you need to pass a state struct (#dlogutil_state_s). You can get it by first configuring the library using the config struct (#dlogutil_config_s) and then calling the dlogutil_config_connect() function.
  38
  39 In order to receive the logs, you have to choose one of three modes: dlogutil_config_mode_set_monitor() is meant to monitor the buffer for fresh logs without terminating, dlogutil_config_mode_set_dump() dumps the current logs and quits, and dlogutil_config_mode_set_continuous() combines the two - it returns everything in the buffer and waits for more. If you set no mode, you will be unable to receive logs, but will still be able to fetch information about the buffers.
  40
  41 One possible issue to be aware of is that reading timestamp data in dlog is nontrivial. In particular, the data might be missing, and the functions will return the special missing value. You can, however, avoid this, by using the dlogutil_buffer_* functions. They allow you to receive information about a buffer; in particular, which timestamps are guaranteed to be available, and which timestamp is the default one (which not only is guaranteed to be available, but also is considered by dlog as the best possible representation of the true log sending time). Some of the functions require #dlogutil_state_s to be passed, while others don't.
  42
  43 While receiving logs, you can decide to also sort or filter them. These can be configured by calling the corresponding functions on the #dlogutil_config_s struct. You can also pass a timeout to the dlogutil_get_log() function.
  44
  45 ## Timestamp types
  46
  47 The timestamps can be generated by one of the two types of clocks:
  48
  49 - *monotonic*, which give the time since device boot (which isn't comparable across devices, nor across device boots),
  50 - and *realtime*, which give the wall-clock time (which isn't sortable, being adjustable backwards by a user).
  51
  52 These map directly to `CLOCK_MONOTONIC` and `CLOCK_REALTIME` as described in the `clock_getres(2)` manpage. Additionally, each timestamp can be either generated by:
  53
  54 - the *sender*, which means the timestamp is the close representation of the log sending time,
  55 - or the *receiver*, which means the timestamp tells us when the dlog daemon received the log from the application.
  56
  57 Usually, the *sender* timestamps are preferable, but they aren't always available.
  58
  59 ## Sorting quality
  60
  61 When it comes to sorting, there are two options possible:
  62
  63 - sorting may be unnecessary. This might happen when you disable sorting manually, or when you enable sorting by the default timestamp (by which the data is already sorted). In this case, there will be no additional sorting (because it is unnecessary), so the sorting quality will be as good as the log source provides,
  64 - sorting may be necessary, which happens in all other situations. In this case, sorting will be performed.
  65
  66 Unfortunately, sorting the logs in a perfect way is harder than it might look. This is due to the need to output the logs in a timely manner, as well as the sheer amount of them. What if we receive a log from an hour ago? If we have already output the logs from the last second, it is now impossible to output the new log before them. Therefore, correct sorting is impossible in this case. In theory, this issue does not appear in the dump mode, but in this case, the number of logs might become an issue --- some products based on Tizen have huge amounts of logs generated every second. In this case, we could end up timing out even if `O(nlogn)` sorting is used.
  67
  68 Our solution is to compare only close logs, while returning it as they come. The idea is to hold a circular buffer of logs of a fixed size, and, instead of returning incoming logs immediately, put them into the buffer. As we put the log into the buffer, we immediately make sure it's sorted. This is performant in our case because the input is almost sorted (the timestamps of different types should be correlated with each other, and the input is sorted by one of them).
  69
  70 A log will be finally returned in three cases:
  71
  72 - when the buffer is filled up and we receive a new log, the oldest log in the buffer is returned and removed from the buffer to create space for the new one,
  73 - when the oldest log is older than the time limit specified in dlog configuration file, it is returned and removed from the buffer,
  74 - when we receive all logs in the dump mode, the buffer is cleaned up by returning all the remaining logs.
  75
  76 Note that in the first two cases, it is possible, that we will receive in the future a log that should be returned before the returned one. The probability of this happening in the second case depends on the configured time limit, but in general it is extremely low. However, in the first case, missort is possible, and the probability directly depends on the buffer size, which is configurable using the dlogutil_config_sorting_enable_with_size() function. The argument will set the size of the sort buffer in entries, which means that the memory usage of the log receiving funtion is mostly linear to this argument (as the buffer will usually stay full most of the time). The default value is currently `131072` and there exists a maximum of `1048576`.
  77
  78 We'd like to reiterate that usually you don't need to worry about this, as if you disable sorting or sort by the default timestamp, the data is already received in the correct form, and there isn't even a need to create a buffer, so the data will come sorted as well as the source allows (which usually means perfect sorting).
  79
  80 ## Other operations
  81
  82 You can also use the API to erase the log buffers --- this can be done using the dlogutil_buffer_clear() function.
  83
  84 */
  85
  86 #endif /* __TIZEN_SYSTEM_DLOGUTIL_DOC_H__ */