More logging categories

[gzotti]

Description

Our logfile is sometimes filled with excessive messages. Sometimes it is good for debugging, sometimes messages are less relevant.
This branch brings two more logging categories, for HiPS and StelProperties. Both emitted excessive messages in Debug builds when the --verbose CLI was given, now this can be tuned with environment variable QT_LOGGING_RULES. Default logging of well-behaving stable classes should be set to Info, so that qCDebug messages in these categories can be usually suppressed.

It may be useful to add more categories, e.g. to scripting and Multimedia, or also to skyculture-related messages. In this branch or later. And CLI option --verbose might be removed later as its purpose of finetuning log messages is the same.

EDIT: CLI option --verbose has been removed after introducing log categories for all modules which earlier reacted to --verbose.

Fixes # (issue)

Screenshots (if appropriate):

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• This change requires a documentation update
• Housekeeping

How Has This Been Tested?

Test Configuration:

• Operating system: Windows
• Graphics Card: (irrelevant)

Checklist:

• My code follows the code style of this project.
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (header file)
• I have updated the respective chapter in the Stellarium User Guide
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[github-actions]

Hello @gzotti!

Thank you for the suggested improvement.

[github-actions]

Great PR! Please pay attention to the following items before merging:

Files matching src/**/*.cpp:

• Are possibly unused includes removed?

This is an automatically generated QA checklist based on modified files.

[10110111]

Default logging should be set to Info, so that qDebug is usually suppressed.

Do you mean qCDebug is suppressed, not qDebug? From your changes it looks like you only define the default for Property and HiPS.

[gzotti]

Yes, qCDebug should be suppressed by default. I have amended the description.

Currently I have replaced qDebug() by qCDebug(category) for these two classes (and qInfo()->qCInfo(category) etc), and have configured both to only show log messages of qCInfo and higher, but to suppress qCDebug by default. (Unless configured by the QT_LOGGING_RULES environment variable.) In debug builds with --verbose CLI flag set, HiPSMgr floods the logfile with messages. The log categories allow better fine-tuning of which parts of log messages we are really interested.

