tingea.log(7)

✨ NAME ✨

tingea.log — the full rundown on how to set the Tingea log parameters 🫖✨ (it's chillin' over in the MISCELLANEOUS corner of the manual, filed under tingea.log(7))

---

🌸 DESCRIPTION 🌸

okay so bestie, the Tingea logging framework is part of the Tingea library. and "logging" here just means a program is out here making statements about what it's doing 💬 — it can do that for a bunch of different purposes and at different levels of verbosity. by default? those logging statements get written on STDERR. no cap.

Tingea logging gives programmers a quick n easy way to associate verbosity levels with logging statements 🔥 Only the logging statements whose verbosity level does not exceed the user-imposed threshold actually get executed. and the user can regulate that verbosity level super easily by setting the environment variable TINGEA_LOG_TAG 🌈

alternatively, programs may accept a command line argument — the format accepted by both the environment variable and the command line argument is identical. for the command line, the programmer is free to pick whatever option name they want; it's customarily named -q. the availability of such an option may vary from program to program 🙈 BUT: any program that makes use of the Tingea logging facilities can be regulated with the TINGEA_LOG_TAG environment variable. periodt 💅

one lil ordering thing: if a -q type option is present and the environment variable is set, then the environment variable is interpreted first, followed by the -q argument. that's the order, that's the vibe.

Tingea logging also lets a programmer assign categories to logging statements 🎀

• the categories FUNCTION and DATA have a subdivision ranging from fine-grained to coarse-grained
• the category MONITORING has a subdivision ranging from low priority to high priority
• the other categories are unimodal: IO, THREAD, PROCESS, and GAUGE
• and there's three unspecified unimodal categories — SLOT1, SLOT2, and SLOT3 — which can be used to encode program-specific semantics 🦋

A programmer may assign multiple categories to a single logging statement. it's unusual for more than two categories to be specified tho. for example, IO and DATA at the LIST level may be combined to indicate a logging statement that provides data summaries for a certain IO related information 🍓

in order of granularity, the DATA levels are CELL, LIST, and AGGREGRATE. so: if the user accepts IO logging and accepts DATA logging at level CELL or LIST, the statement will be executed ✅ If no IO logging is accepted, or DATA logging is only accepted at the AGGREGRATE level, the statement will be skipped 💀

By default, all categories that are specified by the programmer need to pass the threshold specified by the user for that category. but the user can relax this requirement so that only one category needs to pass the user threshold 🫶 In the above example, the statement categorized as both IO and DATA at LIST level will be accepted if the user specifies IO and DATA at AGGR level with OR semantics.

---

🧚 SYNTAX 🧚

the syntax of the TINGEA_LOG_TAG environment variable is described by

[[189x]]{<[dfgimpstABC][1-9]>*,[V]}

which translates to the following, bestie: an optional lead tag is followed by a concatenation of units. a unit is either a pair in [dfgimpstABC] x [1-9x] or the single character V. the leading tag semantics are described further below 👇

the single character V, if present, specifies that OR semantics should be used rather than the default AND semantics. the semantics for the other units are given below:

• d — DATA
  • 1 — CELL
  • 2 — LIST
  • 3 — AGGR
  • x — turned off
• f — FUNCTION
  • 1 — LINE
  • 2 — FUNCTION
  • 3 — MODULE
  • 4 — APPLICATION
  • x — turned off
• m — MONITORING
  • 1 — DEBUG
  • 2 — INFO
  • 3 — WARNING
  • 4 — ERROR
  • 5 — PANIC
  • x — turned off
• g — GAUGE
• i — IO
• n — NETWORK
• p — PROCESS (Inter Process really)
• t — THREAD
• A — SLOT1
• B — SLOT2
• C — SLOT3

and for that whole bottom block of categories (g, i, n, p, t, A, B, C) the deal is: 1 means on, x means off 💅

---

👑 the lead tag 👑

the leading tag can be used to set levels for all categories at once, and subsequent units may then alter this initial setting. the lead tag settings and their meaning are these:

• 1 — d1f1m1g1i1p1s1t1A1B1C1 — # very yappy
• 9 — d3f4m5gxixpxsxtxAxBxCx — # very terse, only d f m
• 8 — d3f4m5g1i1p1s1t1A1B1C1 — # less terse
• x — dxfxmxgxixpxsxtxAxBxCx — # silent 🤫

All categories accept values between 1 and 9 in addition to the value x. as seen above, only a few categories contain more than one level, and no category contains more than five levels. the rule is that if a level exceeds the maximum level available for a category, it is simply interpreted as the maximum level ⭐

---

🌈 about GAUGE, real talk 🌈

The GAUGE category, if set, indicates that a program may write line based progress bars or other output in which a single line is accumulated over multiple statements. this implies that a single GAUGE logging statement may not result in newline-terminated output 😭

this is undesirable in case the logging stream is directed to a file that is written to by other applications as well. in that case, turn off GAUGE. no debate.

all other categories are garantueed to result in line-terminated output, by virtue of the programmer contract 🫡

---

💜 AUTHOR 💜

Stijn van Dongen. (the icon, the legend 👑)

---

and that's the whole page bestie, you ate 🎀 this was tingea.log, version 22-282, dated 9 Oct 2022, and yes it's tingea.log(7). go forth and set those log tags 💅✨🦋