If you’re building a Business Central extension, you probably already benefit from the built-in telemetry that the platform sends to Azure Application Insights—long running AL methods, long running operations (SQL), web service calls, report generation times, and more. But what about the things that are specific to your extension? Maybe you need to know when a critical integration call fails, how often users trigger a particular workflow, or which branch of a complex calculation is being hit in production.

That’s where custom telemetry events come in. With a single LogMessage call in your AL code, you can send your own trace signals to Azure Application Insights, giving you visibility into exactly what your extension is doing in the real world. This article walks through how it works, when to use it, and the recommended approach that will save you headaches down the road.

You can find the full code for the example on GitHub.

Telemetry vs. Traditional Event Logging

Before exploring the how, it’s worth understanding the distinction. Traditional event logging—like writing to the Windows event log on a Business Central Server instance—focuses on infrastructure: server errors, deployment issues, performance counters. Telemetry is different. It’s about collecting data on what users are doing inside the application and how your code is behaving in production environments.

Azure Application Insights is the recommended destination for telemetry in Business Central. It works for both online and on-premises deployments, and it gives you powerful querying capabilities through Kusto Query Language (KQL) as well as some other community driven tools such as Waldo’s BC Telemetry Buddy.

Where Telemetry Gets Sent

When you emit a custom telemetry event from your extension, there are two possible destinations:

• Extension publisher’s Application Insights — the Azure Application Insights resource configured in your extension’s app.json file.
• Environment Application Insights — the resource configured by the admin on the Business Central environment itself.

You control which destination receives your events through the TelemetryScope parameter:

• TelemetryScope::ExtensionPublisher — sends the event only to the Application Insights resource defined in your extension’s app.json.
• TelemetryScope::All — sends the event to both the extension’s resource and the environment’s resource.

This scoping is useful. If you’re an ISV, you might want some internal diagnostics to stay in your own Application Insights resource (ExtensionPublisher), while other events—like feature usage or error conditions that an admin should know about—go to both destinations (All).

It’s worth noting that having an Application Insights resource configured in your app.json is not required to use custom telemetry. If you only use TelemetryScope::All, the events will be sent to the environment’s resource (if one is configured).

The LogMessage Method

The core of custom telemetry is Session.LogMessage. There are two overloads—one that accepts a Dictionary of custom dimensions, and one that lets you pass dimension name/value pairs directly as parameters.

Dictionary overload:

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

Dimension overload (up to two dimensions):

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

Both methods can be called from any AL object—Codeunits, pages, reports, triggers, or methods. Let’s break down the parameters.

Understanding the Parameters

A couple of these deserve extra emphasis:

• DataClassification: For privacy reasons, only events with DataClassification::SystemMetadata are sent to Azure Application Insights. If you use any other classification, the event won’t be transmitted. This is by design—it prevents customer data from accidentally leaking into telemetry resources.
• Verbosity: For on-premises deployments, the Diagnostic Trace Level setting on the Business Central Server instance controls which severity levels are sent. If the trace level is set to Warning, then Normal and Verbose signals won’t reach Application Insights.

A Practical Example

Let’s say your extension integrates with an external API and you want to log both successful calls and failures. Here’s how you might structure that:

codeunit 50100 "DVLPR API Integration"
{
    procedure CallExternalApi(Endpoint: Text): Boolean
    var
        Client: HttpClient;
        Response: HttpResponseMessage;
        Dimensions: Dictionary of [Text, Text];
        Success: Boolean;
    begin
        Success := Client.Get(Endpoint, Response);

        Dimensions.Add('Endpoint', Endpoint);
        Dimensions.Add('HttpStatusCode', Format(Response.HttpStatusCode()));
        Dimensions.Add('Success', Format(Success and Response.IsSuccessStatusCode()));

        if Success and Response.IsSuccessStatusCode() then begin
            LogMessage(
                'DVLPR-1001',
                'External API called successfully',
                Verbosity::Normal,
                DataClassification::SystemMetadata,
                TelemetryScope::ExtensionPublisher,
                Dimensions
            );
            exit(true);
        end;

        LogMessage(
            'DVLPR-1002',
            'External API call failed',
            Verbosity::Error,
            DataClassification::SystemMetadata,
            TelemetryScope::All,
            Dimensions
        );
        exit(false);
    end;
}

A few things to notice:

• The success event uses TelemetryScope::ExtensionPublisher because it’s routine operational data the ISV cares about.
• The failure event uses TelemetryScope::All because the environment admin might also want to know about failures.
• Each event has a unique EventId (DVLPR-1001 and DVLPR-1002), which makes it easy to find specific events in Application Insights.
• The Endpoint dimension is included in both calls so you can filter and group by endpoint in KQL queries.

