Standardize Qt logging categories used in KF
Open, Needs TriagePublic

Description

PROBLEMS

There are some issues currently when it comes to categories used by KF modules for the Qt Logging infrastructure:

  • no pattern in the naming, cannot be guessed
  • no easy way to do mass control across modules for categories related to a certain feature

((For completeness, other problems which are to be solved in a separate task (already have an idea for):

  • usually no good description/definition about the scope, especially for subcategories
  • no central place where to look up the present category names, code has to be searched))

Examples of current category names used in KF:

  • org.kde.attica
  • org.kde.pim.kcalcore
  • kf5.kconfig.core
  • kf5.kconfigwidgets
  • sonnet.core
  • sonnet.plugins.aspell
  • kf5.kemoticons.plugin_adium

So when wanting to change level of logging for a given KF module, one cannot derive the actual category name from the module, library or feature, but has to look up the actual name. Or in the case of using the tool kdebugsettings hope that there is a .categories file deployed and which has correct data. (Correct data should be less an issue thanks to new ecm_qt_install_logging_categories() generating those files from the original data).

WANTED

Required:

  1. be able to control logging for the whole of KF in one go
  2. be able to control logging for a whole KF module in one go, including external plugins for the module
  3. be able to control logging for a certain feature across all KF modules implementing it in one go
  4. be able to derive the main category name from the name of the KF module, library or helper executable

PROPOSED SOLUTION

Category names for KF modules would be made from the following patterns:

  • "kf".<module>[.<library>][.<internalfeature>]
  • "kf".<module>.<type-of-plugins>.<plugin>[.<internalfeature>]
  • "kf".<module>.<demon/tool>[.<internalfeature>]
  • "kf".<module>.<publicfeature>[.<othercode>]

"kf." namespace prefix

