test

WBEMfor Solaris on Sun Developer's Guide

Chapter 13 Logging Events

Logging is a service that enables WBEM administrators to track uncommon events to determine how they occurred. This chapter covers the following topics:

About Logging

The logging service records all actions completed by Solaris WBEM Services or Sun WBEM SDK components. Informational and error content 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 WBEM administrator can check the log record to trace the cause of the occurrence.

All Sun WBEM SDK and Solaris WBEM Services components, applications, and providers start logging automatically, in response to events. For example, the CIM Object Manager automatically logs events after is installed and started.

You can set up logging for applications and providers that you develop for the WBEM environment. For information, see "Using the APIs to Enable Logging". You can also view log data in CIM WorkShop for administration purposes or to debug the logging functionality that you develop for applications.

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/opt/SUNWconn/wbem/log/. 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 /var/opt/SUNWconn/wbem/log.

Log files are renamed with a .1 file extension, saved, and archived 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:

When you want to specify any of these attributes for an application that writes data to a log file, you create a new instance of Solaris_LogServiceProperties and set the values of its associated properties.

Log File Format

The logging service provides three general types of log files: application logs, system logs, and security logs. 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; however, logs do not necessarily use all fields. 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 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 set the values of any of the following fields in your log files:

Log Classes

Logging uses two Solaris Schema classes: Solaris_LogRecord and Solaris_LogService.

Solaris_LogRecord

Solaris_LogRecord 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, view the Solaris_Core1.0.mof file in a text editor of your choice. The Solaris_Core1.0.mof file is located in /opt/SUNWconn/wbem/schema.

Solaris_LogRecord 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 writeable 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.

Solaris_LogService

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 uses the following methods:

You can view the definition of Solaris_LogService in the Solaris_Core1.0.mof file by opening the file in a text editor of your choice. The Solaris_Core1.0.mof file is located in /opt/SUNWconn/wbem/schema.

Viewing Log Data

If your application has been enabled to log data in response to events, you can view the generated data in CIM Workshop.

How to View Log Data

  1. In CIM Workshop, select solaris_logrecord in the class inheritance tree.

  2. Click Action->Instances.

  3. In the left side of the Instances for Solaris_LogRecord window, click the instance that was generated by your application.

    In the right side of the Instances for Solaris_LogRecord window, the fields of the log file are displayed as properties. Values for each property are provided in the Values column.

Using the APIs to Enable Logging

Currently, you can view log file content in CIM Workshop. However, you can develop your own log viewer if you prefer to view log files in a customized manner. You can use the logging application programming interfaces (APIs) to develop a log viewer. The APIs enable you to write data from an application to a log file or read data from a log file to your log viewer.

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 necessary java.rmi classes.

    Example 13-1 Importing Classes

    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 public class CreateLog and the following values:

    • CIMClient value

    • CIMObjectPath value

    • CIMNameSpace value

    Example 13-2 Declaring the CreateLog Class and Values

    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.

    Example 13-3 Specifying the Vector of Properties and their Values

    Vector keys = new Vector();  		
CIMProperty logsvcKey = new CIMProperty("RecordID"); 		
logsvcKey.setValue(new CIMValue(new Integer(0))); 		
keys.addElement(logsvcKey); 		
logsvcKey = new CIMProperty("RecordHashCode"); 		
logsvcKey.setValue(new CIMValue(new Integer(0))); 		
keys.addElement(logsvcKey); 		
logsvcKey = new CIMProperty("Filename"); 		
logsvcKey.setValue(new CIMValue("some_file")); 		
keys.addElement(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 CIMObject Path for the log record.

    Example 13-4 Declaring the New Instance of CIMObjectPath

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

  5. Declare the new instance of Solaris_LogRecord. Set vector of properties to write to a file.

    Example 13-5 Setting the Instance and Properties

    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.

    Example 13-6 Closing the Session

    	// 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 Solaris_LogRecord and Read Data

  1. Import all necessary java.rmi classes.

    Example 13-7 Importing Classes

    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.

    Example 13-8 Declaring the ReadLog Class

    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 client, object path, and namespace values of the ReadLog class.

    Example 13-9 

    	} 	
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 instances of Solaris_LogRecord.

    Example 13-10 Enumerating Instances

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

  5. Send property values to an output device.

    Example 13-11 Sending Property Values

    	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.

    Example 13-12 Returning an Error Message

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

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

    Example 13-13 Closing the Session

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