You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document described how logging is performed across all 3 different processes: IDEA, Engine and Instrumented.
3
+
This document describes
4
+
how logging is implemented across the UnitTestBot Java [processes](https://github.com/UnitTestBot/UTBotJava/blob/main/docs/RD%20for%20UnitTestBot.md):
5
+
the IDE process, the Engine process, and the Instrumented process.
4
6
5
7
## Architecture
6
8
7
-
All logging relies on log4j2.
8
-
When UtBot is used as IDEA plugin - [`utbot-intellij/log4j2.xml`](../utbot-intellij/src/main/resources/log4j2.xml)
9
-
is used as configuration file.
10
-
In other cases(`ContestEstimator`, `Gradle/Maven` tasks, `CLI`, tests) it searches for the first `log4j2.xml` in resources in classpath.
9
+
The UnitTestBot Java logging system relies on `log4j2` library.
10
+
11
+
For UnitTestBot Java used as an IntelliJ IDEA plugin, the configuration file for logging is [`utbot-intellij/log4j2.xml`](../utbot-intellij/src/main/resources/log4j2.xml).
12
+
13
+
When used as Contest estimator or the Gradle/Maven plugins, via CLI or during the CI test runs,
14
+
UnitTestBot Java engine searches classpath for the first `log4j2.xml` in the `resources` directory.
11
15
12
16
### IDE process
13
-
IDEA part of UtBot write logs to `idea.log`.
14
-
Log configuration file is used as is, so if you want to configure logs in IDEA part - use it straight.
15
-
If you want to change log configuration in already built plugin -
16
-
use `Help > Diagnostic Tools > Debug Log Settings...` to change `log4j2.xml` configuration for plugin.
17
17
18
+
The IDE process writes logging information to standard `idea.log` files and puts them into the default log directory.
18
19
19
-
### UtBot plugin
20
+
To configure logs for the IDE process, use the log configuration file in a straightforward way.
20
21
22
+
To change the log configuration for the prebuilt plugin,
23
+
go to **Help** > **Diagnostic Tools** > **Debug Log Settings...** and configure `log4j2.xml`.
Then this file is provided to the Engine process via the following CLI switch:
37
43
```
38
44
-Dlog4j2.configurationFile=%configuration_file%
39
45
```
40
46
41
-
where`%configuration_file%`will be either:
42
-
1.Modified copy of [`utbot-intellij/log4j2.xml`](../utbot-intellij/src/main/resources/log4j2.xml)at UtBot temp directory.
47
+
Here,`%configuration_file%`can take one of two values:
48
+
1.A modified copy of [`utbot-intellij/log4j2.xml`](../utbot-intellij/src/main/resources/log4j2.xml)file, which is stored in UnitTestBot Java temporary directory.
43
49
44
-
More precisely, there are 2 appenders in configuration file:
50
+
More precisely, there are 2 appenders in the configuration file:
45
51
```xml
46
52
<Appenders>
47
53
<Consolename="IdeaAppender" .../>
48
54
<RollingFilename="EngineProcessAppender" .../>
49
55
</Appenders>
50
56
```
51
-
By default `IdeaAppender` is used everywhere in file, which is used in IDEA plugin.
57
+
By default, `IdeaAppender` is used everywhere in a file for the IDE plugin.
52
58
53
-
When working as Engine process - temporary `log4j2.`xml would be created, in which
54
-
substring `ref="IdeaAppender"` will be replaced with `ref="EngineProcessAppender"`,
55
-
thus changing all appenders and log pattern, but preserving same categories and log levels for loggers.
59
+
For the Engine process, a temporary `log4j2.xml` is created,
60
+
where the `ref="IdeaAppender"` substring is replaced with `ref="EngineProcessAppender"`:
61
+
this replacement changes all the appenders and the log pattern
62
+
but keeps categories and log levels for the loggers the same.
56
63
57
-
After that, logs will be written by `RollingFileAppender` in `utbot-engine-current.log` file with rolling over
58
-
after file reaches 20MB size. Previous log files are named `utbot-engine-%i.log`. Log file with
59
-
maximal index is the last one rolled. For example, `utbot-engine-1.log` is created earlier than `utbot-engine-10.log`.
64
+
As soon as the file reaches 20 MB size, `RollingFileAppender` writes the logs to the `utbot-engine-current.log` file.
65
+
The created log files are named `utbot-engine-%i.log`.
66
+
A log file with the largest index is the latest one: `utbot-engine-1.log` has been created earlier than `utbot-engine-10.log`.
60
67
61
-
In IDEA log following lines are printed each time Engine process started:
68
+
Each time the Engine process starts, the following lines are printed into the IntelliJ IDEA log:
62
69
```
63
70
| UtBot - EngineProcess | Engine process started with PID = 4172
2. Path from `UtSettings.engineProcessLogConfigFile`.
75
+
2. A path from `UtSettings.engineProcessLogConfigFile`.
69
76
70
-
This option allows to provide path to external Log4j2 configuration file instead of [`utbot-intellij/log4j2.xml`](../utbot-intellij/src/main/resources/log4j2.xml).
71
-
At `~/.utbot/settings.properties` you can set path to custom configuration file,
72
-
which would apply for engine process, for example:
77
+
The option provides the external `log4j2` configuration file with the path instead of [`utbot-intellij/log4j2.xml`](../utbot-intellij/src/main/resources/log4j2.xml).
78
+
In the `~/.utbot/settings.properties` file, one can set this path to a custom configuration file applicable to the Engine process, for example:
Rd has its own logging system, based on `com.jetbrains.rd.util.Logger` interface. It is convenient to use
93
-
RD logging as default logging system in instrumented process because log4j2 classes in utbot would be confused
94
-
at concrete execution with log4j2 classes in tested project - we will have duplicated versions of log4j2 libs,
95
-
this would break instrumentation and coverage statistics.
98
+
## Rd logging system
96
99
97
-
You should always override default RD logging strategy as by default it writes to stdout/stderr - use `com.jetbrains.rd.util.Logger.Companion.set` method to provide custom
98
-
`com.jetbrains.rd.util.ILoggerFactory`. Already created loggers will be automatically reinstantiated to obtain
99
-
new logger from provided factory. You can obtain logger via `com.jetbrains.rd.util.getLogger` function.
100
-
Check `EngineProcessMain` for RD logging example.
100
+
Rd has the custom logging system based on `com.jetbrains.rd.util.Logger` interface.
101
+
It is convenient to set the Rd logging system as default for the Instrumented process:
102
+
during concrete execution,
103
+
the `log4j2` classes in UnitTestBot Java could be confused with the `log4j2` classes from the project under test.
104
+
Duplicated `log4j2` libraries can break instrumentation and coverage statistics.
101
105
102
-
For available RD factories see `org.utbot.rd.loggers` package - it contains useful implemented factories,
103
-
which log message in the same format as described in `utbot-intellij/src/main/resources/log4j2.xml`.
106
+
You should always override the default Rd logging strategy, which writes log data to `stdout/stderr`.
107
+
Use `com.jetbrains.rd.util.Logger.Companion.set` method to provide custom
108
+
`com.jetbrains.rd.util.ILoggerFactory`.
109
+
The created loggers will be automatically re-instantiated to obtain a new logger from the provided factory.
110
+
You can obtain a logger via the `com.jetbrains.rd.util.getLogger` function.
111
+
Check `EngineProcessMain` for Rd logging example.
112
+
113
+
For available Rd factories, see the `org.utbot.rd.loggers` package: it contains the implemented factories.
114
+
The format of the log messages is the same as described in `utbot-intellij/src/main/resources/log4j2.xml`.
104
115
105
116
## Implementation details
106
117
107
118
### Additivity
108
119
109
-
Sometimes same log entry might be written to log multiple times. At log you will see something like:
120
+
An entry may appear in a log many times due to _additivity_. The resulting log may look like this:
110
121
```
111
122
13:55:41.204 | INFO | AnalyticsConfigureUtil | PathSelectorType: INHERITORS_SELECTOR
112
123
13:55:41.204 | INFO | AnalyticsConfigureUtil | PathSelectorType: INHERITORS_SELECTOR
113
124
```
114
125
115
-
This is because of loggers *additivity* - their full names defines tree structure, and events from children
116
-
are visible for parents. For example, following `log4j2.xml` configuration in IDEA will produce such problem:
126
+
The logger's full name constitutes a tree structure so that the logged events from a child are visible to a parent.
127
+
128
+
For example, the following `log4j2.xml` configuration in IntelliJ IDEA will produce such a problem:
117
129
```xml
118
130
...
119
131
<Loggers>
@@ -127,10 +139,10 @@ are visible for parents. For example, following `log4j2.xml` configuration in ID
127
139
...
128
140
```
129
141
130
-
This happens because `org.utbot` logger is parent for`org.utbot.intellij`, and all events from
131
-
`org.utbot.intellij` are also transferred to parent. This is called `additivity`.
142
+
This happens because the `org.utbot` logger is a parent to`org.utbot.intellij`, and all the events from
143
+
`org.utbot.intellij` are also transferred to `org.utbot`.
132
144
133
-
The solution is to manually add ```additivity="false"``` tag to all loggers:
145
+
To modify this behavior, add the `additivity="false"` tag to all loggers manually:
134
146
```xml
135
147
...
136
148
<Loggers>
@@ -144,64 +156,68 @@ The solution is to manually add ```additivity="false"``` tag to all loggers:
144
156
...
145
157
```
146
158
147
-
Consider this problem when you manually configure log level and appender for logger.
159
+
Consider this problem when you manually configure log level and appender for a logger.
148
160
149
-
More information is available [here](https://logging.apache.org/log4j/2.x/manual/configuration.html#Additivity).
161
+
For more information,
162
+
refer to the [`log4j2` additivity](https://logging.apache.org/log4j/2.x/manual/configuration.html#Additivity) document.
150
163
151
-
### Useful
152
-
See auxiliary methods to work with logs at `UtRdLogUtil.kt` and `Logging.kt`.
153
-
If you want to trace how long execution took - use `org.utbot.common.LoggingKt.logMeasure`
154
-
method with corresponding log level scope.
164
+
### Logging: auxiliary methods
155
165
156
-
In the Engine process log entries from Instrumented process are logged by `org.utbot.instrumentation.rd.InstrumentedProcessKt.rdLogger`.
166
+
Find more logging-related methods at `UtRdLogUtil.kt` and `Logging.kt`.
157
167
158
-
## How to use log4j2 loggers
168
+
To trace the execution duration,
169
+
use the `measureTime` method (see `Logging.kt`) with the corresponding log level scope.
159
170
160
-
See related document - [How to use loggers](../HowToUseLoggers.md).
171
+
In the Engine process, the entries from the Instrumented process are logged by `org.utbot.instrumentation.rd.InstrumentedProcessKt.rdLogger`.
161
172
162
-
## Miscellaneous
173
+
## Log levels and performance
163
174
164
-
### Performance considerations
175
+
For development, the `Debug` level is preferred in most cases.
165
176
166
-
`Debug`level is preferred in the most cases for developing. `Info` is sufficient for release.
177
+
The `Info` log level is sufficient for release.
167
178
168
-
`Trace` log level for RD loggers(for ex. if you specify `Trace` for all loggers, or as default level for root logger)
169
-
will enable logging all technical send/receive event from protocol,
170
-
causing ~50mb additional logs per generation and ***heavily*** polluting log. This might be useful
171
-
when troubleshooting inter-process communication, but in all other cases prefer `Debug` level or
172
-
specify `Trace` level per logger explicitly.
179
+
In Rd, if you choose the `Trace`level for all loggers or set it as default for the root logger,
180
+
this enables logging for all technical _send/receive_ events from protocol.
181
+
It may cause ~50 MB of additional entries per generation to appear and _heavily_ pollutes the log. This might be useful
182
+
for troubleshooting interprocess communication but in all other cases prefer the`Debug` level or
183
+
specify the `Trace` level per logger explicitly.
173
184
174
-
If your`Debug` levellog message requires heavy string interpolation - wrap it in lambda, for example:
185
+
For the`Debug` level, if a log message requires heavy string interpolation, wrap it in lambda, for example:
175
186
```kotlin
176
187
val someVeryBigDataStructure =VeryBigDataStructure()
0 commit comments