15.1 Telemetry Configuration & Azure Application Insights

15.1 Telemetry Configuration & Azure Application Insights

Modern enterprise application management requires real-time visibility into runtime performance, system health, and unexpected runtime errors. Dynamics 365 Business Central features native integration with Azure Application Insights, a comprehensive Application Performance Management (APM) service within Microsoft Azure. For the MB-820 exam, developers must understand the telemetry ingestion architecture, manifest configuration properties, diagnostic event schemas, and how to author Kusto Query Language (KQL) queries to diagnose performance bottlenecks and extension errors.

1. Business Central Telemetry Architecture

The Business Central telemetry subsystem is built directly into the Business Central Server (Navision Server Tier - NST). As business logic executes, the runtime automatically emits diagnostic telemetry events covering database operations, web service requests, report executions, user sessions, page render timings, and AL runtime exceptions.

+-----------------------------------------------------------------------+
|                   BUSINESS CENTRAL CLOUD / NST RUNTIME                |
|                                                                       |
|  [AL Runtime Logic]   [Web Service Pipeline]   [Data Access Layer]    |
|          │                      │                       │             |
|          ▼                      ▼                       ▼             |
|   (Custom Signals)       (OData / API Traces)    (SQL Query Timings)  |
|          │                      │                       │             |
|          └──────────────────────┼───────────────────────┘             |
|                                 ▼                                     |
|               [Telemetry Background Emission Queue]                   |
|                    (Asynchronous / Non-Blocking)                      |
+---------------------------------┬-------------------------------------+
                                  │ (Encrypted HTTPS Payload / Ingestion API)
                                  ▼
+-----------------------------------------------------------------------+
|                   AZURE APPLICATION INSIGHTS & LOGS                   |
|                                                                       |
|   - Traces Table (Custom Signals, System Events, Event IDs: RT*, LC*) |
|   - Requests Table (Incoming API & OData Calls, Page Views)           |
|   - Exceptions Table (Unhandled AL Runtime Errors, Call Stacks)       |
|   - Performance Metrics (Execution Duration, SQL Row Counts)          |
+---------------------------------┬-------------------------------------+
                                  │ (Kusto Query Language / KQL)
                                  ▼
+-----------------------------------------------------------------------+
|                 MONITORING, ALERTS & VISUALIZATION                    |
|   - Azure Log Analytics & KQL Workbooks                               |
|   - Azure Monitor Alert Rules (Automated Email / SMS / Webhooks)      |
|   - Power BI Telemetry Performance Dashboards                         |
+-----------------------------------------------------------------------+

Key Architectural Principles

1. Asynchronous Non-Blocking Emission: Telemetry events are buffered in-memory and dispatched to Azure Application Insights over background threads. Emitting telemetry never blocks user transactions, introduces database row locks, or degrades the execution speed of business routines.
2. Tenant Isolation: In multi-tenant cloud environments, telemetry emitted by tenant activities is tagged with tenant identifiers (tenantId, environmentName, environmentType), preventing cross-tenant telemetry leaks.
3. Emission Scopes: Business Central supports two complementary configuration tiers: Environment-Level Telemetry and Extension-Level Telemetry.

2. Configuring Telemetry: Extension vs. Environment Scope

Business Central provides two distinct administrative mechanisms for directing telemetry streams to Azure Application Insights:

1. Extension-Level Telemetry (app.json)

An Independent Software Vendor (ISV) or extension developer can configure telemetry directly within their extension's manifest file (app.json). This ensures that diagnostic signals, performance metrics, and unhandled errors originating exclusively from their extension are streamed directly to the ISV's private Azure Application Insights resource, regardless of where the extension is deployed.

{
  "id": "9c8b7a65-4321-4def-9876-123456789abc",
  "name": "Contoso Advanced Logistics",
  "publisher": "Contoso Solutions Inc.",
  "version": "24.0.1002.0",
  "applicationInsightsConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://eastus-8.in.applicationinsights.azure.com/;LiveEndpoint=https://eastus.livediagnostics.monitor.azure.com/",
  "target": "Cloud",
  "runtime": "13.0"
}

Exam Watchout — Connection String vs. Instrumentation Key: In earlier versions of Business Central, extensions used the applicationInsightsKey property containing a bare GUID instrumentation key. Microsoft has deprecated applicationInsightsKey in favor of applicationInsightsConnectionString. Connection strings are mandatory for modern cloud deployments because they embed regional ingestion endpoints, support Microsoft Entra authentication, and enhance data residency compliance.

2. Environment-Level Telemetry (Business Central Admin Center)

Tenant administrators configure environment-level telemetry within the Business Central Admin Center under the specific environment settings (Application Insights Connection String):

• Scope: Captures all platform-wide events across the entire environment, including all installed extensions (PTEs and AppSource apps), base application posting routines, user logins, report generations, job queue executions, incoming web service calls, database lock timeouts, and capacity metrics.
• Separation of Concerns: The tenant administrator sees full operational telemetry for the entire tenant, while an ISV extension developer only receives telemetry originating from their specific extension package.

