smartinspectpython.sifileprotocol

@export
class SIFileProtocol(smartinspectpython.siprotocol.SIProtocol):

The standard SmartInspect protocol for writing log packets to a log file.

SIFileProtocol is the base class for all protocol classes which deal with log files. By default, it uses the binary log file format which is compatible to the Console. Derived classes can change this behavior. For example, for a simple protocol which is capable of creating plain text files, see the SITextProtocol class.

The file protocol supports a variety of options, such as log rotation (by size and date), encryption and I/O buffers.

For a list of available protocol options, please refer to the IsValidOption method.

Threadsafety:

The public members of this class are thread-safe.

SIFileProtocol()

Initializes a new instance of the class.

DefaultFileName: str

Gets the DefaultFileName property value.

Returns the default filename for this log file protocol.

The standard implementation of this method returns the string "log.sil" here. Derived classes can change this behavior by overriding this property method.

Gets the Formatter property value.

Returns the formatter for this log file protocol.

The standard implementation of this method returns an instance of the SIBinaryFormatter class. Derived classes can change this behavior by overriding this property method.

Name: str

Overridden. Returns "file".

def BuildOptions( self, builder: smartinspectpython.siconnectionsbuilder.SIConnectionsBuilder) -> None:

Overridden. 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.
@staticmethod
def GetIVector() -> bytes:

Returns a new MD5 hashed initialization vector for AES cryptographic functions. The vector is based on a current datetime ticks value.

Returns:

A new MD5 hashed initialization vector of 16 bytes (128-bits).

def GetStream(self, stream: _io.BytesIO) -> None:

Intended to provide a wrapper stream for the underlying file stream.

Arguments:
  • stream (BytesIO): The underlying file stream.
Returns:

The wrapper stream.

This method can be used by custom protocol implementers to wrap the underlying file stream into a filter stream. Such filter streams include System.Security.Cryptography.CryptoStream for encrypting or System.IO.Compression.DeflateStream for compressing log files, for example.

By default, this method simply returns the passed stream argument.

def InternalConnect(self) -> None:

Overridden. Opens the destination file.

Raises:
  • Exception: Opening the destination file failed.

This method tries to open the destination file, which can be specified by passing the "filename" option to the Initialize method. For other valid options which might affect the behavior of this method, please see the IsValidOption method.

def InternalDisconnect(self) -> None:

Overridden. Closes the destination file.

Raises:
  • Exception: Closing the destination file failed.

This method closes the underlying file handle if previously created and disposes any supplemental objects.

def InternalWritePacket(self, packet: smartinspectpython.sipacket.SIPacket) -> None:

Overridden. Writes a packet to the destination file.

Arguments:
  • packet (SIPacket): The packet to write.
Raises:
  • Exception: Writing the packet to the destination file failed.

If the "maxsize" option is set and the supplied packet would exceed the maximum size of the destination file, then the current log file is closed and a new file is opened. Additionally, if the "rotate" option is active, the log file is rotated if necessary. Please see the documentation of the IsValidOption method for more information.

def IsValidOption(self, name: str) -> bool:

Overridden. Validates if a protocol option is supported.

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 for the FILE protocol.

Valid Options (default value) Description
append (false) Specifies if new packets should be appended to the destination file instead of overwriting the file first.
buffer (0) Specifies the I/O buffer size in kilobytes. It is possible to specify size units like this: "1 MB". Supported units are "KB", "MB" and "GB". A value of 0 disables this feature. Enabling the I/O buffering greatly improves the logging performance but has the disadvantage that log packets are temporarily stored in memory and are not immediately written to disk.
encrypt (false) Specifies if the resulting log file should be encrypted. Note that the 'append' option cannot be used with encryption enabled. If encryption is enabled the 'append' option has no effect.
filename ([varies]) Specifies the filename of the log.
key ([empty]) Specifies the secret encryption key as string if the 'encrypt' option is enabled.
maxparts ([varies]) Specifies the maximum amount of log files at any given time when log rotating is enabled or the maxsize option is set. Specify 0 for no limit. See below for information on the default value for this option.
maxsize (0) Specifies the maximum size of a log file in kilobytes. When this size is reached, the current log file is closed and a new file is opened. The maximum amount of log files can be set with the maxparts option. It is possible to specify size units like this: "1 MB". Supported units are "KB", "MB" and "GB". A value of 0 disables this feature.
rotate (none) Specifies the rotate mode for log files. Please see below for a list of available values. A value of "none" disables this feature. The maximum amount of log files can be set with the maxparts option. See the SIFileRotate enum for more info.

