Add a basic .clang-tidy file and fix typedef warnings
[lttng-tools.git] / include / lttng / event.h
... / ...
CommitLineData
1/*
2 * Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
3 * Copyright (C) 2016 Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 *
5 * SPDX-License-Identifier: LGPL-2.1-only
6 *
7 */
8
9#ifndef LTTNG_EVENT_H
10#define LTTNG_EVENT_H
11
12#include <lttng/handle.h>
13#include <lttng/lttng-export.h>
14#include <lttng/userspace-probe.h>
15
16#ifdef __cplusplus
17extern "C" {
18#endif
19
20/*
21 * Instrumentation type of tracing event.
22 */
23enum lttng_event_type {
24 LTTNG_EVENT_ALL = -1,
25 LTTNG_EVENT_TRACEPOINT = 0,
26 LTTNG_EVENT_PROBE = 1,
27 LTTNG_EVENT_FUNCTION = 2,
28 LTTNG_EVENT_FUNCTION_ENTRY = 3,
29 LTTNG_EVENT_NOOP = 4,
30 LTTNG_EVENT_SYSCALL = 5,
31 LTTNG_EVENT_USERSPACE_PROBE = 6,
32};
33
34/*
35 * Loglevel information.
36 */
37enum lttng_loglevel_type {
38 LTTNG_EVENT_LOGLEVEL_ALL = 0,
39 LTTNG_EVENT_LOGLEVEL_RANGE = 1,
40 LTTNG_EVENT_LOGLEVEL_SINGLE = 2,
41};
42
43/*
44 * Available loglevels.
45 */
46enum lttng_loglevel {
47 LTTNG_LOGLEVEL_EMERG = 0,
48 LTTNG_LOGLEVEL_ALERT = 1,
49 LTTNG_LOGLEVEL_CRIT = 2,
50 LTTNG_LOGLEVEL_ERR = 3,
51 LTTNG_LOGLEVEL_WARNING = 4,
52 LTTNG_LOGLEVEL_NOTICE = 5,
53 LTTNG_LOGLEVEL_INFO = 6,
54 LTTNG_LOGLEVEL_DEBUG_SYSTEM = 7,
55 LTTNG_LOGLEVEL_DEBUG_PROGRAM = 8,
56 LTTNG_LOGLEVEL_DEBUG_PROCESS = 9,
57 LTTNG_LOGLEVEL_DEBUG_MODULE = 10,
58 LTTNG_LOGLEVEL_DEBUG_UNIT = 11,
59 LTTNG_LOGLEVEL_DEBUG_FUNCTION = 12,
60 LTTNG_LOGLEVEL_DEBUG_LINE = 13,
61 LTTNG_LOGLEVEL_DEBUG = 14,
62};
63
64/*
65 * Available loglevels for the JUL domain. Those are an exact map from the
66 * class java.util.logging.Level.
67 */
68enum lttng_loglevel_jul {
69 LTTNG_LOGLEVEL_JUL_OFF = INT32_MAX,
70 LTTNG_LOGLEVEL_JUL_SEVERE = 1000,
71 LTTNG_LOGLEVEL_JUL_WARNING = 900,
72 LTTNG_LOGLEVEL_JUL_INFO = 800,
73 LTTNG_LOGLEVEL_JUL_CONFIG = 700,
74 LTTNG_LOGLEVEL_JUL_FINE = 500,
75 LTTNG_LOGLEVEL_JUL_FINER = 400,
76 LTTNG_LOGLEVEL_JUL_FINEST = 300,
77 LTTNG_LOGLEVEL_JUL_ALL = INT32_MIN,
78};
79
80/*
81 * Available loglevels for the LOG4j domain. Those are an exact map from the
82 * class org.apache.log4j.Level.
83 */
84enum lttng_loglevel_log4j {
85 LTTNG_LOGLEVEL_LOG4J_OFF = INT32_MAX,
86 LTTNG_LOGLEVEL_LOG4J_FATAL = 50000,
87 LTTNG_LOGLEVEL_LOG4J_ERROR = 40000,
88 LTTNG_LOGLEVEL_LOG4J_WARN = 30000,
89 LTTNG_LOGLEVEL_LOG4J_INFO = 20000,
90 LTTNG_LOGLEVEL_LOG4J_DEBUG = 10000,
91 LTTNG_LOGLEVEL_LOG4J_TRACE = 5000,
92 LTTNG_LOGLEVEL_LOG4J_ALL = INT32_MIN,
93};
94
95/*
96 * Available loglevels for the Python domain. Those are an exact map from the
97 * Level class.
98 */
99enum lttng_loglevel_python {
100 LTTNG_LOGLEVEL_PYTHON_CRITICAL = 50,
101 LTTNG_LOGLEVEL_PYTHON_ERROR = 40,
102 LTTNG_LOGLEVEL_PYTHON_WARNING = 30,
103 LTTNG_LOGLEVEL_PYTHON_INFO = 20,
104 LTTNG_LOGLEVEL_PYTHON_DEBUG = 10,
105 LTTNG_LOGLEVEL_PYTHON_NOTSET = 0,
106};
107
108/*
109 * LTTng consumer mode
110 */
111enum lttng_event_output {
112 LTTNG_EVENT_SPLICE = 0,
113 LTTNG_EVENT_MMAP = 1,
114};
115
116/* Event context possible type */
117enum lttng_event_context_type {
118 LTTNG_EVENT_CONTEXT_PID = 0,
119 LTTNG_EVENT_CONTEXT_PERF_COUNTER = 1, /* Backward compat. */
120 LTTNG_EVENT_CONTEXT_PROCNAME = 2,
121 LTTNG_EVENT_CONTEXT_PRIO = 3,
122 LTTNG_EVENT_CONTEXT_NICE = 4,
123 LTTNG_EVENT_CONTEXT_VPID = 5,
124 LTTNG_EVENT_CONTEXT_TID = 6,
125 LTTNG_EVENT_CONTEXT_VTID = 7,
126 LTTNG_EVENT_CONTEXT_PPID = 8,
127 LTTNG_EVENT_CONTEXT_VPPID = 9,
128 LTTNG_EVENT_CONTEXT_PTHREAD_ID = 10,
129 LTTNG_EVENT_CONTEXT_HOSTNAME = 11,
130 LTTNG_EVENT_CONTEXT_IP = 12,
131 LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER = 13,
132 LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER = 14,
133 LTTNG_EVENT_CONTEXT_APP_CONTEXT = 15,
134 LTTNG_EVENT_CONTEXT_INTERRUPTIBLE = 16,
135 LTTNG_EVENT_CONTEXT_PREEMPTIBLE = 17,
136 LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE = 18,
137 LTTNG_EVENT_CONTEXT_MIGRATABLE = 19,
138 LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL = 20,
139 LTTNG_EVENT_CONTEXT_CALLSTACK_USER = 21, /* Supported on x86_32 and x86_64 only. */
140 LTTNG_EVENT_CONTEXT_CGROUP_NS = 22,
141 LTTNG_EVENT_CONTEXT_IPC_NS = 23,
142 LTTNG_EVENT_CONTEXT_MNT_NS = 24,
143 LTTNG_EVENT_CONTEXT_NET_NS = 25,
144 LTTNG_EVENT_CONTEXT_PID_NS = 26,
145 LTTNG_EVENT_CONTEXT_USER_NS = 27,
146 LTTNG_EVENT_CONTEXT_UTS_NS = 28,
147 LTTNG_EVENT_CONTEXT_UID = 29,
148 LTTNG_EVENT_CONTEXT_EUID = 30,
149 LTTNG_EVENT_CONTEXT_SUID = 31,
150 LTTNG_EVENT_CONTEXT_GID = 32,
151 LTTNG_EVENT_CONTEXT_EGID = 33,
152 LTTNG_EVENT_CONTEXT_SGID = 34,
153 LTTNG_EVENT_CONTEXT_VUID = 35,
154 LTTNG_EVENT_CONTEXT_VEUID = 36,
155 LTTNG_EVENT_CONTEXT_VSUID = 37,
156 LTTNG_EVENT_CONTEXT_VGID = 38,
157 LTTNG_EVENT_CONTEXT_VEGID = 39,
158 LTTNG_EVENT_CONTEXT_VSGID = 40,
159 LTTNG_EVENT_CONTEXT_TIME_NS = 41,
160};
161
162enum lttng_event_field_type {
163 LTTNG_EVENT_FIELD_OTHER = 0,
164 LTTNG_EVENT_FIELD_INTEGER = 1,
165 LTTNG_EVENT_FIELD_ENUM = 2,
166 LTTNG_EVENT_FIELD_FLOAT = 3,
167 LTTNG_EVENT_FIELD_STRING = 4,
168};
169
170enum lttng_event_flag {
171 LTTNG_EVENT_FLAG_SYSCALL_32 = (1U << 0),
172 LTTNG_EVENT_FLAG_SYSCALL_64 = (1U << 1),
173};
174
175/*
176 * Perf counter attributes
177 *
178 * The structures should be initialized to zero before use.
179 */
180#define LTTNG_PERF_EVENT_PADDING1 16
181struct lttng_event_perf_counter_ctx {
182 uint32_t type;
183 uint64_t config;
184 char name[LTTNG_SYMBOL_NAME_LEN];
185
186 char padding[LTTNG_PERF_EVENT_PADDING1];
187};
188
189/*
190 * Event/channel context
191 *
192 * The structures should be initialized to zero before use.
193 */
194#define LTTNG_EVENT_CONTEXT_PADDING1 16
195#define LTTNG_EVENT_CONTEXT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
196struct lttng_event_context {
197 enum lttng_event_context_type ctx;
198 char padding[LTTNG_EVENT_CONTEXT_PADDING1];
199
200 union {
201 struct lttng_event_perf_counter_ctx perf_counter;
202 struct {
203 char *provider_name;
204 char *ctx_name;
205 } app_ctx;
206 char padding[LTTNG_EVENT_CONTEXT_PADDING2];
207 } u;
208};
209
210/*
211 * Event probe.
212 *
213 * Either addr is used or symbol_name and offset.
214 *
215 * The structures should be initialized to zero before use.
216 */
217#define LTTNG_EVENT_PROBE_PADDING1 16
218struct lttng_event_probe_attr {
219 uint64_t addr;
220
221 uint64_t offset;
222 char symbol_name[LTTNG_SYMBOL_NAME_LEN];
223
224 char padding[LTTNG_EVENT_PROBE_PADDING1];
225};
226
227/*
228 * Function tracer
229 *
230 * The structures should be initialized to zero before use.
231 */
232#define LTTNG_EVENT_FUNCTION_PADDING1 16
233struct lttng_event_function_attr {
234 char symbol_name[LTTNG_SYMBOL_NAME_LEN];
235
236 char padding[LTTNG_EVENT_FUNCTION_PADDING1];
237};
238
239/*
240 * Generic lttng event
241 *
242 * The structures should be initialized to zero before use.
243 */
244#define LTTNG_EVENT_PADDING1 12
245#define LTTNG_EVENT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
246struct lttng_event {
247 /* Offset 0 */
248 enum lttng_event_type type;
249
250 /* Offset 4 */
251 char name[LTTNG_SYMBOL_NAME_LEN];
252
253 /* Offset 260 */
254 enum lttng_loglevel_type loglevel_type;
255
256 /* Offset 264 */
257 int loglevel;
258
259 /* Offset 268 */
260 int32_t enabled; /* Does not apply: -1 */
261
262 /* Offset 272 */
263 pid_t pid;
264
265 /* Offset 276 */
266 unsigned char filter; /* filter enabled ? */
267
268 /* Offset 277 */
269 unsigned char exclusion; /* exclusions added ? */
270
271 /* Offset 278 */
272 char padding2[2];
273
274 /* Offset 280 */
275 /* Event flag, from 2.6 and above. */
276 enum lttng_event_flag flags;
277
278 /* Offset 284 */
279 char padding[4];
280
281 /* Offset 288 */
282 union {
283 uint64_t padding;
284 void *ptr;
285 } extended;
286
287 /* Offset 296 */
288 /* Per event type configuration */
289 union {
290 struct lttng_event_probe_attr probe;
291 struct lttng_event_function_attr ftrace;
292
293 char padding[LTTNG_EVENT_PADDING2];
294 } attr;
295};
296
297#define LTTNG_EVENT_FIELD_PADDING LTTNG_SYMBOL_NAME_LEN + 32
298struct lttng_event_field {
299 char field_name[LTTNG_SYMBOL_NAME_LEN];
300 enum lttng_event_field_type type;
301 char padding[LTTNG_EVENT_FIELD_PADDING];
302 struct lttng_event event;
303 int nowrite;
304};
305
306/*
307 * List the event(s) of a session channel.
308 *
309 * Both handle and channel_name CAN NOT be NULL.
310 *
311 * Return the size (number of entries) of the "lttng_event" array. Caller must
312 * free events. On error a negative LTTng error code is returned.
313 */
314LTTNG_EXPORT extern int lttng_list_events(struct lttng_handle *handle,
315 const char *channel_name, struct lttng_event **events);
316
317/*
318 * Create an lttng_event.
319 *
320 * This creation function, introduced in LTTng 2.11, works around
321 * the fact that the layout of the 'lttng_event' is publicly exposed.
322 *
323 * It allocates a larger object which exposes the same public fields
324 * as a 'struct lttng_event', but also allows the use of the following extended
325 * attribute setters:
326 * - lttng_event_set_userspace_probe_location();
327 *
328 * Events created through this function must be destroyed using
329 * lttng_event_destroy().
330 *
331 * Returns a zeroed lttng_event on success, NULL on error.
332 */
333LTTNG_EXPORT extern struct lttng_event *lttng_event_create(void);
334
335/*
336 * Destroy an lttng_event.
337 *
338 * This destruction function, introduced in LTTng 2.11, should only
339 * be used with events created by lttng_event_create().
340 */
341LTTNG_EXPORT extern void lttng_event_destroy(struct lttng_event *event);
342
343/*
344 * Get the filter expression of a specific LTTng event.
345 *
346 * If the call is successful, then the filter expression's address is put
347 * in *filter_expression. If the event has no filter expression,
348 * *filter_expression is set to NULL. The caller does NOT own
349 * *filter_expression.
350 *
351 * Returns 0 on success, or a negative LTTng error code on error.
352 */
353LTTNG_EXPORT extern int lttng_event_get_filter_expression(struct lttng_event *event,
354 const char **filter_string);
355
356/*
357 * Get the number of exclusion names of a specific LTTng event.
358 *
359 * Returns the number of exclusion names on success, or a negative
360 * LTTng error code on error.
361 */
362LTTNG_EXPORT extern int lttng_event_get_exclusion_name_count(struct lttng_event *event);
363
364/*
365 * Get an LTTng event's exclusion name at a given index.
366 *
367 * If the call is successful, then the exclusion name string's address
368 * is put in *exclusion_name. The caller does NOT own *exclusion_name.
369 *
370 * Returns 0 on success, or a negative LTTng error code on error.
371 */
372LTTNG_EXPORT extern int lttng_event_get_exclusion_name(struct lttng_event *event,
373 size_t index, const char **exclusion_name);
374
375/*
376 * Get the userspace probe location of a specific LTTng event.
377 * If the call is successful, then a pointer to the probe location is returned.
378 * If the event has no probe location a NULL pointer is returned. The caller
379 * does not own the returned probe location.
380 */
381LTTNG_EXPORT extern const struct lttng_userspace_probe_location *
382lttng_event_get_userspace_probe_location(const struct lttng_event *event);
383
384/*
385 * Set an LTTng event's userspace probe location.
386 *
387 * If the call is successful, then the probe location is set to the event. The
388 * ownership of the probe_location is given to the event.
389 *
390 * Note that the event must have been created using 'lttng_event_create()' in
391 * order for this call to succeed.
392 *
393 * Returns 0 on success, or a negative LTTng error code on error.
394 */
395LTTNG_EXPORT extern int lttng_event_set_userspace_probe_location(struct lttng_event *event,
396 struct lttng_userspace_probe_location *probe_location);
397
398/*
399 * List the available tracepoints of a specific lttng domain.
400 *
401 * The handle CAN NOT be NULL.
402 *
403 * Return the size (number of entries) of the "lttng_event" array. Caller must
404 * free events. On error a negative LTTng error code is returned.
405 */
406LTTNG_EXPORT extern int lttng_list_tracepoints(struct lttng_handle *handle,
407 struct lttng_event **events);
408
409/*
410 * List the available tracepoints fields of a specific lttng domain.
411 *
412 * The handle CAN NOT be NULL.
413 *
414 * Return the size (number of entries) of the "lttng_event_field" array.
415 * Caller must free fields. On error a negative LTTng error code is
416 * returned.
417 */
418LTTNG_EXPORT extern int lttng_list_tracepoint_fields(struct lttng_handle *handle,
419 struct lttng_event_field **fields);
420
421/*
422 * List the available kernel syscall.
423 *
424 * Return the size (number of entries) of the allocated "lttng_event" array.
425 * All events in will be of type syscall. Caller must free events. On error a
426 * negative LTTng error code is returned.
427 */
428LTTNG_EXPORT extern int lttng_list_syscalls(struct lttng_event **events);
429
430/*
431 * Add context to event(s) for a specific channel (or for all).
432 *
433 * If the channel_name is NULL and they are no channel for the domain, the
434 * default channel is created (channel0). The context is then added on ALL
435 * channels since no name was specified.
436 *
437 * The event_name is ignored since adding a context to an event is not possible
438 * for now.
439 *
440 * Return 0 on success else a negative LTTng error code.
441 */
442LTTNG_EXPORT extern int lttng_add_context(struct lttng_handle *handle,
443 struct lttng_event_context *ctx, const char *event_name,
444 const char *channel_name);
445
446/*
447 * Create or enable an event (or events) for a channel.
448 *
449 * If the event you are trying to enable does not exist, it will be created,
450 * else it is enabled. If channel_name is NULL, the default channel is used
451 * (channel0).
452 *
453 * The handle and ev params can not be NULL.
454 *
455 * Return 0 on success else a negative LTTng error code.
456 */
457LTTNG_EXPORT extern int lttng_enable_event(struct lttng_handle *handle,
458 struct lttng_event *ev, const char *channel_name);
459
460/*
461 * Create or enable an event with a specific filter.
462 *
463 * If the event you are trying to enable does not exist, it will be created,
464 * else it is enabled.
465 * If ev is NULL, all events are enabled with that filter.
466 * If channel_name is NULL, the default channel is used (channel0) and created
467 * if not found.
468 * If filter_expression is NULL, an event without associated filter is
469 * created.
470 *
471 * Return 0 on success else a negative LTTng error code.
472 */
473LTTNG_EXPORT extern int lttng_enable_event_with_filter(struct lttng_handle *handle,
474 struct lttng_event *event, const char *channel_name,
475 const char *filter_expression);
476
477/*
478 * Create or enable an event with a filter and/or exclusions.
479 *
480 * If the event you are trying to enable does not exist, it will be created,
481 * else it is enabled.
482 * If ev is NULL, all events are enabled with the filter and exclusion options.
483 * If channel_name is NULL, the default channel is used (channel0) and created
484 * if not found.
485 * If filter_expression is NULL, an event without associated filter is
486 * created.
487 * If exclusion count is zero, the event will be created without exclusions.
488 *
489 * Return 0 on success else a negative LTTng error code.
490 */
491LTTNG_EXPORT extern int lttng_enable_event_with_exclusions(struct lttng_handle *handle,
492 struct lttng_event *event, const char *channel_name,
493 const char *filter_expression,
494 int exclusion_count, char **exclusion_names);
495
496/*
497 * Disable event(s) of a channel and domain.
498 *
499 * If name is NULL, all events are disabled.
500 * If channel_name is NULL, the default channel is used (channel0).
501 *
502 * Return 0 on success else a negative LTTng error code.
503 */
504LTTNG_EXPORT extern int lttng_disable_event(struct lttng_handle *handle,
505 const char *name, const char *channel_name);
506
507/*
508 * Disable event(s) of a channel and domain.
509 *
510 * Takes a struct lttng_event as parameter.
511 * If channel_name is NULL, the default channel is used (channel0).
512 *
513 * Currently, @filter_expression must be NULL. (disabling specific
514 * filter expressions not implemented)
515 * Currently, only LTTNG_EVENT_ALL and LTTNG_EVENT_SYSCALL event types
516 * are implemented for field @ev.
517 *
518 * Return 0 on success else a negative LTTng error code.
519 */
520LTTNG_EXPORT extern int lttng_disable_event_ext(struct lttng_handle *handle,
521 struct lttng_event *ev, const char *channel_name,
522 const char *filter_expression);
523
524#ifdef __cplusplus
525}
526#endif
527
528#endif /* LTTNG_EVENT_H */
This page took 0.024557 seconds and 4 git commands to generate.