vy commented on code in PR #2660:
URL: https://github.com/apache/logging-log4j2/pull/2660#discussion_r1639471208
##########
src/site/antora/modules/ROOT/examples/manual/markers/log4j2.xml:
##########
@@ -25,16 +25,14 @@
<PatternLayout pattern="%d{HH:mm:ss.SSS} (%marker) %m%n"/>
</Console>
</Appenders>
+ <MarkerFilter marker="SQL"
Review Comment:
Really liked this `MarkerFilter` usage at the root level. :star_struck: I
stole it for #2662.
##########
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:
I don't see the point of this advice. By design, markers are expected to be
seldom changed. Given this, the shared performance impact – I presume, due to
`System.arraycopy()` – is insignificant.
##########
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.
Review Comment:
Removed last sentence, which, IMHO, doesn't add value:
```suggestion
Developers are advised to avoid generic marker names, as they may conflict
with those provided by third parties.
```
--
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]