For simpler scenarios, you can skip the dictionary and use the dimension overload:

LogMessage(
    'DVLPR-2001',
    'Order import completed',
    Verbosity::Normal,
    DataClassification::SystemMetadata,
    TelemetryScope::ExtensionPublisher,
    'OrderCount', Format(OrderCount),
    'DurationMs', Format(Duration)
);

This is convenient when you only need one or two dimensions.

What Shows Up in Application Insights

When your event arrives in Azure Application Insights, it lands in the traces table. The Message and Verbosity appear as general dimensions. Everything else appears as custom dimensions.

One important detail: Similar to EventIds, Business Central automatically prefixes your custom dimension keys with al. So if you define a dimension called OrderCount in your AL code, it appears as alOrderCount in Application Insights. Because of this, use PascalCasing for your dimension names—OrderCount, not order_count or order count. This keeps your custom dimensions consistent with how built-in Business Central telemetry dimensions are named.

You also get a set of default dimensions for free on every event, including:

• alObjectId / alObjectName / alObjectType — which object emitted the event.
• extensionName / extensionId / extensionVersion — which extension the event came from.
• environmentName / environmentType — which environment it happened in.
• companyName — which company was active.
• clientType — what type of client triggered the code (Web, Background, API, etc.).

These built-in dimensions are incredibly useful for filtering. You don’t need to add them yourself.

Recommended Approach

The Business Central team treats telemetry event definitions as an API—and you should too. Here are the key practices to follow:

• Use unique EventIds. Every LogMessage call in your code should have a distinct EventId. This makes it trivial to pinpoint where in the code a particular event was emitted. Use a prefix unique to your extension (e.g., DVLPR-, CONTOSO-).
• Follow the “Object ActionInPastTense” pattern for messages. Instead of "Calling API", write "External API called" or "Order import completed". This reads naturally in a KQL query ordered by timestamp. Consider including key dimension values in the message itself so you can scan events without opening custom dimensions every time.
• Don’t use spaces in dimension names. Spaces make KQL queries harder to write. Stick to PascalCase: OrderCount, not Order Count.
• Treat dimension changes as breaking changes. Once your extension is in production and people have built alerts or Power BI reports on your telemetry, renaming or removing a dimension will break their work. Add new dimensions freely, but be cautious about changing existing ones.
• Keep DataClassification as SystemMetadata. Events with any other classification won’t be sent. Review your LogMessage calls to make sure you’re not accidentally including personal or customer data in dimension values.
• Make events actionable. Before adding a telemetry event, ask yourself: “What can someone do with this information?” If the answer isn’t clear, reconsider whether the event is worth adding.
• Don’t over-instrument. Telemetry costs money (Application Insights charges by data volume) and adds overhead. Focus on events that provide diagnostic or usage value. High-frequency loops are not good candidates for telemetry.

Feature Telemetry Module

It’s worth mentioning the Feature Telemetry module from the System Application. This module provides a higher-level abstraction over Session.LogMessage and is particularly useful for tracking feature usage. Instead of calling LogMessage directly, you call FeatureTelemetry.LogUsage or FeatureTelemetry.LogError, and the module handles the event structure for you.

If your primary goal is tracking which features in your extension are being used (and which aren’t), the Feature Telemetry module is often a better fit than raw LogMessage calls. You can learn more about it in the Microsoft documentation on Using Feature telemetry.

Wrapping Up

Custom telemetry events give you a direct window into how your extension behaves in production. With LogMessage, you can emit targeted signals from anywhere in your AL code, control where those signals land through telemetry scoping, and attach rich custom dimensions that make analysis in Application Insights straightforward.

The investment is minimal—a handful of well-placed LogMessage calls—but the payoff is significant. You get real production diagnostics, usage patterns, and error tracking without needing access to the customer’s environment. Start with your most critical code paths (integrations, complex calculations, error handlers) and expand from there.

Learn more:

• Instrumenting an application for telemetry (Microsoft Learn)
• Creating custom telemetry events for Azure Application Insights (Microsoft Learn)
• Using Feature telemetry (Microsoft Learn)

Note: The code and information discussed in this article are for informational and demonstration purposes only. This content was written referencing Microsoft Dynamics 365 Business Central 2025 Wave 2 online. Custom telemetry events via LogMessage are available from Business Central 2020 release wave 2 and later. Always test in a sandbox first.

If you’ve ever worked on a Business Central extension that needs to support multiple “flavors” of the same operation—different shipping providers, different document formats, different pricing strategies—you’ve probably felt the pain of tightly coupled code. Interfaces in AL solve that problem by letting you define a contract (a set of methods) and then swap implementations without touching the calling code.

