SendLogMessage Method (MessageLog2 Interface)

                    

 

The SendLogMessage method provides advanced logging capabilities taking the place of MessageLog.PutString.  The method can be used to send messages to a message log based on message templates identified by an ID and can also be used to provide additional data parameters associated with a message.  This additional data provides context that can be used to evaluate and categorize messages as well as helping to debug problems reported in the logs.  Template messages have been predefined and are delivered with the PI System.  Subsequent releases may provide new template messages.

SendLogMessage timestamps each message as it is called, avoiding ordering issues due to network latency and load on the receiving subsystem. When sending messages to a remote message log, the method uses the destination's UTC time to avoid issues with clock drift and time zone settings between nodes. In contrast the MessageLog.PutString method sends the message to the message subsystem (local or remote) which stamps the message as it added it to the store which can introduce latency that makes it hard to compare messages from different systems.

This method continues to support sending messages without a template by passing the template ID of 0 and still allows the additional message parameters to be passed.  The use of templates and the passing of additional message parameters is supported even against PI Message Subsystems prior to 3.4.380.  In this case, the PI-SDK detects the version of the target message subsystem and renders the message locally and automatically inserts the resulting message and passed parameter names and values into the message text.

An interface, IMessageSendNames, is provided by the PI-SDK to aid in message construction.  This interface contains as properties all the additional message parameters that can be passed to a message.  Each property returns the official parameter name so using this interface in conjunction with the construction of the nvMessageParams NamedValues argument allows the caller to select supported parameters and use the correct names.  In many programming environments this experience is enhanced by Intellisense allowing the user to select the desired message parameters from a dropdown list.

Syntax

object.SendLogMessage msgID, nvTemplateParams, nvMessageParams

The SendLogMessage method syntax has these parts:

Part Description
object An object expression that evaluates to a MessageLog2 interface.
msgID A long integer representing the template identifier from the OSIsoftTemplateMessages.htm file or 0 for a plain text message.
nvTemplateParams

A NamedValues collection of values to be inserted in a template message replacing the template's placeholders. The NamedValues collection should have its Sorted property set to false and the parameters should be added in the order they appear in the template. TThe name portion of each NamedValue contained is not currently needed but for consistency and debugging purposes, you should name the first NamedValue “1”, the second NamedValue “2”, and so on. For messages sent with a msgID of 0, the first NamedValue in the collection should contain the complete text of the desired message.

nvMessageParams

A NamedValues collection containing additional information about the message being sent.  Only a specific set of message parameters are supported so the names are fixed.  These names are shown in a table below however an easier way to supply this name is to use the IMessageSendNames interface (available as a property of the MessageLog2 object) whose properties are named for the supported parameters and the property returns the official string used to specify the value.

Settings

The possible values in the nvMessageParams argument are:

Name Data Type Meaning
Category String The category message parameter is provided to allow the programmer to specify a text string with a message that can be used to group similar messages.  The value passed can be any string leaving it to the programmer to determine useful categories.
OriginatingHost String

An originating host represents the fully qualified domain name (FQDN) of the machine sending a message as determined by an application.  The SendLogMessage method will automatically add the ProcessHost to any log message sent to a PI server's Message log (remote messages).  When sending messages to the local log it is assumed the process host is the same as the host of the PI Message subsystem and this parameter is not logged.  However in some cases, such as an application server, the machine where the application is running (the process host) may not be the machine that the message pertains to.  In this case the application may choose to use the OriginatingHost property of a message to clearly define the source of the message.

OriginatingOSUser String
An originating O/S user represents the user sending a message as determined by an application.  The SendLogMessage method will automatically add the ProcessOSUser to each log message.  However in some cases, such as an application server, the user associated with the application's process may not be the user that the message pertains to.  In this case the application may choose to use the OriginatingOSUser property of a message to clearly define the sender or related user of the message.

