By default, the Unity Client configuration file (obunity.exe.config ) does not contain routes that enable the ability to log events to diagnostics tools, such as the Diagnostics Console or Event Viewer. To enable event logging, the Hyland.Logging element and associated Routes and (if auditing) AuditRoutes elements must be added to the configuration file.
To enable event logging in the Unity Client:
-
Locate the configuration file (obunity.exe.config
).
The default location for this file is C:\Program Files (x86)\Hyland\Unity Client.
-
Open the configuration file in a plain text editor, such as Notepad.
Note:
The *.config file should only be edited in a plain-text editor, such as Notepad, or a utility specifically designed to edit XML files. It should not be edited in a binary editor, such as Microsoft Word. Using a binary editor can introduce invalid characters to the file and make it unreadable by the software.
-
Within the <configSections> element, add the following
element:
<section name="Hyland.Logging" type="Hyland.Logging.Configuration.ClientConfigurationHandler,Hyland.Logging" />
-
Add the following <Hyland.Logging> element after the
</appSettings> closing element and before the
<Hyland.Canvas> opening element:
<Hyland.Logging> <WindowsEventLogging sourcename="Unity Client" /> <Routes> <Route name="Route1Name"> <add key/> </Route> </Routes> <AuditRoutes> <Route name="Audit1Name"> <add key/> </Route> </AuditRoutes> </Hyland.Logging>
-
In the <Routes> element, edit the first
<Route> and (if needed) add additional
<Route> elements to include names and <add
key> elements that define each of the routes needed for diagnostics
logging.
Routes listed in the <Routes> element are used for general logging. The following routes are directly supported, with each route showing the <add key> element that needs to be added to define the route. Any value in brackets needs to be replaced with information based on your solution configuration.
Note: You may also use any route that is supported by Serilog. For more information on all available routing settings, see Serilog's documentation.Route Type <add key> Defining Entry Additional Keys Console <add key="Console" /> - OutputFormat
- minimum-level
- maximum-level
- include-profiles
- exclude-profiles
- DisableIPAddressMasking
File <add key="File" value="[PathToFile]" /> - OutputFormat
- FileRollOnSize
- FileRollInterval
- FileCountLimit
- FileByteLimit
- minimum-level
- maximum-level
- include-profiles
- exclude-profiles
- DisableIPAddressMasking
HTTP <add key="Http" value="[EndpointAddress]" /> - minimum-level
- maximum-level
- include-profiles
- exclude-profiles
- DisableIPAddressMasking
Durable HTTP <add key="DurableHttp" value="[EndpointAddress]" /> - DurableBufferPath
- DurableBufferRollingInterval
- minimum-level
- maximum-level
- include-profiles
- exclude-profiles
- DisableIPAddressMasking
Splunk <add key="Splunk" value="[SplunkHostAddress] /> <add key="SplunkToken" value="[SplunkAuthToken]" /> - SplunkIndex
- SplunkSource
- SplunkHost
- SplunkSourceType
- minimum-level
- maximum-level
- include-profiles
- exclude-profiles
- DisableIPAddressMasking
Event Log <add key="EventLog" value="[source]" /> Note: If the source value is not defined, the event log is written to the Hyland log.- minimum-level
- maximum-level
- include-profiles
- exclude-profiles
- DisableIPAddressMasking
The following keys are used with the previously listed routes:
Key Type <add key> Entry Description OutputFormat <add key="OutputFormat" value="[Type]" /> This determines the output format for File or Console routes. The [Type] can be defined as Minimal, Text, or Json.
- Minimal: Writes only the time, log level, exception, and message fields. In Console routes, this is used by default if another output format is not specified.
- Text: Writes all of the message as a list of key-value pairs.
- Json: Writes the message in a compact JSON format on a single line. In File routes, this is used by default if another output format is not specified.
minimum-level <add key="minimum-level" value="[LogLevel]" /> This sets the minimum Log Level that will be written to this route. If not present, by default, the minimum level is Information.
For more information on Log Levels, see Microsoft's documentation.
maximum-level <add key="maximum-level" value="[LogLevel]" /> This sets the maximum Log Level that will be written to this route. If not present, by default, the maximum level is Critical.
For more information on Log Levels, see Microsoft's documentation.
include-profiles <add key="include-profiles" value="[ProfileList]" /> This defines which profiles will be written to this route. The ProfileList must be formatted as a comma-separated list. All profiles not listed will not be written.
exclude-profiles <add key="exclude-profiles" value="[ProfileList]" /> This defines which profiles will be not written to this route. The ProfileList must be formatted as a comma-separated list. All profiles not listed will be written.
DisableIPAddressMasking <add key="DisableIPAddressMasking" value="[true/false]" /> This toggles whether IP addresses are masked. If set to true, the Source IP in the message is shown, not masked. If set to false or not included, then the Source IP will not show the individual address.
This is only needed in the <Routes> list, not the <AuditRoutes> list.
FileRollInterval <add key="FileRollInterval" value="[TimeInterval]" /> This enables file rolling on a defined time interval. The [TimeInterval] can be defined as Minute, Hour, Day, Month, Year, or Infinite.
FileRollOnSize <add key="FileRollOnSize" value="true" /> This enables file rolling when the FileByteLimit is reached.
FileCountLimit <add key="FileCountLimit" value="[Number]" /> This sets the maximum number of files to retain when using rolling files. The default value is 31. If the key is set but the value is empty, the file count is unlimited.
FileByteLimit <add key="FileByteLimit" value="[ByteLimit]" /> This sets the maximum file size for any individual log file. The default value is 1073741824, which is 1 gigabyte. If the key is set but the value is empty, the file size is unlimited.
DurableBufferPath <add key="DurableBufferPath" value="[FilePath]" /> This allows Durable HTTP buffer files to be written to a non-default file path. This is a required key for Durable HTTP logging routes when installing applications in Admin locations.
CAUTION: Do not use "{Date}", "{Hour}", or "{HalfHour}" when defining the path as this may cause issues when used with Hyland Logging.DurableBufferRollingInterval <add key="DurableBufferRollingInterval" value="[TimeInterval]" /> This allows the user to specify the frequency of Durable Buffer file rolling. The [TimeInterval] can be defined as Date, HalfHour, or Hour. The default is Date.
SplunkIndex <add key="SplunkIndex" value="[user_index]" /> This defines the index of users when validating the SplunkToken for users defining a Splunk route.
SplunkSource <add key="SplunkSource" value="[SourceURL]" /> This defines the Splunk source for users defining a Splunk route.
SplunkHost <add key="SplunkHost" value="[Host]" /> This defines the Splunk host for users defining a Splunk route.
SplunkSourceType <add key="SplunkSourceType" value="[SourceType]" /> This defines what type of source is used when specifying a source for users defining a Splunk route.
-
In the <AuditRoutes> element, edit the first
<Route> and (if needed) add additional
<Route> elements to include names and <add
key> elements that define each of the routes needed for diagnostics
logging.
Routes listed in the <AuditRoutes> element are used specifically for auditing. For more information on defining routes, see the tables in step 5.
The following example shows a <Hyland.Logging> element configured to log to a JSON file that is then accessible for auditing in the Diagnostics Console:
<Hyland.Logging> <WindowsEventLogging sourcename="Unity Client" /> <Routes> <Route name="FileRoute"> <add key="File" value="C:\HylandLogs\ClientLog.json" /> <add key="OutputFormat" value="JSON" /> <add key="FileRollOnSize" /> <add key="FileRollInterval" value="Infinite" /> <add key="FileCountLimit" value="7" /> <add key="FileByteLimit" value="15000000" /> <add key="minimum-level" value="Trace" /> </Route> </Routes> <AuditRoutes> <Route name="DiagnosticsConsole"> <add key="Http" value="http://localhost:8989" /> </Route> </AuditRoutes> </Hyland.Logging>
- Save and close the configuration file.