Skip to content

More logging categories #4652

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Nov 20, 2025
+498 −501
Merged

More logging categories #4652

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
b2e0f94
Add logging categories to HiPS and StelProperties
gzotti Nov 16, 2025
574a9b2
Add logging category stel.Media
gzotti Nov 17, 2025
e311d21
Add logging category stel.Scripting
gzotti Nov 17, 2025
f08b14e
Add logging category stel.Atmosphere
gzotti Nov 17, 2025
ebec7d1
Add logging category stel.Texture
gzotti Nov 17, 2025
ee51316
Add logging categories stel.GPS and stel.LocIP
gzotti Nov 18, 2025
de65905
replace --verbose option by LogCategory
gzotti Nov 18, 2025
46a4f7d
Remove a message
gzotti Nov 18, 2025
5a3b6d0
SUG: Describe logging categories
gzotti Nov 18, 2025
8ea29e7
Remove --verbose CLI option
gzotti Nov 18, 2025
5cd4b83
SUG: extend description of logging finetuning
gzotti Nov 20, 2025
0056f90
SUG: amendments
gzotti Nov 20, 2025
22a16b1
Docfixes
gzotti Nov 20, 2025
165e201
remove unneeded header inclusion
gzotti Nov 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 60 additions & 12 deletions guide/ch_advanced_use.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -468,8 +468,7 @@ \subsubsection{NMEA Device}
group (or whichever group owns your serial port). Better yet, use
\program{gpsd} (see above).}

If GPS lookup fails, run Stellarium with the \texttt{--verbose} option and
see the logfile for diagnostic messages.
If GPS lookup fails, see section~\ref{sec:Environment:Logfile} to enable more diagnostic messages in the logfile.

\paragraph{Bluetooth GPS} Most smartphones provide GPS and Bluetooth
hardware. You can install a virtual COM port in your Windows Bluetooth
Expand Down Expand Up @@ -571,7 +570,6 @@ \section{Command Line Options}
-\/-spout or -S & all or sky & Act as Spout sender (See section \ref{sec:CommandLineOptions:Special:Spout}).%
\footnote{\label{FN:WinOnly}On Windows only}\textsuperscript{,}\footnote{This function requires running in OpenGL mode.}\\
-\/-spout-name & name & Use \texttt{name} as name of the Spout sender. Default name: \texttt{Stellarium}.\footref{FN:WinOnly}\\\midrule
-\/-verbose & & Even more diagnostic output in logfile (esp.\ multimedia handling)\\
-\/-dump-opengl-details or -d & {[}none{]} & Dump information about OpenGL support to logfile.
Use this is you have graphics problems and want to send a bug report. \\\midrule
-\/-angle-mode or -a & {[}none{]} & Use ANGLE as OpenGL ES2 rendering engine (autodetect Direct3D version).\footref{FN:WinOnly}\textsuperscript{,}\footnote{\label{FN:Qt5only}Qt5-based Stellarium versions only}\\
Expand Down Expand Up @@ -629,33 +627,83 @@ \section{Environment Variables}

Some command-line options can be set permanently by storing them into
environment variables. How to set them depends on the respective
operating system. Calling the respective options on the command line
still overrides an environment variable (apart from
\texttt{STEL\_OPTS}).
operating system.

\paragraph{Windows}
Press the start menu, search for ``environment variable''. Use the command to change user variables.
After setting, you can call Stellarium via its menu entry or desktop links.

This may be especially helpful on Windows systems with older graphics
cards which may not fully be compatible with OpenGL. Here we recommend
you either use the program links using the ANGLE-related options, or
you can set the environment variable once and forget about the
problems.

\paragraph{Linux}
You will usually set such variables at the end of your \file{\textasciitilde{}/.bashrc} file.
Open this with a text editor and add, near the end,
\begin{configfile}
export STEL_OPTS=-platform xcb --single-buffer
\end{configfile}
This forces use of the X11 platform plugin which may work better than \texttt{wayland} on older systems.

