smartinspectpython.siprotocol
Is the abstract base class for a protocol. A protocol is responsible for transporting packets.
A protocol is responsible for the transport of packets. This base class offers all necessary methods to handle the protocol options and it declares several abstract protocol specific methods for handling protocol destinations like connecting or writing packets.
The following table lists the available protocols together with their identifier in the SmartInspect.Connections and a short description.
Protocol (Identifier) | Description |
---|---|
SIFileProtocol ("file") | Used for writing log files in the standard SmartInspect binary log file format which can be loaded into the Console. |
SIMemoryProtocol ("mem") | Used for writing log data to memory and saving it to a stream on request. |
SIPipeProtocol ("pipe") | Used for sending log data over a named pipe directly to a local Console. |
SITcpProtocol ("tcp") | Used for sending packets over a TCP connection directly to the Console. |
SITextProtocol ("text") | Used for writing log files in a customizable text format. Best suited for end-user notification purposes. |
There are several options which are IsValidOption and beyond that each protocol has its own set of additional options. For those protocol specific options, please refer to the documentation of the corresponding protocol class. Protocol options can be set with Initialize and derived classes can query option values using the Get methods.
Threadsafety:
The public members of this class are thread-safe.
Event raised when a protocol has an informational message to convey.
Gets the AppName property value.
The application name of a protocol is usually set to the name of the application this protocol is created in. The application name can be used to write LogHeader packets after a successful protocol connect.
Gets the Asynchronous property value.
Indicates if this protocol is operating in asynchronous protocol mode.
If this property returns true, this protocol is operating in asynchronous protocol mode. Otherwise, it returns false. Asynchronous protocol mode can be enabled with the Initialize method. Also see IsValidOption for information on asynchronous logging and how to enable it.
Gets the Caption property value.
Returns the caption of this protocol.
The caption is used in the SmartInspect.Dispatch method to lookup a requested connection. The caption can be set with the Options property. If you use only one connection at once or does not use the SmartInspect.Dispatch method, the caption option can safely be ignored.
For more information, please refer to the documentation of the Dispatch and SmartInspect.Dispatch methods.
Gets the Failed property value.
Returns if the last executed connection-related operation of this protocol has failed. Indicates if the next operation is likely to block.
Gets the HostName property value.
The host name of a protocol is usually set to the name of the machine this protocol is created in. The host name can be used to write LogHeader packets after a successful protocol connect.
Gets the Name property value.
Specifies the name of a real protocol implementation.
Raises:
- NotImplementedError: Thrown if the property method is not overridden in an inheriting class.
Real implementations should return a meaningful name which represents the protocol. For example, the SIFileProtocol returns "file", the SITcpProtocol "tcp" and the SITextProtocol "text".
Fills a SIConnectionsBuilder instance with the options currently used by this protocol.
Arguments:
- builder (SIConnectionsBuilder): The SIConnectionsBuilder object to fill with the current options of this protocol.
The filled options string consists of key, value option pairs separated by commas.
This function takes care of the options (see IsValidOption). To include protocol specific options, override this function.
Connects to the protocol specific destination.
Raises:
- SIProtocolException: Connecting to the destination failed. Can only occur when operating in normal blocking mode. In asynchronous mode, the Error event is used for reporting exceptions instead.
In normal blocking mode (see IsValidOption), this method does nothing more than to verify that the protocol is not already connected and does not use the IsValidOption and then calls the abstract protocol specific InternalConnect method in a thread-safe and exception-safe context.
When operating in asynchronous mode instead, this method schedules a connect operation for asynchronous execution and returns immediately. Please note that possible exceptions which occur during the eventually executed connect are not thrown directly but reported with the Error event.
Disconnects from the protocol destination.
Raises:
- SIProtocolException: Disconnecting from the destination failed. Can only occur when operating in normal blocking mode. In asynchronous mode, the Error event is used for reporting exceptions instead.
In normal blocking mode (see IsValidOption), this method checks if this protocol has a working connection and then calls the protocol specific InternalDisconnect method in a thread-safe and exception-safe context.
When operating in asynchronous mode instead, this method schedules a disconnect operation for asynchronous execution and then blocks until the internal protocol thread is done. Please note that possible exceptions which occur during the eventually executed disconnect are not thrown directly but reported with the Error event.
Dispatches a custom action to a concrete implementation of a protocol.
Arguments:
- command (SIProtocolCommand): The protocol command object which provides protocol specific information about the custom action. Can be null.
Raises:
- SIProtocolException: An exception occurred in the custom action. Can only occur when operating in normal blocking mode. In asynchronous mode, the Error event is used for reporting exceptions instead.
In normal blocking mode (see IsValidOption), this method does nothing more than to call the protocol specific InternalDispatch method with the supplied command argument in a thread-safe and exception-safe way. Please note that this method dispatches the custom action only if the protocol is currently connected.
When operating in asynchronous mode instead, this method schedules a dispatch operation for asynchronous execution and returns immediately. Please note that possible exceptions which occur during the eventually executed dispatch are not thrown directly but reported with the Error event.
Disconnects from the protocol destination.
Raises:
- SIProtocolException: Disconnecting from the destination failed. Can only occur when operating in normal blocking mode. In asynchronous mode, the Error event is used for reporting exceptions instead.
In normal blocking mode (see IsValidOption), this method checks if this protocol has a working connection and then calls the protocol specific InternalDisconnect method in a thread-safe and exception-safe context.
When operating in asynchronous mode instead, this method schedules a disconnect operation for asynchronous execution and then blocks until the internal protocol thread is done. Please note that possible exceptions which occur during the eventually executed disconnect are not thrown directly but reported with the Error event.
Gets the boolean value of a key.
Arguments:
- key (str): The key whose value to return.
- defaultValue (bool): The value to return if the key does not exist.
Returns:
Either the value if the key exists or defaultValue otherwise. Note that this method can throw an exception of type ArgumentNullException if you pass a null reference as key.
Raises:
- ArgumentNullException: The key argument is null.
A bool value will be treated as true if the value of the key matches either "true", "yes" or "1" and as false otherwise. Note that this method can throw an exception of type ArgumentNullException if you pass a null reference as key.
Gets the byte array value of a key.
Arguments:
- key (str): The key whose value to return.
- size (int): The desired size in bytes of the returned byte array. If the element value does not have the expected size, it is shortened or padded automatically.
- defaultValue (bytearray): The value to return if the given key is unknown or if the found value has an invalid format.
Returns:
Either the value converted to a byte array for the given key if an element with the given key exists and the found value has a valid format or defaultValue otherwise.
Raises:
- ArgumentNullException: The key argument is null.
The returned byte array always has the desired length as specified by the size argument. If the element value does not have the required size after conversion, it is shortened or padded (with zeros) automatically. This method returns the defaultValue argument if either the supplied key is unknown or the found value does not have a valid format (e.g. invalid characters when using hexadecimal strings).
Note that this method can throw an exception of type ArgumentNullException if you pass a null reference as key.
Gets the integer value of a key.
Arguments:
- key (str): The key whose value to return.
- defaultValue (int): The value to return if the key does not exist.
Returns:
Either the value if the key exists or defaultValue otherwise. Note that this method can throw an exception of type ArgumentNullException if you pass a null reference as key.
Raises:
- ArgumentNullException: The key argument is null.
Please note that if a value could be found but is not a valid integer, the supplied default value will be returned. Only non-negative integers will be recognized as valid values. Also note that this method can throw an exception of type ArgumentNullException if you pass a null reference as key.
Gets the Level value of a key.
Arguments:
- key (str): The key whose value to return.
- defaultValue (SILevel): The value to return if the key does not exist.
Returns:
Either the value converted to the corresponding Level value for the given key if an element with the given key exists and the found value is a valid Level value or defaultValue otherwise.
Raises:
- ArgumentNullException: The key argument is null.
This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid Level value. Please see the Level enum for more information on the available values. Note that this method can throw an exception of type ArgumentNullException if you pass a null reference as key.
Gets the FileRotate value of a key.
Arguments:
- key (str): The key whose value to return.
- defaultValue (SIFileRotate): The value to return if the key does not exist.
Returns:
Either the value converted to a FileRotate value for the given key if an element with the given key exists and the found value is a valid FileRotate or defaultValue otherwise. Note that this method can throw an exception of type ArgumentNullException if you pass a null reference as key.
Raises:
- ArgumentNullException: The key argument is null.
This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid Level value. Please see the Level enum for more information on the available values. Note that this method can throw an exception of type ArgumentNullException if you pass a null reference as key.
Gets an integer value of a key. The integer value is interpreted as a byte size and it is supported to specify byte units.
Arguments:
- key (str): The key whose value to return.
- defaultValue (int): The value to return if the key does not exist.
Returns:
Either the value converted to an integer for the given key if an element with the given key exists and the found value is a valid integer or defaultValue otherwise.
Raises:
- ArgumentNullException: The key argument is null.
This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid integer or ends with an unknown byte unit. Only non-negative integer values are recognized as valid.
It is possible to specify a size unit at the end of the value. If a known unit is found, this function multiplies the resulting value with the corresponding factor. For example, if the value of the element is "1KB", the return value of this function would be 1024.
The following table lists the available units together with a short description and the corresponding factor.
Unit Name / Factor | Description |
---|---|
KB / 1024 | KiloByte |
MB / 1024^2 | MegaByte |
GB / 1024^3 | GigaByte |
If no unit is specified, this function defaults to the KB unit. Note that this method can throw an exception of type ArgumentNullException if you pass a null reference as key.
Gets the string value of a key.
Arguments:
- key (str): The key whose value to return.
- defaultValue (str): The value to return if the key does not exist.
Returns:
Either the value if the key exists or defaultValue otherwise. Note that this method can throw an exception of type ArgumentNullException if you pass a null reference as key.
Raises:
- ArgumentNullException: The key argument is null.
Gets an integer value of a key. The integer value is interpreted as a time span and it is supported to specify time span units.
Arguments:
- key (str): The key whose value to return.
- defaultValue (float): The value to return if the key does not exist.
Returns:
Either the value converted to an integer for the given key if an element with the given key exists and the found value is a valid integer or defaultValue otherwise. The value is returned in milliseconds.
Raises:
- ArgumentNullException: The key argument is null.
This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid integer or ends with an unknown time span unit.
It is possible to specify a time span unit at the end of the value. If a known unit is found, this function multiplies the resulting value with the corresponding factor. For example, if the value of the element is "1s", the return value of this function would be 1000.
The following table lists the available units together with a short description and the corresponding factor.
Unit Name / Factor | Description |
---|---|
s (Seconds) | 1000 |
m (Minutes) | 60*s |
h (Hours) | 60*m |
d (Days) | 24*h |
If no unit is specified, this function defaults to the Seconds unit. Please note that the value is always returned in milliseconds.
Handles a protocol exception.
Arguments:
- message (str): The exception message.
Raises:
- SIProtocolException: Always in normal blocking mode; never in asynchronous mode.
This method handles an occurred protocol exception. It first sets the Failed flag and creates a SIProtocolException object with the name and options of this protocol. In normal blocking mode (see IsValidOption), it then throws this exception. When operating in asynchronous mode, it invokes the Error event handlers instead and does not throw an exception.
Sets and initializes the options of this protocol.
Arguments:
- options (str): Protocol options, in string delimited format.
Raises:
- SmartInspectException: Invalid options syntax or an unknown option key.
This property expects an options string which consists of key, value pairs separated by commas like this: "filename=log.sil, append=true". To use a comma in a value, you can use quotation marks like in the following example: "filename=\"log.sil\", append=true".
Please note that a SmartInspectException exception is thrown if an incorrect options string is assigned. An incorrect options string could use an invalid syntax or contain one or more unknown option keys. This method can be called only once. Further calls have no effect. Pass null or an empty string to use the default options of a particular protocol.
Connects to the protocol destination Abstract method - inheriting classes must override.
Raises:
- Exception: Connecting to the destination failed.
This method initiates a protocol specific connection attempt. The behavior of real implementations of this method can often be changed by setting protocol options with the Initialize method. This method is always called in a thread-safe and exception-safe context.
Disconnects from the protocol destination. Abstract method - inheriting classes must override.
Raises:
- Exception: Disconnecting from the destination failed.
This method is intended for real protocol implementations to disconnect from the protocol specific source. This could be closing a file or disconnecting a TCP socket, for example. This method is always called in a thread-safe and exception-safe context.
Executes a protocol specific custom action.
Arguments:
- command (SIProtocolCommand): The protocol command which provides protocol specific information about the custom action. Can be null.
Raises:
- Exception: Executing the custom action failed.
The default implementation does nothing. Derived protocol implementations can override this method to add custom actions. Please see the SIMemoryProtocol.InternalDispatch method for an example. This method is always called in a thread-safe and exception-safe way.
Reconnects to the protocol specific destination.
Returns:
True if the reconnect attempt has been successful and false otherwise.
Raises:
- Exception: Reconnecting to the destination failed.
This method initiates a protocol specific reconnect attempt. The behavior of real method implementations can often be changed by setting protocol options with Initialize. This method is always called in a thread-safe and exception-safe context.
The default implementation simply calls the protocol specific InternalConnect method. Derived classes can change this behavior by overriding this method.
Writes a packet to the protocol destination.
Arguments:
- packet (SIPacket): The packet to write.
Raises:
- Exception: Writing the packet to the destination failed.
This method is intended for real protocol implementations to write the supplied packet to the protocol specific destination. This method is always called in a thread-safe and exception-safe context.
Overriddeable. Validates if a option is supported by this protocol.
True if the option is supported and false otherwise.
Arguments:
- name (str): The option name to validate.
Returns:
True if the option is supported and false otherwise.
The following table lists all valid options, their default values and descriptions common to all protocols. See below for explanations.
Option Name (Default Value) | Description |
---|---|
level (debug) | Specifies the log level of this protocol. |
reconnect (false) | Specifies if a reconnect should be initiated when a connection gets dropped. |
reconnect.interval (0) | If reconnecting is enabled, specifies the minimum time in seconds between two successive reconnect attempts. If 0 is specified, a reconnect attempt is initiated for each packet if needed. It is possible to specify time span units like this: "1s". Supported units are "s" (seconds), "m" (minutes), "h" (hours) and "d" (days). |
caption ([name]) | Specifies the caption of this protocol as used by SmartInspect.Dispatch. By default, it is set to the protocol identifier (e.g., "file" or "mem"). |
async.enabled (false) | Specifies if this protocol should operate in asynchronous instead of the default blocking mode. |
async.queue (2048) | Specifies the maximum size of the asynchronous queue in kilobytes. It is possible to specify size units like this: "1 MB". Supported units are "KB", "MB" and "GB". |
async.throttle (true) | Specifies if the application should be automatically throttled in asynchronous mode when more data is logged than the queue can handle. |
async.clearondisconnect (false) | Specifies if the current content of the asynchronous queue should be discarded before disconnecting. Useful if an application must not wait for the logging to complete before exiting. |
backlog.enabled (false) | Enables the backlog feature (see below). |
backlog.queue (2048) | Specifies the maximum size of the backlog queue in kilobytes. It is possible to specify size units like this: "1 MB". Supported units are "KB", "MB" and "GB". |
backlog.flushon (error) | Specifies the flush level for the backlog functionality. |
backlog.keepopen (false) | Specifies if the connection should be kept open between two successive writes when the backlog feature is used. |
With the log level of a protocol you can limit the amount of data being logged by excluding packets which don't have a certain minimum log level. For example, if you set the level to "message", all packets with a log level of "debug" or "verbose" are ignored. For a complete list of available log level values, please see the documentation of the Level enum.
The caption option specifies the caption for this protocol as used by the SmartInspect.Dispatch method. This method can send and initiate custom protocol actions and the caption is used to lookup the requested connection. By default, the caption is set to the identifier of a protocol (e.g., "file" or "mem"). For more information about the dispatching of custom protocol actions, please refer to the documentation of the Dispatch and SmartInspect.Dispatch methods.
If the backlog option is enabled, all packets whose log level is less than the flushon level and equal to or higher than the general log level of a protocol, will be written to a queue rather than directly to the protocol specific destination. When a packet arrives with a log level of at least the same value as the flushon option, the current content of the queue is written. The total amount of memory occupied by this queue can be set with the queue option. If the packet queue has been filled up with packets and a new packet is about to be stored, old packets are discarded.
As an example, if the backlog queue is set to "2 MB" and the flushon level to "error", all packets with a log level less than error are written to a queue first. By specifying a queue option of "2 MB", the backlog queue is set to a maximum memory size of 2 megabyte. Now, when a packet with a log level of error arrives, the current content of the queue and then the error itself are written.
With the keepopen option of the backlog feature you can specify if a connection should be kept open between two successive writes. When keepopen is set to false, a connection is only available during the actual write / flush. A connection is thus only created when absolutely necessary.
A protocol can either operate in normal blocking (the default) or in asynchronous mode. In blocking mode, the operations of this protocol (Connect, Disconnect, Dispatch and WritePacket) are executed synchronously and block the caller until they are done. In asynchronous mode, these operations are not executed directly but scheduled for execution in a different thread and return immediately. Asynchronous logging can increase the logging performance and reduce the blocking of applications.
When operating in asynchronous mode, this protocol uses a queue to buffer the logging data. The total amount of memory occupied by this queue can be set with the queue option. The throttle option specifies if an application should be automatically throttled in asynchronous mode when more data is logged / generated than the queue can handle. If this option is disabled and the queue is currently full, old packets are discarded when new data is logged. The throttle option ensures that no logging data is lost but can be disabled if logging performance is critical.
With the clearondisconnect option, you can specify if the current content of the asynchronous queue should be discarded before disconnecting. This can be useful if an application must not wait for the logging to complete before exiting.
The reconnect option allows a protocol to reconnect automatically before a packet is being written. A reconnect might be necessary if a working connection has been unexpectedly disconnected or could not be established in the first place. Possible errors during a reconnect attempt will silently be ignored and not reported.
Please note that the reconnect functionality causes a protocol by default to initiate a connection attempt for every packet until a connection has been successfully (re-) established. This can be a very time consuming process, especially when using a protocol which requires a complex connection process like SITcpProtocol, for example. This can slow down the logging performance. When using the reconnect option, it is thus recommended to also enable asynchronous logging to not block the application or to specify a reconnect interval to minimize the reconnect attempts.
Overriddeable. Loads and inspects protocol-specific options.
This method is intended to give real protocol implementations the opportunity to load and inspect options. This method will be called automatically when the options have been changed. The default implementation of this method takes care of the options IsValidOption and should thus always be called by derived classes which override this method.
Method that will handle the SIProtocol.ErrorEvent event. Inheriting classes can override this method to handle the event.
Arguments:
- sender (object): The object which fired the event.
- e (SIErrorEventArgs): Arguments that contain detailed information related to the event.
Derived classes can override this method to intercept the SIProtocol.Error event. Note that the Error event is only used in combination with asynchronous logging (please see IsValidOption for more information). In normal blocking mode, exceptions are reported by throwing.
IMPORTANT: Keep in mind that adding SmartInspect log statements to the event handlers can cause a presumably undesired recursive behavior!
Method that will handle the SIProtocol.InfoEvent event. Inheriting classes can override this method to handle the event.
Arguments:
- sender (object): The object which fired the event.
- e (SIInfoEventArgs): Arguments that contain detailed information related to the event.
Derived classes can override this method to intercept the SIProtocol.Info event.
IMPORTANT: Keep in mind that adding SmartInspect log statements to the event handlers can cause a presumably undesired recursive behavior!
Raises the InfoEvent event with an informational message.
Arguments:
- message (str) The message that caused the event.
This method is used to inform other objects that an informational message was issued by a protocol function.
Resets the protocol and brings it into a consistent state.
This method resets the current protocol state by clearing the internal backlog queue of packets, setting the connected status to false and calling the abstract InternalDisconnect method of a real protocol implementation to cleanup any protocol specific resources.
Writes a packet to the protocol specific destination.
Arguments:
- packet (SIPacket): The packet to write.
Raises:
- SIProtocolException: Writing the packet to the destination failed. Can only occur when operating in normal blocking mode. In asynchronous mode, the Error event is used for reporting exceptions instead.
This method first checks if the log level of the supplied packet is sufficient to be logged. If this is not the case, this method returns immediately.
Otherwise, in normal blocking mode (see IsValidOption), this method verifies that this protocol is successfully connected and then writes the supplied packet to the IsValidOption or passes it directly to the protocol specific destination by calling the InternalWritePacket method. Calling InternalWritePacket is always done in a thread-safe and exception-safe way.
When operating in asynchronous mode instead, this method schedules a write operation for asynchronous execution and returns immediately. Please note that possible exceptions which occur during the eventually executed write are not thrown directly but reported with the Error event.