3. Standard Telemetry Event Dimensions & Schema

All telemetry events in Azure Application Insights are stored within standard schema tables, with the majority of diagnostic events landing in the traces table. Every record includes standard Application Insights columns alongside rich Business Central contextual metadata encapsulated inside the customDimensions JSON dictionary.

Core Standard Columns in traces

• timestamp (datetime): The precise UTC timestamp when the event was generated on the NST.
• message (string): Human-readable description of the event (e.g., 'Long running SQL statement').
• severityLevel (int): Standard logging severity (0 = Verbose, 1 = Information, 2 = Warning, 3 = Error, 4 = Critical).
• customDimensions (dynamic JSON): Key-value dictionary containing structured metadata emitted by Business Central.

Essential customDimensions Properties

Common Diagnostic Event IDs (Exam Reference)

• RT0005 (Operation exceeded time threshold (SQL query)): Emitted when a single SQL statement exceeds the long-running SQL query threshold — 750 ms in Business Central online.
• RT0018 (Operation exceeded time threshold (AL method)): Emitted when a single AL method exceeds the long-running AL method threshold. Do not confuse it with RT0006, which is report generation.
• RT0006 / RT0007 / RT0011 (Report generation): Capture successful report generation, rendering failures, cancellation, and the "report cancelled but a commit occurred" case, including run duration, dataset rows, and rendering format (RDLC, Word, Excel).
• RT0012 (Database Lock Timeout): Emitted when an AL transaction fails because it was blocked waiting for a SQL table/row lock held by another session.
• RT0008 (Web service called): Captures incoming OData, SOAP, and API request durations, HTTP status codes, and endpoint paths. Outgoing calls from AL HttpClient are RT0019. (RT0001–RT0004 are authorization events, not web-service events.)
• LC0020 / LC0021 (Extension compiled successfully / failed to compile): Emitted during automated cloud platform update validation. LC0020 is the success signal; LC0021 is the failure you alert on, alongside LC0023 (Extension failed to update).

4. Kusto Query Language (KQL) for Operational Diagnostics

Developers analyze Business Central telemetry in Azure Log Analytics using Kusto Query Language (KQL). KQL provides powerful pipeline operators (|) for filtering, extracting JSON properties from customDimensions, aggregating metrics, and formatting results.

KQL Query 1: Identifying Long-Running SQL Statements (RT0005)

This query identifies the top 10 slowest database queries over the last 24 hours, parses the execution duration and SQL statements, and groups them by offending AL object.

traces
| where timestamp > ago(24h)
| where customDimensions.eventId == 'RT0005'
| extend 
    EventId = tostring(customDimensions.eventId),
    ExecutionTimeMs = toint(customDimensions.executionTime),
    AlObjectType = tostring(customDimensions.alObjectType),
    AlObjectName = tostring(customDimensions.alObjectName),
    AlObjectId = toint(customDimensions.alObjectId),
    ExtensionName = tostring(customDimensions.extensionName),
    SqlStatement = tostring(customDimensions.sqlStatement)
| project timestamp, ExecutionTimeMs, ExtensionName, AlObjectType, AlObjectName, AlObjectId, SqlStatement
| order by ExecutionTimeMs desc
| take 10

KQL Query 2: Tracking Database Lock Timeouts (RT0012)

Database lock timeouts cause disruptive runtime exceptions for end users. This query groups lock timeouts by the locked table and offending AL call stack to pinpoint concurrency bottlenecks.

traces
| where timestamp > ago(7d)
| where customDimensions.eventId == 'RT0012'
| extend 
    TableName = tostring(customDimensions.tableName),
    AlObjectId = toint(customDimensions.alObjectId),
    AlObjectName = tostring(customDimensions.alObjectName),
    AlStackTrace = tostring(customDimensions.alStackTrace),
    ExtensionName = tostring(customDimensions.extensionName)
| summarize LockTimeoutCount = count() by TableName, AlObjectName, ExtensionName
| order by LockTimeoutCount desc

KQL Query 3: Monitoring Unhandled Extension Runtime Errors

Unhandled AL exceptions degrade user experience and trigger customer support escalations. This query extracts unhandled errors from the traces table where severity level is 3 (Error) or 4 (Critical):

traces
| where timestamp > ago(24h)
| where severityLevel >= 3
| extend 
    EventId = tostring(customDimensions.eventId),
    ExtensionName = tostring(customDimensions.extensionName),
    AlObjectId = toint(customDimensions.alObjectId),
    AlObjectName = tostring(customDimensions.alObjectName),
    StackTrace = tostring(customDimensions.alStackTrace)
| project timestamp, message, ExtensionName, AlObjectType = customDimensions.alObjectType, AlObjectName, StackTrace
| order by timestamp desc