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 /** 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 37 #include <mysql/components/component_implementation.h> 38 #include <mysql/components/my_service.h> 39 #include <mysql/components/service_implementation.h> 40 #include <mysql/components/services/log_shared.h> 41 42 /* service helpers */ 43 typedef enum enum_log_service_chistics { 44 /** We do not have information about this service yet. */ 45 LOG_SERVICE_UNSPECIFIED = 0, 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. */ 49 LOG_SERVICE_READ_ONLY = 1, 50 51 /** Service is a singleton -- it may occur in the log service pipeline 52 only once. */ 53 LOG_SERVICE_SINGLETON = 2, 54 55 /** Service is built-in (and can not be INSTALLed/UNINSTALLed */ 56 LOG_SERVICE_BUILTIN = 4, 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. */ 63 LOG_SERVICE_SOURCE = 128, 64 65 /** Service is a filter. A filter should not be the last service in 66 the log service pipeline. */ 67 LOG_SERVICE_FILTER = 256, 68 69 /** Service is a sink (usually a log-writer). Sinks will normally 70 not modify the log-event, but be READ_ONLY. */ 71 LOG_SERVICE_SINK = 512, 72 73 /** Service is a special sink used during start-up that buffers log-events 74 until the log service pipeline is fully set up, at which point we'll 75 flush (that is, filter and prints) the buffered events. 76 Services flagged this must also be flagged LOG_SERVICE_SINK! */ 77 LOG_SERVICE_BUFFER = 1024 78 79 } log_service_chistics; 80 81 BEGIN_SERVICE_DEFINITION(log_service) 82 /** 83 Have the service process one log line. 84 85 @param instance State-pointer that was returned on open. 86 @param ll The log_line collection of log_items. 87 88 @retval <0 an error occurred 89 @retval =0 no work was done 90 @retval >0 number of processed entities 91 */ 92 DECLARE_METHOD(int, run, (void *instance, log_line *ll)); 93 94 /** 95 Flush any buffers. This function will be called by the server 96 on FLUSH ERROR LOGS. The service may write its buffers, close 97 and re-open any log files to work with log-rotation, etc. 98 The flush function MUST NOT itself log anything! 99 A service implementation may provide a nullptr if it does not 100 wish to provide a flush function. 101 102 @param instance State-pointer that was returned on open. 103 Value may be changed in flush. 104 105 @retval <0 an error occurred 106 @retval =0 no work was done 107 @retval >0 flush completed without incident 108 */ 109 DECLARE_METHOD(int, flush, (void **instance)); 110 111 /** 112 Open a new instance. 113 114 @param ll optional arguments 115 @param instance If state is needed, the service may allocate and 116 initialize it and return a pointer to it here. 117 (This of course is particularly pertinent to 118 components that may be opened multiple times, 119 such as the JSON log writer.) 120 This state is for use of the log-service component 121 in question only and can take any layout suitable 122 to that component's need. The state is opaque to 123 the server/logging framework. It must be released 124 on close. 125 126 @retval <0 a new instance could not be created 127 @retval =0 success, returned hande is valid 128 */ 129 DECLARE_METHOD(int, open, (log_line * ll, void **instance)); 130 131 /** 132 Close and release an instance. Flushes any buffers. 133 134 @param instance State-pointer that was returned on open. 135 If memory was allocated for this state, 136 it should be released, and the pointer 137 set to nullptr. 138 139 @retval <0 an error occurred 140 @retval =0 success 141 */ 142 DECLARE_METHOD(int, close, (void **instance)); 143 144 /** 145 Get characteristics of a log-service. 146 147 @retval <0 an error occurred 148 @retval >=0 characteristics (a set of log_service_chistics flags) 149 */ 150 DECLARE_METHOD(int, characteristics, (void)); 151 END_SERVICE_DEFINITION(log_service) 152 153 #endif 154