7.7.12 Troubleshooting in a system that uses file event linkage

This section describes the types of information that can be collected for failures that occur in a system that uses file event linkage. The following types of failure information are related to file event linkage:

Snapshot log
Message log
Method trace
Performance analysis trace
File event trace

The following describes the preceding types of failure information.

Organization of this subsection

(1) Snapshot log
(2) Message log
(3) Method trace
(4) Performance analysis trace
(5) File event trace

(1) Snapshot log

To include the file event reception in the targets of information collection by the mngsvrutil and snapshotlog commands, you might need to modify the file that defines the targets for collection of snapshot log data.

To collect log data at the same logging level as the other receptions of the service platform, add entries as shown in the following paragraphs. You do not need to add these entries if they have already been included in the relevant files.

(a) snapshotlog.conf

${cosminexus.home}/CSC/custom-reception/fileevent/config/.+
${cosminexus.home}/CSC/custom-reception/fileevent/config/common/.+

(b) snapshotlog2.conf

${cosminexus.home}/CC/server/public/ejb/.+/logs/csc/rcp/fileevent/.+/fileeventtrace_.*\.log
&{ejb.public.directory}/ejb/.+/logs/csc/rcp/fileevent/.+/fileeventtrace_.*\.log
&{ejb.server.log.directory}/csc/rcp/fileevent/.+/fileeventtrace_.*\.log

(c) snapshotlog.param.conf

${cosminexus.home}/CSC/custom-reception/fileevent/config/.+
${cosminexus.home}/CSC/custom-reception/fileevent/config/common/.+

To Page Top

(2) Message log

For failures that occur during operation using the file event linkage functionality, messages are output to message logs. The log data that is output to the message log for the file event reception is the message log data that is output by the service platform and is related to J2EE server operations.

The error messages that are output for the file event linkage functionality include the following:

KDEC00459-E: This error message is output to the message log if an exception occurs at the start of the file monitoring function. At this time, the HCSC server start command ends due to an error.
KDEC00455-E: Startup of the file event reception fails if false is set for the fileevent-reception.monitored-file.enabled property in the HCSC server runtime definition file. When this failure occurs, this error message is output to the message log.
KDEC00458-E: Startup of the file event reception fails if the common folder defined in the file-event-reception definition file is not defined in the HCSC server runtime definition file. When this failure occurs, this error message is output to the message log.

For details about the messages that are output, see 2.1 Messages from KDEC00001 to KDEC19999 in the manual Service Platform Messages. For details about the output items and output destination of message log data, see 7.4.1(3) Activity log of J2EE server.

(a) If a fault response message is returned to the file event reception

This section describes troubleshooting when a fault response message is returned to the file event reception. For the error notification method used in this case, see the description of the case where an error is returned by a service component about a user-defined exception in the following section: A.7 Method of notifying error in custom reception in the Service Platform Reception and Adapter Definition Guide.

If a fault response message is returned to the file event reception, take action according to the message that is output, and then take action for the monitoring-target files as described in the following table:

Monitoring-target file	Action
Update completion notification file	If the file to be acquired remains: Use the file transfer and data linkage software to re-create the update completion notification file. If the file to be acquired does not remain: Use the file transfer and data linkage software to re-perform a transfer of the file to be acquired and the subsequent processing.
File to be acquired	Use the following procedure to take action: Check whether the file to be acquired that is renamed remains. If the file remains, use file event traces to confirm that processing for the file has already ended, and then delete the file. Use the file transfer and data linkage software to re-create the file to be acquired.

Monitoring-target file

Action

Update completion notification file

If the file to be acquired remains:: Use the file transfer and data linkage software to re-create the update completion notification file.
If the file to be acquired does not remain:: Use the file transfer and data linkage software to re-perform a transfer of the file to be acquired and the subsequent processing.

File to be acquired

Use the following procedure to take action:

Check whether the file to be acquired that is renamed remains.

If the file remains, use file event traces to confirm that processing for the file has already ended, and then delete the file.
Use the file transfer and data linkage software to re-create the file to be acquired.

(b) If an error is returned by the custom reception framework

This section describes troubleshooting when an error is returned by the custom reception framework. For the error notification method used in this case, see the description of the case where an error is returned by the HCSC server in the following section: A.7 Method of notifying error in custom reception in the Service Platform Reception and Adapter Definition Guide.

If an error is returned by the custom reception framework, take action according to the message that is output, and then take action for the monitoring-target files as described in the following table:

