RepoMirrors/haproxy
1
0
Fork 0
mirror of http://git.haproxy.org/git/haproxy.git/ synced 2024-12-21 20:00:17 +00:00
Code Issues Packages Projects Releases Wiki Activity
be5a288424
haproxy/include/proto/trace.h

127 lines
5.0 KiB
C
Raw Normal View History

MINOR: trace: start to create a new trace subsystem The principle of this subsystem will be to support taking live traces at various places in the code with conditional triggers, filters, and ability to lock on some elements. The traces will support typed events and will be sent into sinks made of ring buffers, file descriptors or remote servers.
2019-08-08 16:21:26 +00:00
/*
* include/proto/trace.h
* This file provides functions for runtime tracing
*
* Copyright (C) 2000-2019 Willy Tarreau - w@1wt.eu
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation, version 2.1
* exclusively.
*
* This library 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
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#ifndef _PROTO_TRACE_H
#define _PROTO_TRACE_H
#include <common/buffer.h>
#include <common/compat.h>
#include <common/config.h>
#include <common/ist.h>
#include <common/mini-clist.h>
#include <types/log.h>
#include <types/sink.h>
#include <types/trace.h>
MINOR: trace: add per-level macros to produce traces The new TRACE_<level>() macros take a mask, 4 args, a callback and a static message. From this they also inherit the TRACE_SOURCE macro from the caller, which contains the pointer to the trace source (so that it's not required to paste it everywhere), and an ist string is also made by the concatenation of the file name and the line number. This uses string concatenation by the preprocessor, and turns it into an ist by the compiler so that there is no operation at all to perform to adjust the data length as the compiler knows where to cut during the optimization phase. Last, the message is also automatically turned into an ist so that it's trivial to put it into an iovec without having to run strlen() on it. All arguments and the callback may be empty and will then automatically be replaced with a NULL pointer. This makes the TRACE calls slightly lighter especially since arguments are not always used. Several other options were considered to use variadic macros but there's no outstanding rule that justifies to place an argument before another one, and it still looks convenient to have the message be the last one to encourage copy- pasting of the trace statements. A generic TRACE() macro takes TRACE_LEVEL in from the source file as the trace level instead of taking it from its name. This may slightly simplify the production of traces that always run at the same level (internal core parts may probably only be called at developer level).
2019-08-12 15:27:09 +00:00
/* Make a string from the location of the trace producer as "file:line" */
#define TRC_LOC _TRC_LOC(__FILE__, __LINE__)
#define _TRC_LOC(f,l) __TRC_LOC(f, ":", l)
#define __TRC_LOC(f,c,l) f c #l
MINOR: trace: change the TRACE() calling convention to put the args and cb last Previously the callback was almost mandatory so it made sense to have it before the message. Now that it can default to the one declared in the trace source, most TRACE() calls contain series of empty args and callbacks, which make them suitable for being at the end and being totally omitted. This patch thus reverses the TRACE arguments so that the message appears first, then the mask, then arg1..arg4, then the callback. In practice we'll mostly see 1 arg, or 2 args and nothing else, and it will not be needed anymore to pass long series of commas in the middle of the arguments. However if a source is enforced, the empty commas will still be needed for all omitted arguments.
2019-08-28 08:35:16 +00:00
/* truncate a macro arg list to exactly 5 args and replace missing ones with NULL */
#define TRC_5ARGS(a1,a2,a3,a4,a5,...) DEFNULL(a1),DEFNULL(a2),DEFNULL(a3),DEFNULL(a4),DEFNULL(a5)
MINOR: trace: add per-level macros to produce traces The new TRACE_<level>() macros take a mask, 4 args, a callback and a static message. From this they also inherit the TRACE_SOURCE macro from the caller, which contains the pointer to the trace source (so that it's not required to paste it everywhere), and an ist string is also made by the concatenation of the file name and the line number. This uses string concatenation by the preprocessor, and turns it into an ist by the compiler so that there is no operation at all to perform to adjust the data length as the compiler knows where to cut during the optimization phase. Last, the message is also automatically turned into an ist so that it's trivial to put it into an iovec without having to run strlen() on it. All arguments and the callback may be empty and will then automatically be replaced with a NULL pointer. This makes the TRACE calls slightly lighter especially since arguments are not always used. Several other options were considered to use variadic macros but there's no outstanding rule that justifies to place an argument before another one, and it still looks convenient to have the message be the last one to encourage copy- pasting of the trace statements. A generic TRACE() macro takes TRACE_LEVEL in from the source file as the trace level instead of taking it from its name. This may slightly simplify the production of traces that always run at the same level (internal core parts may probably only be called at developer level).
2019-08-12 15:27:09 +00:00
/* For convenience, TRACE() alone uses the file's default TRACE_LEVEL, most
MINOR: trace: change the TRACE() calling convention to put the args and cb last Previously the callback was almost mandatory so it made sense to have it before the message. Now that it can default to the one declared in the trace source, most TRACE() calls contain series of empty args and callbacks, which make them suitable for being at the end and being totally omitted. This patch thus reverses the TRACE arguments so that the message appears first, then the mask, then arg1..arg4, then the callback. In practice we'll mostly see 1 arg, or 2 args and nothing else, and it will not be needed anymore to pass long series of commas in the middle of the arguments. However if a source is enforced, the empty commas will still be needed for all omitted arguments.
2019-08-28 08:35:16 +00:00
* likely TRACE_LEVEL_DEVELOPER, though the other explicit variants specify
* the desired level and will work when TRACE_LEVEL is not set. The 5 optional
* arguments are the 4 source-specific arguments that are passed to the cb()
* callback dedicated to decoding, and which may be used for special tracking.
* These 4 arguments as well as the cb() function pointer may all be NULL, or
* simply omitted (in which case they will be replaced by a NULL). This
* ordering allows many TRACE() calls to be placed using copy-paste and just
* change the message at the beginning.
MINOR: trace: add per-level macros to produce traces The new TRACE_<level>() macros take a mask, 4 args, a callback and a static message. From this they also inherit the TRACE_SOURCE macro from the caller, which contains the pointer to the trace source (so that it's not required to paste it everywhere), and an ist string is also made by the concatenation of the file name and the line number. This uses string concatenation by the preprocessor, and turns it into an ist by the compiler so that there is no operation at all to perform to adjust the data length as the compiler knows where to cut during the optimization phase. Last, the message is also automatically turned into an ist so that it's trivial to put it into an iovec without having to run strlen() on it. All arguments and the callback may be empty and will then automatically be replaced with a NULL pointer. This makes the TRACE calls slightly lighter especially since arguments are not always used. Several other options were considered to use variadic macros but there's no outstanding rule that justifies to place an argument before another one, and it still looks convenient to have the message be the last one to encourage copy- pasting of the trace statements. A generic TRACE() macro takes TRACE_LEVEL in from the source file as the trace level instead of taking it from its name. This may slightly simplify the production of traces that always run at the same level (internal core parts may probably only be called at developer level).
2019-08-12 15:27:09 +00:00
*/
MINOR: trace: change the TRACE() calling convention to put the args and cb last Previously the callback was almost mandatory so it made sense to have it before the message. Now that it can default to the one declared in the trace source, most TRACE() calls contain series of empty args and callbacks, which make them suitable for being at the end and being totally omitted. This patch thus reverses the TRACE arguments so that the message appears first, then the mask, then arg1..arg4, then the callback. In practice we'll mostly see 1 arg, or 2 args and nothing else, and it will not be needed anymore to pass long series of commas in the middle of the arguments. However if a source is enforced, the empty commas will still be needed for all omitted arguments.
2019-08-28 08:35:16 +00:00
#define TRACE(msg, mask, ...) \
trace(TRACE_LEVEL, (mask), TRACE_SOURCE, ist(TRC_LOC), TRC_5ARGS(__VA_ARGS__,,,,,), ist(msg))
#define TRACE_USER(msg, mask, ...) \
trace(TRACE_LEVEL_USER, (mask), TRACE_SOURCE, ist(TRC_LOC), TRC_5ARGS(__VA_ARGS__,,,,,), ist(msg))
#define TRACE_PAYLOAD(msg, mask, ...) \
trace(TRACE_LEVEL_PAYLOAD, (mask), TRACE_SOURCE, ist(TRC_LOC), TRC_5ARGS(__VA_ARGS__,,,,,), ist(msg))
#define TRACE_PROTO(msg, mask, ...) \
trace(TRACE_LEVEL_PROTO, (mask), TRACE_SOURCE, ist(TRC_LOC), TRC_5ARGS(__VA_ARGS__,,,,,), ist(msg))
MINOR: trace: add per-level macros to produce traces The new TRACE_<level>() macros take a mask, 4 args, a callback and a static message. From this they also inherit the TRACE_SOURCE macro from the caller, which contains the pointer to the trace source (so that it's not required to paste it everywhere), and an ist string is also made by the concatenation of the file name and the line number. This uses string concatenation by the preprocessor, and turns it into an ist by the compiler so that there is no operation at all to perform to adjust the data length as the compiler knows where to cut during the optimization phase. Last, the message is also automatically turned into an ist so that it's trivial to put it into an iovec without having to run strlen() on it. All arguments and the callback may be empty and will then automatically be replaced with a NULL pointer. This makes the TRACE calls slightly lighter especially since arguments are not always used. Several other options were considered to use variadic macros but there's no outstanding rule that justifies to place an argument before another one, and it still looks convenient to have the message be the last one to encourage copy- pasting of the trace statements. A generic TRACE() macro takes TRACE_LEVEL in from the source file as the trace level instead of taking it from its name. This may slightly simplify the production of traces that always run at the same level (internal core parts may probably only be called at developer level).
2019-08-12 15:27:09 +00:00
MINOR: trace: change the TRACE() calling convention to put the args and cb last Previously the callback was almost mandatory so it made sense to have it before the message. Now that it can default to the one declared in the trace source, most TRACE() calls contain series of empty args and callbacks, which make them suitable for being at the end and being totally omitted. This patch thus reverses the TRACE arguments so that the message appears first, then the mask, then arg1..arg4, then the callback. In practice we'll mostly see 1 arg, or 2 args and nothing else, and it will not be needed anymore to pass long series of commas in the middle of the arguments. However if a source is enforced, the empty commas will still be needed for all omitted arguments.
2019-08-28 08:35:16 +00:00
#define TRACE_STATE(msg, mask, ...) \
trace(TRACE_LEVEL_STATE, (mask), TRACE_SOURCE, ist(TRC_LOC), TRC_5ARGS(__VA_ARGS__,,,,,), ist(msg))
MINOR: trace: add per-level macros to produce traces The new TRACE_<level>() macros take a mask, 4 args, a callback and a static message. From this they also inherit the TRACE_SOURCE macro from the caller, which contains the pointer to the trace source (so that it's not required to paste it everywhere), and an ist string is also made by the concatenation of the file name and the line number. This uses string concatenation by the preprocessor, and turns it into an ist by the compiler so that there is no operation at all to perform to adjust the data length as the compiler knows where to cut during the optimization phase. Last, the message is also automatically turned into an ist so that it's trivial to put it into an iovec without having to run strlen() on it. All arguments and the callback may be empty and will then automatically be replaced with a NULL pointer. This makes the TRACE calls slightly lighter especially since arguments are not always used. Several other options were considered to use variadic macros but there's no outstanding rule that justifies to place an argument before another one, and it still looks convenient to have the message be the last one to encourage copy- pasting of the trace statements. A generic TRACE() macro takes TRACE_LEVEL in from the source file as the trace level instead of taking it from its name. This may slightly simplify the production of traces that always run at the same level (internal core parts may probably only be called at developer level).
2019-08-12 15:27:09 +00:00
MINOR: trace: change the TRACE() calling convention to put the args and cb last Previously the callback was almost mandatory so it made sense to have it before the message. Now that it can default to the one declared in the trace source, most TRACE() calls contain series of empty args and callbacks, which make them suitable for being at the end and being totally omitted. This patch thus reverses the TRACE arguments so that the message appears first, then the mask, then arg1..arg4, then the callback. In practice we'll mostly see 1 arg, or 2 args and nothing else, and it will not be needed anymore to pass long series of commas in the middle of the arguments. However if a source is enforced, the empty commas will still be needed for all omitted arguments.
2019-08-28 08:35:16 +00:00
#define TRACE_DEVEL(msg, mask, ...) \
trace(TRACE_LEVEL_DEVELOPER, (mask), TRACE_SOURCE, ist(TRC_LOC), TRC_5ARGS(__VA_ARGS__,,,,,), ist(msg))
MINOR: trace: add per-level macros to produce traces The new TRACE_<level>() macros take a mask, 4 args, a callback and a static message. From this they also inherit the TRACE_SOURCE macro from the caller, which contains the pointer to the trace source (so that it's not required to paste it everywhere), and an ist string is also made by the concatenation of the file name and the line number. This uses string concatenation by the preprocessor, and turns it into an ist by the compiler so that there is no operation at all to perform to adjust the data length as the compiler knows where to cut during the optimization phase. Last, the message is also automatically turned into an ist so that it's trivial to put it into an iovec without having to run strlen() on it. All arguments and the callback may be empty and will then automatically be replaced with a NULL pointer. This makes the TRACE calls slightly lighter especially since arguments are not always used. Several other options were considered to use variadic macros but there's no outstanding rule that justifies to place an argument before another one, and it still looks convenient to have the message be the last one to encourage copy- pasting of the trace statements. A generic TRACE() macro takes TRACE_LEVEL in from the source file as the trace level instead of taking it from its name. This may slightly simplify the production of traces that always run at the same level (internal core parts may probably only be called at developer level).
2019-08-12 15:27:09 +00:00
MINOR: trace: start to create a new trace subsystem The principle of this subsystem will be to support taking live traces at various places in the code with conditional triggers, filters, and ability to lock on some elements. The traces will support typed events and will be sent into sinks made of ring buffers, file descriptors or remote servers.
2019-08-08 16:21:26 +00:00
extern struct list trace_sources;
MINOR: trace: add allocation of buffer-sized trace buffers This will be needed so that we can implement protocol decoders which will have to emit their contents into such a buffer.
2019-08-19 13:55:34 +00:00
extern THREAD_LOCAL struct buffer trace_buf;
MINOR: trace: start to create a new trace subsystem The principle of this subsystem will be to support taking live traces at various places in the code with conditional triggers, filters, and ability to lock on some elements. The traces will support typed events and will be sent into sinks made of ring buffers, file descriptors or remote servers.
2019-08-08 16:21:26 +00:00
MINOR: trace: implement a call to a decode function The trace() call will support an optional decoding callback and 4 arguments that this function is supposed to know how to use to provide extra information. The output remains unchanged when the function is NULL. Otherwise, the message is pre-filled into the thread-local trace_buf, and the function is called with all arguments so that it completes the buffer in a readable form depending on the expected level of detail.
2019-08-19 14:28:07 +00:00
void __trace(enum trace_level level, uint64_t mask, struct trace_source *src, const struct ist where,
const void *a1, const void *a2, const void *a3, const void *a4,
void (*cb)(enum trace_level level, uint64_t mask, const struct trace_source *src, const struct ist where,
const void *a1, const void *a2, const void *a3, const void *a4),
const struct ist msg);
MINOR: trace: implement a very basic trace() function For now it remains quite basic. It performs a few state checks, calls the source's sink if defined, and performs the transitions between RUNNING, STOPPED and WAITING when the configured events match.
2019-08-12 13:51:58 +00:00
MINOR: trace/cli: register the "trace" CLI keyword to list the sources For now it lists the sources if one is not provided, and checks for the source's existence. It lists the events if not provided, checks for their existence if provided, and adjusts reported events/start/stop/pause events, and performs state transitions. It lists sinks and adjusts them as well. Filters, lock, and level are not implemented yet.
2019-08-08 16:48:12 +00:00
/* return a single char to describe a trace state */
static inline char trace_state_char(enum trace_state st)
{
return (st == TRACE_STATE_RUNNING) ? 'R' :
(st == TRACE_STATE_WAITING) ? 'w' :
'.';
}
/* return a single char to describe an event state */
static inline char trace_event_char(uint64_t conf, uint64_t ev)
{
return (conf & ev) ? '+' : '-';
}
MINOR: trace: start to create a new trace subsystem The principle of this subsystem will be to support taking live traces at various places in the code with conditional triggers, filters, and ability to lock on some elements. The traces will support typed events and will be sent into sinks made of ring buffers, file descriptors or remote servers.
2019-08-08 16:21:26 +00:00
/* registers trace source <source>. Modifies the list element!
* The {start,pause,stop,report} events are not changed so the source may
* preset them.
*/
static inline void trace_register_source(struct trace_source *source)
{
source->lockon = TRACE_LOCKON_NOTHING;
source->level = TRACE_LEVEL_USER;
source->detail_level = LOG_NOTICE;
source->sink = NULL;
source->state = TRACE_STATE_STOPPED;
source->lockon_ptr = NULL;
LIST_ADDQ(&trace_sources, &source->source_link);
}
MINOR: trace: implement a very basic trace() function For now it remains quite basic. It performs a few state checks, calls the source's sink if defined, and performs the transitions between RUNNING, STOPPED and WAITING when the configured events match.
2019-08-12 13:51:58 +00:00
/* sends a trace for the given source */
MINOR: trace: implement a call to a decode function The trace() call will support an optional decoding callback and 4 arguments that this function is supposed to know how to use to provide extra information. The output remains unchanged when the function is NULL. Otherwise, the message is pre-filled into the thread-local trace_buf, and the function is called with all arguments so that it completes the buffer in a readable form depending on the expected level of detail.
2019-08-19 14:28:07 +00:00
static inline void trace(enum trace_level level, uint64_t mask, struct trace_source *src, const struct ist where,
const void *a1, const void *a2, const void *a3, const void *a4,
void (*cb)(enum trace_level level, uint64_t mask, const struct trace_source *src, const struct ist where,
const void *a1, const void *a2, const void *a3, const void *a4),
const struct ist msg)
MINOR: trace: implement a very basic trace() function For now it remains quite basic. It performs a few state checks, calls the source's sink if defined, and performs the transitions between RUNNING, STOPPED and WAITING when the configured events match.
2019-08-12 13:51:58 +00:00
{
if (unlikely(src->state != TRACE_STATE_STOPPED))
MINOR: trace: implement a call to a decode function The trace() call will support an optional decoding callback and 4 arguments that this function is supposed to know how to use to provide extra information. The output remains unchanged when the function is NULL. Otherwise, the message is pre-filled into the thread-local trace_buf, and the function is called with all arguments so that it completes the buffer in a readable form depending on the expected level of detail.
2019-08-19 14:28:07 +00:00
__trace(level, mask, src, where, a1, a2, a3, a4, cb, msg);
MINOR: trace: implement a very basic trace() function For now it remains quite basic. It performs a few state checks, calls the source's sink if defined, and performs the transitions between RUNNING, STOPPED and WAITING when the configured events match.
2019-08-12 13:51:58 +00:00
}
MINOR: trace: start to create a new trace subsystem The principle of this subsystem will be to support taking live traces at various places in the code with conditional triggers, filters, and ability to lock on some elements. The traces will support typed events and will be sent into sinks made of ring buffers, file descriptors or remote servers.
2019-08-08 16:21:26 +00:00
#endif /* _PROTO_TRACE_H */
/*
* Local variables:
* c-indent-level: 8
* c-basic-offset: 8
* End:
*/
Reference in New Issue Copy Permalink