When using the standard binary log file protocol ("file" in the SmartInspect.Connections, the default filename is set to "log.sil". When using text log files ("text" in the SmartInspect.Connections), the default filename is "log.txt".

The append option specifies if new packets should be appended to the destination file instead of overwriting the file. The default value of this option is "false".

The rotate option specifies the date log rotate mode for this file protocol. When this option is used, the filename of the resulting log consists of the value of the filename option and an appended time stamp (the used time stamp format thereby is "yyyy-MM-dd-HH-mm-ss"). To avoid problems with daylight saving time or time zone changes, the time stamp is always in UTC (Coordinated Universal Time). The following table lists the available rotate modes together with a short description.

As example, if you specify "log.sil" as value for the filename option and use the Daily rotate mode, the log file is rotated daily and always has a name of log-yyyy-MM-dd-HH-mm-ss.sil. In addition to, or instead of, rotating log files by date, you can also let the file protocol rotate log files by size. To enable this feature, set the maxsize option to the desired maximum size. Similar to rotating by date, the resulting log files include a time stamp. Note that starting with SmartInspect 3.0, it is supported to combine the maxsize and rotate options (i.e. use both options at the same time).

To control the maximum amount of created log files for the rotate and/or maxsize options, you can use the maxparts option. The default value for maxparts is 2 when used with the maxsize option, 0 when used with rotate and 0 when both options, maxsize and rotate, are used.

SmartInspect log files can be automatically encrypted by enabling the 'encrypt' option. The used cipher is Rijndael (AES) with a key size of 128 bit. The secret encryption key can be specified with the 'key' option. The specified key is automatically shortened or padded (with zeros) to a key size of 128 bit. Note that the 'append' option cannot be used in combination with encryption enabled. If encryption is enabled the 'append' option has no effect.

For further options which affect the behavior of this protocol, please have a look at the documentation of the SIProtocol.IsValidOption method of the parent class.

Sample Code

# package imports.
from smartinspectpython.siauto import *

# the following are sample SI Connections options for this protocol.

# log messages using all default options ("log.sil", no rotating).
SIAuto.Si.Connections = 'file()'

# log messages (appending) to file 'mylog.sil'.
SIAuto.Si.Connections = "file(filename=\"mylog.sil\", append=true)"

# log messages to rotating default file 'log.sil', that do not 
# exceed 16MB in size.
SIAuto.Si.Connections = "file(maxsize=\"16MB\", maxparts=5)"

# log messages to rotating default file 'log.sil', that creates a new log 
# file every week.  since maxparts is not specified, log files will continue 
# to accumulate and must be manually deleted.
SIAuto.Si.Connections = "file(rotate=weekly)"

# log messages to default file 'log.sil', in an encrypted format with a 
# password of "secret".  when opening the log file in the SI Console, you 
# will be prompted for the passphrase key.
SIAuto.Si.Connections = "file(encrypt=true, key=\"secret\")"

def LoadOptions(self) -> None:

Overridden. Loads and inspects specific options for this protocol.

This method loads all relevant options and ensures their correctness. See IsValidOption for a list of options which are recognized by the protocol.

def ThrowException(self, message: str) -> None:

Raises a new SIProtocolException exception

Raises:
  • SIProtocolException: Thrown when this method is called.
def WriteFooter(self, stream: _io.BytesIO) -> None:

Intended to write the footer of a log file.

Arguments:
  • stream (BytesIO): The stream to which the footer should be written to.

The implementation of this method does nothing. Derived class may change this behavior by overriding this method.

def WriteHeader(self, stream: _io.BytesIO, size: int) -> int:

Intended to write the header of a log file.

Arguments:
  • stream (BytesIO): The stream to which the header should be written to.
  • size (int): Specifies the current size of the supplied stream.
Returns:

The new size of the stream after writing the header. If no header is written, the supplied size argument is returned.

This default implementation of this method writes the standard binary protocol header to the supplied Stream instance. Derived classes may change this behavior by overriding this method.