Logging is a service that enables WBEM administrators to track system events to determine how they occurred. You might want to record events such as the inaccessibility of a serial port, an error message generated by the mounting of a file system, or a system disk having reached capacity.
This chapter covers the following topics:
The logging service records all actions that the service provider has been programmed to return and that are completed by Solaris WBEM Services components. Informational content and errors can be recorded to a log. For example, if a user disables a serial port, this information can be logged automatically by a serial port provider. Or, if a system error or other failure occurs, the administrator can check the log record to trace the cause of the occurrence.
All components, applications, and providers start logging automatically, in response to system events. For example, the CIM Object Manager automatically logs events after it is installed and started.
You can set up logging for applications and providers that you write for the WBEM environment. For information, see "Using the APIs to Enable Logging". You can view log data in the Solaris Management Console (SMC) Log Viewer to debug the logging functionality that you have set up. For more information on the SMC, see the man page smc(1M).
When you set up an application or a provider to log events, its events are recorded in log files. All log records are stored in the path: /var/sadm/wbem/logr. Log files use the following naming convention:
wbem_log.#
where # is a number appended to indicate the version of the log file. A log file appended with a .1, such as wbem_log.1, is the most recently saved version. A log file appended with a .2 is the next oldest version. Larger file extensions, for example, wbem_log.16, indicate older versions of the file. Previous versions of the log file and the most recent version co-exist as an archive in /usr/sadm/wbem/log.
Log files are saved and renamed with a .1 filename extension when one of the following two conditions are met:
The current file reaches the file size limit specified by the Solaris_LogServiceProperties class. Default values are set in the /usr/sadm/lib/wbem/WbemServices.properties file.
For information about how the properties of the Solaris_LogServiceProperties class control how a log file is used, see "Log File Rules".
The clearLog() method of the Solaris_LogService class is invoked on the current log file.
For information about the Solaris_LogService class and its methods, see "Solaris_LogService Class".
The Solaris_LogServiceProperties class is defined in Solaris_Core1.0.mof. The Solaris_LogServiceProperties class has properties that control the following attributes of a log file:
Directory where the log file is written
Name of the log file
Size allowed for a log file before it is saved and renamed with a .1 file extension.
Number of log files you can have in the archive
Ability to write log data to syslog
,
the default logging system of the Solaris operating environment
To specify any of these attributes for an application that writes data to a log file, create a new instance of Solaris_LogServiceProperties and set the values of its associated properties. See Example 5-2 for detailed information about how to set the property values of the new instance.
The logging service provides three categories of log records: application, system, and security. Log records may be informational, or may record data derived from errors or warnings. A standard set of fields are defined for the data that can be presented in logs. Logs do not necessarily use all the fields, however. For example, an informational log may provide a brief message describing an event. An error log may provide a more detailed message.
Some log data fields are required to identify data in the CIM Repository. These fields are properties flagged with a read-only key qualifier in the Solaris_LogRecord class. You cannot set the values of these fields. You can, however, set the values of any of the following fields in your log files:
Category - Type of log record
Severity - Severity of conditions that caused data to be written to a log file
AppName - Name of the application from which the data was obtained
UserName - Name of the individual who was using the application when log data was generated
ClientMachineName - Name of the computer on which an incident occurred that generated log data
ServerMachineName - Name of the server on which an incident occurred that generated log data
SummaryMessage - Brief message describing the occurrence
DetailedMessage - Detailed message describing the occurrence
Data - Context information that applications and providers can present to interpret a log message
Logging involves the use of two Solaris Schema classes: Solaris_LogRecord and Solaris_LogService.
The Solaris_LogRecord class is defined in Solaris_Core1.0.mof to model an entry in a log file. When an application or provider calls the Solaris_LogRecord class in response to an event, the Solaris_LogRecord class causes all data generated by the event to be written to a log file. To see the definition of the Solaris_LogRecord class as part of the Solaris Provider, use a text editor to view the Solaris_Core1.0.mof file. The Solaris_Core1.0.mof file is located in /usr/sadm/mof/.
The Solaris_LogRecord class uses a vector of properties and key qualifiers to specify attributes of the events, system, user, and application or provider that generate data. Read-only qualifier values are generated transparently for use between the application and the CIM Repository. For example, the value RecordID uniquely identifies the log entry but is not displayed as part of the log format when you view generated data.
You can set the values of writable qualifier values. For example, you can set the qualifier values of properties such as ClientMachineName and ServerMachineName, which identify the system on which an event occurs.
When the SysLogFlag property is set to true, then
a detailed message of the log record is automatically sent to the syslog
daemon on Solaris systems.
The Solaris_LogService class controls the operation of the logging service and defines the ways in which log data is handled. This class has a set of methods that an application can use to distribute data about a particular event to the CIM Object Manager from the issuing application. The data becomes a trigger that generates a response from the CIM Object Manager, such as a retrieval of data from the CIM Repository.
The Solaris_LogService class has the following methods:
clearLog - Saves and renames a current log file or deletes a saved log file
getNumRecords - Returns the number of records in a particular log file
listLogFiles - Returns a list of all log files stored in /usr/sadm/wbem/log
getCurrentLogFileName - Returns the name of the most recent log file
getNumLogFiles - Returns the number of log files stored in /usr/sadm/wbem/log
getLogFileSize - Returns the size, in megabytes, of a particular log file
getSyslogSwitch - Enables log
data to be sent to syslog
, the logging service
of the Solaris operating environment
getLogStorageName - Returns the name of the host computer or device where log files are stored
getLogFileDir - Returns the path and name of the directory where log files are stored
The Solaris_LogServiceProperties class lets you set logging properties. See "Setting Logging Properties".
You can view the definition of the Solaris_LogService class in the Solaris_Core1.0.mof file, which is located in /usr/sadm/mof/.
You can view log file contents in the Solaris Management Console (SMC) Log Viewer. For more information on the Solaris Management Console, see the man page smc(1M).
You can also develop your own log viewer if you prefer to view log files in a customized manner. You can use the WBEM logging APIs to develop a logging program which will:
Write data from an application to a log file
Read data from a log file to your log viewer
Set logging properties that specify how logging is handled
Enabling an application to write data to a log file involves the following main tasks:
Creating a new instance of the Solaris_LogRecord class
Specifying the properties that will be written to the log file and setting values for the property qualifiers
Setting the new instance and properties to print
Import all the necessary Java classes. The classes listed in Example 5-1 are the minimum classes that are required.
import java.rmi.*; import com.sun.wbem.client.CIMClient; import com.sun.wbem.cim.CIMInstance; import com.sun.wbem.cim.CIMValue; import com.sun.wbem.cim.CIMProperty; import com.sun.wbem.cim.CIMNameSpace; import com.sun.wbem.cim.CIMObjectPath; import com.sun.wbem.cim.CIMClass; import com.sun.wbem.cim.CIMException; import com.sun.wbem.solarisprovider.*; import java.util.*; |
Declare the public class CreateLog and the following values:
CIMClient instance
CIMObjectPath instance
CIMNameSpace instance
public class CreateLog { public static void main(String args[]) throws CIMException { if ( args.length != 3) { System.out.println("Usage: CreateLog host username password"); System.exit(1); } CIMClient cc = null; CIMObjectPath cop = null; try { CIMNameSpace cns = new CIMNameSpace(args[0]); cc = new CIMClient(cns, args[1], args[2]); |
Specify the vector of properties to be returned. Set values for the properties of the qualifiers.
Vector keys = new Vector(); CIMProperty logsvcKey; logsvcKey = new CIMProperty("category"); logsvcKey.setValue(new CIMValue(new Integer(2))); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("severity"); logsvcKey.setValue(new CIMValue(new Integer(2))); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("AppName"); logsvcKey.setValue(new CIMValue("SomeApp")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("UserName"); logsvcKey.setValue(new CIMValue("molly")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("ClientMachineName"); logsvcKey.setValue(new CIMValue("dragonfly")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("ServerMachineName"); logsvcKey.setValue(new CIMValue("spider")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("SummaryMessage"); logsvcKey.setValue(new CIMValue("brief_description")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("DetailedMessage"); logsvcKey.setValue(new CIMValue("detailed_description")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("data"); logsvcKey.setValue(new CIMValue("0xfe 0x45 0xae 0xda")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("SyslogFlag"); logsvcKey.setValue(new CIMValue(new Boolean(true))); keys.addElement(logsvcKey); |
Declare the new instance of the CIMObjectPath class for the log record.
CIMObjectPath logreccop = new CIMObjectPath("Solaris_LogRecord", keys);
Declare the new instance of Solaris_LogRecord. Set the vector of properties to write to a file.
CIMInstance ci = new CIMInstance(); ci.setClassName("Solaris_LogRecord"); ci.setProperties(keys); //System.out.println(ci.toString()); cc.setInstance(logreccop,ci); } catch (Exception e) { System.out.println("Exception: "+e); e.printStackTrace(); } |
Close the session after data has been written to the log file.
// close session. if(cc != null) { cc.close(); } } } |
Enabling an application to read data from a log file to a log viewer involves the following tasks:
Enumerating instances of the Solaris_LogRecord class
Getting the desired instance
Printing properties of the instance to an output device, typically a user interface for the log viewer
Import all the necessary Java classes. The classes listed below are the minimum required.
import java.rmi.*; import com.sun.wbem.client.CIMClient; import com.sun.wbem.cim.CIMInstance; import com.sun.wbem.cim.CIMValue; import com.sun.wbem.cim.CIMProperty; import com.sun.wbem.cim.CIMNameSpace; import com.sun.wbem.cim.CIMObjectPath; import com.sun.wbem.cim.CIMClass; import com.sun.wbem.cim.CIMException; import com.sun.wbem.solarisprovider.*; import java.util.*; import java.util.Enumeration; |
Declare the class ReadLog.
public class ReadLog { public static void main(String args[]) throws CIMException { if ( args.length != 3) { System.out.println("Usage: ReadLog host username password"); System.exit(1); |
Set the CIMClient, CIMObjectPath, and CIMNameSpace values of the ReadLog class.
} CIMClient cc = null; CIMObjectPath cop = null; try { CIMNameSpace cns = new CIMNameSpace(args[0]); cc = new CIMClient(cns, args[1], args[2]); cop = new CIMObjectPath("Solaris_LogRecord"); |
Enumerate the instances of Solaris_LogRecord.
Enumeration e = cc.enumInstances(cop, true); for (; e.hasMoreElements(); ) { |
Send the property values to an output device.
System.out.println("---------------------------------"); CIMObjectPath op = (CIMObjectPath)e.nextElement(); CIMInstance ci = cc.getInstance(op); System.out.println("Record ID : " + (((Long)ci.getProperty("RecordID").getValue(). getValue()).longValue())); System.out.println("Log filename : " + ((String)ci.getProperty("FileName").getValue(). getValue())); int categ = (((Integer)ci.getProperty("category"). getValue().getValue()).intValue()); if (categ == 0) System.out.println("Category : Application Log"); else if (categ == 1) System.out.println("Category : Security Log"); else if (categ == 2) System.out.println("Category : System Log"); int severity = (((Integer)ci.getProperty ("severity").getValue().getValue()).intValue()); if (severity == 0) System.out.println("Severity : Informational"); else if (severity == 1) System.out.println("Severity : Warning Log!"); else if (severity == 2) System.out.println("Severity : Error!!"); System.out.println("Log Record written by :" + ((String)ci.getProperty("AppName").getValue(). getValue())); System.out.println("User : " + ((String)ci. getProperty("UserName").getValue().getValue())); System.out.println("Client Machine : " + ((String)ci. getProperty("ClientMachineName").getValue().getValue())); System.out.println("Server Machine : " + ((String)ci. getProperty("ServerMachineName").getValue().getValue())); System.out.println("Summary Message : " + ((String) ci.getProperty("SummaryMessage").getValue().getValue())); System.out.println("Detailed Message : " + ((String) ci.getProperty("DetailedMessage").getValue().getValue())); System.out.println("Additional data : " + ((String) ci.getProperty("data").getValue().getValue())); boolean syslogflag =((Boolean)ci.getProperty("syslogflag").getValue(). getValue()).booleanValue(); if (syslogflag == true) { System.out.println("Record was written to syslog as well"); } else { System.out.println("Record was not written to syslog"); } System.out.println("---------------------------------"); |
Return an error message to the user if an error condition occurs.
... catch (Exception e) { System.out.println("Exception: "+e); e.printStackTrace(); } ... |
Close the session when the data has been read from the file.
// close session. if(cc != null) { cc.close(); } } } |
You can create an instance of the Solaris_LogServiceProperties class and set property values for the instance to control how your application or provider handles logging. The following code example shows how to set logging properties. Properties are stored in the /usr/sadm/lib/wbem/WbemServices.properties file.
public class SetProps { public static void main(String args[]) throws CIMException { if ( args.length != 3) { System.out.println("Usage: SetProps host username password"); System.exit(1); } CIMClient cc = null; try { CIMNameSpace cns = new CIMNameSpace(args[0]); cc = new CIMClient(cns, args[1], args[2]); CIMObjectPath logpropcop = new CIMObjectPath("Solaris_Log ServiceProperties"); Enumeration e = cc.enumInstances(logpropcop, true); for (; e.hasMoreElements(); ) { CIMObjectPath op = (CIMObjectPath)e.nextElement(); CIMInstance ci = cc.getInstance(op); ci.setProperty("Directory", new CIMValue("/tmp/bar1/")); ci.setProperty("FileSize", new CIMValue("10")); ci.setProperty("NumFiles", new CIMValue("2")); ci.setProperty("SyslogSwitch", new CIMValue("off")); cc.setInstance(logpropcop,ci); } } catch (Exception e) { System.out.println("Exception: "+e); e.printStackTrace(); } // close session. if(cc != null) { cc.close(); } } |
You can view all details of a log record in the Solaris Management Console (SMC) Log Viewer, an application that provides a graphical user interface for viewing recorded data. For more information on the SMC, see the man page smc(1M).
After you have created a log record, you can start the SMC and then its Log Viewer.
Change to the location of the SMC invocation command by typing the following:
# cd /usr/sbin
Start SMC by typing the following command:
# smc
In the Navigation panel, double-click This Computer (or single-click the expand/compress icon next to it) to expand the tree beneath it. Double-click System Status and the Log Viewer icon will be displayed.
Click the Log Viewer icon to start the application.