Calling the respective options on the command line
still overrides an environment variable (apart from
\texttt{STEL\_OPTS}).


\begin{description}
\item[STEL\_OPTS] may contain a default commandline with options in the syntax of the table above.
\item[STEL\_USERDIR] may contain the path to a user data directory
\item[\texttt{STEL\_OPTS}] may contain a default commandline with options in the syntax of the table above. Also some Qt settings can only be tweaked with this.
Copy link
Contributor

@10110111 10110111 Nov 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?).

Copy link
Member Author

@gzotti gzotti Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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, ...?)

Copy link
Member

@alex-w alex-w Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CLI in mac is almost same as CLI in linux

Copy link
Contributor

@10110111 10110111 Nov 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".

Copy link
Member Author

@gzotti gzotti Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

@10110111 10110111 Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

~/.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.

Copy link
Member Author

@gzotti gzotti Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's meant to be a personal setting. I hope those who don't use bash, or those who create multi-user configurations that demand system-wide defaults, know how to translate these instructions to their respective environments. This is not meant to be an all-exhausting general Linux manual, but if you think more ink is needed, please add what you regard as necessary.

Copy link
Contributor

@10110111 10110111 Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see, but the variables set via .bashrc will only take effect if you run Stellarium from a command line. For a e.g. desktop file you need another way for this, e.g. like this.

Copy link
Member Author

@gzotti gzotti Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the information. When developing/testing builds on Linux I launch Stellarium from the command line. I never modified such files and would always need Google to find such platform specific instructions. (Is it the same for Gnome/KDE/...?) I would therefore leave this as exercise for the user, or let you extend on this part. The key information of this section is "There are these environment variables".

For example, users of international keyboards with \key{Alt Gr} key may want to use
\begin{commands}[\scriptsize]
STEL_OPTS=-platform windows:altgr,fontengine=freetype --single-buffer
\end{commands}
The \texttt{-platform} parameter is part of Qt. Its second argument, \texttt{fontengine}, selects a different font engine (i.e., some fonts may look better with it).
The other argument, \texttt{-\,-single-buffer}, is a setting that influences Stellarium (see table above).
\item[\texttt{STEL\_USERDIR}] may contain the path to a user data directory
deviating from the default (see section \ref{sec:Directories}).
\item[QT\_OPENGL]\footref{FN:WinOnly} May be one of \texttt{desktop} (native OpenGL for your GPU, recommended),
\item[\texttt{QT\_OPENGL}]\footref{FN:WinOnly} May be one of \texttt{desktop} (native OpenGL for your GPU, recommended),
\texttt{angle}\footref{FN:Qt5only} or \texttt{software}. The last activates pure software rendering using the MESA OpenGL library. Note that command line options take precedence over this environment variable.
\item[QT\_ANGLE\_PLATFORM]\footref{FN:WinOnly}\textsuperscript{,}\footref{FN:Qt5only} May be one of \texttt{d3d9} (DirectX~9) or \texttt{d3d11} (DirectX~11),
\item[\texttt{QT\_ANGLE\_PLATFORM}]\footref{FN:WinOnly}\textsuperscript{,}\footref{FN:Qt5only} May be one of \texttt{d3d9} (DirectX~9) or \texttt{d3d11} (DirectX~11),
or \texttt{warp} for another software-only solution. Note that command line options take precedence over this environment variable.
\end{description}

\subsection{Logfile tweaks}
\label{sec:Environment:Logfile}

The amount of logging messages in Qt-based programs can be tuned by setting an environment variable \texttt{QT\_LOGGING\_RULES}.
For example, to remove all ``Debug'' messages, set it to \texttt{*.debug=false}. To remove even the ``Info'' messages, add \texttt{;*.info=false}. (Combine several rules with semicola.)
Qt based programs can wrote log files where status messages of varying severity can be written. There are categories
\texttt{debug} (only of developer interest),
\texttt{info} (informational),
\texttt{warning} (something unexpected),
\texttt{critical} (usually connected to some real failure) and
\texttt{fatal} (program must fail here).
The amount of logging messages can be tuned by setting the environment variable \texttt{QT\_LOGGING\_RULES}.
For example, to remove all \texttt{debug} messages, set it to \texttt{*.debug=false;}.
To remove even the \texttt{info} messages, add \texttt{*.info=false;}. (Close each rule, also the last, with semicolon!)
If you experience operating trouble, make sure you allow all messages, i.e., set these entries shown here to \texttt{true} (or delete the variable).

