From 8841d0ae771b3d201ded29e921d8ef3fbe02fbaa Mon Sep 17 00:00:00 2001 From: Daniel Thayer Date: Thu, 19 Mar 2015 16:01:28 -0500 Subject: [PATCH] Minor improvements to logging framework documentation --- scripts/base/frameworks/logging/main.bro | 51 ++++++++++--------- .../base/frameworks/logging/writers/ascii.bro | 14 ++--- 2 files changed, 34 insertions(+), 31 deletions(-) diff --git a/scripts/base/frameworks/logging/main.bro b/scripts/base/frameworks/logging/main.bro index d4d5c0244e..aecc552146 100644 --- a/scripts/base/frameworks/logging/main.bro +++ b/scripts/base/frameworks/logging/main.bro @@ -6,9 +6,10 @@ module Log; export { - ## Type that defines an ID unique to each log stream. Scripts creating new log - ## streams need to redef this enum to add their own specific log ID. The log ID - ## implicitly determines the default name of the generated log file. + ## Type that defines an ID unique to each log stream. Scripts creating new + ## log streams need to redef this enum to add their own specific log ID. + ## The log ID implicitly determines the default name of the generated log + ## file. type Log::ID: enum { ## Dummy place-holder. UNKNOWN @@ -20,25 +21,24 @@ export { ## If true, remote logging is by default enabled for all filters. const enable_remote_logging = T &redef; - ## Default writer to use if a filter does not specify - ## anything else. + ## Default writer to use if a filter does not specify anything else. const default_writer = WRITER_ASCII &redef; - ## Default separator between fields for logwriters. - ## Can be overwritten by individual writers. + ## Default separator to use between fields. + ## Individual writers can use a different value. const separator = "\t" &redef; - ## Separator between set elements. - ## Can be overwritten by individual writers. + ## Default separator to use between elements of a set. + ## Individual writers can use a different value. const set_separator = "," &redef; - ## String to use for empty fields. This should be different from - ## *unset_field* to make the output unambiguous. - ## Can be overwritten by individual writers. + ## Default string to use for empty fields. This should be different + ## from *unset_field* to make the output unambiguous. + ## Individual writers can use a different value. const empty_field = "(empty)" &redef; - ## String to use for an unset &optional field. - ## Can be overwritten by individual writers. + ## Default string to use for an unset &optional field. + ## Individual writers can use a different value. const unset_field = "-" &redef; ## Type defining the content of a logging stream. @@ -63,7 +63,7 @@ export { ## If no ``path`` is defined for the filter, then the first call ## to the function will contain an empty string. ## - ## rec: An instance of the streams's ``columns`` type with its + ## rec: An instance of the stream's ``columns`` type with its ## fields set to the values to be logged. ## ## Returns: The path to be used for the filter. @@ -81,7 +81,8 @@ export { terminating: bool; ##< True if rotation occured due to Bro shutting down. }; - ## Default rotation interval. Zero disables rotation. + ## Default rotation interval to use for filters that do not specify + ## an interval. Zero disables rotation. ## ## Note that this is overridden by the BroControl LogRotationInterval ## option. @@ -116,8 +117,8 @@ export { ## Indicates whether a log entry should be recorded. ## If not given, all entries are recorded. ## - ## rec: An instance of the streams's ``columns`` type with its - ## fields set to the values to logged. + ## rec: An instance of the stream's ``columns`` type with its + ## fields set to the values to be logged. ## ## Returns: True if the entry is to be recorded. pred: function(rec: any): bool &optional; @@ -125,10 +126,10 @@ export { ## Output path for recording entries matching this ## filter. ## - ## The specific interpretation of the string is up to - ## the used writer, and may for example be the destination + ## The specific interpretation of the string is up to the + ## logging writer, and may for example be the destination ## file name. Generally, filenames are expected to be given - ## without any extensions; writers will add appropiate + ## without any extensions; writers will add appropriate ## extensions automatically. ## ## If this path is found to conflict with another filter's @@ -153,7 +154,7 @@ export { ## then the first call to the function will contain an ## empty string. ## - ## rec: An instance of the streams's ``columns`` type with its + ## rec: An instance of the stream's ``columns`` type with its ## fields set to the values to be logged. ## ## Returns: The path to be used for the filter, which will be @@ -177,7 +178,7 @@ export { ## If true, entries are passed on to remote peers. log_remote: bool &default=enable_remote_logging; - ## Rotation interval. + ## Rotation interval. Zero disables rotation. interv: interval &default=default_rotation_interval; ## Callback function to trigger for rotated files. If not set, the @@ -207,9 +208,9 @@ export { ## Removes a logging stream completely, stopping all the threads. ## - ## id: The ID enum to be associated with the new logging stream. + ## id: The ID associated with the logging stream. ## - ## Returns: True if a new stream was successfully removed. + ## Returns: True if the stream was successfully removed. ## ## .. bro:see:: Log::create_stream global remove_stream: function(id: ID) : bool; diff --git a/scripts/base/frameworks/logging/writers/ascii.bro b/scripts/base/frameworks/logging/writers/ascii.bro index 5f59229f7f..c10c86145e 100644 --- a/scripts/base/frameworks/logging/writers/ascii.bro +++ b/scripts/base/frameworks/logging/writers/ascii.bro @@ -1,15 +1,15 @@ ##! Interface for the ASCII log writer. Redefinable options are available ##! to tweak the output format of ASCII logs. ##! -##! The ASCII writer supports currently one writer-specific filter option via -##! ``config``: setting ``tsv`` to the string ``T`` turns the output into +##! The ASCII writer currently supports one writer-specific per-filter config +##! option: setting ``tsv`` to the string ``T`` turns the output into ##! "tab-separated-value" mode where only a single header row with the column ##! names is printed out as meta information, with no "# fields" prepended; no -##! other meta data gets included in that mode. +##! other meta data gets included in that mode. Example filter using this:: ##! -##! Example filter using this:: -##! -##! local my_filter: Log::Filter = [$name = "my-filter", $writer = Log::WRITER_ASCII, $config = table(["tsv"] = "T")]; +##! local f: Log::Filter = [$name = "my-filter", +##! $writer = Log::WRITER_ASCII, +##! $config = table(["tsv"] = "T")]; ##! module LogAscii; @@ -29,6 +29,8 @@ export { ## Format of timestamps when writing out JSON. By default, the JSON ## formatter will use double values for timestamps which represent the ## number of seconds from the UNIX epoch. + ## + ## This option is also available as a per-filter ``$config`` option. const json_timestamps: JSON::TimestampFormat = JSON::TS_EPOCH &redef; ## If true, include lines with log meta information such as column names