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