編集

Creating Custom Telemetry Traces for Application Insights Monitoring

  • [アーティクル]

APPLIES TO: Business Central 2020 release wave 2 and later

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

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 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 a 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. There are several CustomDimensions that will be included in traces by default. See Default CustomDimensions
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.

Note

In Application Insights, the name of custom dimension will be prefixed with al. For example, if the dimension string you define in code is result, then in the trace logged in Application Insights, the name appears as alresult.

Default CustomDimensions

The following table explains CustomDimensions that are automatically included in ALMessage traces that are sent to Application Insights.

Dimension Description or value
aadTenantId Specifies the Microsoft Entra tenant ID used for Microsoft Entra authentication. For on-premises, if you aren't using Microsoft Entra authentication, this value is common.
alCallerAppName Specifies the name of the extension that emitted the telemetry signal to Application Insights. This is typically the base application.
alCallerAppPublishser Specifies the publisher of the extension that emitted the telemetry signal to Application Insights. This is typically the publisher of the base application, which is Microsoft.
alCallerAppVersion Specifies the version number of the extension that emitted the telemetry signal to Application Insights. This is typically the version of the base application.
alObjectId Specifies the ID of the object that called the LOGMESSAGE method.
alObjectName Specifies the name of the object that called the LOGMESSAGE method.
alObjectType Specifies the type of the object that called the LOGMESSAGE method, like PageExtension for a page extension object.
clientType Specifies the type of client that ran LOGMESSAGE method, such as Background or Web. For a list of the client types, see ClientType Option Type.
componentVersion Specifies the version number of the component that emits telemetry (see the component dimension.)
companyName Specifies the company in Business Central
component Dynamics 365 Business Central Server.
componentVersion Specifies the version number of the component that emits telemetry (see the component dimension.)
environmentName Specifies the name of the tenant environment. See Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production, Sandbox, Trial. See Environment Types
extensionName Specifies the name of the extension that called the LOGMESSAGE method.
extensionId Specifies the ID of the extension that called the LOGMESSAGE method.
extensionPublisher Specifies the publisher of the extension that called the LOGMESSAGE method.
extensionVersion Specifies the version of the compiled extension.
deprecatedKeys A comma-separated list of all the keys that have been deprecated. The keys in this list are still supported but will eventually be removed in the next major release. We recommend that update any queries that use these keys to use the new key name.
telemetrySchemaVersion Specifies the version of the Business Central telemetry schema.

Best practices for designing telemetry event

When the Business Central product team designed the partner telemetry feature, we build the following characteristics into it:

  • Telemetry event definitions must treated as an API. Changing custom dimensions is a breaking change (someone might have built reporting or alerting on top of it).
  • Telemetry events must be discoverable in docs. If you see someting in telemetry, it should be easy to learn more about it in documentation. We added the custom dimension eventId because of this. It is good practice to keep eventIds unique, also across apps/extensions.
  • Documented: each telemetry event has good documentation, preferably with guidance on how to react on this event.
  • Actionable (if possible): before we add a new telemetry event, we ask "what can a customer/partner do with this?" If no good answers come to mind, we do not add the event.

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 a critical error message', Verbosity::Normal, DATACLASSIFICATION::SystemMetadata, TelemetryScope::ExtensionPublisher, CustDimension);
end;

Using an overload:

trigger OnRun();
begin
    LogMessage('MyExt-0001', 'This is a 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