Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-02 14:48:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Add reporter bif/framework documentation.

Browse source
This commit is contained in:
Jon Siwek 2011-12-07 16:31:44 -06:00
parent 9ac338341e
commit 5126b65493
3 changed files with 55 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

17
scripts/base/frameworks/reporter/main.bro
View file

@ -1,21 +1,36 @@
##! This framework is intended to create an output and filtering path for
##! internal messages/warnings/errors. It should typically be loaded to
##! avoid Bro spewing internal messages to standard error.
##! avoid Bro spewing internal messages to standard error and instead log
##! them to a file in a standard way. Note that this framework deals with
##! the handling of internally-generated reporter messages, for the
##! interface into actually creating reporter messages from the scripting
##! layer, use the built-in functions in :doc:`/scripts/base/reporter.bif`.
module Reporter;
export {
## The reporter logging stream identifier.
redef enum Log::ID += { LOG };
## An indicator of reporter message severity.
type Level: enum {
## Informational, not needing specific attention.
INFO,
## Warning of a potential problem.
WARNING,
## A non-fatal error that should be addressed, but doesn't
## terminate program execution.
ERROR
};
## The record type which contains the column fields of the reporter log.
type Info: record {
## The network time at which the reporter event was generated.
ts: time &log;
## The severity of the reporter message.
level: Level &log;
## An info/warning/error message that could have either been
## generated from the internal Bro core or at the scripting-layer.
message: string &log;
## This is the location in a Bro script where the message originated.
## Not all reporter messages will have locations in them though.

4
src/event.bif
View file

@ -5575,7 +5575,7 @@ event reporter_info%(t: time, msg: string, location: string%) &error_handler;
## location: A (potentially empty) string describing a location associated with the
## warning.
##
## .. bro:see:: reporter_warning reporter_error Reporter::info Reporter::warning
## .. bro:see:: reporter_info reporter_error Reporter::info Reporter::warning
## Reporter::error
##
## .. note:: Bro will not call reporter events recursively. If the handler of any
@ -5594,7 +5594,7 @@ event reporter_warning%(t: time, msg: string, location: string%) &error_handler;
## location: A (potentially empty) string describing a location associated with the
## error.
##
## .. bro:see:: reporter_error reporter_error Reporter::info Reporter::error
## .. bro:see:: reporter_info reporter_warning Reporter::info Reporter::warning
## Reporter::error
##
## .. note:: Bro will not call reporter events recursively. If the handler of any

35
src/reporter.bif
View file

@ -1,3 +1,11 @@
##! The reporter built-in functions allow for the scripting layer to
##! generate messages of varying severity. If no event handlers
##! exist for reporter messages, the messages are output to stderr.
##! If event handlers do exist, it's assumed they take care of determining
##! how/where to output the messages.
##!
##! See :doc:`/scripts/base/frameworks/reporter/main` for a convenient
##! reporter message logging framework.
module Reporter;
@ -5,6 +13,13 @@ module Reporter;
#include "NetVar.h"
%%}
## Generates an informational message.
##
## msg: The informational message to report.
##
## Returns: Always true.
##
## .. bro:see:: reporter_info
function Reporter::info%(msg: string%): bool
%{
reporter->PushLocation(frame->GetCall()->GetLocationInfo());
@ -13,6 +28,13 @@ function Reporter::info%(msg: string%): bool
return new Val(1, TYPE_BOOL);
%}
## Generates a message that warns of a potential problem.
##
## msg: The warning message to report.
##
## Returns: Always true.
##
## .. bro:see:: reporter_warning
function Reporter::warning%(msg: string%): bool
%{
reporter->PushLocation(frame->GetCall()->GetLocationInfo());
@ -21,6 +43,14 @@ function Reporter::warning%(msg: string%): bool
return new Val(1, TYPE_BOOL);
%}
## Generates a non-fatal error indicative of a definite problem that should
## be addressed. Program execution does not terminate.
##
## msg: The error message to report.
##
## Returns: Always true.
##
## .. bro:see:: reporter_error
function Reporter::error%(msg: string%): bool
%{
reporter->PushLocation(frame->GetCall()->GetLocationInfo());
@ -29,6 +59,11 @@ function Reporter::error%(msg: string%): bool
return new Val(1, TYPE_BOOL);
%}
## Generates a fatal error on stderr and terminates program execution.
##
## msg: The error message to report.
##
## Returns: Always true.
function Reporter::fatal%(msg: string%): bool
%{
reporter->PushLocation(frame->GetCall()->GetLocationInfo());