Skill: AL Telemetry Implementation

Validation Gates

1. After Step 3: Telemetry Logger registered (check OnRegisterTelemetryLogger fires)
2. After Step 5: Events appear in Application Insights within 5 minutes
3. Final: KQL query returns your custom eventIds with correct dimensions

Key Concept

EventId prefix: Platform adds AL automatically → Code: APP-0001 → App Insights: ALAPP-0001

Procedure

Step 1: Configure Application Insights

In app.json:

{
  "applicationInsightsConnectionString": "InstrumentationKey=xxx;IngestionEndpoint=https://xxx.applicationinsights.azure.com/;..."
}

Get connection string from: Azure Portal → Application Insights → Overview → Connection String

Step 2: Choose Telemetry Method

Step 3: Create Telemetry Logger (Required for Feature Telemetry)

CRITICAL: Exactly ONE per publisher!

codeunit <ID> "<PREFIX> Telemetry Logger" implements "Telemetry Logger"
{
    Access = Internal;

    procedure LogMessage(
        EventId: Text;
        Message: Text;
        Verbosity: Verbosity;
        DataClassification: DataClassification;
        TelemetryScope: TelemetryScope;
        CustomDimensions: Dictionary of [Text, Text])
    begin
        Session.LogMessage(EventId, Message, Verbosity, DataClassification,
            TelemetryScope, CustomDimensions);
    end;

    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Telemetry Loggers",
        'OnRegisterTelemetryLogger', '', true, true)]
    local procedure OnRegisterTelemetryLogger(var Sender: Codeunit "Telemetry Loggers")
    var
        TelemetryLogger: Codeunit "<PREFIX> Telemetry Logger";
    begin
        Sender.Register(TelemetryLogger);
    end;
}

Step 4: Define EventId Convention

Format: <PREFIX>-<NNNN> (with hyphen to distinguish from BC standard)

Organization by Range:

Example Registry:

Step 5: Implement Logging

Using Feature Telemetry (Recommended)

var
    FeatureTelemetry: Codeunit "Feature Telemetry";
    CustomDimensions: Dictionary of [Text, Text];
begin
    // Replace <Record> and field names with your source record
    CustomDimensions.Add('<KeyFieldName>', <Record>."<KeyField>");
    CustomDimensions.Add('<RelatedFieldName>', <Record>."<RelatedField>");

    FeatureTelemetry.LogUsage('<PREFIX>-0001', '<FeatureName>', '<OperationDescription>', CustomDimensions);

    FeatureTelemetry.LogError('<PREFIX>-0002', '<FeatureName>', '<OperationDescription>',
        GetLastErrorText(), GetLastErrorCallStack(), CustomDimensions);

    FeatureTelemetry.LogUptake('<PREFIX>-0010', '<FeatureName>',
        Enum::"Feature Uptake Status"::Used);
end;

Using Session.LogMessage (Direct)

var
    CustomDimensions: Dictionary of [Text, Text];
begin
    // Replace <Record> and field names with your source record
    CustomDimensions.Add('<KeyFieldName>', <Record>."<KeyField>");
    CustomDimensions.Add('Operation', '<OperationName>');

    Session.LogMessage('<PREFIX>-0001', '<LogMessage>', Verbosity::Normal,
        DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher, CustomDimensions);
end;

Step 6: Hybrid Logging (Telemetry + Local Table)

For API integrations, use both:

1. Telemetry: Synthetic data for monitoring/alerts
2. Local Table: Complete JSON for debugging

See BC-Telemetry-Guide.md Section 14 for complete implementation.

Step 7: Query in Application Insights

Basic KQL Query:

traces
| where timestamp > ago(24h)
| where customDimensions.eventId startswith "AL<PREFIX>-"
| project
    timestamp,
    eventId = tostring(customDimensions.eventId),
    message,
    customDimensions
| order by timestamp desc

Note: Remember the AL prefix rule from Key Concept when searching in App Insights.

Important Notes

DataClassification: ALWAYS use SystemMetadata - other values won't be sent!

TelemetryScope: ExtensionPublisher = only your App Insights | All = yours AND customer's

Multi-App: ONE Telemetry Logger per publisher. Distinguish apps via alCallerAppName dimension.

Job Queue and Scheduled Task Telemetry

Job Queue entries trigger Scheduled Tasks at platform level. Key event IDs:

• Job Queue (AL): AL0000E24 (Enqueued), AL0000E25 (Started), AL0000E26 (Success), AL0000HE7 (Failure)
• Scheduled Task (LC): LC0040-LC0045, LC0057 (Created → Failed → Timeout)

Correlate via alScheduledTaskId dimension in AL0000E24.

See references/job-queue-telemetry.md for complete event tables and KQL queries.

Troubleshooting

Feedback loop: Fix configuration → Re-deploy → Wait 5 minutes → Re-check in App Insights.

References

See references/ folder for:

• kql-queries.md - Common KQL queries
• job-queue-telemetry.md - Job Queue and Scheduled Task monitoring

External Documentation

BC Telemetry:

• Microsoft: Telemetry Overview
• Microsoft: Telemetry Event IDs
• Microsoft: Feature Telemetry
• Microsoft: Custom Telemetry Events
• Microsoft: Task Scheduler
• BCTech Samples & KQL Queries

KQL Learning:

• MustLearnKQL - 21-part KQL tutorial series (Sentinel-focused but KQL syntax is universal)