platform sdk logging

About SDK logging

The Genetec SDK provides a flexible logging framework and an optional diagnostic interface.

Basic logging allows your application to write trace messages at configurable severity levels to destinations such as files, console, Event Viewer, SQL Server, and others. This is configured through .gconfig files and uses the Logger class at runtime.

DiagnosticServer is an optional component you can initialize in your application. It hosts a web-based Diagnostic Console where you can view logs in real time and execute specially annotated application methods called debug methods. Debug methods are useful for interactive testing and diagnostics while the application is running.

If you only need your application to generate logs, you can configure and use the logging facilities without enabling the DiagnosticServer. You only need to initialize the DiagnosticServer if you want to expose the Diagnostic Console and enable debug methods.

In the C# examples on this page, these types are in Genetec.Sdk.Diagnostics (DiagnosticServer), Genetec.Sdk.Diagnostics.Logging.Core (Logger), and Genetec.Sdk.Diagnostics.Logging (DebugMethodAttribute, UserCommandAttribute).

Basic logging

Basic logging in the SDK uses .gconfig files and Logger instances. This does not require the DiagnosticServer.

Setting up log traces for an external application

1. Create a Configuration File

   • Name it after your executable, including .exe and with .gconfig suffix.

   • Example: for MyApp.exe, create:

     MyApp.exe.gconfig
     

2. Structure of the Configuration File

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <logTargets>
    <!-- logTarget elements go here -->
  </logTargets>
</configuration>

3. Define Log Targets You can define multiple <logTarget> elements in the same .gconfig file. Each log target is independent, and logs matching its <traces> configuration will be written to all applicable targets.

<logTarget type="Genetec.Diagnostics.Logging.Targets.ConsoleTarget, Genetec">
  <settings>
    <add key="TraceExceptionStacks" value="true" />
    <add key="IncludeThreadId" value="true" />
  </settings>
  <traces>
    <add loggerName="MyCompany.MyProject.*" severity="Warning | Error | Fatal"/>
    <add loggerName="MyCompany.MyProject.MyClass" severity="Performance"/>
  </traces>
</logTarget>

Available log targets

The SDK provides the following log targets:

Target	Type Name	Description
Console	Genetec.Diagnostics.Logging.Targets.ConsoleTarget, Genetec	Outputs to console window
Log File	Genetec.Diagnostics.Logging.Targets.LogFileTarget, Genetec	Writes to flat text files
Event Log	Genetec.Diagnostics.Logging.Targets.EventLogTarget, Genetec	Writes to Windows Event Log
SQL Server	Genetec.Diagnostics.Logging.Targets.SqlServerLogTarget, Genetec	Writes to SQL Server database
XML	Genetec.Diagnostics.Logging.Targets.XmlLogTarget, Genetec	Writes to XML files (.gtrace)
Debug	Genetec.Diagnostics.Logging.Targets.DebugTarget, Genetec	Outputs to debug window (Visual Studio)
ETW	Genetec.Diagnostics.Logging.Targets.EtwLogTarget, Genetec	Event Tracing for Windows
OTLP	Genetec.Diagnostics.Logging.Targets.OtlpTarget, Genetec	OpenTelemetry Protocol exporter

ConsoleTarget

Outputs log messages to the console window.

Settings

Key	Type	Default	Description
TraceExceptionStacks	bool	true	Include full exception stack traces
IncludeThreadId	bool	true	Include thread ID in output

Example

<logTarget type="Genetec.Diagnostics.Logging.Targets.ConsoleTarget, Genetec">
  <settings>
    <add key="TraceExceptionStacks" value="true" />
    <add key="IncludeThreadId" value="true" />
  </settings>
  <traces>
    <add loggerName="MyCompany.*" severity="All" />
  </traces>
</logTarget>

LogFileTarget

Writes log messages to flat text files. Files are created in a Logs folder by default.

Settings

Key	Type	Default	Description
prefix	string	(empty)	Prefix for log file names
logFolder	string	Logs	Folder path for log files. Use %EXE% pattern for path relative to the current working directory
deleteOlderThanNDays	int	14	Delete log files older than this many days
logMaxLine	int	(unlimited)	Maximum lines per file before creating a new file
maxDiskUsage	string	(unlimited)	Maximum total disk usage (for example, 500MB, 1GB)
minDiskSpace	string	(none)	Minimum free disk space to maintain
maxFileSize	string	(unlimited)	Maximum size per file (for example, 100MB)
zipFiles	bool	false	Compress old log files
detailedHeader	bool	true	Write detailed header at file start
format	string	Text	Log format: Text or Json
reuseFiles	bool	true	Reuse existing log files (vs. always create new)
prefixWithMachineName	bool	false	Prefix file names with machine name