Error location	Condition	Monitoring-target file
Error location	Condition	Update completion notification file	File to be acquired
File event reception or HCSC message delivery control	None	Use the file transfer and data linkage software to re-create the monitoring-target file (update completion notification file or file to be acquired).
Other locations	If the following conditions are met: An execution history of business processes has been collected. The process instance is re-executable.	Re-execute the process instance. If the file to be acquired does not remain although the file is used during re-execution, use the file transfer and data linkage software to re-perform a transfer of the file to be acquired and the subsequent processing.	Re-execute the process instance.
Other locations	If the preceding conditions are not met:	Use the file transfer and data linkage software to perform the following task: If the file to be acquired remains: Re-create the update completion notification file. If the file to be acquired does not remain: Re-perform a transfer of the file to be acquired and the subsequent processing.	Use the file transfer and data linkage software to re-perform a transfer of the file to be acquired and the subsequent processing.

(c) If an error is detected by the file event reception

The file event reception can detect the following errors:

Non-existence of the file to be acquired
Failure in creating a lock file
Failure in obtaining a lock with the lock file
Failure in releasing a lock with the lock file
Failure in renaming the monitoring-target file (update completion notification file or file to be acquired)

If an error is detected, check whether a file event trace from the collection point IN has been output. If you know whether this trace has been output, you will be able to guess a rough error location and take specific action as shown in the following table.

Table 7‒124: Failure location and action
Has a trace from collection point IN been output?	Failure location	Action
Yes	After the business process was invoked	See the relevant error message that has been output to the message log and determine whether some action must be taken.
No	Before the business process was invoked	Take action according to the relevant message that has been output to the message log, and then take action as follows: If the monitoring-target file has been renamed Use the file transfer and data linkage software to re-create the monitoring-target file.^# When the re-created file is detected at the next file monitoring interval, the file event reception is invoked. If the monitoring-target file has not been renamed You do not need to take action because this file is detected at the next file monitoring interval.

#: If the file to be acquired is the monitoring-target file, you must delete the file before you re-create it. Use the file event traces to check whether processing for the file has already ended. After you have confirmed that processing for the file has already ended, delete it.

To Page Top

(3) Method trace

The method traces for file event linkage conform to the specifications of the method traces that are output by the service platform.

For details about the output items and output destination for method traces, see 7.4.7(3) Method trace.

To Page Top

(4) Performance analysis trace

The performance analysis traces for the file event linkage functionality can be used to analyze performance bottlenecks. These traces can be used to check the following:

Processing of the file monitoring function
Processing of the file event reception function

Before you can collect performance analysis traces, you must specify the necessary settings. For details about the necessary settings, see 7. Performance Analysis by Using Trace Based Performance Analysis in the Application Server Maintenance and Migration Guide.

(a) Output format

Performance analysis traces are output to files that are in the same format as the performance analysis trace files for the J2EE server. For details about the output format, see 7.3 Collecting the trace based performance analysis file by using Management Server in the Application Server Maintenance and Migration Guide.

(b) Output items

The following table shows the items that are output to performance analysis trace files.

Table 7‒125: Items that are output to performance analysis trace files (for file event linkage)
Item		Description
Event ID		The event ID of a collection point is output. For details about collection points, see (c) Collection points of performance analysis traces.
Return code		The collection point type is output: `0`: Normal termination `1`: Abnormal termination
Interface name		The class name is output.
Operation name		The method name is output.
Optional information^#	Message common ID	The request identification information (parent ID) is output. If this information is not set, the string `null` is output.
	Service request ID	The request identification information (child ID) is output. If this information is not set, the string `null` is output.
	Additional information	The following additional information is output: Reception name Reception ID Client correlation ID Service name Service operation name Exception name (only at failure occurrence)

#: The optional information is a maximum of 256 bytes long. This item is not output at collection points 1 and 2 in the figure in (c) Collection points of performance analysis traces.

(c) Collection points of performance analysis traces

The two types of collection points of performance analysis traces for file event linkage are as follows:

Points at which to collect a trace when the file event reception operates
Points at which to collect a trace when the file monitoring processing starts and ends

The following describes the preceding types of collection points:

Points at which to collect a trace when the file event reception operates

Figure 7‒110: Collection points of performance analysis traces (for file event linkage)

