Creating Custom Telemetry Traces for Application Insights Monitoring

APPLIES TO: Business Central 2020 release wave 2 and later

This article explains how to develop extensions to send custom telemetry trace signals to Azure Application Insights for viewing and analyzing.

You can add AL code in extensions to emit messages about activities or operations that users do within the application. At runtime, the messages can be picked up by an Application Insights resource, which you set up in beforehand. In Application Insights, the custom telemetry events are stored in the traces table.

Set up Application Insights

An Application Insights resource can be configured in two places:

When you create a custom telemetry trace signal, you can specify a telemetry scope. The telemetry scope enables you to send an signal only to the Application Insights resource specified in the extension's app.json. Or to all available resources.

Note

Having Application Insights resources configured is not required to create custom signals in AL code.

Create a custom telemetry trace signal

To create a custom telemetry trace signal, use a LOGMESSAGE method in AL code where you want to trigger the signal. The LOGMESSAGE method defines the information that is sent to Application Insights for a specific operation or activity.

There are two variations of the LOGMESSAGE method. The difference is that one method uses a dictionary object to define custom dimensions for the trace signal. The other method includes two overloads so you don't have to construct a dictionary. You can use these methods in any object, trigger, or method. The methods have the following signatures:

Using a dictionary

The LOGMESSAGE method for using a dictionary for dimensions has the following signature:

Session.LogMessage(EventId: String, Message: String, Verbosity: Verbosity, DataClassification: DataClassification, TelemetryScope: TelemetryScope, CustomDimensions: Dictionary of [Text, Text])

Using dimension overloads

The LOGMESSAGE method for using dimension overloads has the following signature:

Session.LogMessage(EventId: String, Message: String, Verbosity: Verbosity, DataClassification: DataClassification, TelemetryScope: TelemetryScope, Dimension1: String, Value1: String [, Dimension2: String] [, Value2: String])

Setting the parameters

Use the parameters to build the dimensions, or columns, that will show for the trace in Application Insights. Message and Verbosity will appear as general dimensions. All other parameters appear as custom dimensions.

Parameter Description Dimension
EventID A text string that assigns an identifier to the telemetry trace signal. The tag can consist of letters, numbers, and special characters. Try to make your tags unique. For example, use at least 8 characters or a prefix, like Cronus-0001 and Cronus-0002. eventId
Message A text string that specifies the descriptive message for the telemetry trace signal. message
Verbosity* An enumeration that specifies the severity level of the telemetry trace signal. The value can be Critical, Error, Warning, Normal, or Verbose. severityLevel

4=Critical
3=Error
2=Warning
1=Normal
0=Verbose
DataClassification* A DataClassification data type that assigns a classification to the telemetry trace signal. For more information, see Data Classifications. dataClassification
TelemetryScope Scope of emitting the telemetry.
  • extensionpublisher sends the custom signal only to the Application Insight resource specified in the extension's app.json file
  • all sends the custom signal to Application Insight resource specified in the extension's app.json file and on the tenant.
telemetryScope
CustomDimensions A dictionary of text that defines the custom dimensions for the trace signal in Application Insights.
Dimension1 A text string that specifies the name of the custom dimension.
Value1 A text string that specifies the value of Dimension1.
Dimension2 A text string that specifies the name of the custom dimension.
Value2 A text string that specifies the value of Dimension2.

Examples

The following code snippets create simple telemetry trace signals. They create a critical-level telemetry signal that is scoped to the signal publisher. For a simple test of this code, add it to the OnRun trigger of a codeunit, and then run the codeunit.

Using a dictionary:

trigger OnRun();
var
    CustDimension: Dictionary of [Text, Text];
begin
    CustDimension.Add('result', 'failed');
    CustDimension.Add('reason', 'critical error in code');
    LogMessage('MyExt-0001', 'This is an critical error message', Verbosity::Normal, DATACLASSIFICATION::SystemMetadata, TelemetryScope::ExtensionPublisher, CustDimension);
end;

Using an overload:

trigger OnRun();
begin
    LogMessage('MyExt-0001', 'This is an critical error message', Verbosity::Critical, DATACLASSIFICATION::SystemMetadata, TelemetryScope::ExtensionPublisher, 'result', 'failed', 'reason', 'critical error in code');
end;

Design considerations

  • For Business Central on-premises, the Diagnostic Trace Level setting on the Business Central Server instance controls which signals are sent, based on their severity level.

    If the Diagnostic Trace Level is set to Warning for example, then Normal and Verbose signals won't be sent to Application Insights. For more information, see Configuring Business Central Server - General.

  • For privacy reasons, events that have a DataClassification other than SystemMetadata aren't sent to Application Insight resources set up on the tenant. During development of your extension, it's good practice to have a privacy review of the use of LOGMESSAGE calls to ensure that customer data isn't mistakenly leaked into Application Insights resources.

See Also

Instrumenting an Application for Telemetry
LOGMESSAGE method
LOGMESSAGE method
Monitoring and Analyzing Telemetry