Enable Tracing

The OPC Client performs various activities while it is running. It may be polling the OPC server or writing a value to a point in the OPC Server. It pings the OPC server. At startup, it creates OPC Groups and Items in the server. It handles point update events being fired by the OPC server.

You decide which of these activities you want to see trace data for, and you decide that on a Device by Device basis. You can set any of the trace properties for every CIMPLICITY device you configure. These are TRUE or FALSE (1 or 0) properties.

These properties can be manipulated at run time by defining device diagnostic points of type BOOL using the point addresses specified in the following table. Remember to check the Diagnostic option next to the Point Address when configuring these points in Workbench. This allows you to modify the activities that are traced, while the project is running.

With some creative engineering, these device diagnostic points can be very powerful. You could start and stop tracing based on a CIMPLICITY event manager script, or with a button on a CimView screen.

Trace Activity properties and corresponding diagnostic point addresses:

Device Parameter Diagnostic Address Type Description
TraceAll !OPC_TRACE_ALL BOOLEAN Trace all activities. This is effectively the same as setting the rest of these properties to 1.
TraceConnection !OPC_TRACE_CONNECTION BOOLEAN Trace activity related to 'connecting to' and 'disconnecting from' the OPC Server.
TraceGroupActivity !OPC_TRACE_GROUP_ACTIVITY BOOLEAN Trace activity related to OPC Groups; adding them to the server, calling Refresh, etc.
TraceItemActivity !OPC_TRACE_ITEM_ACTIVITY BOOLEAN Trace activity related to OPC Items; adding them to the group, removing them from the group, adding them to the OPC Server, etc.
TracePinging !OPC_TRACE_PINGING BOOLEAN Trace activity related to Pinging the OPC server. Did it succeed, did it fail, how long did it take, etc.
TracePolling !OPC_TRACE_POLLING BOOLEAN Trace activity related to polling the OPC server for point values (calling the SyncIO.Read method). Successfully retrieved values are added to the point update queue.
TraceEvent !OPC_TRACE_EVENTS BOOLEAN Trace activity related to point update 'events' 'fired' by the OPC server. When these events occur, the OPC client puts the new value into the point update queue, which is then emptied as the new values are passed into CIMPLICITY.
TraceWriting !OPC_TRACE_WRITING BOOLEAN Trace activity related to writing a new value to a point in the OPC server from CIMPLICITY.
TraceDequeue !OPC_TRACE_DEQUEUE BOOLEAN Trace activity related to processing the point update queue.

Every CIMPLICITY Device you configure can be set to output its trace records to it's own log file with the TraceSeparate property.

Trace Separate Property

Value Description
TraceSeparate TraceSeparate is TRUE or FALSE (1 or 0). The default value is FALSE. If one of your devices contains TraceSeparate=0, this device will output its trace records to the CIMPLICITY Port's circular log file (MASTER_OPC_x.LOG). Otherwise, this device will output its trace records to a file of its own, named with the device ID as follows: MASTER_OPC_x_<YourDeviceID>.LOG In this way, trace data for each configured CIMPLICITY Device is logged separately. This will aid in isolating an issue. Turning TraceSeparate off for one or more devices is useful when trying to diagnose a timing related issue, or some interaction between devices.

Every CIMPLICITY Device you configure contains one more, very important, trace property: TraceLevel.

TraceLevel can be an integer value between one (1) and seven (7). Think of the TraceLevel as the 'volume knob' for tracing. It determines the granularity, or how detailed the trace records will be. These seven values are defined as follows:

Trace Level granularity settings:

Value Name Description
1 BIGERRORS This is the default value for TraceLevel. At this level, only big 'showstopper' type errors that occur during the activities you have enabled will be traced.
2 ALLERRORS At this level, all errors, major and minor, are sent to the Trace file. This is perhaps the best setting to use for the diagnosis of an issue. Only error conditions will be traced, so you will not have to sift through a growing list of successful activities when searching for the cause of an issue.
3 BIGSUCCESSES At this level, in addition to all error conditions, big successes like 'poll successful', 'write successful', and 'success connecting to OPC server' are also included. This level can be very useful when you need to see an error condition within the context of what else was going on at the time. Such as, what was the last successful operation before the error, or did the next attempt succeed.
4 ALLSUCCESSES At this level, all errors and all successes are written to the trace log. Trace Levels of four or higher will cause the log to fill up quickly. In addition, the log will fill with successful operations, making it harder to diagnose problems. This setting is useful when trying to isolate a timing issue or an abnormal termination.
5 ITEMDETAILS This Trace Level is like ALLSUCCESSES. In addition, details about every point are included. You can use this level to see point updates, complete with value, as they arrive from the OPC server. Note: There are other ways to get detailed point information without setting the Trace Level this high. See the section below on Other Trace related diagnostic addresses.
6 DEVELOPER Level 1 Trace statements at this level are intended for the CIMPLICITY development team. They are not likely to be useful unless you have an in-depth knowledge of the OPC client source code.
7 DEVELOPER Level 2 Important: Do not use either of these 'Development' Trace Levels unless instructed to do so by CIMPLICITY support. These two Trace Levels provide an extreme amount of detail that will fill the log file very quickly.
Note:
  • You should never need a Trace Level higher than three (BIGSUCCESSES) to diagnose an issue. It may be feasible to leave minimal tracing enabled, even in production, without severely affecting performance. With TraceAll=1 and TraceLevel=1 or 2, error conditions will be traced as they happen, and only error conditions will be traced. If an issue arises only after the project has been running for some time, this is the way to trap it. While everything is running fine, the log will remain empty. As errors occur, they will be written to the log.
  • A device diagnostic point can be configured so that the Trace Level can be adjusted while the project is running. The address for this point is: !OPC_TRACE_LEVEL, and the point must be configured as an analog point of type SINT or USINT.
  • Three more device diagnostic point addresses provide useful trace functionality. When configuring CIMPLICITY points with these addresses, the point type must be of type BOOL. Writing a value of one (1) will cause the action to occur. A status log message will indicate that the command was executed.

Other Trace related diagnostic point addresses

Point Address Description
$OPC_FLUSH_TRACE_NOW When trace records are written to the log, they are not expressly flushed to the file on disk. Instead, the OS is in charge of this. If you want to view the trace log while the project is still running, you can write a one (1) to this point. This will cause all pending trace records to be written to disk.
$OPC_DUMP_ALL_POINTS Writing a one (1) to this point will cause the OPC client to immediately dump the status of every point in the device to the trace log. Each trace record contains detailed information about the point. This option will allow you to immediately know the answer to the two most popular support questions we get concerning the OPC client:
  • "Why is that point unavailable?", and
  • "Why hasn't that point updated recently?"
This option makes it generally unnecessary to set the Trace Level above two (2). The "ITEMDETAILS" level is just not needed since you can dump point information on demand (as you need).
$OPC_DUMP_BAD_POINTS This diagnostic point performs the same operation as the one above, but it only dumps points marked as unavailable. It will allow you to answer the first of the two big questions above without having to sift through points that are updating fine.