Interfaces were introduced in Business Central 2020 release wave 1 and have quickly become an important pattern for building extensible, maintainable AL solutions. If you haven’t used them yet, this article walks through what they are, why they matter, and how to build with them.

You can find the full code for the example on GitHub.

What Is an Interface?

An interface is a named object that declares one or more procedure signatures—but contains no implementation. It defines what a Codeunit must do, not how it does it.

interface IDocumentValidator
{
    procedure Validate(var RecRef: RecordRef): Boolean;
}

Any Codeunit that claims to implement IDocumentValidator must provide a concrete body for Validate. The AL compiler enforces this at build time—if a method is missing, you get an error.

Key characteristics:

• An interface contains only procedure declarations (no variables, no triggers, no logic).
• It cannot be instantiated or called directly.
• It acts as a contract between the code that calls a behavior and the code that provides it.

Why You Should Care

• Loose coupling: Your calling code depends on the interface, not on a specific Codeunit. You can swap implementations without modifying callers.
• Extensibility without events: Partners and ISVs can add new behavior by implementing the interface and extending the enum—no event subscriptions needed.
• Polymorphism: You can declare a variable as an interface type and call methods on it. At runtime, the actual implementation executes based on which Codeunit was selected.
• Testability: You can create a “mock” Codeunit that implements the interface for testing purposes.

How It Works: The Three-Part Pattern

Interfaces in AL rely on three cooperating objects:

1. The interface – declares the method signatures.
2. One or more Codeunits – each implements the interface with concrete logic.
3. An enum – ties enum values to specific implementations.

This trio is the standard pattern. The enum is the dispatch mechanism. When you assign an enum value, Business Central knows which Codeunit to run.

Example: A Discount Calculator

Let’s say you want to support multiple discount strategies. Start with the interface:

interface IDiscountCalculator
{
    procedure CalculateDiscount(var SalesLine: Record "Sales Line"): Decimal;
}

Then create two implementations:

Codeunit 50100 "DVLPR Standard Discount" implements IDiscountCalculator
{
    procedure CalculateDiscount(var SalesLine: Record "Sales Line"): Decimal
    begin
        exit(SalesLine."Line Amount" * 0.05); // flat 5%
    end;
}

Codeunit 50101 "DVLPR Volume Discount" implements IDiscountCalculator
{
    procedure CalculateDiscount(var SalesLine: Record "Sales Line"): Decimal
    begin
        if SalesLine.Quantity >= 100 then
            exit(SalesLine."Line Amount" * 0.15)
        else
            exit(SalesLine."Line Amount" * 0.05);
    end;
}

Wire them up through an enum:

enum 50160 "DVLPR Discount Strategy" implements IDiscountCalculator
{
    Extensible = true;

    value(0; Standard)
    {
        Implementation = IDiscountCalculator = "DVLPR Standard Discount";
    }
    value(1; Volume)
    {
        Implementation = IDiscountCalculator = "DVLPR Volume Discount";
    }
}

Now your calling code never needs to know which strategy is active:

procedure ApplyDiscount(Strategy: Enum "DVLPR Discount Strategy"; var SalesLine: Record "Sales Line")
var
    Calculator: Interface IDiscountCalculator;
begin
    Calculator := Strategy;
    SalesLine."Line Discount Amount" := Calculator.CalculateDiscount(SalesLine);
end;

If a partner wants to add a “Loyalty” discount strategy later, they just create a new Codeunit that implements IDiscountCalculator, add an enumextension value, and they’re done. No modifications to your calling code.

Using Existing Interfaces in Business Central

Microsoft already ships several interfaces in the base application and system application. A practical way to get comfortable with interfaces is to implement one that already exists.

For example, the E-Document module defines an E-Document interface. To use it:

1. Find the interface: Use the AL Explorer in VS Code to browse available interfaces.
2. Create a Codeunit that implements the interface.
3. Use the “Implement Interface” quick action in VS Code—hover over the interface name and let the tooling generate empty stubs for all required methods.
4. Extend the corresponding enum with your new value and implementation mapping.

This is a great way to learn the pattern because the plumbing is already in place—you just supply the logic.

Snippet Support

VS Code has a built-in snippet for interfaces. Type tinterface in an AL file and the AL Language extension generates the basic structure for you. This is a quick way to scaffold a new interface and avoid syntax mistakes.

Implementing Multiple Interfaces

A single Codeunit can implement more than one interface:

Codeunit 50164 "DVLPR Multi Provider" implements IDiscountCalculator, IShippingProvider
{
    procedure CalculateDiscount(var SalesLine: Record "Sales Line"): Decimal
    begin
        // discount logic
    end;

    procedure GetShippingRate(Length: Decimal; Width: Decimal; Height: Decimal; Weight: Decimal): Decimal
    begin
        // shipping logic
    end;
}