Some modules\newFeature{25.4} can be individually finetuned with respect to the amount of logging.
Most users won't ever want to see the ugly details, so \texttt{debug} is deactivated by default for:
\begin{description}
\item[\texttt{stel.GPS}] GPS related issues.
\item[\texttt{stel.LocIP}] IP-based location queries.
\item[\texttt{stel.Texture}] Texture handling.
\item[\texttt{stel.Atmosphere}] Atmosphere related messages.
\item[\texttt{stel.Scripting}] scripting related messages.
\item[\texttt{stel.Media}] Multimedia related messages.
\item[\texttt{stel.HiPS}] HiPS related messages.
\item[\texttt{stel.Properties}] StelProperty related messages.
\end{description}

If you suspect issues with some features on your computer, add those entries as shown above, e.g., to hunt down issues with a GPS device:
\begin{configfile}
QT_LOGGING_RULES=*.debug=false;stel.GPS.debug=true;
\end{configfile}
or if you are developing scripts and videos don't play, try if this helps:
\begin{configfile}
QT_LOGGING_RULES=*.debug=false;stel.Media.debug=true;
\end{configfile}

More information can be found online\footnote{\scriptsize{\url{https://doc.qt.io/qt-6/qloggingcategory.html}, \url{https://doc.qt.io/qt-6/debug.html}}}.


Expand Down
3 changes: 0 additions & 3 deletions plugins/AngleMeasure/src/AngleMeasure.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -330,9 +330,6 @@ void improveClickMatch(StelProjectorP prj, double x, double y, Vec3d &v)
prj->project(v,win);
double dx = x - win.v[0];
double dy = y - win.v[1];
bool verbose=qApp->property("verbose").toBool();
if (verbose)
qDebug() << "Nick Fedoseev patch: improve click match" << dx << dy;
prj->unProject(x+dx,y+dy,v);
}

Expand Down
5 changes: 0 additions & 5 deletions src/CLIProcessor.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,8 +104,6 @@ void CLIProcessor::parseCLIArgsPreConfig(const QStringList& argList)
<< "--config-file (or -c) : Use an alternative name for the config file\n"
<< "--log-file (or -l) : Use an alternative name for the log file\n"
<< "--user-dir (or -u) : Use an alternative user data directory\n"
<< "--verbose : Even more diagnostic output in logfile \n"
<< " (esp. multimedia handling)\n"
<< "--opengl-compat (or -C) : Request OpenGL Compatibility profile\n"
<< " May help for certain driver configurations.\n"
<< "--low-graphics (or -L) : Force low-graphics mode\n"
Expand Down Expand Up @@ -154,9 +152,6 @@ void CLIProcessor::parseCLIArgsPreConfig(const QStringList& argList)
exit(0);
}

if (argsGetOption(argList, "", "--verbose"))
qApp->setProperty("verbose", true);

#ifdef Q_OS_WIN
if (argsGetOption(argList, "-F", "--no-screensaver"))
qApp->setProperty("onetime_inhibit_screensaver", true);
Expand Down
3 changes: 2 additions & 1 deletion src/StelMainView.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1010,9 +1010,10 @@ void StelMainView::init()

// I doubt this will have any effect on framerate, but may cause problems elsewhere?
QThread::currentThread()->setPriority(QThread::HighestPriority);

#ifndef NDEBUG
// Get an overview of module callOrders
if (qApp->property("verbose")==true)
if (mainview().isDebugEnabled())
{
StelApp::getInstance().dumpModuleActionPriorities(StelModule::ActionDraw);
StelApp::getInstance().dumpModuleActionPriorities(StelModule::ActionUpdate);
Expand Down
23 changes: 12 additions & 11 deletions src/core/StelAudioMgr.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
*/

#include "StelAudioMgr.hpp"
#include "StelVideoMgr.hpp"
#include <QDebug>
#include <QDir>

Expand Down Expand Up @@ -53,13 +54,13 @@ void StelAudioMgr::loadSound(const QString& filename, const QString& id)
{
if (!enabled)
{
qWarning() << "Not loading sound -- audio system disabled by configuration.";
qCWarning(Media) << "Not loading sound -- audio system disabled by configuration.";
return;
}

if (audioObjects.contains(id))
{
qWarning() << "Audio object with ID" << id << "already exists, dropping it";
qCWarning(Media) << "Audio object with ID" << id << "already exists, dropping it";
dropSound(id);
}

Expand Down Expand Up @@ -95,10 +96,10 @@ void StelAudioMgr::playSound(const QString& id)
audioObjects[id]->play();
}
else
qDebug() << "StelAudioMgr: Cannot play sound, " << id << "not correctly loaded.";
qCWarning(Media) << "StelAudioMgr: Cannot play sound, " << id << "not correctly loaded.";
}
else
qDebug() << "StelAudioMgr: Cannot play sound, " << id << "not loaded.";
qCWarning(Media) << "StelAudioMgr: Cannot play sound, " << id << "not loaded.";
}

