X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Flttng.h;h=2b14231eb5534194f695b963c6c3caf2a87ce53a;hp=687a898a1711df0b6d2d09862bd5b391ee53ccf0;hb=7d29a2477524f7ee2ee46a94e538e6141f5ecc0e;hpb=65beb5ffdbe6e17dbd0268aad3c32b02322cd9ad diff --git a/include/lttng/lttng.h b/include/lttng/lttng.h index 687a898a1..2b14231eb 100644 --- a/include/lttng/lttng.h +++ b/include/lttng/lttng.h @@ -24,6 +24,7 @@ #define _LTTNG_H #include +#include #include #include @@ -44,13 +45,33 @@ /* * Every lttng_event_* structure both apply to kernel event and user-space * event. - * - * Every lttng_kernel_* is copied from the LTTng kernel ABI. */ +/* + * Domain type are the different possible tracers. + */ +enum lttng_domain_type { + LTTNG_DOMAIN_KERNEL, + LTTNG_DOMAIN_UST, + LTTNG_DOMAIN_UST_EXEC_NAME, + LTTNG_DOMAIN_UST_PID, + LTTNG_DOMAIN_UST_PID_FOLLOW_CHILDREN, +}; + +struct lttng_domain { + enum lttng_domain_type type; + union { + pid_t pid; + char exec_name[NAME_MAX]; + } attr; +}; + +/* + * Instrumentation type of tracing event. + */ enum lttng_event_type { LTTNG_EVENT_TRACEPOINT, - LTTNG_EVENT_KPROBE, + LTTNG_EVENT_PROBE, LTTNG_EVENT_FUNCTION, }; @@ -58,45 +79,45 @@ enum lttng_event_type { * LTTng consumer mode */ enum lttng_event_output { - /* Using splice(2) */ - LTTNG_EVENT_SPLICE = 0, - /* Using mmap(2) */ - LTTNG_EVENT_MMAP = 1, + LTTNG_EVENT_SPLICE = 0, + LTTNG_EVENT_MMAP = 1, }; -/* Kernel context possible type */ -enum lttng_kernel_context_type { - LTTNG_KERNEL_CONTEXT_PID = 0, - LTTNG_KERNEL_CONTEXT_PERF_COUNTER = 1, - LTTNG_KERNEL_CONTEXT_COMM = 2, - LTTNG_KERNEL_CONTEXT_PRIO = 3, - LTTNG_KERNEL_CONTEXT_NICE = 4, - LTTNG_KERNEL_CONTEXT_VPID = 5, - LTTNG_KERNEL_CONTEXT_TID = 6, - LTTNG_KERNEL_CONTEXT_VTID = 7, - LTTNG_KERNEL_CONTEXT_PPID = 8, - LTTNG_KERNEL_CONTEXT_VPPID = 9, +/* Event context possible type */ +enum lttng_event_context_type { + LTTNG_EVENT_CONTEXT_PID = 0, + LTTNG_EVENT_CONTEXT_PERF_COUNTER = 1, + LTTNG_EVENT_CONTEXT_COMM = 2, + LTTNG_EVENT_CONTEXT_PRIO = 3, + LTTNG_EVENT_CONTEXT_NICE = 4, + LTTNG_EVENT_CONTEXT_VPID = 5, + LTTNG_EVENT_CONTEXT_TID = 6, + LTTNG_EVENT_CONTEXT_VTID = 7, + LTTNG_EVENT_CONTEXT_PPID = 8, + LTTNG_EVENT_CONTEXT_VPPID = 9, }; /* Perf counter attributes */ -struct lttng_kernel_perf_counter_ctx { +struct lttng_event_perf_counter_ctx { uint32_t type; uint64_t config; char name[LTTNG_SYMBOL_NAME_LEN]; }; /* Event/Channel context */ -struct lttng_kernel_context { - enum lttng_kernel_context_type ctx; +struct lttng_event_context { + enum lttng_event_context_type ctx; union { - struct lttng_kernel_perf_counter_ctx perf_counter; + struct lttng_event_perf_counter_ctx perf_counter; } u; }; /* - * Kernel Kprobe. Either addr is used or symbol_name and offset. + * Event probe. + * + * Either addr is used or symbol_name and offset. */ -struct lttng_kernel_kprobe_attr { +struct lttng_event_probe_attr { uint64_t addr; uint64_t offset; @@ -118,7 +139,7 @@ struct lttng_event { enum lttng_event_type type; /* Per event type configuration */ union { - struct lttng_kernel_kprobe_attr kprobe; + struct lttng_event_probe_attr probe; struct lttng_event_function_attr ftrace; } attr; }; @@ -156,53 +177,129 @@ struct lttng_session { char path[PATH_MAX]; }; +/* + * Public LTTng control API + * + * For functions having a lttng domain type as parameter, if a bad value is + * given, NO default is applied and an error is returned. + * + * On success, all functions of the API return 0 or the size of the allocated + * array. + * + * On error, a negative value is returned being a specific lttng-tools error + * code which can be humanly interpreted with lttng_get_readable_code(err). + */ + /* * Session daemon control */ + +/* + * Create tracing session using a name and a path where trace will be written. + */ extern int lttng_create_session(char *name, char *path); +/* + * Destroy tracing session. + * + * The session will not be useable anymore, tracing will stopped for all + * registered trace and tracing buffers will be flushed. + */ extern int lttng_destroy_session(char *name); /* - * Return a "lttng_session" array. Caller must free(3) the returned data. + * List tracing sessions. + * + * Return the size of the "lttng_session" array. Caller must free(3) the + * returned data. */ extern int lttng_list_sessions(struct lttng_session **sessions); +/* + * Check if a session daemon is alive. + */ extern int lttng_session_daemon_alive(void); -/* Set tracing group for the current execution */ +/* + * Set tracing group for the *current* flow of execution. + */ extern int lttng_set_tracing_group(const char *name); +/* + * Set the session name of the *current* flow of execution. + * + * This is a VERY important things to do before doing any tracing actions. If + * it's not done, you'll get an error saying that the session is not found. + * It avoids the use of a session name on every API call. + */ extern void lttng_set_session_name(char *name); +/* + * Return a human readable error message of a lttng-tools error code. + * + * Parameter MUST be a negative value or else you'll get a generic message. + */ extern const char *lttng_get_readable_code(int code); +/* + * Start tracing for *all* registered trace (kernel and user-space). + */ extern int lttng_start_tracing(char *session_name); +/* + * Stop tracing for *all* registered trace (kernel and user-space). + */ extern int lttng_stop_tracing(char *session_name); /* - * LTTng Kernel tracer control + * Add context to event for a specific channel. + * + * If event_name is NULL, the context is applied to all event of the channel. + * If channel_name is NULL, a lookup of the event's channel is done. + * If both are NULL, the context is applied on all events of all channels. */ -extern int lttng_kernel_add_context(struct lttng_kernel_context *ctx, - char *event_name, char *channel_name); - -extern int lttng_kernel_create_channel(struct lttng_channel *chan); - -extern int lttng_kernel_enable_event(struct lttng_event *ev, char *channel_name); -extern int lttng_kernel_enable_channel(char *name); +extern int lttng_add_context(struct lttng_domain *domain, + struct lttng_event_context *ctx, char *event_name, char *channel_name); -extern int lttng_kernel_disable_event(char *name, char *channel_name); +/* + * Create or enable a kernel event. + * + * If the event you are trying to enable does not exist, it will be created, + * else it is enabled. + * + * If channel_name is NULL, the default channel is used (channel0). + */ +extern int lttng_enable_event(struct lttng_domain *domain, struct lttng_event *ev, + char *channel_name); -extern int lttng_kernel_disable_channel(char *name); +/* + * Create or enable a kernel channel. + * + * If name is NULL, the default channel is enabled (channel0). + */ +extern int lttng_enable_channel(struct lttng_domain *domain, struct lttng_channel *chan); -extern int lttng_kernel_list_events(char **event_list); +/* + * Disable kernel event. + * + * If channel_name is NULL, the default channel is used (channel0). + */ +extern int lttng_disable_event(struct lttng_domain *domain, char *name, + char *channel_name); /* - * LTTng User-space tracer control + * Disable kernel channel. + * + * If channel_name is NULL, the default channel is disabled (channel0). */ +extern int lttng_disable_channel(struct lttng_domain *domain, char *name); -//extern int lttng_ust_list_traceable_apps(pid_t **pids); +/* + * List kernel events. + * + * Return the size of the allocated event list. Caller must free(3) the data. + */ +extern int lttng_list_events(struct lttng_domain *domain, char **event_list); #endif /* _LTTNG_H */