Be careful with method name collisions. If two interfaces define a method with the same name and signature, the compiler expects a single implementation to satisfy both. If the signatures differ, you’ll get a compile error. The analyzer rules AL0587 and AL0675 help catch these situations.

Type Testing and Casting

Business Central supports type testing and casting operators for interface variables, which allows you to check at runtime whether an interface variable holds a specific implementation:

var
    Calculator: Interface IDiscountCalculator;
begin
    if Calculator is "DVLPR Volume Discount" then
        Message('Volume discount is active');
end;

This is useful when you need conditional logic based on the underlying implementation, though use it sparingly—heavy use of is checks can undermine the polymorphism that interfaces are meant to provide.

Lists and Dictionaries of Interfaces

Starting with Business Central 2025 release wave 1 (runtime 15.0), you can create List and Dictionary collections of interface types:

var    
    MyCircle: Codeunit Circle;
    MySquare: Codeunit Square;
    Shape: Interface IShape;
    Shapes: List of [Interface IShape];    
begin
    Shapes.Add(MyCircle);
    Shapes.Add(MySquare);

    foreach Shape in Shapes do
        Message('Area: %1', Shape.GetArea());
end;

This opens up patterns like maintaining a registry of handlers or processing a collection of implementations in sequence.

Extending Interfaces

Starting with Business Central 2024 release wave 2, interfaces support the extends keyword. This lets you create a new interface that inherits all methods from one or more existing interfaces and adds its own on top. It’s particularly useful for ISVs and partners who want to build on each other’s interfaces without modifying the originals.

The syntax looks like this:

interface IExtendedInterface extends IBaseInterface
{
    procedure AdditionalMethod();
}

Any Codeunit that implements the extended interface must provide concrete implementations for all methods—both those defined in the base interface(s) and any new methods declared in the extension.

A good real-world example is the "Price Calculation" interface in the base application. This interface is the backbone of the extensible pricing system in Business Central. It declares methods like Init, ApplyDiscount, ApplyPrice, GetLine, and others that a pricing handler must implement. The "Price Calculation Handler" enum maps each value to a Codeunit that implements the interface, which is how Business Central decides which pricing engine runs at runtime.

If you needed to extend this pattern—say you wanted a pricing handler that also supports contract-specific pricing—you could define a new interface that extends the original:

interface IContractPriceCalculation extends "Price Calculation"
{
    procedure SetContractNo(ContractNo: Code[20]);
    procedure GetContractDiscount(): Decimal;
}

A Codeunit implementing IContractPriceCalculation would need to provide all the methods from "Price Calculation" plus the two new ones. This means existing code that works with "Price Calculation" continues to work unchanged, while new code can take advantage of the extended contract.

You can also extend multiple interfaces at once:

interface ICombined extends IFirst, ISecond
{
    procedure CombinedMethod();
}

Codeunit 50160 DVLPRCombines implements ICombined
{
    // Must implement IFirst, ISecond, ICombined 
}

Gotchas and Recommended Approach

• Don’t add methods to published interfaces. Once your interface is in production, adding a method breaks every existing implementation. The AppSourceCop rule AS0066 catches this. Use interface extensions (BC 2024 wave 2+) or versioning instead.
• Keep interfaces small and focused. A few related methods per interface is better than one giant interface that tries to cover everything.
• Use meaningful names. Prefix with I (like IAddressProvider) to make interface types immediately recognizable.
• Be aware of circular references. Interfaces, enums, and implementing Codeunits can create circular dependency chains. Rule AL0852 flags this.
• Avoid naming conflicts with built-in procedures. Rule AL0616 catches this, but it’s easy to trip over.
• Document expected behavior. The interface definition alone tells the compiler what methods exist, but not how they should behave. Use XML documentation comments or a companion doc to describe expectations (pre/post conditions, expected error handling, etc.).
• Set Extensible = true on enums when you want partners to add implementations via enum extensions.

Wrapping Up

Interfaces are a powerful pattern available in AL today. They let you design systems where behavior can be extended and swapped without modifying existing code—a core requirement for any healthy extension ecosystem.

The pattern is straightforward: define an interface, implement it in Codeunits, wire it through an enum, and call it polymorphically. Once you see it in action, you’ll find yourself reaching for it any time you need pluggable behavior.

Learn more:

• Interfaces in AL (Microsoft Learn)
• Implement interfaces in Dynamics 365 Business Central (Training module)

You can find the full code for the example on GitHub.

Note: The code and information discussed in this article are for informational and demonstration purposes only. This content was written referencing Microsoft Dynamics 365 Business Central 2025 Wave 2 online. Interfaces are available from Business Central 2020 release wave 1 and later. Always test in a sandbox first.