15.2 Custom Telemetry Signals with Session.LogMessage & KQL

15.2 Custom Telemetry Signals with Session.LogMessage & KQL

While Business Central automatically emits platform-level telemetry for SQL queries and page rendering, enterprise extensions require custom operational telemetry to track business milestones, measure integration throughput, record feature adoption, and diagnose domain-specific validation failures. AL provides native methods and standardized System Application modules for emitting structured custom telemetry signals into Azure Application Insights.

1. Emitting Custom Telemetry: Session.LogMessage

The foundational AL method for emitting custom telemetry is Session.LogMessage(). This method allows developers to send structured event messages, assign diagnostic event IDs, define verbosity levels, set privacy classifications, and attach custom key-value dimensions.

// Syntax Signature for Session.LogMessage with Custom Dimensions Dictionary
Session.LogMessage(
    EventId: Text, 
    Message: Text, 
    Verbosity: Verbosity, 
    DataClassification: DataClassification, 
    TelemetryScope: TelemetryScope, 
    CustomDimensions: Dictionary of [Text, Text]
);

Core Parameters of Session.LogMessage

1. EventId (Text): A unique, alphanumeric identifier representing the specific business event (e.g., 'CONT-001-SYNCSUCCESS', 'CONT-002-PAYMENTFAILED'). Follow a consistent naming convention with an ISV prefix.
2. Message (Text): A concise, human-readable description explaining what occurred during execution.
3. Verbosity (Enum Verbosity): Specifies the diagnostic severity level of the signal.
4. DataClassification (Enum DataClassification): Declares the privacy classification of the telemetry payload. Must be set to DataClassification::SystemMetadata for unmasked diagnostic transmission.
5. TelemetryScope (Enum TelemetryScope): Controls the routing destination of the telemetry event.
6. CustomDimensions (Dictionary of [Text, Text]): A dynamic map of custom key-value pairs providing structured context (e.g., record counts, response codes, duration, external system IDs).

TelemetryScope Routing Mechanics

The TelemetryScope enum dictates which Azure Application Insights resources receive the signal:

                                  [ Session.LogMessage() ]
                                             │
                                     (TelemetryScope)
                                             │
                     ┌───────────────────────┴───────────────────────┐
                     ▼                                               ▼
       [ TelemetryScope::ExtensionPublisher ]              [ TelemetryScope::All ]
                     │                                               │
                     ▼                                       ┌───────┴───────┐
        [ Extension App Insights ]                           ▼               ▼
       (Configured in app.json)                    [ Extension AI ]   [ Environment AI ]
                                                   (app.json)         (BC Admin Center)

• TelemetryScope::ExtensionPublisher: The telemetry event is dispatched exclusively to the Application Insights connection string declared in the extension's app.json. The customer's tenant administrator cannot see this event in their environment-level Application Insights.
• TelemetryScope::All: The telemetry event is dispatched to both the extension's Application Insights resource (from app.json) and the customer's environment-level Application Insights resource (from the Business Central Admin Center). Use this scope for operational events relevant to tenant administrators (e.g., batch job completion, critical integration failure).

2. The System Application Telemetry & Feature Telemetry Modules

While Session.LogMessage is the low-level runtime API, Microsoft provides high-level telemetry abstractions inside the System Application to standardize logging patterns across extensions.

1. The Telemetry Codeunit Facade

The Telemetry codeunit (Module: Telemetry in System Application) simplifies custom telemetry emission and automatically enriches every logged signal with standard contextual dimensions:

codeunit 50110 "Contoso Carrier Integration"
{
    Access = Internal;

    procedure ProcessShipmentSync(ShipmentNo: Code[20]; RecordCount: Integer)
    var
        Telemetry: Codeunit Telemetry;
        CustomDimensions: Dictionary of [Text, Text];
    begin
        CustomDimensions.Add('ShipmentNo', ShipmentNo);
        CustomDimensions.Add('TotalRecords', Format(RecordCount));
        CustomDimensions.Add('CarrierCode', 'FEDEX');

        Telemetry.LogMessage(
            'CONT-0010',
            'Carrier shipment synchronization completed successfully.',
            Verbosity::Normal,
            DataClassification::SystemMetadata,
            TelemetryScope::All,
            CustomDimensions
        );
    end;
}