Example

<logTarget type="Genetec.Diagnostics.Logging.Targets.LogFileTarget, Genetec">
  <settings>
    <add key="prefix" value="MyApp" />
    <add key="logFolder" value="C:\Logs\MyApp" />
    <add key="deleteOlderThanNDays" value="30" />
    <add key="maxFileSize" value="50MB" />
  </settings>
  <traces>
    <add loggerName="MyCompany.*" severity="All" />
  </traces>
</logTarget>

EventLogTarget

Writes log messages to the Windows Event Log.

Settings

Key	Type	Default	Description
EventViewerLoggerName	string	(system default)	Custom event log source name

Severity mapping

• Error, Fatal map to Windows Event Log Error
• Information, Performance, Debug map to Windows Event Log Information
• Warning maps to Windows Event Log Warning

Example

<logTarget type="Genetec.Diagnostics.Logging.Targets.EventLogTarget, Genetec">
  <settings>
    <add key="EventViewerLoggerName" value="MyApplication" />
  </settings>
  <traces>
    <add loggerName="MyCompany.*" severity="Error | Fatal" />
  </traces>
</logTarget>

SqlServerLogTarget

Writes log messages to a SQL Server database. Automatically creates the required LogEntry table.

Settings

Key	Type	Default	Description
Server	string	(required)	SQL Server instance name
Database	string	(required)	Database name
MaxLogEntries	int	10000	Maximum entries to keep in database
CleanupTime	TimeSpan	00:00	Time of day to run cleanup (for example, 02:30 for 2:30 AM)
MaxNumberOfErrors	int	10	Max connection errors before disabling target
MaxWorkItems	int	2000	Max queued log entries

Example

<logTarget type="Genetec.Diagnostics.Logging.Targets.SqlServerLogTarget, Genetec">
  <settings>
    <add key="Server" value="localhost\SQLEXPRESS" />
    <add key="Database" value="ApplicationLogs" />
    <add key="MaxLogEntries" value="50000" />
    <add key="CleanupTime" value="03:00" />
  </settings>
  <traces>
    <add loggerName="MyCompany.*" severity="Warning | Error | Fatal" />
  </traces>
</logTarget>

XmlLogTarget

Writes log messages to XML files with .gtrace extension.

Settings

Key	Type	Default	Description
prefix	string	(empty)	Prefix for file names
logFolder	string	Logs	Folder path for log files
maximumFileSizeInMegabytes	int	100	Maximum file size in MB before rotation
totalMaximumFileSizeInMegabytes	int	1024	Maximum total size of all log files
retentionPeriodInDays	int	-1 (disabled)	Delete files older than this many days

Example

<logTarget type="Genetec.Diagnostics.Logging.Targets.XmlLogTarget, Genetec">
  <settings>
    <add key="prefix" value="MyApp" />
    <add key="logFolder" value="C:\Logs\Traces" />
    <add key="maximumFileSizeInMegabytes" value="50" />
    <add key="retentionPeriodInDays" value="7" />
  </settings>
  <traces>
    <add loggerName="MyCompany.*" severity="Full" />
  </traces>
</logTarget>

DebugTarget

Outputs log messages to the debug output window (visible in Visual Studio when debugging).

Settings

Key	Type	Default	Description
TraceWithoutDebugger	bool	false	Output even when no debugger is attached
HideExceptionStack	bool	false	Show only exception messages without stack traces

Example

<logTarget type="Genetec.Diagnostics.Logging.Targets.DebugTarget, Genetec">
  <settings>
    <add key="TraceWithoutDebugger" value="false" />
    <add key="HideExceptionStack" value="false" />
  </settings>
  <traces>
    <add loggerName="MyCompany.*" severity="Full" />
  </traces>
</logTarget>

EtwLogTarget

Writes log messages using Event Tracing for Windows (ETW).

Settings

