public class Trace extends Object implements TraceInterface
Copyright: Copyright 2003-2014, Knowledge Science Group, University of Calgary. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. The Knowledge Science Group makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.
This class is responsible for CASA's trace mechanism which uses String identifiers called "trace tags" to control whether a particular "topic" is recorded. Trace messages on particular tags (topics) are divided into 10 levels by appending a trace tag identifier with a digit (0 being the most basic, and 9 being the highest level of detail). Trace messages are normally logged to a file as (potentially multi-line) records. For example:>>>>>>>>>>>>>>>>>>>>>>>>> casa.abcl.Lisp.signalError(Lisp.java:349) [*14.39.12.788:CASAProcess1403296740779:error:main*] Lisp.abclEval: (load "scripts/sc2.lisp") : #In addition, a memory-resident trace record may be kept, and agent observers will be notified (if the trace is on behalf of an agent).: Unexpected non-ControlTransfer exception during execution of lisp operator AGENT.TELL: java.lang.NullPointerException at casa.TransientAgent$14.execute(TransientAgent.java:8412) at casa.abcl.CasaLispOperator.execute(CasaLispOperator.java:603) at org.armedbear.lisp.Lisp.eval(Lisp.java:495) at org.armedbear.lisp.Lisp.progn(Lisp.java:674) ... : casa.abcl.LispException <<<<<<<<<<<<<<<<<<<<<<<<<
Most often, users will use the println() family o methods. However if there is no agent in scope or otherwise no Trace object in scope, users may equivalently use the log() family of methods (with the same parameters as the println() methods) to access the process-wide trace object.
For added control, several flags may be used with the println() an log() methods:
Modifier and Type | Class and Description |
---|---|
private static class |
Trace.LogStream |
Modifier and Type | Field and Description |
---|---|
private CasaObservable |
agent
The agent that "owns" this Trace object.
|
private static String |
dateFormat
WARNING: the timestamp format should NOT contain any colons (":"), as that would screw up any code that parses the header
|
private static int |
errors
The accumulated number of errors seen.
|
private FileWriter |
fileWriter
The file stream we will be writing to.
|
private StringBuffer |
history
The internal history buffer; if null, no history will be saved.
|
private static TreeSet<String> |
knownTags
The set of knowTags, initialized by
getKnownTagsFromPersistentStore() . |
private static String |
LINE_SEPARATOR
For platform-independence it's recommended that line.separator be used
|
(package private) File |
logFile
The file we are logging to.
|
private boolean |
logToFile
Flag to indicate we are logging to a file.
|
private static String |
LONG_TIMESTAMP_FORMAT
WARNING: the timestamp format should NOT contain any colons (":"), as that would screw up any code that parses the header
|
static int |
MAX_FILE_SIZE
The maximum file size (in bytes) for log files.
|
private long |
maxHistory
The maximum size (in bytes) of the internal history to be saved.
|
static long |
maxHistoryDefault
The default maximum size (in bytes) of the internal history to be saved.
|
static int |
OPT_COPY_TO_SYSERR
Copies output to syserr.
|
static int |
OPT_COPY_TO_SYSOUT
Copies output to sysout.
|
static int |
OPT_FORCE_STACK_TRACE
Default for print methods that include an Exception parameter where the Exception is non-null.
|
static int |
OPT_INCLUDE_CODE_LINE_NUMBER
Default for error and warning tags.
|
static int |
OPT_SUPPRESS_AGENT_LOG
Only applicable to the process-wide Trace; forces output to sysout rather than trying to find an agent.
|
static int |
OPT_SUPPRESS_HEADER_ON_SYSOUT
Suppresses the header block and >>>> flagging when printing to sysout or syserr
|
static int |
OPT_SUPRESS_STACK_TRACE
Default for print methods that do not include an Exception parameter or method calls that have a null Exception parameter.
|
private static PrintStream |
originalSysErr |
private static PrintStream |
originalSysOut |
private String |
prefix
The prefix to go after the header and before the actual message in trace records.
|
private static Trace |
processWideTrace
An Trace object used by the static methods to track messages not associated with any particular agent.
|
(package private) int |
restarts
The number of file resets we have done.
|
(package private) String |
startDate
Holds the startDate as a convenience for file resets.
|
private String |
traceName
The name of this trace; this is used to name the trace file.
|
private TreeMap<String,Integer> |
traceTags
The structure used to save trace tags for quick lookup.
|
private static int |
warnings
The accumulated number of warnings seen.
|
Modifier | Constructor and Description |
---|---|
|
Trace(CasaObservable agent)
Equivalent to
Trace(agent, null, 0) |
|
Trace(CasaObservable agent,
String name)
Equivalent to
Trace(agent, name, 0) |
|
Trace(CasaObservable agent,
String name,
long maxTraceHistoryBytes)
Equivalent to
Trace(agent, name, 0, LONG_TIMESTAMP_FORMAT) |
private |
Trace(CasaObservable agent,
String name,
long maxTraceHistoryBytes,
String timeStampFormat)
Creates a new Trace object.
|
private |
Trace(String name)
Equivalent to
Trace(null, name, 0) |
Modifier and Type | Method and Description |
---|---|
int |
addTraceTags(String tags)
Adds a comma-delimited list of trace tags to a string.
|
static void |
captureSysout()
Replaces
System.out out and System.err to log any program output to the process-wide trace
file. |
void |
clearAllTraceTags()
Turns off ALL the trace tags.
|
static void |
clearKnownTags()
Sets the set of known tags to the empty set, and stores it persistently (and globally to CASA).
|
protected void |
finalize()
Assures
fileWriter is closed. |
static int |
getErrors() |
private String |
getHeader(String tag) |
static String |
getHeader(String tag,
String agentName)
Return a formatted a header.
|
String |
getHistory() |
private static TreeSet<String> |
getKnownTagsFromPersistentStore() |
static String |
getKnownTagsString() |
boolean |
getLogToFile() |
String |
getName() |
String |
getPrefix() |
(package private) static File |
getProcessTraceFile() |
boolean |
getSaveHistory() |
static String |
getStackTraceString(Throwable ex)
Converts the parameter Throwable to a string, including the stack trace and the "caused by" trace.
|
protected int |
getTagDetail(String tag) |
static String |
getTags() |
protected String |
getTagString(String tag) |
protected static String |
getTimeStamp() |
File |
getTraceFile() |
String |
getTraceTags() |
private static StackTraceElement[] |
getTrimmedStackTrace() |
private static StackTraceElement[] |
getTrimmedStackTrace(int skip) |
static String |
getTrimmedStackTraceString()
Returns the stack with the best guess at trimming the the Trace methods off the top.
|
static int |
getWarnings() |
boolean |
isLoggingTag(String tag)
Determine if the specified trace tag spec will print, taking
into account the last digit appended on the tag if it's there.
|
private static boolean |
isPrintMethodElement(StackTraceElement t) |
static String |
log(String tag,
String message)
Logs the message if tag is in effect to the in-scope agent's log files, windows, etc.
|
static String |
log(String tag,
String message,
int options)
Logs the message if tag is in effect to the in-scope agent's log files, windows, etc.
|
static String |
log(String tag,
String message,
Throwable ex)
Logs the message if tag is in effect to the in-scope agent's log files, windows, etc.
|
static String |
log(String tag,
String message,
Throwable ex,
int options)
Logs the message if tag is in effect to the in-scope agent's log files, windows, etc.
|
static String |
log(TraceInterface agent,
String tag,
String message,
Throwable ex,
int options)
Logs the message to the TraceInterface object in the first argument.
|
static String |
logToSysout(String tag,
String message,
Throwable ex,
int options)
Deprecated.
|
private String |
print(String tag,
String string,
Throwable e,
int flags)
This is the print method that all the other println methods eventually call.
|
String |
println(String tag,
String string)
Equivalent to
println(tag, string, null, 0) |
String |
println(String tag,
String string,
int flags)
Equivalent to
println(tag, string, null, flag) |
String |
println(String traceTag,
String txt,
Throwable ex)
Equivalent to
println(tag, string, ex, 0) |
String |
println(String traceTag,
String txt,
Throwable ex,
int flags)
This is the println method that defines all the other println methods.
|
private void |
printToFile(String msg) |
private void |
printToOriginalSysErr(String msg) |
private void |
printToOriginalSysErr(String msg,
Throwable e) |
private void |
printToOriginalSysOut(String msg) |
int |
removeTraceTags(String tags)
Removes the tags in the comma-delimited streams specified in tags.
|
void |
resetLogFile()
Starts or restarts (by wiping and re-initializing) the log file.
|
private static void |
saveKnownTagsToPersistentStore()
Saves the known tags back to persistent store by calling
CASA.putPreference("knownTraceTags", tags, CASA.USER|CASA.SYSTEM) |
void |
setAllTraceTags()
Turns all ALL the trace tags.
|
void |
setHistoryMaxBytes(long max)
Sets the maximum bytes of history information to save.
|
boolean |
setLogToFile(boolean b)
Makes this Trace object start/stop logging to a File.
|
void |
setName(String value)
Sets the name of this Trace object.
|
String |
setPrefix(String newPrefix)
Sets the prefix to be used in records.
|
(package private) static void |
setProcessLogToFile(boolean b)
Turns on or off logging to the process-wide trace file.
|
void |
setSaveHistory(boolean value)
Sets whether or not this Trace object will save history information.
|
static void |
setTags(String tags)
Sets the process-wide trace tags.
|
int |
setTraceTags(String tags)
Works the same as addTraceTags, but removes all previous tags beforehand.
|
private static void |
updateTags(String tag)
Records the tag to persistent tags if it's not already there.
|
public static final int OPT_SUPRESS_STACK_TRACE
public static final int OPT_FORCE_STACK_TRACE
public static final int OPT_INCLUDE_CODE_LINE_NUMBER
public static final int OPT_SUPPRESS_AGENT_LOG
public static final int OPT_COPY_TO_SYSOUT
public static final int OPT_COPY_TO_SYSERR
public static final int OPT_SUPPRESS_HEADER_ON_SYSOUT
private static final String LONG_TIMESTAMP_FORMAT
getHeader(String);
,
Constant Field Valuespublic static final int MAX_FILE_SIZE
private static String LINE_SEPARATOR
private static String dateFormat
getHeader(String);
private String traceName
private StringBuffer history
public static final long maxHistoryDefault
private long maxHistory
private boolean logToFile
traceName
private String prefix
private TreeMap<String,Integer> traceTags
private CasaObservable agent
private FileWriter fileWriter
private static int errors
private static int warnings
private static final Trace processWideTrace
File logFile
int restarts
MAX_FILE_SIZE
String startDate
resetLogFile()
private static TreeSet<String> knownTags
getKnownTagsFromPersistentStore()
.private static PrintStream originalSysErr
private static PrintStream originalSysOut
private Trace(String name)
Trace(null, name, 0)
name
- The name of this trace; used to specify the trace file name.
If null, will default to the name of the current process.public Trace(CasaObservable agent)
Trace(agent, null, 0)
agent
- The agent that "owns" this Trace object.public Trace(CasaObservable agent, String name)
Trace(agent, name, 0)
agent
- The agent that "owns" this Trace object.name
- The name of this trace; used to specify the trace file name.
If null, will default to the agent name or the name of the current process if agent is null.public Trace(CasaObservable agent, String name, long maxTraceHistoryBytes)
Trace(agent, name, 0, LONG_TIMESTAMP_FORMAT)
agent
- The agent that "owns" this Trace object.name
- The name of this trace; used to specify the trace file name.
If null, will default to the agent name or the name of the current process if agent is null.maxTraceHistoryBytes
- The maximum number of bytes to save in the internal history.LONG_TIMESTAMP_FORMAT
private Trace(CasaObservable agent, String name, long maxTraceHistoryBytes, String timeStampFormat)
agent
- The agent that "owns" this Trace object.name
- The name of this trace; used to specify the trace file name.
If null, will default to the agent name or the name of the current process if agent is null.maxTraceHistoryBytes
- The maximum number of bytes to save in the internal history.timeStampFormat
- The timeStampFormat to use; must not contain any colons (":") as that will mess up header parsing.
Defaults to LONG_TIMESTAMP_FORMAT
("HH.mm.ss.SSS") if this is null.protected void finalize() throws Throwable
fileWriter
is closed.finalize
in class Object
Throwable
Object.finalize()
public boolean setLogToFile(boolean b) throws IOException
b
- True if we want to start logging to a file, false to stop.IOException
public void resetLogFile() throws IOException
getName()
with the extension ".log". A "standard" header
will be written to the new file.IOException
public boolean getLogToFile()
public String getPrefix()
setPrefix(String)
,
print(String, String, Throwable, int)
public String setPrefix(String newPrefix)
newPrefix
- The new prefix to use.getPrefix()
,
print(String, String, Throwable, int)
public int addTraceTags(String tags)
addTraceTags
in interface TraceInterface
tags
- a comma-delimited list of trace tagsTraceInterface.addTraceTags(java.lang.String)
public int removeTraceTags(String tags)
removeTraceTags
in interface TraceInterface
tags
- The tags to be removed.TraceInterface.removeTraceTags(java.lang.String)
,
setTraceTags(String)
public int setTraceTags(String tags)
setTraceTags
in interface TraceInterface
tags
- A command-delimited list of tags. White space is ignored.TraceInterface.setTraceTags(java.lang.String)
public void setAllTraceTags()
setAllTraceTags
in interface TraceInterface
casa.util.TraceInterface#setAllTraceTags(java.lang.String)
public void clearAllTraceTags()
clearAllTraceTags
in interface TraceInterface
casa.util.TraceInterface#clearAllTraceTags(java.lang.String)
public String getTraceTags()
getTraceTags
in interface TraceInterface
TraceInterface.getTraceTags()
public boolean isLoggingTag(String tag)
isLoggingTag
in interface TraceInterface
tag
- TraceInterface.isLoggingTag(java.lang.String)
protected int getTagDetail(String tag)
tag
- protected String getTagString(String tag)
tag
- the tag string to parseprotected static String getTimeStamp()
dateFormat
format.public void setName(String value)
value
- The new name.public String getName()
public boolean getSaveHistory()
public void setSaveHistory(boolean value)
value
- True if history is to be saved.public void setHistoryMaxBytes(long max)
max
- The maximum bytes of history to be saved.public String getHistory()
setSaveHistory(boolean)
,
setHistoryMaxBytes(long)
private static TreeSet<String> getKnownTagsFromPersistentStore()
CASA.getPreference("knownTraceTags", "", 0)
saveKnownTagsToPersistentStore()
,
updateTags(String)
private static void saveKnownTagsToPersistentStore()
CASA.putPreference("knownTraceTags", tags, CASA.USER|CASA.SYSTEM)
private static void updateTags(String tag)
tag
- The tag NAME (without trailing digit).getKnownTagsFromPersistentStore()
,
saveKnownTagsToPersistentStore()
public static String getKnownTagsString()
saveKnownTagsToPersistentStore()
public static void clearKnownTags()
private static boolean isPrintMethodElement(StackTraceElement t)
t
- private static StackTraceElement[] getTrimmedStackTrace()
private static StackTraceElement[] getTrimmedStackTrace(int skip)
skip
- The number of top-level element to skipisPrintMethodElement(StackTraceElement)
public static String getTrimmedStackTraceString()
getTrimmedStackTrace()
,
isPrintMethodElement(StackTraceElement)
private String print(String tag, String string, Throwable e, int flags)
OPT_INCLUDE_CODE_LINE_NUMBER
is in flags then so short string of ">"'s.
In any of these cases, the ">"'s is followed by the guess of the calling source file and line number.
OPT_SUPRESS_STACK_TRACE
is not set, or OPT_FORCE_STACK_TRACE
is set.
tag
- This tag MUST be present in set of traceTags for anything to be printed/logged.string
- The message to be printed/logged.e
- If this is non-null, the stack trace will be appended to the messageflags
- The options flags; use bitwise disjunct ("|") to combine options - OPT_SUPPRESS_AGENT_LOG
, OPT_COPY_TO_SYSERR
, OPT_COPY_TO_SYSOUT
, OPT_FORCE_STACK_TRACE
, OPT_INCLUDE_CODE_LINE_NUMBER
, OPT_SUPPRESS_HEADER_ON_SYSOUT
, OPT_SUPRESS_STACK_TRACE
.public String println(String tag, String string)
TraceInterface
println(tag, string, null, 0)
println
in interface TraceInterface
TraceInterface.println(String, String, Throwable, int)
public String println(String tag, String string, int flags)
TraceInterface
println(tag, string, null, flag)
println
in interface TraceInterface
flags
- The options flags; use bitwise disjunct ("|") to combine options - #OPT_SUPPRESS_AGENT_LOG
, #OPT_COPY_TO_SYSERR
, #OPT_COPY_TO_SYSOUT
, #OPT_FORCE_STACK_TRACE
, #OPT_INCLUDE_CODE_LINE_NUMBER
, #OPT_SUPPRESS_HEADER_ON_SYSOUT
, #OPT_SUPRESS_STACK_TRACE
.TraceInterface.println(java.lang.String, java.lang.String, int)
public String println(String traceTag, String txt, Throwable ex)
TraceInterface
println(tag, string, ex, 0)
println
in interface TraceInterface
traceTag
- This tag MUST be present in set of traceTags for anything to be printed/logged.txt
- The message to be printed/logged.ex
- If this is non-null, the stack trace will be appended to the messageTraceInterface.println(String, String, Throwable, int)
public String println(String traceTag, String txt, Throwable ex, int flags)
TraceInterface
#OPT_INCLUDE_CODE_LINE_NUMBER
is in flags then so short string of ">"'s.
In any of these cases, the ">"'s is followed by the guess of the calling source file and line number.
#OPT_SUPRESS_STACK_TRACE
is not set, or #OPT_FORCE_STACK_TRACE
is set.
[* timestamp : agentName : tag : thread-name *]
println
in interface TraceInterface
traceTag
- This tag MUST be present in set of traceTags for anything to be printed/logged.txt
- The message to be printed/logged.ex
- If this is non-null, the stack trace will be appended to the messageflags
- The options flags; use bitwise disjunct ("|") to combine options - #OPT_SUPPRESS_AGENT_LOG
, #OPT_COPY_TO_SYSERR
, #OPT_COPY_TO_SYSOUT
, #OPT_FORCE_STACK_TRACE
, #OPT_INCLUDE_CODE_LINE_NUMBER
, #OPT_SUPPRESS_HEADER_ON_SYSOUT
, #OPT_SUPRESS_STACK_TRACE
.public static String getStackTraceString(Throwable ex)
ex
- private void printToFile(String msg)
public static String getHeader(String tag, String agentName)
[* timestamp : agentName : tag : thread-name *]
tag
- the tag used in the header.agentName
- the agentName used in the header.public static int getErrors()
public static int getWarnings()
public File getTraceFile()
@Deprecated public static String logToSysout(String tag, String message, Throwable ex, int options)
log(String, String, Throwable, options|#OPT_COPY_TO_SYSOUT|#OPT_SUPPRESS_AGENT_LOG)
insteadtag
- Used in the output messagemessage
- The message to logex
- If ex is not null, the stack dump is appended to the message.printStackTrace
- set to true to print a stack trace (note that if ex is not null, the trace will be printed anyway).public static String log(TraceInterface agent, String tag, String message, Throwable ex, int options)
agent
- tag
- message
- ex
- options
- public static String log(String tag, String message, Throwable ex)
tag
- A trace tag: if an agent can't be found in scope this is ignoredmessage
- The message to logex
- If ex is not null, the stack dump is appended to the message.log(String, String)
,
CASAUtil.getAbstractProcessInScope()
public static String log(String tag, String message, Throwable ex, int options)
tag
- A trace tag: if an agent can't be found in scope this is ignoredmessage
- The message to logex
- If ex is not null, the stack dump is appended to the message.log(String, String)
,
CASAUtil.getAbstractProcessInScope()
public static String log(String tag, String message)
tag
- A trace tag: if an agent can't be found in scope this is ignoredmessage
- The message to loglog
,
CASAUtil.getAbstractProcessInScope()
public static String log(String tag, String message, int options)
tag
- A trace tag: if an agent can't be found in scope this is ignoredmessage
- The message to loglog
,
CASAUtil.getAbstractProcessInScope()
public static void captureSysout()
System.out
out and System.err
to log any program output to the process-wide trace
file. Prints messages to out and err to indicate these have been re-routed. The output is captured, but
is then copied to the original out and err streams, so there is no apparent effect (other than the output
is captured and logged).private void printToOriginalSysErr(String msg)
private void printToOriginalSysOut(String msg)
static void setProcessLogToFile(boolean b) throws IOException
b
- true to set tracing on.IOException
static File getProcessTraceFile()
public static void setTags(String tags)
tags
- setTraceTags(String)
public static String getTags()