-
-
Notifications
You must be signed in to change notification settings - Fork 273
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[JENKINS-39370,JENKINS-39369] - Support of work directories in Remoti…
…ng (#129) * [JENKINS-39370,JENKINS-39369] - Add workDir parameter and automatically create logs there if specified * Save the progress * [JENKINS-39370] - Generalize the workspace manager for Java Web Start * [JENKINS-39370] - WiP - Save progress in the test suite * [JENKINS-39370] - Add tests for WorkDirManager * [JENKINS-39370] - Restrict the range of supported symbols in the remoting work directory * [JENKINS-39370] - Generalize the workspace initialization checks * [JENKINS-39130] - Allow specifying flag for failing initialization if workdir is missing * [JENKINS-39370] - Reference DirType in WorkDirManager Javadocs * [JENKINS-39370] - @stephenc noticed that workDir may be null, Intellij IDEA adoption fun * [JENKINS-39370] - Seems this message breaks our CI * [JENKINS-39370] - Another message, which likely breaks the CI instance * [JENKINS-39370] - Simplify the log handling logic * [JENKINS-39817] - Introduce the agentLog parameter in remoting.jnlp.Main @stephenc suggested doing it in the PR, so I decided to address it as a part of JENKINS-39370. But the code still has initialization in hudson.remoting.Launcher for other logging modes. * Enable JUL logging to a log-rotated file by default * [JENKINS-18578] - If workspace manager is defined, use JAR Cache within its interbal directory * [JENKINS-39370] - Fix the workDirManager's log initialization in Launcher * [JENKINS-39370] - Draft the documentation * [JENKINS-39369] - Make JUL logging system configurable via property file * [JENKINS-39369] - Fixes in logging management after the manual testing * [JENKINS-39369] - Add tests for the logging subsystem * [JENKINS-39369] - Respect configuration being passed from java.util.logging.config.file system property
- Loading branch information
1 parent
3df4ce6
commit 76c9b8c
Showing
10 changed files
with
1,219 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,46 @@ | ||
Logging | ||
=== | ||
|
||
In Remoting logging is powered by the standard `java.util.logging` engine. | ||
The default behavior depends on the [Work Directory](workDir.md) mode. | ||
|
||
### Configuration | ||
|
||
In order to configure logging it is possible to use an external property file, path to which can be defined using the `-loggingConfig` CLI option or the `java.util.logging.config.file` system property. | ||
|
||
If logging is configured via `-loggingConfig`, some messages printed before the logging system initialization may be missing in startup logs configured by this option. | ||
|
||
See details about the property file format | ||
in [Oracle documentation](https://docs.oracle.com/cd/E19717-01/819-7753/6n9m71435/index.html) | ||
and [this guide](http://tutorials.jenkov.com/java-logging/configuration.html). | ||
Note that `ConsoleHandler` won't be enabled by default if this option is specified. | ||
|
||
### Default behavior with work directory | ||
|
||
With work directory Remoting automatically writes logs to the disk. | ||
This is a main difference from the legacy mode without workDir. | ||
|
||
Logging destinations: | ||
|
||
* STDOUT and STDERR | ||
* Logs include `java.util.logging` and messages printed to _STDOUT/STDERR_ directly. | ||
* Files - `${workDir}/${internalDir}/logs` directory | ||
* File base name - `remoting.log` | ||
* Logs are being automatically rotated. | ||
By default, Remoting keeps 5 10MB files | ||
* Default logging level - `INFO` | ||
* If the legacy `-agentLog` or `-slaveLog` option is enabled, this file logging will be disabled. | ||
|
||
If `-agentLog` or `-slaveLog` are not specified, `${workDir}/${internalDir}/logs` directory will be created during the work directory initialization (if required). | ||
|
||
<!--TODO: Mention conflict with early initialization by java.util.logging.config.file?--> | ||
|
||
### Default behavior without work directory (legacy mode) | ||
|
||
* By default, all logs within the system are being sent to _STDOUT/STDERR_ using `java.util.logging`. | ||
* If `-agentLog` or `-slaveLog` option is specified, the log will be also forwarded to the specified file | ||
* The existing file will be overridden on startup | ||
* Remoting does not perform automatic log rotation of this log file | ||
|
||
Particular Jenkins components use external features to provide better logging in the legacy mode. | ||
E.g. Windows agent services generate logs using features provided by [Windows Service Wrapper (WinSW)](https://github.com/kohsuke/winsw/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,45 @@ | ||
Remoting Work directory | ||
=== | ||
|
||
In Remoting work directory is a storage | ||
|
||
Remoting work directory is available starting from Remoting `TODO`. | ||
Before this version there was no working directory concept in the library itself; | ||
all operations were managed by library users (e.g. Jenkins agent workspaces). | ||
|
||
### Before Remoting TODO | ||
|
||
* There is no work directory management in Remoting itself | ||
* Logs are not being persisted to the disk unless `-slaveLog` option is specified | ||
* JAR Cache is being stored in `${user.home}/.jenkins` unless `-jarCache` option is specified | ||
|
||
### After Remoting TODO | ||
|
||
Due to compatibility reasons, Remoting retains the legacy behavior by default. | ||
Work directory can be enabled using the `-workDir` option in CLI or via the `TODO` [system property](configuration.md). | ||
|
||
Once the option is enabled, Remoting starts using the following structure: | ||
|
||
``` | ||
${WORKDIR} | ||
|_ ${INTERNAL_DIR} - defined by '-internalDir', 'remoting' by default | ||
|_ jarCache - JAR Cache | ||
|_ logs - Remoting logs | ||
|_ ... - Other directories contributed by library users | ||
``` | ||
|
||
Structure of the `logs` directory depends on the logging settings. | ||
See [this page](logging.md) for more information. | ||
|
||
### Migrating to work directories in Jenkins | ||
|
||
:exclamation: Remoting does not perform migration from the previous structure, | ||
because it cannot identify potential external users of the data. | ||
|
||
Once the `-workDir` flag is enabled in Remoting, admins are expected to do the following: | ||
|
||
1. Remove the `${user.home}/.jenkins` directory if there is no other Remoting instances running under the same user. | ||
2. Consider upgrading configurations of agents in order to enable Work Directories | ||
* SSH agents can be configured in agent settings. | ||
* JNLP agents should be started with the `-workDir` parameter. | ||
* See [JENKINS-TODO](TODO) for more information about changes in Jenkins plugins, which enable work directories by default. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.