test

Solaris WBEM Services Administrator's Guide

Chapter 5 System Logging

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:

About Logging

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).

Log Files

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:

Log File Rules

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:

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.

Log File Format

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:

Log Classes

Logging involves the use of two Solaris Schema classes: Solaris_LogRecord and Solaris_LogService.

Solaris_LogRecord Class

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.

Solaris_LogService Class

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:

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/.

Using the APIs to Enable Logging

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:

Writing Data to a Log File

Enabling an application to write data to a log file involves the following main tasks:

How to Create an Instance of Solaris_LogRecord To Write Data

  1. Import all the necessary Java classes. The classes listed in Example 5-1 are the minimum classes that are required.

    Example 5-1 Creating an Instance of Solaris_LogRecord To Write Data

    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.*;

  2. 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]);

  3. 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);

  4. Declare the new instance of the CIMObjectPath class for the log record.

    CIMObjectPath logreccop = new CIMObjectPath("Solaris_LogRecord", keys);

  5. 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();
	}

  6. Close the session after data has been written to the log file.

    // close session.
	if(cc != null) {
	    cc.close();
	}
    }
}

Reading Data From a Log File

Enabling an application to read data from a log file to a log viewer involves the following tasks:

How to Get an Instance of the Solaris_LogRecord Class and Read Data

  1. 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;

  2. 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);

  3. 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");

  4. Enumerate the instances of Solaris_LogRecord.

    Enumeration e = cc.enumInstances(cop, true);
    for (; e.hasMoreElements(); ) {

  5. 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("---------------------------------");

  6. Return an error message to the user if an error condition occurs.

    ...
	catch (Exception e) {
	    System.out.println("Exception: "+e);
		e.printStackTrace(); }
...

  7. Close the session when the data has been read from the file.

    // close session.
	if(cc != null) {
	    cc.close();
	}
}
}

Setting Logging Properties

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.

Example 5-2 Setting Logging Properties

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();
	}    
}

Viewing Log Data

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).

Starting Log Viewer

After you have created a log record, you can start the SMC and then its Log Viewer.

How to Start SMC and Log Viewer

  1. Change to the location of the SMC invocation command by typing the following:

    # cd /usr/sbin

  2. Start SMC by typing the following command:

    # smc

  3. 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.

  4. Click the Log Viewer icon to start the application.

Figure 5-1 Solaris Management Console, with Log Viewer Selected

Graphic