doc/examples/easy-ust/sample_component_provider.h

   1 /*
   2  * Copyright (C) 2011-2012  Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   3  * Copyright (C) 2011-2012  Matthew Khouzam <matthew.khouzam@ericsson.com>
   4  *
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy
   6  * of this software and associated documentation files (the "Software"), to deal
   7  * in the Software without restriction, including without limitation the rights
   8  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9  * copies of the Software, and to permit persons to whom the Software is
  10  * furnished to do so, subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be included in
  13  * all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  21  * SOFTWARE.
  22  */
  23
  24 /*
  25  * Sample lttng-ust tracepoint provider.
  26  */
  27
  28 /*
  29  * First part: defines
  30  * We undef a macro before defining it as it can be used in several files.
  31  */
  32
  33 /*
  34  * Must be included before include tracepoint provider
  35  * ex.: project_event
  36  * ex.: project_component_event
  37  *
  38  * Optional company name goes here
  39  * ex.: com_efficios_project_component_event
  40  *
  41  * In this example, "sample" is the project, and "component" is the
  42  * component.
  43  */
  44 #undef TRACEPOINT_PROVIDER
  45 #define TRACEPOINT_PROVIDER sample_component
  46
  47 /*
  48  * include file (this files's name)
  49  */
  50 #undef TRACEPOINT_INCLUDE
  51 #define TRACEPOINT_INCLUDE "./sample_component_provider.h"
  52
  53 /*
  54  * Add this macro and its matching element to make sure the program
  55  * works in c++.
  56  */
  57 #ifdef __cplusplus
  58 extern "C" {
  59 #endif /* __cplusplus */
  60
  61 /*
  62  * Add this precompiler conditionals to ensure the tracepoint event generation
  63  * can include this file more than once.
  64  */
  65 #if !defined(_SAMPLE_COMPONENT_PROVIDER_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
  66 #define _SAMPLE_COMPONENT_PROVIDER_H
  67 /*
  68  * Add this to allow programs to call "tracepoint(...):
  69  */
  70 #include <lttng/tracepoint.h>
  71
  72 /*
  73  * The following tracepoint event writes a message (c string) into the
  74  * field message of the trace event message in the provider
  75  * sample_component in other words:
  76  *
  77  *    sample_component:message:message = text.
  78  */
  79 TRACEPOINT_EVENT(
  80         /*
  81          * provider name, not a variable but a string starting with a letter
  82          * and containing either letters, numbers or underscores.
  83          * Needs to be the same as TRACEPOINT_PROVIDER
  84          */
  85         sample_component,
  86         /*
  87          * tracepoint name, same format as sample provider. Does not need to be
  88          * declared before. in this case the name is "message"
  89          */
  90         message,
  91         /*
  92          * TP_ARGS macro contains the arguments passed for the tracepoint
  93          * it is in the following format
  94          *              TP_ARGS( type1, name1, type2, name2, ... type10, name10)
  95          * where there can be from zero to ten elements.
  96          * typeN is the datatype, such as int, struct or double **.
  97          * name is the variable name (in "int myInt" the name would be myint)
  98          *              TP_ARGS() is valid to mean no arguments
  99          *              TP_ARGS( void ) is valid too
 100          */
 101         TP_ARGS(char *, text),
 102         /*
 103          * TP_FIELDS describes how to write the fields of the trace event.
 104          * You can use the args here
 105          */
 106         TP_FIELDS(
 107         /*
 108          * The ctf_string macro takes a c string and writes it into a field
 109          * named "message"
 110          */
 111                 ctf_string(message, text)
 112         )
 113 )
 114 /*
 115  * Trace loglevel, shows the level of the trace event. It can be TRACE_EMERG,
 116  * TRACE_ALERT, TRACE_CRIT, TRACE_ERR, TRACE_WARNING, TRACE_INFO or others.
 117  * If this is not set, TRACE_DEFAULT is assumed.
 118  * The first two arguments identify the tracepoint
 119  * See details in <lttng/tracepoint.h> line 347
 120  */
 121 TRACEPOINT_LOGLEVEL(
 122        /*
 123         * The provider name, must be the same as the provider name in the
 124         * TRACEPOINT_EVENT and as TRACEPOINT_PROVIDER above.
 125         */
 126         sample_component,
 127        /*
 128         * The tracepoint name, must be the same as the tracepoint name in the
 129         * TRACEPOINT_EVENT
 130         */
 131         message,
 132        /*
 133         * The tracepoint loglevel. Warning, some levels are abbreviated and
 134         * others are not, please see <lttng/tracepoint.h>
 135         */
 136         TRACE_WARNING)
 137
 138 #endif /* _SAMPLE_COMPONENT_PROVIDER_H */
 139
 140 /*
 141  * Add this after defining the tracepoint events to expand the macros.
 142  */
 143 #include <lttng/tracepoint-event.h>
 144
 145 /*
 146  * Add this macro and its matching element to make sure the program
 147  * works in c++.
 148  */
 149 #ifdef __cplusplus
 150 }
 151 #endif /* __cplusplus */