From df51ce7f3966080f5ee35918cf1ff891ef659496 Mon Sep 17 00:00:00 2001 From: Jeff Hong Date: Thu, 16 Nov 2017 13:56:44 -0600 Subject: [PATCH 1/4] Create STARTS-LOGGING.md adds logging documentation to STARTS, incorporating the paper's details on artifact storage --- README.md | 2 ++ STARTS-LOGGING.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 STARTS-LOGGING.md diff --git a/README.md b/README.md index d30edefa..1d89af25 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,8 @@ checksums of files in the latest version, while the command in (4) behavior. For example, to update the checksums while checking the diff, run `mvn starts:diff -DupdateDiffChecksums=true`. +[Logging and Artifact storage Docs](./STARTS-LOGGING.md) + ## Papers on STARTS Below is a list of research papers that describe some aspects of diff --git a/STARTS-LOGGING.md b/STARTS-LOGGING.md new file mode 100644 index 00000000..c2209448 --- /dev/null +++ b/STARTS-LOGGING.md @@ -0,0 +1,82 @@ + +# Logging + +## Intro + +Logging in STARTS is a customized (read: simpler) version of [java.util.logging (JUL)](https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html). + +The code for logging is located in starts-core/src/main/java/edu/illinois/starts/util/Logger.java + + + +For any piece of starts that you'd like to add logging to, begin by adding two import statements at the top: +- ``import edu.illinois.starts.util.Logger;`` +- ``import java.util.logging.Level;`` +_note: you may need to make minor changes to the positioning of these two import statements to ensure checkstyle does not break. place ``edu.illinois.starts.util.Logger`` directly underneath the other imports with the same package name, and do the same with ``java.util.logging.Level``. additionally, ensure you have a newline separating different package names_ + +Next, instantiate your Logger as a class variable: +- ``protected static final Logger logger = Logger.getGlobal();`` + +## Levels +There are 7 logging levels (excluding OFF and ALL), just like JUL: +- SEVERE (highest value) +- WARNING +- __INFO (default)__ +- CONFIG +- FINE +- FINER +- FINEST (lowest value) + +To set the logging level of your log, use the ``setLoggingLevel(Level level)`` method. +i.e. +``logger.setLoggingLevel(Level.CONFIG);`` + +To check the logging level, use the ``getLoggingLevel()`` method, which will return an object of type [Level](https://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html). +i.e. +``Level currentLevel = logger.getLoggingLevel();`` + +## Writing messages +There are two methods you can use to log that differ only in the number of arguments you pass in. + +###### ``public void log(Level lev, String msg, Throwable thr)`` +should be used when you want to have a custom message AND an exception message + + +###### ``public void log(Level lev, String msg)`` +should be used when you only want to have a custom message + +i.e. ``logger.log(Level.SEVERE, "houston we have a problem");`` + +In both cases above, the provided message will only be logged if the specified logging Level is equal to or higher in severity than the Level the logger is set to. +For example, if ``logger.setLoggingLevel(Level.SEVERE);``, then only ``logger.log()`` messages with Level.SEVERE will be spit out. +Similarly, if ``logger.setLoggingLevel(Level.CONFIG);``, then ``logger.log()`` with Level.INFO will be output, but not Level.FINER. + +## Where will messages be output? +Standard Output (System.out) + +## Artifact Storage +The logging granularities serve a dual purpose - both to control which log messages in code are sent to standard output, AND to control which artifacts are stored between runs. + +The default Level.INFO will store: +- checksum +- dependency file (.starts/deps.zlc) + +Level.FINER will store: +- dependency file (.starts/deps.zlc) +- list of all tests +- list of impacted tests + +Level.FINEST will store: +- list of all tests +- list of impacted tests +- list of non-impacted tests +- list of dependencies computed by jdeps +- classpath that STARTS used +- yasgl graph that STARTS constructed +- set of changed types + +To set the log level at runtime, call starts like this: + +``mvn starts:starts -DStartsLogging=`` + +i.e. ``mvn starts:starts -DStartsLogging=FINEST`` From e144cb244bdd242f609a0ad931684e65dd82613c Mon Sep 17 00:00:00 2001 From: Jeff Hong Date: Fri, 17 Nov 2017 15:07:25 -0600 Subject: [PATCH 2/4] adds fixes suggested by August --- README.md | 2 +- STARTS-LOGGING.md | 62 ++++++++++++++++++++++++++++------------------- 2 files changed, 38 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 1d89af25..8f3220d5 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ checksums of files in the latest version, while the command in (4) behavior. For example, to update the checksums while checking the diff, run `mvn starts:diff -DupdateDiffChecksums=true`. -[Logging and Artifact storage Docs](./STARTS-LOGGING.md) +[Logging and Artifact Storage Docs](./STARTS-LOGGING.md) ## Papers on STARTS diff --git a/STARTS-LOGGING.md b/STARTS-LOGGING.md index c2209448..b48800c4 100644 --- a/STARTS-LOGGING.md +++ b/STARTS-LOGGING.md @@ -8,11 +8,13 @@ Logging in STARTS is a customized (read: simpler) version of [java.util.logging The code for logging is located in starts-core/src/main/java/edu/illinois/starts/util/Logger.java - For any piece of starts that you'd like to add logging to, begin by adding two import statements at the top: -- ``import edu.illinois.starts.util.Logger;`` + +- ``import edu.illinois.starts.util.Logger;`` - ``import java.util.logging.Level;`` -_note: you may need to make minor changes to the positioning of these two import statements to ensure checkstyle does not break. place ``edu.illinois.starts.util.Logger`` directly underneath the other imports with the same package name, and do the same with ``java.util.logging.Level``. additionally, ensure you have a newline separating different package names_ + +_note: you may need to make minor changes to the positioning of these two import statements to ensure checkstyle does not break. Place ``edu.illinois.starts.util.Logger`` directly underneath the other imports with the same package name, and do the same with ``java.util.logging.Level``. Additionally, ensure you have a newline separating different package names_ + Next, instantiate your Logger as a class variable: - ``protected static final Logger logger = Logger.getGlobal();`` @@ -27,12 +29,18 @@ There are 7 logging levels (excluding OFF and ALL), just like JUL: - FINER - FINEST (lowest value) -To set the logging level of your log, use the ``setLoggingLevel(Level level)`` method. -i.e. +To set the logging level of your log, use the + +``setLoggingLevel(Level level)`` + +method. +i.e., + ``logger.setLoggingLevel(Level.CONFIG);`` To check the logging level, use the ``getLoggingLevel()`` method, which will return an object of type [Level](https://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html). -i.e. +i.e., + ``Level currentLevel = logger.getLoggingLevel();`` ## Writing messages @@ -45,7 +53,9 @@ should be used when you want to have a custom message AND an exception message ###### ``public void log(Level lev, String msg)`` should be used when you only want to have a custom message -i.e. ``logger.log(Level.SEVERE, "houston we have a problem");`` +i.e., + +``logger.log(Level.SEVERE, "houston we have a problem");`` In both cases above, the provided message will only be logged if the specified logging Level is equal to or higher in severity than the Level the logger is set to. For example, if ``logger.setLoggingLevel(Level.SEVERE);``, then only ``logger.log()`` messages with Level.SEVERE will be spit out. @@ -54,29 +64,31 @@ Similarly, if ``logger.setLoggingLevel(Level.CONFIG);``, then ``logger.log()`` w ## Where will messages be output? Standard Output (System.out) -## Artifact Storage +## Artifact storage The logging granularities serve a dual purpose - both to control which log messages in code are sent to standard output, AND to control which artifacts are stored between runs. -The default Level.INFO will store: -- checksum -- dependency file (.starts/deps.zlc) +The default __Level.INFO__ will store: +- _dependency file/checksum (.starts/deps.zlc)_ -Level.FINER will store: -- dependency file (.starts/deps.zlc) -- list of all tests -- list of impacted tests +__Level.FINER__ will store: +- _dependency file/checksum (.starts/deps.zlc)_ +- _list of all tests_ +- _list of impacted tests_ -Level.FINEST will store: -- list of all tests -- list of impacted tests -- list of non-impacted tests -- list of dependencies computed by jdeps -- classpath that STARTS used -- yasgl graph that STARTS constructed -- set of changed types +__Level.FINEST__ will store: +- _dependency file/checksum (.starts/deps.zlc)_ +- _list of all tests_ +- _list of impacted tests_ +- _list of non-impacted tests_ +- _list of dependencies computed by jdeps_ +- _classpath that STARTS used_ +- _yasgl graph that STARTS constructed_ +- _set of changed types_ To set the log level at runtime, call starts like this: -``mvn starts:starts -DStartsLogging=`` +``mvn starts:starts -DstartsLogging=`` + +i.e., -i.e. ``mvn starts:starts -DStartsLogging=FINEST`` +``mvn starts:starts -DstartsLogging=FINEST`` From 901a6fa313bdb64a5fa11538be03fcf270bead3b Mon Sep 17 00:00:00 2001 From: Owolabi Legunsen Date: Tue, 22 Aug 2023 14:46:26 -0400 Subject: [PATCH 3/4] capitalization Co-authored-by: Benjamin Shen <34158284+benjamin-shen@users.noreply.github.com> --- STARTS-LOGGING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STARTS-LOGGING.md b/STARTS-LOGGING.md index b48800c4..7f295114 100644 --- a/STARTS-LOGGING.md +++ b/STARTS-LOGGING.md @@ -13,7 +13,7 @@ For any piece of starts that you'd like to add logging to, begin by adding two i - ``import edu.illinois.starts.util.Logger;`` - ``import java.util.logging.Level;`` -_note: you may need to make minor changes to the positioning of these two import statements to ensure checkstyle does not break. Place ``edu.illinois.starts.util.Logger`` directly underneath the other imports with the same package name, and do the same with ``java.util.logging.Level``. Additionally, ensure you have a newline separating different package names_ +_note: You may need to make minor changes to the positioning of these two import statements to ensure checkstyle does not break. Place ``edu.illinois.starts.util.Logger`` directly underneath the other imports with the same package name, and do the same with ``java.util.logging.Level``. Additionally, ensure you have a newline separating different package names_ Next, instantiate your Logger as a class variable: From 82e197acb413943b210cc058db26d28e0412f8cd Mon Sep 17 00:00:00 2001 From: Owolabi Legunsen Date: Tue, 22 Aug 2023 14:46:57 -0400 Subject: [PATCH 4/4] stylize URL Co-authored-by: Benjamin Shen <34158284+benjamin-shen@users.noreply.github.com> --- STARTS-LOGGING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STARTS-LOGGING.md b/STARTS-LOGGING.md index 7f295114..3117d1f3 100644 --- a/STARTS-LOGGING.md +++ b/STARTS-LOGGING.md @@ -5,7 +5,7 @@ Logging in STARTS is a customized (read: simpler) version of [java.util.logging (JUL)](https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html). -The code for logging is located in starts-core/src/main/java/edu/illinois/starts/util/Logger.java +The code for logging is located in [util/Logger.java](./starts-core/src/main/java/edu/illinois/starts/util/Logger.java). For any piece of starts that you'd like to add logging to, begin by adding two import statements at the top: