|
Packit |
1422b7 |
/**
|
|
Packit |
1422b7 |
* @file liblognorm.h
|
|
Packit |
1422b7 |
* @brief The public liblognorm API.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* Functions other than those defined here MUST not be called by
|
|
Packit |
1422b7 |
* a liblognorm "user" application.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* This file is meant to be included by applications using liblognorm.
|
|
Packit |
1422b7 |
* For lognorm library files themselves, include "lognorm.h".
|
|
Packit |
1422b7 |
*//**
|
|
Packit |
1422b7 |
* @mainpage
|
|
Packit |
1422b7 |
* Liblognorm is an easy to use and fast samples-based log normalization
|
|
Packit |
1422b7 |
* library.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* It can be passed a stream of arbitrary log messages, one at a time, and for
|
|
Packit |
1422b7 |
* each message it will output well-defined name-value pairs and a set of
|
|
Packit |
1422b7 |
* tags describing the message.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* For further details, see it's initial announcement available at
|
|
Packit |
1422b7 |
* http://blog.gerhards.net/2010/10/introducing-liblognorm.html
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* The public interface of this library is describe in liblognorm.h.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* Liblognorm fully supports Unicode. Like most Linux tools, it operates
|
|
Packit |
1422b7 |
* on UTF-8 natively, called "passive mode". This was decided because we
|
|
Packit |
1422b7 |
* so can keep the size of data structures small while still supporting
|
|
Packit |
1422b7 |
* all of the world's languages (actually more than when we did UCS-2).
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* At the technical level, we can handle UTF-8 multibyte sequences transparently.
|
|
Packit |
1422b7 |
* Liblognorm needs to look at a few US-ASCII characters to do the
|
|
Packit |
1422b7 |
* sample base parsing (things to indicate fields), so this is no
|
|
Packit |
1422b7 |
* issue. Inside the parse tree, a multibyte sequence can simple be processed
|
|
Packit |
1422b7 |
* as if it were a sequence of different characters that make up a their
|
|
Packit |
1422b7 |
* own symbol each. In fact, this even allows for somewhat greater parsing
|
|
Packit |
1422b7 |
* speed.
|
|
Packit |
1422b7 |
*//*
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* liblognorm - a fast samples-based log normalization library
|
|
Packit |
1422b7 |
* Copyright 2010-2013 by Rainer Gerhards and Adiscon GmbH.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* Modified by Pavel Levshin (pavel@levshin.spb.ru) in 2013
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* This file is part of liblognorm.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* This library is free software; you can redistribute it and/or
|
|
Packit |
1422b7 |
* modify it under the terms of the GNU Lesser General Public
|
|
Packit |
1422b7 |
* License as published by the Free Software Foundation; either
|
|
Packit |
1422b7 |
* version 2.1 of the License, or (at your option) any later version.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* This library is distributed in the hope that it will be useful,
|
|
Packit |
1422b7 |
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit |
1422b7 |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Packit |
1422b7 |
* Lesser General Public License for more details.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* You should have received a copy of the GNU Lesser General Public
|
|
Packit |
1422b7 |
* License along with this library; if not, write to the Free Software
|
|
Packit |
1422b7 |
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* A copy of the LGPL v2.1 can be found in the file "COPYING" in this distribution.
|
|
Packit |
1422b7 |
*/
|
|
Packit |
1422b7 |
#ifndef V1_LIBLOGNORM_H_INCLUDED
|
|
Packit |
1422b7 |
#define V1_LIBLOGNORM_H_INCLUDED
|
|
Packit |
1422b7 |
#include "liblognorm.h"
|
|
Packit |
1422b7 |
|
|
Packit |
1422b7 |
/**
|
|
Packit |
1422b7 |
* Inherit control attributes from a library context.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* This does not copy the parse-tree, but does copy
|
|
Packit |
1422b7 |
* behaviour-controling attributes such as enableRegex.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* Just as with ln_initCtx, ln_exitCtx() must be called on a library
|
|
Packit |
1422b7 |
* context that is no longer needed.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* @return new library context or NULL if an error occured
|
|
Packit |
1422b7 |
*/
|
|
Packit |
1422b7 |
ln_ctx ln_v1_inherittedCtx(ln_ctx parent);
|
|
Packit |
1422b7 |
|
|
Packit |
1422b7 |
|
|
Packit |
1422b7 |
/**
|
|
Packit |
1422b7 |
* Reads a sample stored in buffer buf and creates a new ln_samp object
|
|
Packit |
1422b7 |
* out of it.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* @note
|
|
Packit |
1422b7 |
* It is the caller's responsibility to delete the newly
|
|
Packit |
1422b7 |
* created ln_samp object if it is no longer needed.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* @param[ctx] ctx current library context
|
|
Packit |
1422b7 |
* @param[buf] NULL terminated cstr containing the contents of the sample
|
|
Packit |
1422b7 |
* @return Returns zero on success, something else otherwise.
|
|
Packit |
1422b7 |
*/
|
|
Packit |
1422b7 |
int
|
|
Packit |
1422b7 |
ln_v1_loadSample(ln_ctx ctx, const char *buf);
|
|
Packit |
1422b7 |
|
|
Packit |
1422b7 |
/**
|
|
Packit |
1422b7 |
* Load a (log) sample file.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* The file must contain log samples in syntactically correct format. Samples are added
|
|
Packit |
1422b7 |
* to set already loaded in the current context. If there is a sample with duplicate
|
|
Packit |
1422b7 |
* semantics, this sample will be ignored. Most importantly, this can \b not be used
|
|
Packit |
1422b7 |
* to change tag assignments for a given sample.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* @param[in] ctx The library context to apply callback to.
|
|
Packit |
1422b7 |
* @param[in] file Name of file to be loaded.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* @return Returns zero on success, something else otherwise.
|
|
Packit |
1422b7 |
*/
|
|
Packit |
1422b7 |
int ln_v1_loadSamples(ln_ctx ctx, const char *file);
|
|
Packit |
1422b7 |
|
|
Packit |
1422b7 |
/**
|
|
Packit |
1422b7 |
* Normalize a message.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* This is the main library entry point. It is called with a message
|
|
Packit |
1422b7 |
* to normalize and will return a normalized in-memory representation
|
|
Packit |
1422b7 |
* of it.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* If an error occurs, the function returns -1. In that case, an
|
|
Packit |
1422b7 |
* in-memory event representation has been generated if event is
|
|
Packit |
1422b7 |
* non-NULL. In that case, the event contains further error details in
|
|
Packit |
1422b7 |
* normalized form.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* @note
|
|
Packit |
1422b7 |
* This function works on byte-counted strings and as such is able to
|
|
Packit |
1422b7 |
* process NUL bytes if they occur inside the message. On the other hand,
|
|
Packit |
1422b7 |
* this means the the correct messages size, \b excluding the NUL byte,
|
|
Packit |
1422b7 |
* must be provided.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* @param[in] ctx The library context to use.
|
|
Packit |
1422b7 |
* @param[in] str The message string (see note above).
|
|
Packit |
1422b7 |
* @param[in] strLen The length of the message in bytes.
|
|
Packit |
1422b7 |
* @param[out] json_p A new event record or NULL if an error occured. Must be
|
|
Packit |
1422b7 |
* destructed if no longer needed.
|
|
Packit |
1422b7 |
*
|
|
Packit |
1422b7 |
* @return Returns zero on success, something else otherwise.
|
|
Packit |
1422b7 |
*/
|
|
Packit |
1422b7 |
int ln_v1_normalize(ln_ctx ctx, const char *str, size_t strLen, struct json_object **json_p);
|
|
Packit |
1422b7 |
|
|
Packit |
1422b7 |
|
|
Packit |
1422b7 |
/**
|
|
Packit |
1422b7 |
* create a single sample.
|
|
Packit |
1422b7 |
*/
|
|
Packit |
1422b7 |
struct ln_v1_samp* ln_v1_sampCreate(ln_ctx __attribute__((unused)) ctx);
|
|
Packit |
1422b7 |
|
|
Packit |
1422b7 |
/* here we add some stuff from the compatibility layer. A separate include
|
|
Packit |
1422b7 |
* would be cleaner, but would potentially require changes all over the
|
|
Packit |
1422b7 |
* place. So doing it here is better. The respective replacement
|
|
Packit |
1422b7 |
* functions should usually be found under ./compat -- rgerhards, 2015-05-20
|
|
Packit |
1422b7 |
*/
|
|
Packit |
1422b7 |
|
|
Packit |
1422b7 |
#endif /* #ifndef LOGNORM_H_INCLUDED */
|