ppkarwasz commented on code in PR #2660: URL: https://github.com/apache/logging-log4j2/pull/2660#discussion_r1640114681
########## src/site/antora/modules/ROOT/pages/manual/markers.adoc: ########## @@ -61,88 +61,110 @@ include::example$manual/markers/marker-filtering.log[tag=use-marker] A marker can have zero or more parent markers, allowing for a hierarchy of markers. To create such a hierarchy, you must use the `addParents()` method on the `Marker` object after you make the child marker. -[source, java, indent=0] +[source,java,indent=0] ---- include::example$manual/markers/MarkerExample.java[tag=create-marker-parent] ---- Child markers do not differ from simple markers; one must pass them on as the first argument of a logging call. -[source, java, indent=0] +[source,java,indent=0] ---- include::example$manual/markers/MarkerExample.java[tag=use-marker-parent] ---- Messages marked with children's markers behave as if they were both marked with the children's marker and all its parents. If you use the <<example-configuration,configuration example below>>, you'll see the following log statement on your console: -[source, text] +[source,text] ---- include::example$manual/markers/marker-filtering.log[tag=use-marker-parent] ---- +[#pitfalls] +== Pitfalls + +It is important to note that marker names must be unique, as Log4j registers them permanently by name. +Developers should avoid generic marker names, as they may conflict with +those provided by third parties. Except, of course, if the user is aware of the implications. + +While it is possible to add or remove parent markers dynamically through the `setParents()` method, +it is generally advisable to set the parents when the marker is created for efficiency and performance reasons. Review Comment: This is a legacy comment. I guess we should replace it with something like: > For technical reasons the `setParents` method can be called at runtime to modify the list of parents of the current marker. > However, we discourage such a practice and advise you to only use the method at initialization time. WDYT? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