Key	Type	Default	Description
providerName	string	(required)	ETW provider name
autoRegisterEventLog	bool	false	Automatically register the event log provider
eventLogMaxSizeInMegabyte	int	100	Maximum event log size in MB

Example

<logTarget type="Genetec.Diagnostics.Logging.Targets.EtwLogTarget, Genetec">
  <settings>
    <add key="providerName" value="MyCompany-MyApp" />
    <add key="autoRegisterEventLog" value="true" />
    <add key="eventLogMaxSizeInMegabyte" value="200" />
  </settings>
  <traces>
    <add loggerName="MyCompany.*" severity="All" />
  </traces>
</logTarget>

OtlpTarget

Exports log messages using the OpenTelemetry Protocol (OTLP). Requires an OTLP-compatible collector endpoint.

Settings

This target uses the standard OpenTelemetry OTLP exporter configuration through environment variables:

• OTEL_EXPORTER_OTLP_ENDPOINT - The OTLP collector endpoint
• OTEL_EXPORTER_OTLP_HEADERS - Headers for authentication

Example

<logTarget type="Genetec.Diagnostics.Logging.Targets.OtlpTarget, Genetec">
  <traces>
    <add loggerName="MyCompany.*" severity="All" />
  </traces>
</logTarget>

Common settings

These settings are available on all log targets and are configured in the <settings> element:

Key	Type	Default	Description
summarize	int	(disabled)	Summarize repeated messages within this time window (milliseconds)
domainFilter	string	(all)	Wildcard filter to enable target only for specific AppDomain names

summarize

When the same log message is written repeatedly in a short time (for example, in a loop or during rapid event processing), the log file can become flooded with duplicate entries. The summarize setting collapses these repeated messages into a single entry within the specified time window.

Set the value in milliseconds. For example, 5000 means repeated messages within 5 seconds are summarized.

domainFilter

Security Center runs multiple processes, each with its own AppDomain name. The domainFilter setting restricts a log target to only write logs from processes whose AppDomain name matches the wildcard pattern.

Use standard wildcard characters: * matches any characters, ? matches a single character.

Example

<logTarget type="Genetec.Diagnostics.Logging.Targets.LogFileTarget, Genetec">
  <settings>
    <add key="summarize" value="5000" />
    <add key="domainFilter" value="MyPlugin*" />
  </settings>
  <traces>
    <add loggerName="MyCompany.*" severity="All" />
  </traces>
</logTarget>

This configuration:

• Summarizes repeated log messages that occur within 5 seconds
• Only writes logs from AppDomains whose name starts with "MyPlugin"

Traces element

Each <logTarget> contains a <traces> element, which defines which loggers and severity levels this log target listens to.

You can think of <traces> as a filter for the specific log target. Only log messages that match a loggerName and a specified severity inside <traces> will be written to that log target. Messages that do not match any <add /> in <traces> are ignored by that target, but may still go to other targets.

Scope

The <traces> element is scoped per log target. Each log target has its own <traces> block, and its filtering applies only to that target.

Logger name

The loggerName refers to the fully qualified logger name, which typically includes the namespace and optionally the class name. For example:

• Genetec.Dap : matches all loggers in the Genetec.Dap namespace.
• Genetec.Dap.MyClass : matches only the logger for the specific class.
• Wildcards (*) can be used for broader matching, such as Genetec.*.Samples.

Multiple <add /> elements

You can include multiple <add /> elements inside a single <traces> block. Each one specifies a loggerName and a severity. All <add /> elements are cumulative: if any of them matches a log message, that message is written to the target.

Example: single <add />

<traces>
  <add loggerName="Genetec.Dap" severity="Information|Error" />
</traces>

Example: multiple <add />

<traces>
  <add loggerName="Genetec.Dap.Module1" severity="Information|Error" />
  <add loggerName="Genetec.Dap.Module2" severity="Warning|Error|Fatal" />
</traces>

The Logger class

The Logger class is used in your application code to emit log messages at different severity levels. It works in conjunction with the .gconfig file, which defines where and which messages are written.

You can create either an instance logger or a class logger, depending on your use case.

Instance logger

Use an instance logger when you want a logger tied to a specific instance of your class.

class InstanceLogger : IDisposable
{
    private readonly Logger m_logger;

    public InstanceLogger()
    {
        m_logger = Logger.CreateInstanceLogger(this);
    }

    public void Dispose()
    {
        m_logger.Dispose();
    }

