From 938419830684c4cc7df8724932b7c3bc2a1884c7 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Mon, 19 Jun 2017 17:41:12 -0400 Subject: [PATCH] doc/logging-guide.adoc: document standard way of choosing tag names MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- doc/logging-guide.adoc | 216 +++++------------------------------------ 1 file changed, 22 insertions(+), 194 deletions(-) diff --git a/doc/logging-guide.adoc b/doc/logging-guide.adoc index 18a9cfc2..cfd099f9 100644 --- a/doc/logging-guide.adoc +++ b/doc/logging-guide.adoc @@ -417,7 +417,7 @@ To instrument a C source file (`.c`): A logging tag name is a namespace for a specific source file. Its name is part of every log message generated by the statements of the file. A logging tag name _must_ be only uppercase letters, digits, and the -hyphen (`-`) character. See <> for +hyphen (`-`) character. See <> for a list of standard tags. . Use the <> in the file's @@ -461,207 +461,31 @@ the C source file. [[tags]] -=== Babeltrace standard tags +=== Choose a tag -==== CTF IR (library) +For plugins, the format of the tag name for a given source file _must_ +be: -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Attributes |`ATTRS` -|Clock class and values |`CLOCK-CLASS` -|Event class |`EVENT-CLASS` -|Event |`EVENT` -|Field path |`FIELD-PATH` -|Field types |`FIELD-TYPES` -|Fields |`FIELDS` -|Packet |`PACKET` -|Resolver |`RESOLVE` -|Stream class |`STREAM-CLASS` -|Stream |`STREAM` -|Trace |`TRACE` -|Validation |`VALIDATION` -|Visitor |`VISITOR` -|=== - - -==== CTF writer (library) - -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Clock |`CTF-WRITER-CLOCK` -|CTF writer |`CTF-WRITER` -|Serialization |`CTF-WRITER-SER` -|=== - - -==== Graph (library) - -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Clock class priority map |`CC-PRIO-MAP` -|Component (common) |`COMP` -|Component class |`COMP-CLASS` -|Connection |`CONNECTION` -|Filter component |`COMP-FILTER` -|Graph |`GRAPH` -|Notification iterator |`NOTIF-ITER` -|Port |`PORT` -|Sink component |`COMP-SINK` -|Source component |`COMP-SOURCE` -|=== - -==== Notifications (library) - -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Event notification |`NOTIF-EVENT` -|Inacitivity notification |`NOTIF-INACTIVITY` -|Notification |`NOTIF` -|Packet notification |`NOTIF-PACKET` -|Stream notification |`NOTIF-STREAM` -|=== - - -==== Plugin (library) - -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Plugin |`PLUGIN` -|Python plugin provider |`PLUGIN-PY` -|Shared object plugin provider |`PLUGIN-SO` -|=== - - -==== Values (library) - -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Values |`VALUES` -|=== - - -==== Reference counting (library) - -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Reference counting |`REF` -|=== - - -==== Common (library) - -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Common |`COMMON` -|=== - - -==== CLI - -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|CLI (main) |`CLI` -|CLI configuration (common) |`CLI-CFG` -|CLI configuration from CLI arguments |`CLI-CFG-ARGS` -|CLI connection configuration from CLI arguments |`CLI-CFG-ARGS-CONNECT` -|=== - - -==== libctfcopytrace (plugin convenience library) - -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Clock fields |`LIBCTFCOPYTRACE-CLOCK-FIELDS` -|libctfcopytrace |`LIBCTFCOPYTRACE` -|=== +[verse] +PLUGIN-__PNAME__-__CCNAME__-__CCTYPE__[-__FILE__] +__PNAME__:: + Plugin's name. -==== `ctf` plugin +__CCNAME__:: + Component class's name. -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Plugin (main) |`PLUGIN-CTF` -|Common: BTR |`PLUGIN-CTF-BTR` -|Common: CTF IR generation metadata visitor |`PLUGIN-CTF-METADATA-IR-VISITOR` -|Common: Metadata decoder |`PLUGIN-CTF-METADATA-DECODER` -|Common: Metadata lexer |`PLUGIN-CTF-METADATA-LEXER` -|Common: Metadata parser |`PLUGIN-CTF-METADATA-PARSER` -|Common: Notification iterator |`PLUGIN-CTF-NOTIF-ITER` -|`fs` sink (main) |`PLUGIN-CTF-FS-SINK` -|`fs` sink: write |`PLUGIN-CTF-FS-SINK-WRITE` -|`fs` source (main) |`PLUGIN-CTF-FS-SRC` -|`fs` source: data stream |`PLUGIN-CTF-FS-SRC-DS` -|`fs` source: file |`PLUGIN-CTF-FS-SRC-FILE` -|`fs` source: metadata |`PLUGIN-CTF-FS-SRC-METADATA` -|`lttng-live` source (main) |`PLUGIN-CTF-LTTNG-LIVE-SRC` -|`lttng-live` source: data stream |`PLUGIN-CTF-LTTNG-LIVE-SRC-DS` -|`lttng-live` source: metadata |`PLUGIN-CTF-LTTNG-LIVE-SRC-METADATA` -|`lttng-live` source: viewer connection |`PLUGIN-CTF-LTTNG-LIVE-SRC-VIEWER` -|=== +__CCTYPE__:: + Component class's type (`SRC`, `FLT`, or `SINK`). +__FILE__:: + Additional information to specify the source file name or module. -==== `lttng-utils` plugin +Examples: -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Plugin (main) |`PLUGIN-LTTNG-UTILS` -|`debug-info` filter (main) |`PLUGIN-LTTNG-UTILS-DBG-INFO-FILT` -|`debug-info` filter: binary info |`PLUGIN-LTTNG-UTILS-DBG-INFO-FILT-BIN-INFO` -|`debug-info` filter: copy |`PLUGIN-LTTNG-UTILS-DBG-INFO-FILT-COPY` -|`debug-info` filter: CRC32 |`PLUGIN-LTTNG-UTILS-DBG-INFO-FILT-CRC32` -|`debug-info` filter: DWARF |`PLUGIN-LTTNG-UTILS-DBG-INFO-FILT-DWARF` -|=== - - -==== `text` plugin - -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Plugin (main) |`PLUGIN-TEXT` -|`pretty` filter (main) |`PLUGIN-TEXT-PRETTY-SINK` -|`pretty` filter: print |`PLUGIN-TEXT-PRETTY-SINK-PRINT` -|=== - - -==== `utils` plugin - -[options="header,autowidth"] -|=== -|Subsystem/object |Tag name - -|Plugin (main) |`PLUGIN-UTILS` -|`dummy` sink (main) |`PLUGIN-UTILS-DUMMY-SINK` -|`muxer` filter (main) |`PLUGIN-UTILS-MUXER-FILT` -|`trimmer` filter (main) |`PLUGIN-UTILS-TRIMMER-FILT` -|`trimmer` filter: copy |`PLUGIN-UTILS-TRIMMER-FILT-COPY` -|`trimmer` filter: iterator |`PLUGIN-UTILS-TRIMMER-FILT-ITER` -|=== +* `PLUGIN-CTF-LTTNG-LIVE-SRC` +* `PLUGIN-CTF-LTTNG-LIVE-SRC-VIEWER` +* `PLUGIN-UTILS-MUXER-FLT` [[level]] @@ -699,6 +523,7 @@ least exit cleanly. implementation and the satisfied preconditions. For example, the failure to create an empty object (no parameters): most probably failed internally because of an allocation error. +* Almost any error in terminal elements: CLI and plugins. |Almost none: should be executed in production. |_WARN_ @@ -709,6 +534,9 @@ is directly or indirectly caused by the user. For example, not having enough memory is considered beyond the user's control, so we always log memory errors with an _ERROR_ level (not _FATAL_ because we usually don't abort in this condition). + +Almost all the library's errors are logged as warnings because they are +caused by the user. | * Not honoring a public function's preconditions (NULL parameters, index out of bounds, etc.). -- 2.34.1