OriginatingPIUser String An originating PI user represents the authenticated PI user sending a message as determined by an application.  The SendLogMessage method will automatically add the ProcessPIUser to any log message sent to a PI server's Message log (remote messages).  When sending messages to the local log the PI-SDK can not determine the proper PI user so this property is not added automatically though can be explicitly sent by an application.  In some cases, such as an application server, the PI user associated with the application's process may not be the PI user that the message pertains to.  In this case the application may choose to use the OriginatingPIUser property of a message to clearly define the authenticated PI user sending the message or related to the message's contents.
Priority Integer The Priority property of a message is an integer between 1 and 10 (1 being the most important - "highest priority")that is used by an application to define the order in which a message condition should be handled relative to other messages.  Unlike severity, which defines the criticality of a message, priority is intended to indicate ordering of corrective action.  Priority is always an optional part of a message as only an application can determine if it is needed and what its value should be.
ProcessHost String The process host represents the fully qualified domain name of the machine sending a message. SendLogMessage method will automatically add the ProcessHost to any log message sent to a PI server's Message log (remote messages).  When sending messages to the local log it is assumed the process host is the same as the host of the PI Message subsystem and this parameter is not automatically logged but can be added by an application.
ProcessOSUser String The ProcessOSUser represents the authenticated user of the application which is logging the message. This parameter is automatically added to all messages sent with MessageLog2.SendLogMessage.  This is typically the intended sender of the messaage however this is not always the case. For applications that do impersonation, the identity of the impersonating thread posting a message may differ from the process identity.  This is because different threads may have different identities and also because the request to log may be invoked on one thread but is executed on the thread where the MessageLog2 object was instantiated (for single threaded apartment objects such as the MessageLog and MessageLog2).  For this reason only the process identity is automatically recorded. The application can override the ProcessOSUser parameter for this case.   Even without impersonation it is also possible that an application is doing work, and logging a message in that regard, on behalf of a different user (application servers behave this way).  For this case the application can specify the OriginatingOSUser field when sending a message to provide a more accurate picture of the message context.
ProcessPIUser String The ProcessPIUser is the authenticated PI user associated with a message being logged. SendLogMessage method will automatically add the ProcessPIUser to any log message sent to a PI server's Message log (remote messages).  When sending messages to the local log the PI-SDK can not determine the proper PI user so this property is not added automatically though can be explicitly sent by an application.  If an application is doing work on behalf of a PI User not associated with the server connection being used to log a message, the OriginatingPIUser message property should instead be sent.
SeverityOverride Integer Template messages have an associated severity code statically assigned to them.  If the message sender wishes to override the severity of such a message or provide a severity for a message that does not use a template they may add this parameter.  The allowed values are shown below. Either the numeric or the constant from the MsgSeverityConstants enumeration can be sent.
Source1 String Log messages sent with the PI-SDK automatically send the application name with each message.  When a programmer wishes to further identify the cause or contributors to a condition a message is reporting, these extra source fields can be supplied with a string value.  By convention the sources are ordered going from general to specific.  Source1 being the most general, Source2 to being the next level of specificity and so on.  To support this convention, the more general source items must be included if the more specific ones are used (for example you must send Source1 if you send Source2). Not all sources will be hierarchical but more specific information that leads to a resolution of a problem is always desirable.  If there are several peer problem sources they can be sent in these arguments provided the rule above is satisfied (for example to send Source3 you must send Source2 and Source1).
Source2 String See above.
Source3 String See above.

 

Severity Override values are:

Number MsgSeverityConstants Meaning Description
1 mscCritical Critical The message is reporting a critical problem that can impact operations.
2 mscError Error The message is indicating an error condition that should be resolved eventually. 
3 mscWarning Warning
The message indicates an issue that could elevate into a more serious problem or may be only a transient condition.

4 mscInformation Information The message is informational only and does not indicate a problem.
5 mscDebug Debug The message is only provided to aid in debugging.

 

Remarks

The list of delivered template messages that can be used is provided in the file PIMessageDefinitions.htm in the PIPC\Help directory.  The file lists all currently defined message templates in order of their message ID (msgID).  The text of the message is presented with replaceable parameters indicated by ordered integers preceded by the percent sign (e.g. %1, %2).  This is followed by the message default severity, keywords that can be used to search for the message in a log (this search is not yet supported), and a list of the replaceable parameters. For example:

3020
Message: Failed to register with License Manager on the primary server %1 - %2
Severity: Error
Keywords:
Parameters: %1 = FQDN Type: String
%2 = Status Type: Status
 

Here message ID 3020 is displayed along with its message which contains two replaceable parameters.  Unless overridden by passing the SeverityOverride keyword in the nvMessageParams argument, the severity of the message posted will be "Error".  There are no defined keywords for searching for this error in a log. The two template parameters are a fully qualified domain name (FQDN) of type string and a Status.  Status arguments in this file refer to PI3 error codes (e.g.  -12001). 

The first several messages in the file have no message text and are intended for users who want to send a message with a predefined severity but passing their own message string.  In that case the first object in the nvTemplateParams collection is a NamedValue containing the desired message string.  This could also be accomplished by using message ID 0, passing the same nvTemplateParams collection and passing an nvMessageParams collection that contained a NamedValue object named SeverityOverride with one of the allowed  values shown above.

 

 

Trappable Errors

In addition to generic errors (such as Out of Memory), the following errors may be returned :

Error Description
pseNOERRORSTRING A message ID of 0 was passed but the first NamedValue did not contain any text.
pseSUBSYSNOVERSION Unable to obtain the version of the PIMessage subsystem being written to
pseLOGMESSAGEPOST Failed to send a message to the server.  Error description usually contains more detailed information.

Enabling Operational Intelligence