Skip to content

Commit d2bc171

Browse files
heuermhandreasprlic
heuermh
authored and
andreasprlic
committed
Content copied from draft in Google doc courtesy of benjamin.t.boyle@
1 parent 56ce659 commit d2bc171

File tree

2 files changed

+126
-0
lines changed

2 files changed

+126
-0
lines changed

‎_wikis/BioJava3_logging.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: BioJava3 logging
3+
---
4+
5+
BioJava Logging Usage Policy
6+
----------------------------
7+
8+
- SLF4J established as BioJava logging facade
9+
- <http://www.slf4j.org/>
10+
- Standard for initializing logger by class
11+
- `private final static Logger logger = LoggerFactory.getLogger(<<Class_Name.class>>);`
12+
- Where \<<Class_Name.class>\> like “BioJavaAADemo.class”
13+
- Note, use current (this) class’ name
14+
- Use SLF4J substitution pattern (`‘{}’`)
15+
- Most importantly, for efficiency. String concatenation is
16+
avoided and toString() is not called if the logging statement is
17+
filtered.
18+
- Meaning if logging level is set to INFO, then all strings in
19+
any debug statements will not be concatenated/toString()’d
20+
- Also, calls to `isDebugEnabled()` or DEBUG constant is not
21+
necessary and redundant
22+
- Enhances readability/conciseness
23+
- Example:
24+
`logger.info("Protein Sequence: {}, Peptide Properties: {}", pSequence.getAccession(), peptide.getIsoelectricPoint(pSequence));`
25+
- No “magic” logs; meaning logs should stand alone, and be reasonable
26+
understandable to an independent developer.
27+
- No printing of random IDs standalone
28+
- `logger.info(protein.getAccesstion());`
29+
- No random symbols
30+
- `logger.debug(“>>>@+”);`
31+
- Mostly, just add context to the log statement
32+
- Demo classes
33+
- Should use `System.out` for logging and other output
34+
- For simplicity
35+
- Logging Levels
36+
- Production, log level set to: WARN
37+
- Test, log level set to: INFO
38+
- Error (logger.error)
39+
- Serious issue, fatal error, process can not continue.
40+
- Must be investigated immediately.
41+
- No system can tolerate items logged on this level.
42+
- <u>Example</u>: NPE, database unavailable, mission critical
43+
use case cannot be continued.
44+
- Warning (logger.warn)
45+
- The process may be able to continue, but not necessarily
46+
guaranteed.
47+
- The application may be able to tolerate warning messages,
48+
but they should always be justified and examined.
49+
- <u>Example</u>: “Application running in development mode”,
50+
“Administration console is not secured with a password”, or
51+
“Format not recognized”.
52+
- Info (logger.info)
53+
- Important business process information
54+
- Process started/finished
55+
- In an ideal world, administrator or advanced user should be
56+
able to understand INFO messages and quickly find out what
57+
the application is doing.
58+
- An action that changes the state of the application
59+
significantly (database update, external system request).
60+
- <u>Example</u>: if an application is all about booking
61+
airplane tickets, there should be only one INFO statement
62+
per each ticket saying “[Who] booked ticket from [Where] to
63+
[Where]“.
64+
- Debug (logger.debug)
65+
- Developers stuff exclusively.
66+
- Trace (logger.trace)
67+
- Very detailed information, intended only for development.
68+
- The distinction between DEBUG and TRACE is the most
69+
difficult, but if you put logging statement and remove it
70+
after the feature has been developed and tested, it should
71+
probably be on TRACE level.
72+
73+
### References
74+
75+
Data in “Logging Levels” section borrowed from:
76+
<http://www.javacodegeeks.com/2011/01/10-tips-proper-application-logging.html>

‎_wikis/BioJava3_logging.mediawiki‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
== BioJava Logging Usage Policy ==
2+
3+
* SLF4J established as BioJava logging facade
4+
** http://www.slf4j.org/
5+
* Standard for initializing logger by class
6+
** <code>private final static Logger logger = LoggerFactory.getLogger(<<Class_Name.class>>);</code>
7+
** Where <<Class_Name.class>> like “BioJavaAADemo.class”
8+
*** Note, use current (this) class’ name
9+
* Use SLF4J substitution pattern (<code>‘{}’</code>)
10+
** Most importantly, for efficiency. String concatenation is avoided and toString() is not called if the logging statement is filtered.
11+
*** Meaning if logging level is set to INFO, then all strings in any debug statements will not be concatenated/toString()’d
12+
*** Also, calls to <code>isDebugEnabled()</code> or DEBUG constant is not necessary and redundant
13+
** Enhances readability/conciseness
14+
** Example: <code>logger.info("Protein Sequence: {}, Peptide Properties: {}", pSequence.getAccession(), peptide.getIsoelectricPoint(pSequence));</code>
15+
* No “magic” logs; meaning logs should stand alone, and be reasonable understandable to an independent developer.
16+
** No printing of random IDs standalone
17+
*** <code>logger.info(protein.getAccesstion());</code>
18+
** No random symbols
19+
*** <code>logger.debug(“>>>@+”);</code>
20+
** Mostly, just add context to the log statement
21+
* Demo classes
22+
** Should use <code>System.out</code> for logging and other output
23+
*** For simplicity
24+
* Logging Levels
25+
** Production, log level set to: WARN
26+
** Test, log level set to: INFO
27+
** Error (logger.error)
28+
*** Serious issue, fatal error, process can not continue.
29+
*** Must be investigated immediately.
30+
*** No system can tolerate items logged on this level.
31+
*** <u>Example</u>: NPE, database unavailable, mission critical use case cannot be continued.
32+
** Warning (logger.warn)
33+
*** The process may be able to continue, but not necessarily guaranteed.
34+
*** The application may be able to tolerate warning messages, but they should always be justified and examined.
35+
*** <u>Example</u>: “Application running in development mode”, “Administration console is not secured with a password”, or “Format not recognized”.
36+
** Info (logger.info)
37+
*** Important business process information
38+
**** Process started/finished
39+
*** In an ideal world, administrator or advanced user should be able to understand INFO messages and quickly find out what the application is doing.
40+
*** An action that changes the state of the application significantly (database update, external system request).
41+
*** <u>Example</u>: if an application is all about booking airplane tickets, there should be only one INFO statement per each ticket saying “[Who] booked ticket from [Where] to [Where]“.
42+
** Debug (logger.debug)
43+
*** Developers stuff exclusively.
44+
** Trace (logger.trace)
45+
*** Very detailed information, intended only for development.
46+
*** The distinction between DEBUG and TRACE is the most difficult, but if you put logging statement and remove it after the feature has been developed and tested, it should probably be on TRACE level.
47+
48+
=== References ===
49+
50+
Data in “Logging Levels” section borrowed from: http://www.javacodegeeks.com/2011/01/10-tips-proper-application-logging.html

0 commit comments

Comments
 (0)