third_party/pigweed/repo/pw_log/public/pw_log/log.h

   1 // Copyright 2020 The Pigweed Authors
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
   4 // use this file except in compliance with the License. You may obtain a copy of
   5 // the License at
   6 //
   7 //     https://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  12 // License for the specific language governing permissions and limitations under
  13 // the License.
  14
  15 // This file describes Pigweed's public user-facing logging API.
  16 //
  17 // THIS PUBLIC API IS NOT STABLE OR COMPLETE!
  18 //
  19 // Key functionality is still missing:
  20 //
  21 // - API for controlling verbosity at run time
  22 // - API for querying if logging is enabled for the given level or flags
  23 //
  24 #pragma once
  25
  26 #include "pw_log/levels.h"
  27 #include "pw_log/options.h"
  28
  29 // log_backend.h must ultimately resolve to a header that implements the macros
  30 // required by the logging facade, as described below.
  31 //
  32 // Inputs: Macros the downstream user provides to control the logging system:
  33 //
  34 //   PW_LOG_MODULE_NAME
  35 //     - The module name the backend should use
  36 //
  37 //   PW_LOG_LEVEL
  38 //     - General log level setting. By default, logs below this level are
  39 //       excluded from the build.
  40 //
  41 // Outputs: Macros log_backend.h is expected to provide:
  42 //
  43 //   PW_LOG(level, flags, fmt, ...)
  44 //     - Required.
  45 //       Level - An integer level as defined by pw_log/levels.h
  46 //       Flags - Arbitrary flags the backend can leverage; user-defined.
  47 //               Example: HAS_PII - A log has personally-identifying data
  48 //               Example: HAS_DII - A log has device-identifying data
  49 //               Example: RELIABLE_DELIVERY - Ask backend to ensure the
  50 //               log is delivered; this may entail blocking other logs.
  51 //               Example: BEST_EFFORT - Don't deliver this log if it
  52 //               would mean blocking or dropping important-flagged logs
  53 //
  54 //   PW_LOG_DEBUG(fmt, ...)
  55 //   PW_LOG_INFO(fmt, ...)
  56 //   PW_LOG_WARN(fmt, ...)
  57 //   PW_LOG_ERROR(fmt, ...)
  58 //   PW_LOG_CRITICAL(fmt, ...)
  59 //     - Optional. If not defined by the backend, the facade's default
  60 //       implementation defines these in terms of PW_LOG().
  61 //
  62 #include "pw_log_backend/log_backend.h"
  63
  64 #ifndef PW_LOG
  65 #define PW_LOG(level, flags, message, ...)               \
  66   do {                                                   \
  67     if (PW_LOG_ENABLE_IF(level, flags)) {                \
  68       PW_HANDLE_LOG(level, flags, message, __VA_ARGS__); \
  69     }                                                    \
  70   } while (0)
  71 #endif  // PW_LOG
  72
  73 // For backends that elect to only provide the general PW_LOG() macro and not
  74 // specialized versions, define the standard PW_LOG_<level>() macros in terms
  75 // of the general PW_LOG().
  76 #ifndef PW_LOG_DEBUG
  77 #define PW_LOG_DEBUG(message, ...) \
  78   PW_LOG(PW_LOG_LEVEL_DEBUG, PW_LOG_DEFAULT_FLAGS, message, __VA_ARGS__)
  79 #endif  // PW_LOG_DEBUG
  80
  81 #ifndef PW_LOG_INFO
  82 #define PW_LOG_INFO(message, ...) \
  83   PW_LOG(PW_LOG_LEVEL_INFO, PW_LOG_DEFAULT_FLAGS, message, __VA_ARGS__)
  84 #endif  // PW_LOG_INFO
  85
  86 #ifndef PW_LOG_WARN
  87 #define PW_LOG_WARN(message, ...) \
  88   PW_LOG(PW_LOG_LEVEL_WARN, PW_LOG_DEFAULT_FLAGS, message, __VA_ARGS__)
  89 #endif  // PW_LOG_WARN
  90
  91 #ifndef PW_LOG_ERROR
  92 #define PW_LOG_ERROR(message, ...) \
  93   PW_LOG(PW_LOG_LEVEL_ERROR, PW_LOG_DEFAULT_FLAGS, message, __VA_ARGS__)
  94 #endif  // PW_LOG_ERROR
  95
  96 #ifndef PW_LOG_CRITICAL
  97 #define PW_LOG_CRITICAL(message, ...) \
  98   PW_LOG(PW_LOG_LEVEL_CRITICAL, PW_LOG_DEFAULT_FLAGS, message, __VA_ARGS__)
  99 #endif  // PW_LOG_CRITICAL
 100
 101 // Default: Number of bits available for the log level
 102 //
 103 // All log statements have a level, and this define is the number of bits
 104 // available for the level. Some backends restrict this for better efficiency.
 105 // By default, pick a restricted but large enough value to work for most cases.
 106 #ifndef PW_LOG_LEVEL_BITS
 107 #define PW_LOG_LEVEL_BITS 6
 108 #endif  // PW_LOG_LEVEL_BITS
 109
 110 // Default: Number of bits available for the log flags
 111 //
 112 // All log statements have a flags field, and this define is the number of bits
 113 // available for the flags. Some backends restrict this for better efficiency.
 114 // By default, pick a restricted but large enough value to work for most cases.
 115 #ifndef PW_LOG_FLAG_BITS
 116 #define PW_LOG_FLAG_BITS 10
 117 #endif  // PW_LOG_FLAG_BITS
 118
 119 // Define short, usable names if requested.
 120 // TODO(pwbug/17): Convert this to the config system when available.
 121 #ifndef PW_LOG_USE_SHORT_NAMES
 122 #define PW_LOG_USE_SHORT_NAMES 0
 123 #endif
 124
 125 // Define ultra short, usable names if requested.
 126 #ifndef PW_LOG_USE_ULTRA_SHORT_NAMES
 127 #define PW_LOG_USE_ULTRA_SHORT_NAMES 0
 128 #endif  // PW_LOG_USE_SHORT_NAMES
 129
 130 // clang-format off
 131 #if PW_LOG_USE_SHORT_NAMES
 132 #define LOG          PW_LOG
 133 #define LOG_DEBUG    PW_LOG_DEBUG
 134 #define LOG_INFO     PW_LOG_INFO
 135 #define LOG_WARN     PW_LOG_WARN
 136 #define LOG_ERROR    PW_LOG_ERROR
 137 #define LOG_CRITICAL PW_LOG_CRITICAL
 138 #endif  // PW_LOG_USE_SHORT_NAMES
 139 // clang-format on
 140
 141 // clang-format off
 142 #if PW_LOG_USE_ULTRA_SHORT_NAMES
 143 #if !PW_LOG_USE_SHORT_NAMES
 144 #define LOG PW_LOG
 145 #endif  // LOG
 146 #define DBG PW_LOG_DEBUG
 147 #define INF PW_LOG_INFO
 148 #define WRN PW_LOG_WARN
 149 #define ERR PW_LOG_ERROR
 150 #define CRT PW_LOG_CRITICAL
 151 #endif  // PW_LOG_USE_ULTRA_SHORT_NAMES
 152 // clang-format on