| Solstice Enterprise Manager 4.1 Developing C++ Applications |
|
Troubleshooting
Applications will not always behave as expected. Therefore, good testing and debugging practices are an essential part of any serious software engineering project. During the final stages of development, you need to find and correct all errors in your applications. Such errors typically result from logical errors or simple typing mistakes in the code. In addition, you need to make sure that changes to the environment in which your applications run do not cause your deployed applications to fail.
This chapter provides guidelines on how to troubleshoot errors specific to applications developed by using the Solstice EM C++ APIs.
- Section 15.1 Testing and Debugging Programs
- Section 15.2 Monitoring Communications With the MIS
- Section 15.3 Avoiding Common Problems
- Section 15.4 Example Troubleshooting Scenarios
15.1 Testing and Debugging Programs
The Solstice EM C++ development environment provides tools to help you test and debug your programs. Use these tools for:
- Verifying Guidelines for the Definition of Managed Objects (GDMO) and Abstract Syntax Notation One (ASN.1) syntax and logic
- Trapping errors in high-level Portable Management Interface (PMI) function calls
- Trapping programming logic errors
- Monitoring protocol translation by a management protocol adapter (MPA)
- Reloading GDMO documents
15.1.1 Verifying GDMO and ASN.1 Syntax and Logic
Verify that the GDMO and ASN.1 syntax and logic of your function calls are correct if your application fails to:
- Perform create, set, get, or delete operations
- Send an action request
To verify the GDMO and ASN.1 syntax and logic of your function calls, use the MIS Objects tool. The MIS Objects tool enables you to perform operations directly on managed objects in the management information tree (MIT). Use the MIS Objects tool to verify GDMO and ASN.1 syntaxes in your function calls by performing the operation your application is attempting. If you can perform the operation by using the MIS Objects tool, make sure that your program uses the same syntax and logic when it performs the same operation.
15.1.2 Trapping Errors in PMI Function Calls
The classes of the high-level Portable Management Interface (PMI) inherit error handling methods from the Error class. To detect the failure of a high-level PMI call, call the get_error_type function. The error type set by a failed call provides valuable information about what caused the failure.
Use the functions and operators inherited from the Error class to print a diagnostic message if a function call fails. Use the get_error_string function of the Error class to display information about the specific error. Printing other information, such as the name of the function that failed and the values of parameters passed to the function, also provides information useful in trapping errors in PMI function calls.
For more information, refer to Chapter 4.
15.1.3 Trapping Programming Logic Errors
Programming logic errors result when a program does not execute the correct code in response to an input. Programming logic errors frequently arise when runtime conditions are different from those envisaged when the application was designed.
To trap programming logic errors, trace the code that the application executes. Tracing the code that the application executes determines the exact point at which the program logic differs from the expected behavior, for example, an if statement is present where an else statement is required.
Trace the code that the application executes by using:
- Text output functions, such as cout or printf, of standard C++ libraries
- A standard debugging tool such as dbx or the GUI-based debugger embedded in the ForteTM (formerly Sun WorkShopTM) C or Forte C++ software
If you are using the Forte compilers and want to use a standard debugging tool, you must set the -g flag when you compile your programs.
15.1.4 Monitoring Protocol Translation by an MPA
An MPA performs protocol translation required for communication between the Solstice EM MIS and an external entity, such as an agent. Solstice EM provides MPAs for the following protocols:
- Simple Network Management Protocol (SNMP)
- Common Management Information Protocol (CMIP)
- Remote procedure call (RPC) protocol
To obtain detailed information about the protocol translation that the MPAs perform, run them in debug mode.
The MPAs of Solstice EM are started by the /etc/rc2.d/S98ipmpa script. To run the MPAs in debug mode, modify this script to specify a debug flag, then restart the MPAs. Modify the script to turn off debug mode when you no longer require information about the protocol translation that the MPAs perform.
- -debug - Shows SNMP, RPC, and CMIP translations
- -debug2 - Shows all translations specified by the -debug flag and shows user datagram protocol (UDP) packets
Note – Only the root user usually has write access to the /etc/rc2.d/S98ipmpa script. If you do not have write access to this script, ask your system administrator to give you write access to it.
To specify a debug flag, change the occurrence of $EXE_PATH/$1 in the else statement of the startmpa() function to read:
Where flag is -debug or -debug2.
The translation information from each MPA is written to the following files:
- /tmp/dbgout_em_mpa_snmp (for output from the SNMP MPA)
- /tmp/dbgout_em_mpa_rpc (for output from the RPC MPA)
To stop and restart the MPAs after you have edited the script, type the following commands as root:
15.1.5 Reloading GDMO Documents
During development, particularly during the early phases of development, the GDMO documents that describe your object model are likely to change. If a GDMO document that is already loaded into the metadata repository (MDR) changes, you need to reload the GDMO document into the MDR.
Reloading GDMO documents is rarely required for deployed applications. When equipment is added to your network, a GDMO document that describes the equipment is usually supplied with the equipment. All you need to do is load this document into the MDR.
When you load a GDMO document into the MDR, any version that already exists is not overwritten. To make your new version effective, you must remove the existing version before loading the new version.
You can remove a GDMO document by:
- Rebuilding the Solstice EM database. Rebuild the Solstice EM database only if you have no data in the Solstice EM database that you want to preserve.
- Removing a single compiled GDMO document. Remove a single compiled GDMO document if you want to preserve data in the Solstice EM database.
15.1.5.1 Removing a GDMO Document by Rebuilding the Solstice EM Database
Removing a GDMO document by rebuilding the Solstice EM database guarantees that your GDMO document is removed from the MDR, but the entire Solstice EM database is destroyed and rebuilt in the process. Rebuild the Solstice EM database only if you have no data in the Solstice EM database that you want to preserve.
To Remove a GDMO Document by Rebuilding the Solstice EM Database
1. Ensure that the uncompiled GDMO document file is not present in the /opt/SUNWconn/em/etc/gdmo directory.
- If necessary, delete the file from the /opt/SUNWconn/em/etc/gdmo directory. For example, to remove the satman.gdmo document file, type the following commands:
Note – If you want to modify a GDMO document instead of removing it, modify the uncompiled GDMO document file instead of deleting the file.
2. Type the command for rebuilding the Solstice EM database:
- When the em_services -reload command is run:
For more information on maintaining the MIS, refer to the Management Information Server (MIS) Guide.
15.1.5.2 Removing a Single Compiled GDMO Document
Removing a single compiled GDMO document preserves data in the remainder of the Solstice EM database, but requires more work than rebuilding the Solstice EM database. Remove a single compiled GDMO document if you have existing data in the Solstice EM database that you want to preserve.
Note – If you are using Solstice EM in an agent role and have set agent role behavior for Solstice EM, you must rebuild the Solstice EM database. You cannot remove a single compiled GDMO document. For information on how to set agent role behavior for Solstice EM, refer to Section 2.6.2 Setting Agent Role Behavior of Solstice EM.
To remove a single compiled GDMO document, locate the file that contains the compiled GDMO document on the MIS host and delete the file.
The name and location of the file that contains a compiled GDMO document depend on the options set when the document was loaded in to the MDR:
- If an output directory was specified, the file is located in the directory specified. The name of the file is the GDMO document name as specified in the MODULE construct of the GDMO document. Each space in the document name is replaced with an underscore. For example, a GDMO document named Satellite Manager would be compiled into a file named Satellite_Manager.
- If no output directory was specified, the file is located in the /var/opt/SUNWconn/em/data/MDR directory on the MIS host. The name of the file is assigned automatically by Solstice EM. The file name begins with the characters MA.
To locate a compiled GDMO document the name of which was automatically assigned, use the grep command to find all files the names of which start with the characters MA that contain the document name. For example, to remove the compiled Satellite Manager GDMO document, type the following commands:
After you have removed or replaced a compiled GDMO document, restart the MIS by typing em_services -start. This command restarts the MIS without rebuilding the Solstice EM database.
15.2 Monitoring Communications With the MIS
Monitoring communications with the management information server (MIS) enables you to verify if requests sent from your application and notifications emitted by managed objects reach the MIS. Monitoring communications with the MIS provides information on the content of:
- Messages the MIS receives
- Management requests your application sends to the MIS
- Responses sent by managed objects to management requests
- Notifications emitted by managed objects
To monitor communications with the MIS, use the em_debug utility. The em_debug utility connects to the debug port of the MIS and receives the debugging messages you specify when you start em_debug.
15.2.1 Starting em_debug
When you start em_debug, you can select the types of message you want to display, or exclude message types. When you exclude message types, all currently running em_debug sessions stop showing the excluded message types.
To start em_debug and select message types, type:
To start em_debug and exclude message types, type:
- hostname is the name of the host on which the MIS is running. If hostname is not specified, the local host is assumed.
- port is the debug port of the MIS. The default is 5556.
- messageType is the type of message that you want em_debug to display or exclude. Wildcard characters are permitted in messageType.
Commonly used em_debug message types are given in TABLE 15-1. For a complete list, see Section 15.2.3 Full List of em_debug Message Types.
Specify the wildcard character (*) if you want to specify several message types in the command to start em_debug. For example, to specify that em_debug displays all messages related to the OAM, type:
15.2.2 Interpreting em_debug Messages
Interpret em_debug messages to find the data related to your application and identify the information your application exchanges with the MIS.
The messages displayed by em_debug contain ASN.1 data encoded by using rules specified in ITU-T X.209/ISO-8825 Specification of Basic Encoding Rules for Abstract Syntax Notation One (ASN.1). Values that are encoded by using ASN.1 basic encoding rules have the following fields:
- Tag identifies the type of data that is contained in the Value field.
- Len indicates the number of octets used for the Value field.
- Value contains a data value of the type specified by the Tag field that has a length in bytes as specified by the Length field.
A tag is a combination of the class and the tag number. For example, a context-specific class that uses the value 7 for a specific meaning is displayed as C7. Application class tags are displayed as A1, A2, A3, etc. Private tags are displayed as P1, P2, P3, etc. Some of the Universal class tags are displayed by using text identifiers. For example, an object identifier (OID) tag is displayed as OID rather than as U6.
15.2.2.1 Classes of Tags
ASN.1 defines the following classes of tags:
- Universal class. Universal class tags are defined by the ASN.1 standards: ITU-T X.208/ISO-8824 Specification of Abstract Syntax Notation One (ASN.1) and ITU-T X.209/ISO-8825 Specification of Basic Encoding Rules for Abstract Syntax Notation One (ASN.1). Each universal class tag is assigned to a unique data type or is assigned to a data type that is used to construct new data types. Each tag number shown in TABLE 15-2 is a universal class tag.
- Application class. Application class tags are assigned to data types by other international standards. An application class tag is unique within a standard. An example of an application class tag is the IpAddress data type used for Internet network management applications, which is defined in an Internet request for comments (RFC).
- Context-specific class. Context-specific class tags are interpreted within the context in which they are used. They are normally used with constructed data types such as SET or SEQUENCE. In the case of SET or SEQUENCE, a context-specific tag only has meaning within the context of a previously defined SET or SEQUENCE.
- Private class. Private class tags are not assigned by international standards. Private class tags can be used by enterprises to define proprietary data types.
15.2.2.2 ASN.1 Data Types and Tag Numbers
A data type is a type of value, such as integer, real, or string. ASN.1 defines a number of data types and assigns a tag number to identify each of the data types. ASN.1 data types and tag numbers are shown in TABLE 15-2.
15.2.2.3 Tips For Reading em_debug Output
Note – In addition to the messages transmitted between applications and the MIS, em_debug displays messages that the MIS generates internally.
After you understand how to read em_debug output, search for output from your application and identify information that has been exchanged with the MIS.
Output from em_debug contains all communication with the MIS and some internally generated messages. If other applications are running, you will see messages from them in addition to messages from your application. You will have to sift through the messages to find what is relevant to you. With a little experience, you will learn how to focus on the messages for your application.
Each request is followed by a response. Whether you are debugging the request or the response from the MIS, start by searching for the request from your application. After you find the request, search for the next matching response if you need it.
For example, if you are debugging a failed create request, search through the em_debug output until you find a create request. Then check the managed object specified in the request to see if the create request you are looking at is the one your application sent.
After you find your create request, check the corresponding create response.
The example in Section 15.2.2.4 Example em_debug Output shows you how to read em_debug output.
15.2.2.4 Example em_debug Output
CODE EXAMPLE 15-1 shows an example of the output from em_debug. In this example, em_debug was started by typing
In the example in CODE EXAMPLE& nbsp;15-1, the following message indicates that an application has just started and connected to the MIS:
Several lines later in the em_debug output, the keyword oc = is followed by the OID of the managed object class specified in the create request as follows:
This OID is defined in the GDMO documents supplied with Solstice EM. It is the OID of the emApplicationInstance managed object class.
On the next line of the em_debug output, the keyword oi = is followed by the name of managed object instance specified in the create request as follows:
In this example, oi = NULL, indicating that the request is from a call to the create_within function of the Image class.
The keyword superior_oi = is followed by the name of the superior object specified in the create request. The superior object is identified by the local distinguished name subSystemId="EM-MIS". The MIS assigns the relative distinguished name of the new object automatically.
The keyword attr_list = is followed by each attribute that is set in the create request and the value it is set to as follows:
The OIDs of the attributes are defined in the GDMO documents supplied with Solstice EM. These OIDs are as follows:
- 1.3.6.1.4.1.42.2.2.2.1.7.1 is the OID of the emApplicationID attribute.
- 1.3.6.1.4.1.42.2.2.2.1.7.2 is the OID of the emApplicationType attribute.
The emApplicationID attribute is set to the INTEGER value 22. The emApplicationType attribute is set to the GraphicString "Object Editor".
15.2.3 Full List of em_debug Message Types
The full list of em_debug message types is given in TABLE 15-1.
TABLE 15-3 em_debug Message Types Access control ac_init_debug access_debug access_error ace_debug ace_error ace_init_error audit_trail emDbInfo_debug emDbInfo_info emDbObject_debug emDbObject_info security_alarm Action messages actmsg_debug Alarm services alarmsvc_debug alarmsvc_error Annotation secretary anno_debug anno_error anno_info ASN.1 asn_debug asn_error asn_info asn_trace Backing store bs_error bsblob_error CMIP cmip_debug cmip_error cmip_info cmip_trace Connection manager connectMgr_error connectMgr_impl connectMgr_info Debugging port dbgport_error dbgport_trace Distributed alarm log manager dalarm_debug dalarm_impl Distributed transaction processing XA_error XA_info XA_xactimpl_info xactimpl_error Discriminators discrim_info Event management module emm_debug emm_error emm_info emm_stat_info emm_trace sieve_stat_info sv_debug sv_error sv_info Exceptions exception_info Filtering filt_debug filt_error filt_info Geographical maps map_debug map_error map_trace High-level PMI hi_debug hi_error hi_info hi_trace Initialization init_debug init_error Log management evr2oc_error evr2oc_info log_error log_info Message routing module mrm_debug mrm_error mrm_info mrm_trace MDR mdr_debug mdr_error mdr_info mdr_trace Nerve Center interface nc_deb nc_error nc_event nc_miniger_debug nc_miniger_error nc_mosi_debug nc_mosi_error nc_mosi_trace nc_poll nc_poll_debug nc_poll_error nc_poll_info nc_state ncam_if_debug nce_at_debug nce_at_error nce_at_info nce_debug nce_error nce_info nce_poll_debug nce_poll_error nce_poll_info nce_poll_trace nce_snmp_error nce_trace mi_info minigreg_debug minigreg_error minigreg_info mosireg_error pm_deb pm_error pm_trace rcl_debug OAM oam_debug oam_error oam_info oam_trace oammsg_debug oamnot_debug oamrmt_debug oamsvc_error oamsvc_info swap_debug Object collections coll_debug coll_error coll_trace Scheduler sched_debug sched_error sched_info Shutdown manager shutdown_debug Topology topo_debug topo_error topo_info topo_trace
15.3 Avoiding Common Problems
Avoid some of the most common problems encountered with custom Solstice EM applications by:
- Verifying attribute and class names
- Creating automatically named managed object instances appropriately
- Testing that scopes and filters are supported
15.3.1 Verifying Attribute and Class Names
Whenever the MIS responds with an error message of the type Unknown object class or Unknown attribute, verify that the attribute or managed object class name in your application code matches exactly the name in the GDMO document.
All GDMO identifiers, including managed object class names and attribute names, are case-sensitive. Therefore, the case and the spelling of an attribute or managed object class name in your application code must match exactly the name in its GDMO document. A common mistake is to specify the systemId attribute (note the lower case d) as systemID.
If the MIS still responds with an error after you have verified an attribute or class name, verify that the correct version of the GDMO document is loaded into the MDR. For more information, refer to Section15.1.5 Reloading GDMO Documents.
15.3.2 Creating Automatically Named Managed Object Instances Appropriately
If you want to create an automatically named managed object, you must call the create_within function of the Image class. An attempt to create an automatically named managed object by calling the create function of the Image class fails.
Check the name binding between a managed object class and its superior managed object class to determine if instances of the class are automatically named. The name binding is part of the GDMO specification of a managed object. If the name binding specifies CREATE WITH-AUTOMATIC-INSTANCE-NAMING, instances of the managed object class are automatically named. For example, instances of the topoNode and logRecord managed object classes are automatically named.
For information on name bindings, refer to Section 2.2.6.1 Name Bindings.
15.3.3 Testing That Scopes and Filters are Supported
Some MPAs and agents may not fully support scopes and filters. Find out whether the agents your application will manage support scopes and filters before implementing them in your management application.
To test if an MPA or agent supports scopes and filters, write a simple application that sends management requests with scopes and filters. If the requests fail, verify that the failure is not due to an error in your application. If the failure is not due to an error in your application, the agent or MPA does not support scopes or filters.
If your application will be used with an MPA or agent that does not support scopes or filters, select managed objects by performing multiple derivations. In these derivations, avoid specifying scopes or filters to select objects that are accessed via an agent or MPA that does not support scopes or filters.
For information on how to select managed objects by derivation, refer to Section 6.3.1 Defining the Membership by Derivation.
The code in CODE EXAMPLE 15-2 shows how to work with an MPA that does not support filters. In this example, a filtered request for satellite and channel object instances will fail. Instead, an Album instance is created that contains all instances of the satellite class and their contained channel instances. An instance of the AlbumImage class is then created to obtain each channel instance.
CODE EXAMPLE 15-2 Replacing a Scope and a Filter With Multiple Derivations
{satellites = Album("collection of all satellites");if (!satellites.set_prop(duTRACKMODE, duTRACK)) {if (!satellites.set_prop(duAUTOIMAGE, duYES)) {derive_str += "/CMISFilter(item:equality:{objectClass,satellite})";if (!satellites.set_derivation((char *) derive_str.data())) {if (!satellites.derive()) {{channels = Album("collection of all channels");if (!channels.set_prop(duTRACKMODE, duTRACK)) {if (!channels.set_prop(duAUTOIMAGE, duYES)) {for (ai = satellites.first_image(); ai; ai = ai.next_image()) {Album tmpch = Album("temporary holder for channels");if (im.get_error_type() != PMI_SUCCESS) {if (!tmpch.set_derivation((char *) derive_str.data())) {if (!tmpch.derive(300)) {15.4 Example Troubleshooting Scenarios
This section explains how to apply troubleshooting techniques described in this chapter to the following scenarios:
- Failure to set an attribute value
- Failure to process event notifications
15.4.1 Failure to Set an Attribute Value
If an application attempts but fails to set an attribute value, debug the application by:
- Verifying GDMO and ASN.1 specifications
- Trapping errors in high-level PMI function calls
- Trapping programming logic errors
- Monitoring communications with the MIS
15.4.1.1 Verifying GDMO and ASN.1 Specifications
To verify that your application code is consistent with the GDMO and ASN.1 specifications of your object model:
- Verify that the case and the spelling of the attribute or managed object class name in your application code matches exactly the name in its GDMO specification.
- Check the managed object class definition to ensure that the managed object class you specified includes the attribute that you want to set.
- Verify that the attribute that you want to set is settable. Specifically, the property list in the ATTRIBUTES construct of the attribute's GDMO specification must include the operation you want to perform when setting the attribute. For more information, refer to Section C.4 Package Template.
- Use the MIS Objects tool to set the attribute. If you succeed, make sure your application code matches the attributes you used in the MIS Objects tool.
15.4.1.2 Trapping Errors in High-Level PMI Function Calls
To trap errors in high-level PMI function calls:
- Use the overloaded not (!) operator on high-level PMI function calls before the attempt to set the attribute to verify that those calls succeeded.
- Call the get_error_string function of the Image class after the attempt to set the attribute. The error string returned may provide valuable information on the cause of the problem.
For more information on handling errors in high-level PMI function calls, refer to Chapter 4.
15.4.1.3 Trapping Programming Logic Errors
To verify that the program is executing the code that you expect it to execute:
- Set the -g flag when you compile the code, then run a debugger and step through the code one line at a time.
- Add print statements to verify that the program calls the function to set the attribute. You may find, for example, that the function is inside an if statement that is never called.
15.4.1.4 Monitoring Communications With the MIS
To verify that the MIS receives the set request and sends a successful response:
- Run em_debug, specifying "on oam*" to print all object access messages that are sent to the MIS.
- Check the debug output for the set request. It is possible that the MIS never receives the request.
- Check the debug output for a response to the set request. The response may contain more useful information about why the request failed.
15.4.2 Failure to Process Notifications
If an application has registered to receive a type of event notification, but appears not to be acting on event notifications of that type, debug the application by:
- Verifying GDMO and ASN.1 specifications
- Trapping errors in high-level PMI function calls
- Trapping programming logic errors
- Monitoring communications with the MIS
15.4.2.1 Verifying GDMO and ASN.1 Specifications
To verify that your application code is consistent with the GDMO and ASN.1 specifications of your object model:
- Verify that the case and the spelling of the event type in your application code matches exactly the event type in its GDMO specification.
- Use the MIS Objects tool and watch the status line for event notifications of the type your application has registered to receive.
15.4.2.2 Trapping Errors in High-Level PMI Function Calls
To trap errors in high-level PMI function calls:
- Use the overloaded not (!) operator on high-level PMI function calls before the registration of the callback for the event type to verify that those calls succeeded.
- Verify that you are not excluding the event type in your application discriminator.
- Use the MIS Objects tool to check the subsystemId="EM-MIS"/emApplicationID=
and check the value for the discriminator attribute.yourApplicationId For more information on handling errors in high-level PMI function calls, refer to Chapter 4.
15.4.2.3 Trapping Programming Logic Errors
To verify that the program is executing the code that you expect it to execute:
- Verify that you have registered the correct callback function for the event type you want to handle.
- Add print statements to verify if your callbacks have been called.
- Set the -g flag when you compile the code, then run a debugger. Set breakpoints in the callback functions and check that the breakpoints are reached.
15.4.2.4 Monitoring Communication With the MIS
To verify that event notifications that your application has registered to receive are reaching the MIS:
- Run em_debug, specifying "on not*" to print out all notifications that are sent to the MIS.
- Check the em_debug output for event notifications of the type your application has registered to receive. It is possible that the event notifications of the type are never sent to the MIS.
- If the source of the event notification is an SNMP agent, turn on SNMP debugging, and monitor that trace to verify that the event notification was received by the SNMP MPA.
|
Sun Microsystems, Inc. Copyright information. All rights reserved. |
Doc Set | Contents | Previous | Next | Index |