(I think I had introduced --verbose when bringing the Multimedia back to life with Qt5, but it was hugely unstable, or some documented signals just did not fire, so I needed more insights. It's so much better on Qt6... The Multimedia verbosity could also be tuned by a logging category like stel.Media, and --verbose could ultimately be either repurposed or removed.)

[10110111]

Won't this removal of Debug messages from the log by default result in us asking users to add additional settings before posting a log? They already ignore the request for a log from the issue template, and now they'll additionally complain that they don't understand how to do what we are asking.

[gzotti]

So far I replace those log messages that already required --verbose to be logged. (And decided in a few cases to change debug to info/warning.) So, when you had to give --verbose earlier and got more log stuff from several modules of which only one was interesting for the problem in question, now you can configure additional messages from each such module, separately. E.g., when I know that media support works, I don't need the list of working codecs. Maybe when I am developing a show, I might be interested to trace the various video loading steps, then I would configure the env.var to also show debug messages.

Most of the qDebug messages are of real interest during development and our testing, so I think limiting output to qInfo to report real problems (file not found etc.) is OK. (Once I used Scientific Linux on one system, and here the debug-class messages were configured away by some system default. Only this, with a super-thin logfile, pointed me towards using qInfo etc. where applicable, and later the log categories.) For now, I don't intend to categorize all modules, though. Adding "stel.GPS" as next is one I see useful to hunt down GPS hardware related issues. Of course, SUG 6.2.1 will be extended with a list of available keys.

There is a way to override env.var settings on program launch. Then the --verbose CLI option could be kept and used to override-configure QT_LOGGING_RULES and switch on all log categories, even those configured otherwise by env.vars. But this only comes to my mind now that you are asking.

[alex-w]

I think we should add a few examples of usage for this feature into SUG

[gzotti]

So far we have documented "--verbose" as providing "more output". Not sure whether anybody except myself was using it for diagnostics. This now selects the single modules as listed in SUG 6.2.1 and header docs. Is that not enough?

[alex-w]

So far we have documented "--verbose" as providing "more output". Not sure whether anybody except myself was using it for diagnostics. This now selects the single modules as listed in SUG 6.2.1 and deader docs. Is that not enough?

Let imagine that SUG will read a person with a low "technical" knowledge - he can read the text, but I fear he will not understand it.

[gzotti]

You mean, starting at the level "How do I set an environment variable"? (Concept, 3 platforms, 2 pages.) Or just add another example in 6.2.1?

[alex-w]

You mean, starting at the level "How do I set an environment variable"? (Concept, 3 platforms, 2 pages.) Or just add another example in 6.2.1?

A bit expanding 6.2 (a concept) and adding examples for couple platforms (linux + windows is enough IMHO) into 6.2.1

[alex-w]

Thanks!

[10110111]

The value with spaces must be quoted.

[10110111]

This continuation of the paragraph looks like a Linux-specific description, while the options below say -platform windows, which is aggravated by a lack of quotes around a value containing spaces (generally, I'm not even sure what language that line is in—bash?).

[gzotti]

The section title is "Environment variables". Then there are two unnumbered paragraphs of basic computer operating knowledge asked for by AW named after the platforms. (Anybody add how does it work on Macs?)
Indeed below should be a subsection title that represents the description of our 2 and 2 more often-needed environment variables from Qt. I accept suggestions that would avoid repeating the section title "6.2 Environment Variables" with "6.2.1 Environment Variables". Would it be enough for you to leave a line before "Calling the respective..."? Or describe the variables first and only then give platform specific instructions? Or demote the paragraphs into a (hopefully indented) description environment?

The environment variable is a string that is written exactly as shown, without quotes. It may depend whether you use the system tool found in Windows 11 to set environment variables (and which is massively better than that found on earlier versions, actually to the point of being usable!) or a more advanced program like Rapid Environment Editor, where you have to enclose it with quotes. As I do not mention REE in the Guide, I don't show quotes around the setting.

I am not sure atm: would the Linux STEL_OPTS shown in the 'export' line need quotes? And: are there any other Qt-specific arguments that are of interest and should be listed? (Linux fontengine, media codecs, device plugins, optional libraries, ...?)

[alex-w]

CLI in mac is almost same as CLI in linux

[10110111]

I accept suggestions that would avoid repeating the section title "6.2 Environment Variables" with "6.2.1 Environment Variables".

"List of Variables", "List of Useful Variables".

Would it be enough for you to leave a line before "Calling the respective..."?

No, I don't think it's a sufficient way to separate the paragraph.

I am not sure atm: would the Linux STEL_OPTS shown in the 'export' line need quotes?

As I said in another comment, yes, the quotes must be present, or all options except the first will be ignored.

The environment variable is a string that is written exactly as shown, without quotes.

The issue is that it's preceded by STEL_OPTS=, which makes an impression of a command or at least some language construct. And the only language that comes to mind is some kind of Bourne-like shell, where the quotation is mandatory. I suggest removing this prefix, possibly rewording "may want to use\nSTEL_OPTS=XXX" to "may want to set STEL_OPTS to\nXXX".

[gzotti]

is it also ~.bashrc or some other shell? (IIRC (decades ago...) NeXt OpenStep (pre-Darwin) used zsh or tcsh?) Is there an environment editor GUI available on today's Macs that users in need of these instructions would prefer to use?

[10110111]

~/.bashrc is bash-specific, as follows from its name, and is only applied to interactive non-login shells. zsh and tcsh use their own files.

Generally, for a system-wide setting (on usual Linux distros) regardless of your shell being interactive/login/non-login you'd add a file in /etc/profile.d/ (or, if the system isn't configured to read files from this directory, then edit /etc/profile).

How it is in macOS I don't know.