You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by rm...@apache.org on 2023/12/08 15:20:27 UTC
(logging-log4cxx) branch master updated: Add flowchart on how messages are logged #302 (#308)
This is an automated email from the ASF dual-hosted git repository.
rmiddleton pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
The following commit(s) were added to refs/heads/master by this push:
new 5ed6125e Add flowchart on how messages are logged #302 (#308)
5ed6125e is described below
commit 5ed6125e7fb3783402340c9ebfdda5c1b9abdb14
Author: Robert Middleton <rm...@users.noreply.github.com>
AuthorDate: Fri Dec 8 10:20:20 2023 -0500
Add flowchart on how messages are logged #302 (#308)
---
src/site/images/log4cxx-flow.png | Bin 0 -> 77275 bytes
src/site/log4cxx-flow.drawio | 116 ++++++++++++++++++++++++
src/site/markdown/1-usage.md | 1 +
src/site/markdown/log-flow.md | 49 ++++++++++
src/site/markdown/macros-influencing-log4cxx.md | 4 +-
5 files changed, 168 insertions(+), 2 deletions(-)
diff --git a/src/site/images/log4cxx-flow.png b/src/site/images/log4cxx-flow.png
new file mode 100644
index 00000000..73d55e75
Binary files /dev/null and b/src/site/images/log4cxx-flow.png differ
diff --git a/src/site/log4cxx-flow.drawio b/src/site/log4cxx-flow.drawio
new file mode 100644
index 00000000..6fd77aca
--- /dev/null
+++ b/src/site/log4cxx-flow.drawio
@@ -0,0 +1,116 @@
+<mxfile host="app.diagrams.net" modified="2023-12-06T22:01:10.298Z" agent="Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Firefox/102.0" etag="GWKIO4Cc-Fpw4qUow2BO" version="22.1.7" type="device">
+ <diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">
+ <mxGraphModel dx="1434" dy="822" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+ <root>
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-0" />
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-1" parent="WIyWlLk6GJQsqaUBKTNV-0" />
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-2" value="" style="rounded=0;html=1;jettySize=auto;orthogonalLoop=1;fontSize=11;endArrow=block;endFill=0;endSize=8;strokeWidth=1;shadow=0;labelBackgroundColor=none;edgeStyle=orthogonalEdgeStyle;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="WIyWlLk6GJQsqaUBKTNV-3" target="WIyWlLk6GJQsqaUBKTNV-6" edge="1">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-3" value="Logging macro(e.g. LOG4CXX_DEBUG)" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+ <mxGeometry x="145" y="70" width="150" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-4" value="Yes" style="rounded=0;html=1;jettySize=auto;orthogonalLoop=1;fontSize=11;endArrow=block;endFill=0;endSize=8;strokeWidth=1;shadow=0;labelBackgroundColor=none;edgeStyle=orthogonalEdgeStyle;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="WIyWlLk6GJQsqaUBKTNV-6" target="WIyWlLk6GJQsqaUBKTNV-10" edge="1">
+ <mxGeometry y="20" relative="1" as="geometry">
+ <mxPoint as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-5" value="No" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;jettySize=auto;orthogonalLoop=1;fontSize=11;endArrow=block;endFill=0;endSize=8;strokeWidth=1;shadow=0;labelBackgroundColor=none;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="WIyWlLk6GJQsqaUBKTNV-6" target="WIyWlLk6GJQsqaUBKTNV-7" edge="1">
+ <mxGeometry y="10" relative="1" as="geometry">
+ <mxPoint as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-6" value="Macro Enabled<br>(see LOG4CXX_THRESHOLD)" style="rhombus;whiteSpace=wrap;html=1;shadow=0;fontFamily=Helvetica;fontSize=12;align=center;strokeWidth=1;spacing=6;spacingTop=-4;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+ <mxGeometry x="107.5" y="180" width="225" height="180" as="geometry" />
+ </mxCell>
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-7" value="<div>no-op(compiled out of program)</div>" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+ <mxGeometry x="510" y="240" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-8" value="<div>Yes</div>" style="rounded=0;html=1;jettySize=auto;orthogonalLoop=1;fontSize=11;endArrow=block;endFill=0;endSize=8;strokeWidth=1;shadow=0;labelBackgroundColor=none;edgeStyle=orthogonalEdgeStyle;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="WIyWlLk6GJQsqaUBKTNV-10" target="oChkvwbR2C9QrrlvOqCN-6" edge="1">
+ <mxGeometry x="0.3333" y="20" relative="1" as="geometry">
+ <mxPoint as="offset" />
+ <mxPoint x="220" y="630" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-9" value="No" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;jettySize=auto;orthogonalLoop=1;fontSize=11;endArrow=block;endFill=0;endSize=8;strokeWidth=1;shadow=0;labelBackgroundColor=none;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="WIyWlLk6GJQsqaUBKTNV-10" target="WIyWlLk6GJQsqaUBKTNV-12" edge="1">
+ <mxGeometry y="10" relative="1" as="geometry">
+ <mxPoint as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-10" value="<div>Level enabled</div>" style="rhombus;whiteSpace=wrap;html=1;shadow=0;fontFamily=Helvetica;fontSize=12;align=center;strokeWidth=1;spacing=6;spacingTop=-4;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+ <mxGeometry x="145" y="410" width="150" height="120" as="geometry" />
+ </mxCell>
+ <mxCell id="WIyWlLk6GJQsqaUBKTNV-12" value="Message not logged" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+ <mxGeometry x="505" y="440" width="130" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-3" value="Message logged" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+ <mxGeometry x="160" y="1050" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-10" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="oChkvwbR2C9QrrlvOqCN-6" target="oChkvwbR2C9QrrlvOqCN-8">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-6" value="Give log message to each appender" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+ <mxGeometry x="160" y="630" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-11" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="oChkvwbR2C9QrrlvOqCN-8" target="oChkvwbR2C9QrrlvOqCN-3">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-12" value="No" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="oChkvwbR2C9QrrlvOqCN-11">
+ <mxGeometry x="-0.2364" relative="1" as="geometry">
+ <mxPoint x="10" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-13" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="oChkvwbR2C9QrrlvOqCN-8" target="oChkvwbR2C9QrrlvOqCN-15">
+ <mxGeometry relative="1" as="geometry">
+ <mxPoint x="460" y="855" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-14" value="Yes" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="oChkvwbR2C9QrrlvOqCN-13">
+ <mxGeometry x="0.2031" y="-1" relative="1" as="geometry">
+ <mxPoint x="-10" y="-16" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-8" value="Appender has filters" style="rhombus;whiteSpace=wrap;html=1;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+ <mxGeometry x="155" y="790" width="130" height="130" as="geometry" />
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-16" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="oChkvwbR2C9QrrlvOqCN-15" target="oChkvwbR2C9QrrlvOqCN-3">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-17" value="<div>Accept Message / <br></div><div>No more filters<br></div>" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="oChkvwbR2C9QrrlvOqCN-16">
+ <mxGeometry x="0.0204" y="2" relative="1" as="geometry">
+ <mxPoint x="-10" y="-22" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-18" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="oChkvwbR2C9QrrlvOqCN-15" target="oChkvwbR2C9QrrlvOqCN-20">
+ <mxGeometry relative="1" as="geometry">
+ <mxPoint x="780" y="975" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-19" value="<div>Reject message</div>" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="oChkvwbR2C9QrrlvOqCN-18">
+ <mxGeometry x="0.3918" y="-3" relative="1" as="geometry">
+ <mxPoint x="-25" y="-18" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-15" value="Check if next filter accepts or rejects message" style="rhombus;whiteSpace=wrap;html=1;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+ <mxGeometry x="400" y="890" width="170" height="170" as="geometry" />
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-20" value="Message not logged" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+ <mxGeometry x="700" y="945" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-23" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="oChkvwbR2C9QrrlvOqCN-15" target="oChkvwbR2C9QrrlvOqCN-15">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="340" y="975" />
+ <mxPoint x="340" y="890" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="oChkvwbR2C9QrrlvOqCN-24" value="Neutral" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="oChkvwbR2C9QrrlvOqCN-23">
+ <mxGeometry x="-0.2424" y="-4" relative="1" as="geometry">
+ <mxPoint x="16" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git a/src/site/markdown/1-usage.md b/src/site/markdown/1-usage.md
index 42b3d648..a01d38ff 100644
--- a/src/site/markdown/1-usage.md
+++ b/src/site/markdown/1-usage.md
@@ -39,3 +39,4 @@ See the following pages for usage information:
* @subpage conclusions
* @subpage faq
* @subpage buildsystems
+* @subpage log-flow
diff --git a/src/site/markdown/log-flow.md b/src/site/markdown/log-flow.md
new file mode 100644
index 00000000..76f8b49a
--- /dev/null
+++ b/src/site/markdown/log-flow.md
@@ -0,0 +1,49 @@
+Log Flow {#log-flow}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+Messages are logged as follows:
+
+1. If using the Log4cxx macros(e.g. `LOG4CXX_DEBUG`), the macro must first be
+enabled. If the macro is not enabled(for example by setting the `LOG4CXX_THRESHOLD`
+macro), then the log message is not compiled in and the line of code becomes
+a no-op.
+2. The logger level is checked to see if the current level is enabled. If
+it is, the message is then sent to the logger.
+3. The logger creates a new message and gives it to all of its appenders.
+4. Each appender checks its filters to see if the message should be logged.
+
+Filters can perform the following actions:
+
+1. Accept the message: This message will immediately be logged without
+consulting any remaining filters
+2. Reject the message: This message will immediately be rejected without
+consulting any remaining filters
+3. Neutral: This filter neither rejects nor accepts the message, it will
+be passed on to the next filter in the chain
+
+If no filter rejects or accepts the message, the message will be logged.
+
+The following flow diagram shows how messages flow through the system:
+
+
+
diff --git a/src/site/markdown/macros-influencing-log4cxx.md b/src/site/markdown/macros-influencing-log4cxx.md
index dea45709..f85033ff 100644
--- a/src/site/markdown/macros-influencing-log4cxx.md
+++ b/src/site/markdown/macros-influencing-log4cxx.md
@@ -29,7 +29,7 @@ Log4cxx includes), or they may be set globally via your build system.
| Macro | Usage |
| ----- | ----- |
-| LOG4CXX\_THRESHOLD | Used to determine if log messages are compiled in or not. A higher value causes more messages to be compiled out. See [removing log statements](usage.html#removing-log-statements) for more information. |
+| LOG4CXX\_THRESHOLD | Used to determine if log messages are compiled in or not. A higher value causes more messages to be compiled out. See [removing log statements](concepts.html#removing-log-statements) for more information. |
| LOG4CXX\_DISABLE\_LOCATION\_INFO | Define this macro to disable location information on log statements. Location information includes the filename, class name, method name, and line number |
| LOG4CXX\_ENABLE\_STACKTRACE | Define this macro to cause a stacktrace string to be inserted into the MDC with a key of 'stacktrace'. This requires Boost Stacktrace or C++23 stacktrace to be available when compiling your application. When using the PatternLayout, print out the stacktrace using the `%%X{stacktrace}` specifier. See [stacktrace support](stacktrace-support.html) for more information. |
-| LOG4CXX_FORMAT_NS | Override the namespace that LOG4CXX_XXXX_FMT macros use by default. The value can be either 'fmt' or 'std'. You would use the value 'std' if Log4cxx was built with LOG4CXX_FORMAT_NAMESPACE=fmt. |
\ No newline at end of file
+| LOG4CXX_FORMAT_NS | Override the namespace that LOG4CXX_XXXX_FMT macros use by default. The value can be either 'fmt' or 'std'. You would use the value 'std' if Log4cxx was built with LOG4CXX_FORMAT_NAMESPACE=fmt. |