The following table shows the event IDs, trace collection points, and collection levels of performance analysis traces. The numbers in the Number in figure column of the table correspond to the circled numbers in the preceding figure.

Table 7‒126: Collection points of performance analysis traces (for file event linkage)
Event ID	Number in figure	Trace collection point	Level^#
0x98B0	1	Entry to a custom reception	A
0x98B1	2	Exit from a custom reception	A
0x98B2	3	Point for invoking the custom reception framework	B
0x98B3	4	Point for receiving a response from the custom reception framework	B
0x9860	5	Entry to the custom reception framework	A
0x9861	6	Exit from the custom reception framework	A
0x9864	7	Point for invoking the message delivery control	A
0x9865	8	Point for receiving a response from the message delivery control	A

Legend:

A: Indicates the Standard level.

B: Indicates the Advance level.

#

For details about how to change the collection level of performance analysis traces, see the Application Server Maintenance and Migration Guide.

Points at which to collect a trace when the file monitoring processing starts and ends

Figure 7‒111: Collection points of performance analysis traces (for file event linkage)

Table 7‒127: Collection points of performance analysis traces (for file event linkage)
Event ID	Number in figure	Trace collection point	Level
0x98B4	9	Start of the file monitoring processing	A
0x98B5	10	End of the file monitoring processing	A

Legend:: A: Standard level

To Page Top

(5) File event trace

When the file event reception starts, it initializes file event traces. If initialization fails, a warning message (KDEC00457-W) is output to the message log and the processing to start the file event reception continues. No file event traces can be collected using the file event reception that failed in initialization.

(a) Output destination

The output destination of file event traces is as follows:

log-output-directory-on-the-J2EE-server\csc\rcp\fileevent\reception-ID

The log data output directory on the J2EE server can be specified by using the ejb.server.log.directory key in the option definition file (usrconf.cfg) for the J2EE server on which the HCSC server operates. The following table shows the names of file event trace files.

Table 7‒128: Names of file event trace files
Trace file output mode	Trace file name
Wraparound mode	`fileeventtrace_N.log`
Shift mode	`fileeventtrace_.log`

(b) Number of files

The default number of output files is 8. The number of files can be changed by using the urecp-fileevent.trace.filenum key in the file-event-reception configuration file.

For details about the file-event-reception configuration file, see 6.9.1 File-event-reception configuration file in the manual Service Platform Reference Guide.

(c) File size

The default output file size is 2 MB. The file size can be changed by using the urecp-fileevent.trace.filesize key in the file-event-reception configuration file.

For details about the file-event-reception configuration file, see 6.9.1 File-event-reception configuration file in the manual Service Platform Reference Guide.

(d) Output format

The following figure shows the output format of file event traces.

Figure 7‒112: Output format of file event traces

(e) Output items

The following table shows the output items of file event traces.

Table 7‒129: Output items of file event traces (for file event linkage)
Item	Description
Number	The sequence number of each file event trace is output.
Date	The date on which the file event trace was collected is output in `YYYY/MM/DD` format.
Time	The time at which the file event trace was collected is output in `hh:mm:ss.SSS` format.
Product ID	The string `CSCMSG` is output as a product identifier.
Pid	The identifier of each process is output.
tid	The identifier of each thread is output.
ID	Blank
Reception ID	The ID of the file event reception that processed the request is output.
Collection point	The following items are output as the information about collection points: `IN`: Entry to the file event reception `OUT`: Exit from the file event reception (This item is output only if `true` is set in the `success` element of the response message.) `FAULT`: Error (This item is output only if `false` is set in the `success` element of the response message.) `ERROR`: Error (An error was returned by the caller of the file event reception or an error occurred in the file event reception.)
Root application information	Root application information
Additional information	If the information about the collection point is `IN` The name of the file created when file creation was detected and the size of the file to be acquired is output. If the information about the collection point is not `IN` If a value is set in the `message` element of the response message, the value is output. If an exception is returned, the error message obtained from the exception is output.
CRLF	The record end code is output.

(f) Collection points of file event traces

The following figure shows the collection points of file event traces.

Figure 7‒113: Collection points of file event traces

The following table shows the collection points of file event traces and the collection point information. The numbers in the Number in figure column of the table correspond to the circled numbers in the preceding figure.

Table 7‒130: Collection points of file event traces
Number in figure	Trace collection point	Collection point information
1	Entry to the file event reception	IN
2	Exit from the file event reception	OUT
		FAULT
		ERROR

To Page Top