MySQL 8.0.31
Source Code Documentation
log_service.h
Go to the documentation of this file.
1/* Copyright (c) 2017, 2022, Oracle and/or its affiliates.
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/**
24 @brief
25
26 This defines the API used to call functions in logging components.
27 When implementing such a service, refer to log_service_imp.h instead!
28
29 A log service may take the shape of a writer for a specific log format
30 (JSON, XML, traditional MySQL, etc.), it may implement a filter that
31 removes or modifies log_items, etc.
32*/
33
34#ifndef LOG_SERVICE_H
35#define LOG_SERVICE_H
36
41
42/* service helpers */
44 /** We do not have information about this service yet. */
46
47 /** Service is read-only -- it guarantees it will not modify the log-event.
48 This information may later be used to e.g. run log-writers in parallel. */
50
51 /** Service is a singleton -- it may occur in the log service pipeline
52 only once. */
54
55 /** Service is built-in (and can not be INSTALLed/UNINSTALLed */
57
58 // values from 8..64 are reserved for extensions
59
60 /** Service is a source. It adds key/value pairs beyond those in the
61 statement that first created the log-event. Log-sources are not
62 normally READ_ONLY. */
64
65 /** Service is a filter. A filter should not be the last service in
66 the log service pipeline. */
68
69 /** Service is a sink (usually a log-writer). Sinks will normally
70 not modify the log-event, but be READ_ONLY. */
72
73 /** Service supports the performance_schema.error_log table.
74 If the caller provides a buffer, the service will write output
75 to be displayed in the performance-schema table there.
76 This can be the entirety of the log-entry, or a projection
77 thereof (usually omitting key/value pairs that are already
78 shown in other columns of said table).
79 Services flagged this must also be flagged LOG_SERVICE_SINK! */
81
82 /** Service can parse lines in the format it outputs. Services flagged
83 this must also be flagged LOG_SERVICE_SINK | LOG_SERVICE_PFS_SUPPORT! */
86
87/**
88 Error codes. These are grouped (general issues, invalid data,
89 file ops, etc.). Each group has a sparsely populated range so
90 we may add entries as needed without introducing incompatibility
91 by renumbering the existing ones.
92*/
94 /// no error
96
97 /// error not otherwise specified
99
100 /// no error, but no effect either
102
103 /**
104 arguments are valid, we just don't have the space (either pre-allocated
105 in this function, or passed to us by the caller)
106 */
108
109 /// we cannot allocate a (temporary or return) buffer of the required size
111
112 /// service uninavailable (bad internal state/underlying service unavailable)
114
115 /// for a method with modes, a mode unsupported by this service was requested
117
118 /// argument was invalid (out of range, malformed, etc.)
120
121 /**
122 argument too long (a special case of malformed).
123 E.g. a path longer than FN_REFLEN, or a presumed data longer than
124 specified in ISO-8601.
125 use LOG_SERVICE_INVALID_ARGUMENT, LOG_SERVICE_BUFFER_SIZE_INSUFFICIENT,
126 or LOG_SERVICE_OUT_OF_MEMORY if more appropriate.
127 */
129
130 /**
131 invalid data, but not arguments to a C++ function
132 (bad log-file to parse, filter language statement, etc.)
133 */
135
136 /// could not make log name
138
139 /// lock error (could not init, or is not inited, etc.)
141
142 /// can not write
148
149 /// no more instances of this service are possible.
152
154/**
155 Have the service process one log line.
156
157 @param instance State-pointer that was returned on open.
158 @param ll The log_line collection of log_items.
159
160 @retval <0 an error occurred
161 @retval =0 no work was done
162 @retval >0 number of processed entities
163*/
164DECLARE_METHOD(int, run, (void *instance, log_line *ll));
165
166/**
167 Flush any buffers. This function will be called by the server
168 on FLUSH ERROR LOGS. The service may write its buffers, close
169 and re-open any log files to work with log-rotation, etc.
170 The flush function MUST NOT itself log anything (as the caller
171 holds THR_LOCK_log_stack)!
172 A service implementation may provide a nullptr if it does not
173 wish to provide a flush function.
174
175 @param instance State-pointer that was returned on open.
176 Value may be changed in flush.
177
178 @returns LOG_SERVICE_NOTHING_DONE no work was done
179 @returns LOG_SERVICE_SUCCESS flush completed without incident
180 @returns otherwise an error occurred
181*/
183
184/**
185 Open a new instance.
186
187 @param ll optional arguments
188 @param instance If state is needed, the service may allocate and
189 initialize it and return a pointer to it here.
190 (This of course is particularly pertinent to
191 components that may be opened multiple times,
192 such as the JSON log writer.)
193 This state is for use of the log-service component
194 in question only and can take any layout suitable
195 to that component's need. The state is opaque to
196 the server/logging framework. It must be released
197 on close.
198
199 @returns LOG_SERVICE_SUCCESS success, returned handle is valid
200 @returns otherwise a new instance could not be created
201*/
203
204/**
205 Close and release an instance. Flushes any buffers.
206
207 @param instance State-pointer that was returned on open.
208 If memory was allocated for this state,
209 it should be released, and the pointer
210 set to nullptr.
211
212 @returns LOG_SERVICE_SUCCESS success
213 @returns otherwise an error occurred
214*/
216
217/**
218 Get characteristics of a log-service.
219
220 @retval <0 an error occurred
221 @retval >=0 characteristics (a set of log_service_chistics flags)
222*/
223DECLARE_METHOD(int, characteristics, (void));
224
225/**
226 Parse a single line in an error log of this format. (optional)
227
228 @param line_start pointer to the beginning of the line ('{')
229 @param line_length length of the line
230
231 @retval 0 Success
232 @retval !=0 Failure (out of memory, malformed argument, etc.)
233*/
234DECLARE_METHOD(log_service_error, parse_log_line,
235 (const char *line_start, size_t line_length));
236
237/**
238 Provide the name for a log file this service would access.
239
240 @param instance instance info returned by open() if requesting
241 the file-name for a specific open instance.
242 nullptr to get the name of the default instance
243 (even if it that log is not open). This is used
244 to determine the name of the log-file to load on
245 start-up.
246 @param buf Address of a buffer allocated in the caller.
247 The callee may return an extension starting
248 with '.', in which case the path and file-name
249 will be the system's default, except with the
250 given extension.
251 Alternatively, the callee may return a file-name
252 which is assumed to be in the same directory
253 as the default log.
254 Values are C-strings.
255 @param bufsize The size of the allocation in the caller.
256
257 @retval 0 Success
258 @retval -1 Mode not supported (only default / only instances supported)
259 @retval -2 Buffer not large enough
260 @retval -3 Misc. error
261*/
263 (void *instance, char *buf, size_t bufsize));
264
266
267#endif
Specifies macros to define Components.
static void run(mysql_harness::PluginFuncEnv *)
Definition: io_plugin.cc:194
enum enum_log_service_error log_service_error
Error codes.
enum enum_log_service_chistics log_service_chistics
This defines the API used to call functions in logging components.
enum_log_service_chistics
This defines the API used to call functions in logging components.
Definition: log_service.h:43
@ LOG_SERVICE_SINK
Service is a sink (usually a log-writer).
Definition: log_service.h:71
@ LOG_SERVICE_LOG_PARSER
Service can parse lines in the format it outputs.
Definition: log_service.h:84
@ LOG_SERVICE_UNSPECIFIED
We do not have information about this service yet.
Definition: log_service.h:45
@ LOG_SERVICE_READ_ONLY
Service is read-only – it guarantees it will not modify the log-event.
Definition: log_service.h:49
@ LOG_SERVICE_SOURCE
Service is a source.
Definition: log_service.h:63
@ LOG_SERVICE_SINGLETON
Service is a singleton – it may occur in the log service pipeline only once.
Definition: log_service.h:53
@ LOG_SERVICE_BUILTIN
Service is built-in (and can not be INSTALLed/UNINSTALLed.
Definition: log_service.h:56
@ LOG_SERVICE_PFS_SUPPORT
Service supports the performance_schema.error_log table.
Definition: log_service.h:80
@ LOG_SERVICE_FILTER
Service is a filter.
Definition: log_service.h:67
enum_log_service_error
Error codes.
Definition: log_service.h:93
@ LOG_SERVICE_BUFFER_SIZE_INSUFFICIENT
arguments are valid, we just don't have the space (either pre-allocated in this function,...
Definition: log_service.h:107
@ LOG_SERVICE_LOCK_ERROR
lock error (could not init, or is not inited, etc.)
Definition: log_service.h:140
@ LOG_SERVICE_OPEN_FAILED
Definition: log_service.h:145
@ LOG_SERVICE_UNSUPPORTED_MODE
for a method with modes, a mode unsupported by this service was requested
Definition: log_service.h:116
@ LOG_SERVICE_UNABLE_TO_READ
Definition: log_service.h:144
@ LOG_SERVICE_PARSE_ERROR
invalid data, but not arguments to a C++ function (bad log-file to parse, filter language statement,...
Definition: log_service.h:134
@ LOG_SERVICE_TOO_MANY_INSTANCES
no more instances of this service are possible.
Definition: log_service.h:150
@ LOG_SERVICE_SEEK_FAILED
Definition: log_service.h:147
@ LOG_SERVICE_ARGUMENT_TOO_LONG
argument too long (a special case of malformed).
Definition: log_service.h:128
@ LOG_SERVICE_CLOSE_FAILED
Definition: log_service.h:146
@ LOG_SERVICE_NOT_AVAILABLE
service uninavailable (bad internal state/underlying service unavailable)
Definition: log_service.h:113
@ LOG_SERVICE_MISC_ERROR
error not otherwise specified
Definition: log_service.h:98
@ LOG_SERVICE_COULD_NOT_MAKE_LOG_NAME
could not make log name
Definition: log_service.h:137
@ LOG_SERVICE_OUT_OF_MEMORY
we cannot allocate a (temporary or return) buffer of the required size
Definition: log_service.h:110
@ LOG_SERVICE_INVALID_ARGUMENT
argument was invalid (out of range, malformed, etc.)
Definition: log_service.h:119
@ LOG_SERVICE_SUCCESS
no error
Definition: log_service.h:95
@ LOG_SERVICE_NOTHING_DONE
no error, but no effect either
Definition: log_service.h:101
@ LOG_SERVICE_UNABLE_TO_WRITE
can not write
Definition: log_service.h:143
Definition: buf0block_hint.cc:29
stdx::expected< void, std::error_code > close(file_handle_type native_handle)
close file handle.
Definition: file.h:238
static mysql_service_status_t flush(reference_caching_cache cache) noexcept
Definition: component.cc:121
stdx::expected< int, std::error_code > open(const char *fname, int flags, mode_t mode) noexcept
Definition: file_handle.cc:81
#define DECLARE_METHOD(retval, name, args)
Declares a method as a part of the Service definition.
Definition: service.h:102
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:90
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:85
Specifies macros to define Service Implementations.
log_line ("log event")
Definition: keyring_log_builtins_definition.cc:71