Performance Logger Application Programming Interface (API)

Performance Logger is an Application Programming Interface (API) that allows different applications to log events of interest in the Historical database. These events can then be used to conduct a detailed inspection of performance. Each event of interest contains the following details:

• The name of the calling application.

• The timestamp capturing when the event occurred.

• The hostname of the machine processing the event.

• The table that is being processed.

• The record that is being processed.

• The dataset corresponding to the record being processed.

• A short description of the event of interest (for example, Queue Request Received or Execution Started).

• Additional context around the event of interest.

For example, an application that queues incoming requests and processes them one at a time can log events such as when the request was enqueued, when the request started getting processed, and when the processing was completed. This will help understand the average waiting time for requests in the queue and identify potential bottlenecks.

To use the Performance Logger utility, you will need to install the Performance Logger database, call the Performance Logger API where needed in the code, manage performance runs, and then inspect the raw results in the Performance database. The following information expands on the details for each step.

Step 1: Install the Performance Logger database

To install the Performance Logger database, make the following call from the shared silo:

Publish-DataTierApplications.ps1 -Install -ServerName ".\OASySHDB" -Configuration @{ 'Performance' = @() }

Step 2: Call the Performance Logger API where needed in the code

Note: This step is only required if you are using the Performance Logger API in your custom code. If a baseline application uses this utility, the appropriate user guide will provide further documentation. For an example, see Using Performance Logger to Analyze Line Blockage Performance in the AVEVA Pipeline Operations for Liquids Administrator guide.

Performance Logger API Example

using System;

using OASySDNA.RealTime.Data.Common;

using OASySDNA.RealTime.Data.Model;

using OASySDNA.RealTime.Performance.Log;

namespace Example

{

/// <summary>

/// An example of processing an <see cref="IAnalog"/> by adding the values of all analogs together.

/// </summary>

public sealed class AnalogAggregator

{

IPerformanceLogger _logger;

public Double Total { get; private set; }

/// <summary>

/// Unit Test constructor.

/// </summary>

/// <param name="logger">for performance logging.</param>

internal AnalogAggregator(IPerformanceLogger logger)

{

_logger = logger;

Total = 0;

}

/// <summary>

/// Default Constructor.

/// </summary>

public AnalogAggregator()

: this(PerformanceLogger.Instance)

{ }

/// <summary>

/// Do some work based on an <see cref="IAnalog"/>.

/// </summary>

/// <param name="analog"></param>

public void Process(IAnalog analog)

{

_logger.LogEvent(() => new("Example",

analog.Dataset.Number,

analog.TableNumber,

analog.RecordNumber,

"Processing Start",

$"Processing the analog '{analog.Name}' with value {analog.CurrentValue}"));

Total += analog.CurrentValue;

_logger.LogEvent(() => new("Example",

analog.Dataset.Number,

analog.TableNumber,

analog.RecordNumber,

"Processing End",

$"The analog '{analog.Name}' gave new total {Total}"));

}

/// <summary>

/// The application entry point.

/// </summary>

/// <param name="args">Commandline arguments.</param>

/// <returns><see cref="0"/> if no errors.</returns>

public static Int32 Main(String[] args)

{

var aggregator = new AnalogAggregator();

try

{

IDataContext context = new DataContext(new RecordCollectionFactory());

var analogCollection = context.CollectionFor<IAnalog>();

analogCollection.ForEach(analog => aggregator.Process(analog), LockType.SAFE_READ, LockType.SAFE_READ);

Console.WriteLine($"The current Analog total is: {aggregator.Total}");

}

catch (Exception ex)

{

Console.WriteLine(ex);

return 1;

}

return 0; // successful

}

}

}

Step 3: Manage performance runs

You can manage performance runs by completing the following steps:

1. In the Advanced Database Editor (ADE) Application Row Edit window, create a new application record and set the Name field to PerformanceLogger. The description field can be used to describe the purpose of using the utility.

   

2. In the Values tab, set the String Value to a name of your choice. This is the name that will be associated with the events generated by the same run in the Historical database.

   Note: This name is meant to be a user friendly identifier for each performance run. The system will not validate uniqueness of the name across different runs.

   

3. Save the application record.

4. To start a performance run, edit the newly created PerformanceLogger application record by checking Boolean Value. When you save the application record, a run with a unique Run ID will start. This means that calls to the Performance Logger API will start sending events of interest to the Historical database.

   

5. To stop a performance run, edit the PerformanceLogger application record by unchecking the Boolean Value. When you save the application record, the run will stop.

Step 4: Inspect the raw results in the Performance database

You can inspect the raw results of the performance run by querying the EventView view in the Performance database. The results can be filtered using RunName or RunId. In order to produce a meaningful analysis of performance, an additional step might be required to interpret the raw results manually, or by using an automated process.