1 /** 2 * @file liblognorm.h 3 * @brief The public liblognorm API. 4 * 5 * <b>Functions other than those defined here MUST not be called by 6 * a liblognorm "user" application.</b> 7 * 8 * This file is meant to be included by applications using liblognorm. 9 * For lognorm library files themselves, include "lognorm.h". 10 *//** 11 * @mainpage 12 * Liblognorm is an easy to use and fast samples-based log normalization 13 * library. 14 * 15 * It can be passed a stream of arbitrary log messages, one at a time, and for 16 * each message it will output well-defined name-value pairs and a set of 17 * tags describing the message. 18 * 19 * For further details, see it's initial announcement available at 20 * http://blog.gerhards.net/2010/10/introducing-liblognorm.html 21 * 22 * The public interface of this library is describe in liblognorm.h. 23 * 24 * Liblognorm fully supports Unicode. Like most Linux tools, it operates 25 * on UTF-8 natively, called "passive mode". This was decided because we 26 * so can keep the size of data structures small while still supporting 27 * all of the world's languages (actually more than when we did UCS-2). 28 * 29 * At the technical level, we can handle UTF-8 multibyte sequences transparently. 30 * Liblognorm needs to look at a few US-ASCII characters to do the 31 * sample base parsing (things to indicate fields), so this is no 32 * issue. Inside the parse tree, a multibyte sequence can simple be processed 33 * as if it were a sequence of different characters that make up a their 34 * own symbol each. In fact, this even allows for somewhat greater parsing 35 * speed. 36 *//* 37 * 38 * liblognorm - a fast samples-based log normalization library 39 * Copyright 2010-2013 by Rainer Gerhards and Adiscon GmbH. 40 * 41 * Modified by Pavel Levshin (pavel@levshin.spb.ru) in 2013 42 * 43 * This file is part of liblognorm. 44 * 45 * This library is free software; you can redistribute it and/or 46 * modify it under the terms of the GNU Lesser General Public 47 * License as published by the Free Software Foundation; either 48 * version 2.1 of the License, or (at your option) any later version. 49 * 50 * This library is distributed in the hope that it will be useful, 51 * but WITHOUT ANY WARRANTY; without even the implied warranty of 52 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 53 * Lesser General Public License for more details. 54 * 55 * You should have received a copy of the GNU Lesser General Public 56 * License along with this library; if not, write to the Free Software 57 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 58 * 59 * A copy of the LGPL v2.1 can be found in the file "COPYING" in this distribution. 60 */ 61 #ifndef V1_LIBLOGNORM_H_INCLUDED 62 #define V1_LIBLOGNORM_H_INCLUDED 63 #include "liblognorm.h" 64 65 /** 66 * Inherit control attributes from a library context. 67 * 68 * This does not copy the parse-tree, but does copy 69 * behaviour-controling attributes such as enableRegex. 70 * 71 * Just as with ln_initCtx, ln_exitCtx() must be called on a library 72 * context that is no longer needed. 73 * 74 * @return new library context or NULL if an error occured 75 */ 76 ln_ctx ln_v1_inherittedCtx(ln_ctx parent); 77 78 79 /** 80 * Reads a sample stored in buffer buf and creates a new ln_samp object 81 * out of it. 82 * 83 * @note 84 * It is the caller's responsibility to delete the newly 85 * created ln_samp object if it is no longer needed. 86 * 87 * @param[ctx] ctx current library context 88 * @param[buf] NULL terminated cstr containing the contents of the sample 89 * @return Returns zero on success, something else otherwise. 90 */ 91 int 92 ln_v1_loadSample(ln_ctx ctx, const char *buf); 93 94 /** 95 * Load a (log) sample file. 96 * 97 * The file must contain log samples in syntactically correct format. Samples are added 98 * to set already loaded in the current context. If there is a sample with duplicate 99 * semantics, this sample will be ignored. Most importantly, this can \b not be used 100 * to change tag assignments for a given sample. 101 * 102 * @param[in] ctx The library context to apply callback to. 103 * @param[in] file Name of file to be loaded. 104 * 105 * @return Returns zero on success, something else otherwise. 106 */ 107 int ln_v1_loadSamples(ln_ctx ctx, const char *file); 108 109 /** 110 * Normalize a message. 111 * 112 * This is the main library entry point. It is called with a message 113 * to normalize and will return a normalized in-memory representation 114 * of it. 115 * 116 * If an error occurs, the function returns -1. In that case, an 117 * in-memory event representation has been generated if event is 118 * non-NULL. In that case, the event contains further error details in 119 * normalized form. 120 * 121 * @note 122 * This function works on byte-counted strings and as such is able to 123 * process NUL bytes if they occur inside the message. On the other hand, 124 * this means the the correct messages size, \b excluding the NUL byte, 125 * must be provided. 126 * 127 * @param[in] ctx The library context to use. 128 * @param[in] str The message string (see note above). 129 * @param[in] strLen The length of the message in bytes. 130 * @param[out] json_p A new event record or NULL if an error occured. <b>Must be 131 * destructed if no longer needed.</b> 132 * 133 * @return Returns zero on success, something else otherwise. 134 */ 135 int ln_v1_normalize(ln_ctx ctx, const char *str, size_t strLen, struct json_object **json_p); 136 137 138 /** 139 * create a single sample. 140 */ 141 struct ln_v1_samp* ln_v1_sampCreate(ln_ctx __attribute__((unused)) ctx); 142 143 /* here we add some stuff from the compatibility layer. A separate include 144 * would be cleaner, but would potentially require changes all over the 145 * place. So doing it here is better. The respective replacement 146 * functions should usually be found under ./compat -- rgerhards, 2015-05-20 147 */ 148 149 #endif /* #ifndef LOGNORM_H_INCLUDED */ 150