1 /* Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved. 2 3 This program is free software; you can redistribute it and/or modify 4 it under the terms of the GNU General Public License, version 2.0, 5 as published by the Free Software Foundation. 6 7 This program is also distributed with certain software (including 8 but not limited to OpenSSL) that is licensed under separate terms, 9 as designated in a particular file or component or in included license 10 documentation. The authors of MySQL hereby grant you an additional 11 permission to link the program and your derivative works with the 12 separately licensed software that they have included with MySQL. 13 14 This program is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 GNU General Public License, version 2.0, for more details. 18 19 You should have received a copy of the GNU General Public License 20 along with this program; if not, write to the Free Software 21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ 22 23 #ifndef LOG_SHARED_H 24 #define LOG_SHARED_H 25 26 #include <mysql/mysql_lex_string.h> 27 28 #include "my_basename.h" 29 #include "my_inttypes.h" 30 #include "my_loglevel.h" 31 32 /** fallback: includer may not have set this to something sensible. */ 33 #ifndef LOG_SUBSYSTEM_TAG 34 #define LOG_SUBSYSTEM_TAG NULL 35 #endif 36 37 /** 38 The logging sub-system internally uses the log_line structure to pass 39 data around. This header primarily the specifics and symbols of that 40 structure. 41 42 Within the server, those interfaces may be used, but it is usually 43 preferable to use the fluent C++ convenience class LogErr() instead 44 where possible (and the variadic convenience function log_message() 45 where it is not). (see sql/log.h). 46 47 (The legacy calls sql_print_(error|warning|information) have now 48 been defined to use log_message().) 49 50 Finally, this header defines log types (error log etc.) as well 51 as log item types (timestamp, message, ...) used by the logging 52 components; these are shared between the variadic convenience 53 functions (log_message(), sql_print_*()) as well as the lower 54 level services using the log_line structure. 55 */ 56 57 /* 58 By historical convention in the lex context, 59 CSTRING means "constant lex string (char * + size_t)", 60 not "C-style string" (char *, \0 terminated)! 61 */ 62 typedef struct MYSQL_LEX_CSTRING LEX_CSTRING; 63 64 /** 65 log_type -- which log to send data to 66 check vs enum_log_table_type and LOG_FILE/LOG_TABLE/LOG_NONE 67 */ 68 enum enum_log_type { 69 LOG_TYPE_UNDEF = 0, 70 LOG_TYPE_ERROR = 1, 71 LOG_TYPE_GENERAL = 2, 72 LOG_TYPE_SLOW = 4, 73 LOG_TYPE_AUDIT = 8, 74 LOG_TYPE_MISC = 16 75 }; 76 77 /** 78 item_type -- what to log 79 80 81 Used by variadic convenience interface 82 log_message(), legacy sql_print_*(), legacy my_plugin_log_message(). 83 Also available via the log_builtins service as message(). 84 85 (Wherever possible, use the fluent C++ wrapper LogErr() (see 86 log_builtins.h) instead, though.) 87 88 LOG_ITEM_GEN_CSTRING lets the caller submit a \0 terminated, 89 C-style string for convenience; it will be converted to 90 lex style (char *, size_t) on submission. 91 92 LOG_ITEM_END should not be used in the variadic interface 93 as submitting a log line without an actual message is discouraged. 94 Instead LOG_ITEM_LOG_MESSAGE or LOG_ITEM_LOG_LOOKUP should be used 95 as the last LOG_ITEM_* key-value pairs: 96 97 - LOG_ITEM_LOG_MESSAGE can be used to submit an ad hoc message 98 directly while debugging. 99 100 - LOG_ITEM_LOG_LOOKUP asks for the given error number to be 101 replaced by the associated error message (i.e. the error message 102 for the error number will be looked up, and the LOOKUP item will 103 be replaced by a MESSAGE one). 104 105 In variadic submission, both ad hoc and well-known error messages 106 are considered printf()-style format strings, and should be followed 107 by any arguments/variables required by that format string. 108 109 In some situations, the variadic interface will automatically 110 generate some items ("If you cannot afford a timestamp, one will 111 be provided for you."). If an item of the required type already 112 exists, the submission interface should not generate another. 113 114 Old-style plug-ins using my_plugin_log_message() will automatically 115 be tagged with a default LOG_ITEM_MSC_COMPONENT of their plug-in name. 116 117 118 119 Non-variadic interface 120 121 In non-variadic submission (i.e. all functions accepting a log_line), 122 LOG_ITEM_LOG_LOOKUP and LOG_ITEM_GEN_CSTRING are not valid item types, 123 while LOG_ITEM_LOG_MESSAGE must already be a string literal (i.e. any 124 substitutions must already have taken place). 125 */ 126 typedef enum enum_log_item_type { 127 LOG_ITEM_END = 0, /**< end of list, see above */ 128 LOG_ITEM_LOG_TYPE = 1 << 0, /**< error log, etc. */ 129 LOG_ITEM_SQL_ERRCODE = 1 << 1, /**< mysql error code (numeric) */ 130 LOG_ITEM_SQL_ERRSYMBOL = 1 << 2, /**< mysql error code (symbolic) */ 131 LOG_ITEM_SQL_STATE = 1 << 3, /**< SQL state */ 132 LOG_ITEM_SYS_ERRNO = 1 << 4, /**< OS errno */ 133 LOG_ITEM_SYS_STRERROR = 1 << 5, /**< OS strerror() */ 134 LOG_ITEM_SRC_FILE = 1 << 6, /**< log called from file ... */ 135 LOG_ITEM_SRC_LINE = 1 << 7, /**< log called from line ... */ 136 LOG_ITEM_SRC_FUNC = 1 << 8, /**< log called from function ... */ 137 LOG_ITEM_SRV_SUBSYS = 1 << 9, /**< log called from subsystem ... */ 138 LOG_ITEM_SRV_COMPONENT = 1 << 10, /**< log called from component ... */ 139 LOG_ITEM_MSC_USER = 1 << 11, /**< offending thread owned by ... */ 140 LOG_ITEM_MSC_HOST = 1 << 12, /**< responsible user on host ... */ 141 LOG_ITEM_SRV_THREAD = 1 << 13, /**< connection ID */ 142 LOG_ITEM_SQL_QUERY_ID = 1 << 14, /**< query ID */ 143 LOG_ITEM_SQL_TABLE_NAME = 1 << 15, /**< table name */ 144 LOG_ITEM_LOG_PRIO = 1 << 16, /**< log priority (error, warn, ...) */ 145 LOG_ITEM_LOG_LABEL = 1 << 17, /**< label, unless auto-derived */ 146 LOG_ITEM_LOG_VERBATIM = 1 << 18, /**< the message, no % substitutions */ 147 LOG_ITEM_LOG_MESSAGE = 1 << 19, /**< the message, format string */ 148 LOG_ITEM_LOG_LOOKUP = 1 << 20, /**< insert message by error-code */ 149 LOG_ITEM_LOG_TIMESTAMP = 1 << 21, /**< ISO8601 timestamp */ 150 LOG_ITEM_LOG_TS = 1 << 22, /**< millisecs since epoch */ 151 LOG_ITEM_LOG_BUFFERED = 1 << 23, /**< integer timestamp if/when buffered */ 152 LOG_ITEM_LOG_SUPPRESSED = 1 << 24, /**< "and ... more" throttled */ 153 LOG_ITEM_GEN_FLOAT = 1 << 25, /**< float not otherwise specified */ 154 LOG_ITEM_GEN_INTEGER = 1 << 26, /**< integer not otherwise specified */ 155 LOG_ITEM_GEN_LEX_STRING = 1 << 27, /**< lex string not otherwise specified */ 156 LOG_ITEM_GEN_CSTRING = 1 << 28 /**< C-string not otherwise specified */ 157 } log_item_type; 158 159 /* some suggested keys for generic items */ 160 161 /** DIAGNOSTICS: for da->message_text() */ 162 #define LOG_TAG_DIAG "DIAGNOSTICS" 163 164 /** AUX: supplementary data not fitting any of the wellknown keys */ 165 #define LOG_TAG_AUX "AUX" 166 167 /* data type */ 168 typedef enum enum_log_item_class { 169 LOG_UNTYPED = 0, /**< undefined */ 170 LOG_CSTRING = 1, /**< string (char * + \0; variadic API only) */ 171 LOG_INTEGER = 2, /**< integer (long long) */ 172 LOG_FLOAT = 3, /**< float (double) */ 173 LOG_LEX_STRING = 4 /**< string (char *, size_t) */ 174 } log_item_class; 175 176 /* do we need to release any parts of the item after use? */ 177 enum enum_log_item_free { 178 LOG_ITEM_FREE_NONE = 0, 179 LOG_ITEM_FREE_KEY = 1, 180 LOG_ITEM_FREE_VALUE = 2 181 }; 182 183 /* union: payload */ 184 typedef union _log_item_data { 185 longlong data_integer; 186 double data_float; 187 LEX_CSTRING data_string; 188 } log_item_data; 189 190 /* item key: for now, a C-string */ 191 typedef const char *log_item_key; 192 193 /* log item: key/value */ 194 typedef struct _log_item { 195 log_item_type type; 196 log_item_class item_class; 197 log_item_key key; 198 log_item_data data; 199 uint32 alloc; 200 } log_item; 201 202 /* service helpers */ 203 typedef enum enum_log_item_error { 204 LOG_ITEM_OK = 0, 205 LOG_ITEM_TYPE_NOT_FOUND = -1, 206 LOG_ITEM_TYPE_RESERVED = -2, 207 LOG_ITEM_CLASS_MISMATCH = -3, 208 LOG_ITEM_KEY_MISMATCH = -4, 209 LOG_ITEM_STRING_NULL = -5, 210 LOG_ITEM_KEY_NULL = -6 211 } log_item_error; 212 213 /** a bit mask of log_types. standardizing the width to 64 bit. */ 214 typedef uint64 log_item_type_mask; 215 216 /** log line: a collection of log items */ 217 typedef struct _log_line log_line; 218 219 /** log iter: an iterator over the collection of log items in a log line */ 220 typedef struct _log_item_iter log_item_iter; 221 222 /** advisory. components must not rely on others using the same value. */ 223 #define LOG_BUFF_MAX 8192 224 225 /** 26 for regular timestamp, plus 7 (".123456") when using micro-seconds */ 226 static const int iso8601_size = 33; 227 228 /** 229 index of first server error message: messages with this index or 230 higher are intended for the error log; messages below this index 231 are intended for the client 232 */ 233 #define ER_SERVER_RANGE_START 10000 234 235 #endif 236