Follows the "qt." example, having the productname (it's abbreviation) as the first name component.
Without the "5", so with KF6 things do not need change (again follows "qt." example).
Enables control of all KF categories via "kf*[.<type>]=true|false"

<module>[.<library>]

A small challenge here is that some KF modules actually consist of multiple libraries, usually split for core, gui or widgets (matching Qt libs) as well as having some qml extension plugin, usually for QtQuick. Naming of such libraries is not consistent (so no pattern of *core, *(g)ui, *widgets),
Some module even have multiple separate libraries for a type, grouped by feature (e.g. KIOFileWidgets & KIOWidgets).
There is also a client & server variant (KWaylandClient, KWaylandServer). One things currently common to all such libraries is that the module name is used as prefix for the library name, which we can make use of (and should also add as requirement to the KF policies).

<module>: the KF module name, lowercased and with the "K" prefix stripped, unless special-no-k-name or abbreviation

Examples:
"Baloo" -> "kf.baloo"
"KArchive" -> "kf.archive"
"KIO" -> "kf.kio"
"KDED" -> "kf.kded"

Enables control of all module categories via "kf.<module>*[.<type>]=true|false"

<library>: the library name, lowercased and with "libKF5" prefix and KF module name stripped, or "quick" for QtQuick QML extension plugins

Examples:
"libKF5NewStuffCore" -> "kf.newstuff.core"
"libnewstuffqmlplugin.so" -> "kf.newstuff.quick"
"libKF5KIOFileWidgets" -> "kf.kio.filewidgets"

Enables control of all library categories via "kf.<module>.<library>*[.<type>]=true|false"

<type-of-plugins>

There could be multiple types of plugins & extensions per module. To allow bulk control separated per type, each type of plugins is namespaced with the name of the type using a plural "s". The <plugin> would be named with or without origina category namespace, depending whether there is no doubt where the plugin is from, or with full category namespace of the origin (like another KF module) if there could be doubt. A full origin namespace also enables to use filter rules with leading "*" and the module namespace to also cover the plugin then.

Examples:
kf.kio.slaves.ftp
kf.kio.urifilters.localdomain
kf.sonnet.clients.aspell
kf.configwidgets.cms.kf.kio.useragentdlg

Enables control of all categories specific to all plugins via "kf.<module>.<type-of-plugins>*[.<type>]=true|false"

<demon/tool>

Helper executables like demons and tools, would be named by their full executable name. Even if specific to a library only, their category would be a subcategory directly to the module, not the library, so they are on same level as libraries.

Examples:
kf.config.kconf_update
kf.kio.kiod

Enables control of all executable specific categories via "kf.<module>.<demon/tool>*[.<type>]=true|false"

<publicfeature>

For features extended by other modules or projects not via plugins, but subclasses or similar library-internal methods, having the option to group logging by a namespace matching the feature is good to have (this was used with the old KDebug a lot, sadly got lost during unorganized porting to QLoggingCategory and no more central registry). <othercode> is the full category name of the module/library where the feature is extended.

Examples (made up):
kf.texteditor.inlinenotes
kf.texteditor.inlinenotes.kdevelop.plugins.problemreporter

Enables control of all categories across libraries and other consumers via "kf.<module>.<publicfeature>*[.<type>]=true|false"

<internalfeature>

For code where more fine-grained control about the scope of logging can be useful. Can be one subcategory or have more subcategories internally.

Examples:
kf.coreaddons.kdelibs4configmigrator
kf.kio.core.copyjob
kf.kio.widgets.kdirmodel
kf.windowsystem.keyserver.x11

Enables control of all categories across libraries and other consumers via "kf.<module>.<publicfeature>*[.<type>]=true|false"

Resulting category name for those currently in use

kf.activities
kf.activitiesstats
kf.archive
kf.attica
kf.auth
kf.baloo
kf.baloo.engine
kf.kio.slaves.timeline
kf.kio.slaves.tags
kf.bluezqt
kf.bookmarks
kf.calendarcore
kf.codecs
kf.config.core
kf.config.kconf_update
kf.configwidgets
kf.contacts
kf.coreaddons
kf.coreaddons.kdirwatch
kf.coreaddons.kaboutdata
kf.coreaddons.desktopparser
kf.coreaddons.kdelibs4configmigrator
kf.crash
kf.dbusaddons
kf.kded
kf.emoticons
kf.emoticons.kde
kf.emoticons.xmpp
kf.emoticons.adium
kf.emoticons.pidgin
kf.filemetadata
kf.globalaccel
kf.i18n
kf.i18n.kuit
kf.iconthemes
kf.idletime
kf.idletime.xsync
kf.init.klauncher
kf.kio.core
kf.kio.core.copyjob
kf.kio.core.dirlister
kf.kio.core.sambashare
kf.kio.slaves.file
kf.kio.slaves.http
kf.kio.slaves.http.cookiejar
kf.kio.slaves.http.auth
kf.kio.slaves.http.filter
kf.kio.slaves.ftp
kf.kio.slaves.trash
kf.kio.slaves.remote
kf.kio.kiod
kf.kio.kpasswdserver
kf.kio.gui.favicons
kf.kio.widgets
kf.kio.widgets.kdirmodel
kf.kio.execd
kf.kio.urifilters.localdomain
kf.kio.urifilters.ikws
kf.kio.urifilters.shorturi
kf.configwidgets.cms.kf.kio.useragentdlg
kf.itemmodels
kf.jobwidgets
kf.newstuff
kf.newstuff.core
kf.newstuff.quick
kf.notifications
kf.package
kf.people
kf.peoplewidgets
kf.runner
kf.service.services
kf.service.sycoca
kf.syntaxhighlighting
kf.texteditor
kf.wallet.api
kf.wallet.backend
kf.wallet.kwalletd
kf.wayland.client
kf.wayland.server
kf.windowsystem
kf.windowsystem.keyserver.x11
kf.xmlgui
kf.xmlrpcclient
kf.modemmanagerqt
kf.networkmanagerqt
kf.plasma
kf.plasma.quick
kf.prison
kf.solid.plugins.udisks2
kf.solid.plugins.fstab
kf.sonnet.core
kf.sonnet.clients.aspell
kf.sonnet.clients.hunspell
kf.sonnet.clients.voikko
kf.sonnet.ui
kf.syndication

kossebau created this task.Feb 17 2020, 6:28 PM
kossebau updated the task description. (Show Details)Feb 17 2020, 6:49 PM

sounds very sensible +1

Yes, sounds like a very good idea!
+1

Very well thought through proposal! +

no objections, maybe mention this here as well then: https://community.kde.org/Frameworks/Policies

no objections

kossebau added a subscriber: apol.Feb 19 2020, 12:08 AM

Thanks for feedback, so seems everyone so far is in agreement. Targetting post 5.68 tagging then for execution of the current proposal.

I hope before though I can present a proposal to solve the other problems I mentioned in the task description, whose execution would then be done in one go with the category renamings.

no objections, maybe mention this here as well then: https://community.kde.org/Frameworks/Policies

Agreed, these rules need to be documented and that seems be the expected place. Would do a proposal for a text soon as well.

I'm not sure if we need a compatibility path for old names though, people/distrosmust have
configured some things.

Also not totally sure myself, and if we can expect them to be fne with having to change setup, similar to like that had to adapt to different files to package. I reason to myself that the default logging level is Info or Warning for all categories I saw, and so far could not come up with a scenario where rules no longer matching would break things (compared to additional category names having appeared).
Guess I should write an email to distributions mailinglist, to be more sure, so doing now.