2. The Feature Telemetry Codeunit Pattern

To track feature adoption, user onboarding, and feature health across the software lifecycle, Microsoft introduced the Feature Telemetry codeunit. This module standardizes three core telemetry events:

• LogUptake: Records when a user discovers, sets up, or enables a feature (FeatureUptakeStatus::Discovered, Set up, Used).
• LogUsage: Records every time a user or background process actively utilizes the feature.
• LogError: Records expected or unexpected runtime failures occurring within the feature boundary.

local procedure PostECommerceOrder(OrderNo: Code[20])
var
    FeatureTelemetry: Codeunit "Feature Telemetry";
    CustomDims: Dictionary of [Text, Text];
    FeatureNameLbl: Label 'Automated Shopify Connector', Locked = true;
begin
    CustomDims.Add('OrderNo', OrderNo);
    
    // 1. Log feature usage
    FeatureTelemetry.LogUsage('0000-SHOP-01', FeatureNameLbl, 'Order Processing Triggered', CustomDims);
    
    // Execute posting logic...
    if not ExecuteShopifyPost(OrderNo) then begin
        // 2. Log feature error if execution fails
        FeatureTelemetry.LogError('0000-SHOP-02', FeatureNameLbl, 'Posting Failed', 'Gateway timeout on capture', '', CustomDims);
        Error('Failed to post Shopify order %1.', OrderNo);
    end;
end;

3. Verbosity Levels & Diagnostic Hierarchy

The Verbosity enum determines the operational importance of the telemetry signal. Azure Application Insights allows administrators to configure ingestion sampling and log filters based on verbosity levels to manage ingestion costs:

4. Privacy, Compliance & Data Classification

Under global data privacy regulations—such as the General Data Protection Regulation (GDPR) and the California Consumer Privacy Act (CCPA)—developers are legally prohibited from transmitting Personal Identifiable Information (PII) or sensitive customer transactional records into cloud telemetry logging stores.

The DataClassification Enforcement Pipeline

When AL code invokes Session.LogMessage or Telemetry.LogMessage, the runtime inspects the DataClassification parameter:

1. DataClassification::SystemMetadata:
   • Indicates that the message and custom dimensions contain only technical system identifiers, object numbers, execution durations, HTTP status codes, and non-sensitive metadata.
   • The runtime transmits the payload to Azure Application Insights unaltered in plain text.
2. DataClassification::CustomerContent / EndUserIdentifiableInformation:
   • If a developer marks telemetry with CustomerContent or EndUserIdentifiableInformation (or if telemetry contains customer-specific fields), Business Central's cloud compliance engine automatically masks the content with hashes or asterisks (***) prior to transmission.
   • Best Practice Rule: Never attempt to log customer names, email addresses, phone numbers, credit card numbers, or physical street addresses in custom telemetry. Always use DataClassification::SystemMetadata and sanitize all custom dimension values to include only system codes and numeric metrics.

5. Querying Custom Telemetry in KQL

Custom telemetry emitted via Session.LogMessage is stored in the traces table. Developers query custom dimensions by casting dynamic JSON properties into typed KQL variables using tostring(), toint(), and toreal().

// Analyze Custom Integration Sync Events
traces
| where timestamp > ago(7d)
| where customDimensions.eventId startswith 'CONT-'
| extend 
    EventId = tostring(customDimensions.eventId),
    CarrierCode = tostring(customDimensions.CarrierCode),
    TotalRecords = toint(customDimensions.TotalRecords),
    ShipmentNo = tostring(customDimensions.ShipmentNo),
    ExecutionScope = tostring(customDimensions.telemetryScope)
| summarize 
    TotalSyncOperations = count(),
    TotalRecordsProcessed = sum(TotalRecords)
    by CarrierCode, bin(timestamp, 1d)
| render timechart