From: Alan T. DeKok Date: Mon, 16 Oct 2023 12:34:10 +0000 (-0400) Subject: add and document log.warn() and log.err() X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=647fd4faf3f4da7d086be83e02724e22ee2366f2;p=thirdparty%2Ffreeradius-server.git add and document log.warn() and log.err() --- diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc index f85a693c289..30f1616faf2 100644 --- a/doc/antora/modules/reference/nav.adoc +++ b/doc/antora/modules/reference/nav.adoc @@ -66,6 +66,7 @@ *** xref:xlat/deprecated.adoc[Deprecated Functions] *** xref:xlat/file.adoc[File handling] *** xref:xlat/function.adoc[Function Syntax] +*** xref:xlat/log.adoc[Logging Functions] *** xref:xlat/builtin.adoc[Built-in Expansions] *** xref:xlat/character.adoc[Single Letter Expansions] *** xref:xlat/attribute.adoc[Attribute References] diff --git a/doc/antora/modules/reference/pages/xlat/builtin.adoc b/doc/antora/modules/reference/pages/xlat/builtin.adoc index ba5089be934..4f2ee3cc4d5 100644 --- a/doc/antora/modules/reference/pages/xlat/builtin.adoc +++ b/doc/antora/modules/reference/pages/xlat/builtin.adoc @@ -978,32 +978,5 @@ This kind of math works well for "tomorrow", but it is less useful for "next week Monday", or "start of next month". The `%nexttime(...)` expansion above should be used for those time operations. -== Logging - -=== %log.debug() - -Logs a message at a DEBUG level. This function returns nothing. - -[source,unlang] ----- -%log.debug("Now processing %interpreter(...filename):%interpreter(...line)") ----- - -The DEBUG messages are printed only when the server has the debug flag set. - -=== %log.info() - -Logs a message at a INFO level. This function returns nothing. - -[source,unlang] ----- -%log.info("Doing something useful now") ----- - -The INFO messages are always logged. We suggest using these messages -only to log special or unusual events. Producing multiple log -messages per packet is not recommended, and can have a surprisingly -large (and negative) impact on performance. - // Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/log.adoc b/doc/antora/modules/reference/pages/xlat/log.adoc new file mode 100644 index 00000000000..0f4c8c12eac --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/log.adoc @@ -0,0 +1,54 @@ += Logging Functions + +These functions perform logging at various levels. + +We suggest using these messages only to log special or unusual events. +Producing multiple log messages per packet is not recommended, and can +have a surprisingly large (and negative) impact on performance. + +== %log.debug(_string_) + +Logs a message at a DEBUG level. This function returns nothing. + +[source,unlang] +---- +%log.debug("Now processing %interpreter(...filename):%interpreter(...line)") +---- + +The DEBUG messages are printed only when the server has the debug flag set. + +== %log.err(_string_) + +Logs a message at a ERROR level. This function returns nothing. + +[source,unlang] +---- +%log.err("Something very bad happened") +---- + +The ERROR messages are always logged. + +== %log.info(_string_) + +Logs a message at a INFO level. This function returns nothing. + +[source,unlang] +---- +%log.info("Doing something useful now") +---- + +The INFO messages are always logged. + +== %log.watn(_string_) + +Logs a message at a WARN level. This function returns nothing. + +[source,unlang] +---- +%log.warn("Something bad might be happening") +---- + +The WARN messages are always logged. + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/src/lib/unlang/xlat_builtin.c b/src/lib/unlang/xlat_builtin.c index 867fca9ffec..4e7fee5fd34 100644 --- a/src/lib/unlang/xlat_builtin.c +++ b/src/lib/unlang/xlat_builtin.c @@ -880,7 +880,7 @@ static xlat_arg_parser_t const xlat_func_log_arg[] = { * * Example: @verbatim -%log("foo") == "0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33" +%log("This is an informational message") @endverbatim * * @ingroup xlat_functions @@ -905,7 +905,7 @@ static xlat_action_t xlat_func_log_info(UNUSED TALLOC_CTX *ctx, UNUSED fr_dcurso * * Example: @verbatim -%log.debug("foo") == "0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33" +%log.debug("This is a message") @endverbatim * * @ingroup xlat_functions @@ -926,6 +926,56 @@ static xlat_action_t xlat_func_log_debug(UNUSED TALLOC_CTX *ctx, UNUSED fr_dcurs } +/** Log something at DEBUG level. + * + * Example: +@verbatim +%log.err("Big errror here") +@endverbatim + * + * @ingroup xlat_functions + */ +static xlat_action_t xlat_func_log_err(UNUSED TALLOC_CTX *ctx, UNUSED fr_dcursor_t *out, + UNUSED xlat_ctx_t const *xctx, + request_t *request, fr_value_box_list_t *args) +{ + fr_value_box_t *vb; + + XLAT_ARGS(args, &vb); + + if (!vb) return XLAT_ACTION_DONE; + + REDEBUG("%s", vb->vb_strvalue); + + return XLAT_ACTION_DONE; +} + + +/** Log something at WARNlevel. + * + * Example: +@verbatim +%log.warn("Maybe something bad happened") +@endverbatim + * + * @ingroup xlat_functions + */ +static xlat_action_t xlat_func_log_warn(UNUSED TALLOC_CTX *ctx, UNUSED fr_dcursor_t *out, + UNUSED xlat_ctx_t const *xctx, + request_t *request, fr_value_box_list_t *args) +{ + fr_value_box_t *vb; + + XLAT_ARGS(args, &vb); + + if (!vb) return XLAT_ACTION_DONE; + + RWDEBUG("%s", vb->vb_strvalue); + + return XLAT_ACTION_DONE; +} + + static xlat_arg_parser_t const xlat_func_map_arg[] = { { .required = true, .concat = true, .type = FR_TYPE_STRING }, XLAT_ARG_PARSER_TERMINATOR @@ -3525,7 +3575,9 @@ do { \ XLAT_REGISTER_ARGS("debug_attr", xlat_func_debug_attr, FR_TYPE_NULL, xlat_func_debug_attr_args); XLAT_REGISTER_ARGS("immutable", xlat_func_immutable_attr, FR_TYPE_NULL, xlat_func_immutable_attr_args); XLAT_REGISTER_ARGS("log.debug", xlat_func_log_debug, FR_TYPE_NULL, xlat_func_log_arg); + XLAT_REGISTER_ARGS("log.err", xlat_func_log_err, FR_TYPE_NULL, xlat_func_log_arg); XLAT_REGISTER_ARGS("log.info", xlat_func_log_info, FR_TYPE_NULL, xlat_func_log_arg); + XLAT_REGISTER_ARGS("log.warn", xlat_func_log_warn, FR_TYPE_NULL, xlat_func_log_arg); XLAT_REGISTER_ARGS("nexttime", xlat_func_next_time, FR_TYPE_UINT64, xlat_func_next_time_args); XLAT_REGISTER_ARGS("pairs", xlat_func_pairs, FR_TYPE_STRING, xlat_func_pairs_args); XLAT_REGISTER_ARGS("subst", xlat_func_subst, FR_TYPE_STRING, xlat_func_subst_args);