void StelAudioMgr::pauseSound(const QString& id)
Expand All @@ -111,10 +112,10 @@ void StelAudioMgr::pauseSound(const QString& id)
if (audioObjects[id]!=nullptr)
audioObjects[id]->pause();
else
qDebug() << "StelAudioMgr: Cannot pause sound, " << id << "not correctly loaded.";
qCWarning(Media) << "StelAudioMgr: Cannot pause sound, " << id << "not correctly loaded.";
}
else
qDebug() << "StelAudioMgr: Cannot pause sound, " << id << "not loaded.";
qCWarning(Media) << "StelAudioMgr: Cannot pause sound, " << id << "not loaded.";
}

void StelAudioMgr::stopSound(const QString& id)
Expand All @@ -127,10 +128,10 @@ void StelAudioMgr::stopSound(const QString& id)
if (audioObjects[id]!=nullptr)
audioObjects[id]->stop();
else
qDebug() << "StelAudioMgr: Cannot stop sound, " << id << "not correctly loaded.";
qCWarning(Media) << "StelAudioMgr: Cannot stop sound, " << id << "not correctly loaded.";
}
else
qDebug() << "StelAudioMgr: Cannot stop sound, " << id << "not loaded.";
qCWarning(Media) << "StelAudioMgr: Cannot stop sound, " << id << "not loaded.";
}

void StelAudioMgr::dropSound(const QString& id)
Expand All @@ -140,7 +141,7 @@ void StelAudioMgr::dropSound(const QString& id)

if (!audioObjects.contains(id))
{
qDebug() << "StelAudioMgr: Cannot drop sound, " << id << "not loaded.";
qCWarning(Media) << "StelAudioMgr: Cannot drop sound, " << id << "not loaded.";
return;
}
if (audioObjects[id]!=nullptr)
Expand All @@ -159,7 +160,7 @@ qint64 StelAudioMgr::position(const QString& id)

if (!audioObjects.contains(id))
{
qDebug() << "StelAudioMgr: Cannot report position for sound, " << id << "not loaded.";
qCWarning(Media) << "StelAudioMgr: Cannot report position for sound, " << id << "not loaded.";
return(-1);
}
if (audioObjects[id]!=nullptr)
Expand All @@ -176,7 +177,7 @@ qint64 StelAudioMgr::duration(const QString& id)

if (!audioObjects.contains(id))
{
qDebug() << "StelAudioMgr: Cannot report duration for sound, " << id << "not loaded.";
qCWarning(Media) << "StelAudioMgr: Cannot report duration for sound, " << id << "not loaded.";
return(-1);
}
if (audioObjects[id]!=nullptr)
Expand Down
Loading
Loading