    public void LogDebugMessage()
    {
        m_logger.TraceDebug("This is a debug message");
    }
}

Class (static) logger

Use a class logger when you want a single logger shared across all instances of a class.

static class StaticLogger
{
    private static readonly Logger s_logger = Logger.CreateClassLogger(typeof(StaticLogger));

    public static void LogDebugMessage()
    {
        s_logger.TraceDebug("This is a debug message");
    }
}

Logging methods

The Logger class provides methods to log at each severity level:

• TraceDebug
• TraceInformation
• TraceWarning
• TraceError
• TraceFatal
• TracePerformance

Each of these methods can accept:

• A simple message string.
• A message with params object[] arguments.
• An Exception and optional message.
• A TraceEntry object for advanced scenarios.

Example usage

_logger.TraceDebug("Operation completed: {0}", operationId);
_logger.TraceError(new InvalidOperationException(), "Unexpected error.");

Notes

• The Logger implements IDisposable. You should dispose instance loggers when no longer needed.
• Class loggers remain valid for the lifetime of the application.

Log severities

Available severity levels:

• Performance
• Debug
• Information
• Warning
• Error
• Fatal
• Full (all levels, including Performance and Debug)
• All (Information and higher, excluding Debug and Performance)

Combine severities with |, e.g.:

Warning | Error | Fatal

DiagnosticServer

The DiagnosticServer provides a web-based console that lets you view logs interactively and execute annotated debug methods at runtime. It is not required for basic logging.

What it does

• Hosts the web-based Diagnostic Console.
• Lists logs in real-time.
• Enables execution of debug methods marked with DebugMethodAttribute.

Example initialization

const int diagnosticServerPort = 4523;
const int webServerPort = 6023;

DiagnosticServer.Instance.InitializeServer(diagnosticServerPort, webServerPort);

• There is no default webServerPort. You must specify it explicitly.
• Requires administrative privileges to bind ports.

Accessing the console

After initialization, open the console in your browser:

http://localhost:<webServerPort>/Console

Security Desk and Config Tool include console ports in their .gconfig files:

• Security Desk: http://localhost:6020/Console
• Config Tool: http://localhost:6021/Console

In the shipped configuration, the gNetServer element is disabled (enabled="false"), so these URLs are not served by default. To use one of these built-in consoles, enable gNetServer in the corresponding .gconfig file.

Cleanup

Dispose properly at shutdown:

if (DiagnosticServer.IsInstanceCreated && DiagnosticServer.Instance.IsInitialized)
{
    DiagnosticServer.Instance.Dispose();
}

Using debug methods

Debug methods are application methods annotated to be discoverable and executable through the Diagnostic Console.

Requirements

• A Logger must exist in the class defining the debug methods.
• Methods can have any access modifier.
• Methods can return string or void.
• If the class uses a static logger, methods must be static.
• If the class uses an instance logger, methods must be instance methods.

Unique DisplayName per class

Each debug method must have a unique DisplayName within the same class. Different classes may reuse the same DisplayName.

Attributes

Use these attributes to expose debug methods in the Diagnostic Console and control how they appear.

DebugMethodAttribute

Property	Description
Description	Description shown in the console.
DisplayName	Unique per class.
IsHidden	Hides the method from the list; can still be invoked by manually entering its DisplayName.
IsSecured	Restricts execution to the local machine.

UserCommandAttribute

Groups the method into a category:

[UserCommand("Diagnostics.SampleCategory")]

Examples

These examples show the minimum attribute usage for instance and static debug methods.

Instance debug method

[DebugMethod(DisplayName = "Instance Debug", Description = "Sample instance method")]
[UserCommand("Diagnostics")]
public string InstanceDebug()
{
    return "Instance executed.";
}

Static debug method

[DebugMethod(DisplayName = "Static Debug", Description = "Sample static method")]
[UserCommand("Diagnostics")]
public static string StaticDebug()
{
    return "Static executed.";
}

Configuring logging for Security Desk and Config Tool

To adjust logging for built-in Security Center applications, modify:

• SecurityDesk.exe.gconfig
• ConfigTool.exe.gconfig

These are located in the Security Center installation folder.

See also

• About the Platform SDK: SDK assemblies and the Engine class.
• Connecting to Security Center: Engine setup, authentication, and logging on to Security Center.