summaryrefslogtreecommitdiff
path: root/common/elapi/elapi_event.h
blob: d1e0dd1281528a3fa82d88742b9166b9adae651a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
/*
    ELAPI

    Header file for the ELAPI event interface.

    Copyright (C) Dmitri Pal <dpal@redhat.com> 2009

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 3 of the License, or
    (at your option) any later version.
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef ELAPI_EVENT_H
#define ELAPI_EVENT_H

#include "collection.h"

/* Possible predefined elements of the event */
#define E_TIMESTAMP "stamp"     /* string - the value is the format for strftime()
                                 * default is standard format for current locale.  */
#define E_UTCTIME   "time"      /* int - UTC time as unix time in seconds since 1970 */
#define E_PID       "pid"       /* int - Process ID of the current process */
#define E_APPNAME   "appnm"     /* string - Name of the current application */
#define E_HOSTNAME  "host"      /* string - Name of the current host */
#define E_HOSTIP    "ip"        /* string - IP address */
#define E_SEVERITY  "sev"       /* int - Same as "priority" in syslog() */
#define E_HOSTALIAS "halias"    /* string - List of alternative host names */
#define E_HOSTIPS   "iplist"    /* string - List of alternative IP addresses */

/* There is a special optional attribute of the event named "message".
 * It is a string that contains text specific to each event.
 * This string can contain placeholders that will be automatically
 * replaced by the values that correspond to other attributes in
 * the message. For example message can be:
 * "Connected to remote %(server)".
 * The token %(server) will be replaced by value
 * in the attribute "server" in the event.
 */
#define E_MESSAGE   "message"

/* Base argument in the template creation function is a bit mask.
 * Each supported predefined element corresponds to its bit in
 * the mask.
 */
#define E_HAVE_TIMESTAMP    0x00000001
#define E_HAVE_UTCTIME      0x00000002
#define E_HAVE_PID          0x00000004
#define E_HAVE_APPNAME      0x00000010
#define E_HAVE_HOSTNAME     0x00000020
#define E_HAVE_HOSTIP       0x00000040
#define E_HAVE_SEVERITY     0x00000100
#define E_HAVE_HOSTALIAS    0x00000200
#define E_HAVE_HOSTIPS      0x00000400

/* Convenient bitmasks */
#define E_BASE_TIME         ( E_HAVE_TIMESTAMP | E_HAVE_UTCTIME )
#define E_BASE_HOST         ( E_HAVE_HOSTIP | E_HAVE_HOSTNAME )
#define E_BASE_APP          ( E_HAVE_APPNAME | E_HAVE_PID )
#define E_BASE_HOSTEXT      ( E_HAVE_HOSTALIAS | E_HAVE_HOSTIPS )
#define E_BASE_DEFV1        ( E_BASE_TIME | E_BASE_HOST | E_BASE_APP | E_HAVE_SEVERITY )

/* The default time stamp format */
#define E_TIMESTAMP_FORMAT "%c"

#define TIME_ARRAY_SIZE 100


/* End of arg list special value */
#define E_EOARG "<EOARG>"



/***************************************************************************/
/* TREAD SAFE ELAPI EVENT API                                              */
/***************************************************************************/

/* In the thread safe API the caller is responsible for
 * carrying context information. It is usually allocated
 * when a "create" function is called
 * and should be deleted using "destroy" function.
 */

/* Create an event template.
 * One can create an event template
 * and specify what fields should be
 * populated in the event at its creation.
 * Possible supported fields are listed above.
 * Base parameter specifies the base collection of
 * attributes. See above. The value of 0 will default
 * to the current version of default combination
 * which might change as the API evolves.
 * The variable list can be used to initialize template.
 * It can be initialized by providing key value pairs.
 * ...base, key, value, key, value);
 * If the key does not contain format specifier
 * the value should be a NULL terminated string.
 * See examples for the specific syntax.
 * If key starts with "-" like "-foo"
 * it means that attribute should be removed.
 * In this case the value should not be provided
 * and next argument should be next key.
 * The attributes selected by base argument will
 * be internally and automatically initialized
 * if there is no key - value pair provided.
 * The timestamps will we overwritten each time
 * the event is created so initializing them
 * does not make sense unless you use the base
 * that does not include them.
 * The list of key value pairs should be terminated by special
 * argument E_EOARG.
 */
int elapi_create_event_template(struct collection_item **template,
                                unsigned base, ...);

/* Function to destroy event template */
void elapi_destroy_event_template(struct collection_item *template);

/***************************************************************************/
/* Creates a new event using template (must be provided)
 * and adds additional fields using collection
 * if provided and/or key value pairs if provided.
 * Mode specifies how the collection should be
 * copied into event.
 * See example for details about format specification.
 */
int elapi_create_event(struct collection_item **event,
                       struct collection_item *template,
                       struct collection_item *collection,
                       int mode, ...);

/* Add/Updates/Removes the event attributes based on the and provided key value pairs */
int elapi_modify_event(struct collection_item *event,
                       struct collection_item *collection,
                       int mode, ...);

/* Create a copy of the event */
int elapi_copy_event(struct collection_item **new_event,
                     struct collection_item *source_event);

/* Function to destroy event. */
/* Keep in mind that as soon as event is logged
 * it is automatically destroyed so the
 * function should be used only in cases
 * when you have an event
 * that you use as a template for other events.
 */
void elapi_destroy_event(struct collection_item *event);

/***************************************************************************/
/* TREAD UNSAFE ELAPI EVENT API - for simple use cases                     */
/***************************************************************************/
/* Initializes default internal template */
int elapi_set_default_template(unsigned base, ...);

/* This function will use internal default template.
 * Hides all complexity from the caller.
 */
int elapi_create_simple_event(struct collection_item **event, ...);


#endif