doc/logging-guide.adoc: document standard way of choosing tag names

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/doc/logging-guide.adoc b/doc/logging-guide.adoc
index 18a9cfc2b9e043f648c2bf116b820d49e6cd7535..cfd099f94e7ef94b9e3241f73e801cdbda5bb1e4 100644 (file)
--- 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 <<tags,Babeltrace standard tags>> for
+hyphen (`-`) character. See <<tags,Choose a tag>> for
 a list of standard tags.
 
 . Use the <<logging-statements,logging statement macros>> 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.).