Analyzing task scheduler telemetry

INTRODUCED IN: Business Central 2021 release wave 2

Task scheduler telemetry gathers information about the execution of scheduled tasks. The data gives insight into what happens in background sessions that are coming from scheduled tasks. It provides information that lets you troubleshoot failures. The data can also help you determine whether tasks would be better scheduled for off hours to limit the load on the service.

For an overview of task scheduler and to understand the flow related to task execution, see Task Scheduler.

Note

In this article, main codeunit refers to the codeunit that's run by the TaskScheduler.CreateTask method.

Each scheduled task is assigned a unique identifier (ID), which is included in each trace related to the task. Using the ID makes it easy to query the flow of a task.

Task created

Occurs when a task was created by a TaskScheduler.CreateTask method call in AL code.

General dimensions

The following table explains the general dimensions of this trace.

DimensionDescription or value
messageTask {taskId} created: {codeunitObjectId} scheduled to run after {notBefore}. Ready to run: {isReady}
severityLevel1

Custom dimensions

DimensionDescription or value
eventIdLC0040
codeunitObjectIdSpecifies the ID of the task's main codeunit.
failureCodeunitObjectIdSpecifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.
isReadySpecifies whether the task was in the ready state when created. True indicates that the task is in the ready state. False indicates that the task isn't in the ready state.
notBeforeSpecifies the earliest date and time the task was scheduled to run.
taskIdSpecifies the unique identifier assigned to the task.
timeoutSpecifies the timeout that was set on the task. If a task takes longer to complete than the specified time, it's canceled. The time has the format hh:mm:ss.sssssss.

Common custom dimensions

The following table explains other custom dimensions that are common to all task scheduler traces.

DimensionDescription or value
aadTenantIdSpecifies 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.
companyNameSpecifies the display name of the Business Central company in which the task was run.
componentDynamics 365 Business Central Server.
componentVersionSpecifies the version number of the component that emits telemetry (see the component dimension.)
environmentTypeSpecifies the environment type for the tenant, such as Production, Sandbox, Trial. Learn more in Environment types.
formatIdSpecifies the regional setting of the session. The value is a locale identifier (LCID), such as 1033 for English - United States.
languageIdSpecifies the language of the session in which the task is run. The value is a locale identifier (LCID), such as 1033 for English - United States.
telemetrySchemaVersionSpecifies the version of the Business Central telemetry schema.

Task ready

Occurs when a task is set to the ready state by a TaskScheduler.SetTaskReady method call in AL code. A task can't be run until it's in the ready state.

General dimensions

The following table explains the general dimensions of this trace.

DimensionDescription or value
messageTask {taskId} ready: {codeunitObjectId} set ready to run after {notBefore}.
severityLevel1

Custom dimensions

DimensionDescription or value
eventIdLC0041
codeunitObjectIdSpecifies the ID of the task's main codeunit.
failureCodeunitObjectIdSpecifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.
isReadyTrue
notBeforeSpecifies the earliest date and time the task was scheduled to run.
taskIdSpecifies the unique identifier assigned to the task.
timeoutSpecifies the timeout that was set on the task. If a task takes longer to complete than the specified time, it's canceled. The time has the format hh:mm:ss.sssssss.
See common custom dimensions

Task removed

Occurs when a task is deleted by a TaskScheduler.CancelTask method call in AL code.

General dimensions

The following table explains the general dimensions of this trace.

DimensionDescription or value
messageTask {taskId} removed: {codeunitObjectId}
severityLevel1

Custom dimensions

DimensionDescription or value
eventIdLC0042
codeunitObjectIdSpecifies the ID of the task's main codeunit.
failureCodeunitObjectIdSpecifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.
isReadySpecifies whether the task was in the ready state when removed. True indicates that the task was in the ready state. False indicates that the task wasn't in the ready state.
notBeforeSpecifies the earliest date and time that was scheduled to run.
taskIdSpecifies the unique identifier assigned to the task.
timeoutSpecifies the timeout that was set on the task. The time has the format hh:mm:ss.sssssss.
See common custom dimensions

Task canceled

Occurs when the execution of a task's main or failure codeunit is canceled by the service or by a user.

For example, the service cancels a task when:

  • It takes longer to complete than the specified timeout. The timeout is specified on the task when it's created. Or if no timeout is specified, then the default timeout of the service is used. For online, the default task timeout is 12 hours. For on-premises, the default timeout is specified by the Default Task Scheduler Session Timeout setting on the Business Central Server instance.
  • The Session.StopSession method was called from AL code.

Users can cancel a task a couple ways. For example, with Business Central online, they can use the Business Central admin center. With on-premises, they can run the Remove-NAVSession cmdlet.

General dimensions

The following table explains the general dimensions of this trace.

DimensionDescription or value
messageThe messages will depend on whether the error occurred in the main codeunit or failure codeunit.

Main codeunit
Task {taskId} main codeunit {codeunitObjectId} canceled. It will not be retried and the failure codeunit {failureCodeunitObjectId} will be run. Reason: Exception is not retriable.

Task {taskId} main codeunit {codeunitObjectId} canceled. It will be retried. Reason: Exception is retriable.

Task {taskId} main codeunit {codeunitObjectId} canceled. It will not be retried. Reason: Exception is retriable but the maximum number of attempts has been reached.

Failure codeunit
Task {taskId} failure codeunit {failureCodeunitObjectId} canceled. It will not be retried. Reason: Exception is not retriable.

Task {taskId} failure codeunit {failureCodeunitObjectId} canceled. It will be retried. Reason: Exception is retriable.

Task {taskId} failure codeunit {failureCodeunitObjectId} canceled. It will not be retried. Reason: Exception is retriable but the maximum number of attempts has been reached.
severityLevel2

Custom dimensions

DimensionDescription or value
eventIdLC0044
attemptNumberSpecifies the run attempt on the codeunit. 0 indicates the first run of the codeunit. Any value other than 0 indicates a retry.
isRunningFailureCodeunitTrue if the failure codeunit was run; otherwise, False.
retryMessageExplains whether the codeunit will be retried and why.
cancelReasonSpecifies why the task was canceled.
cancelReasonMessageSpecifies the exception that caused the cancellation.
codeunitObjectIdSpecifies the ID of the task's main codeunit.
failureCodeunitObjectIdSpecifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.
isReadyTrue
notBeforeSpecifies the earliest date and time the task was scheduled to run.
resultCanceled
serverExecutionTimeSpecifies the amount of time it took the server to run the codeunit. The time has the format hh:mm:ss.sssssss.
sessionIdSpecifies the unique identifier of the session in which the task's codeunit was run.
sqlExecutesSpecifies the number of SQL statements that were executed by the codeunit before the task was canceled.
sqlRowsReadSpecifies the number of table rows that were read by the SQL statements before the task was canceled.
taskIdSpecifies the unique identifier assigned to the task.
timeoutSpecifies the timeout that was set on the task. The time has the format hh:mm:ss.sssssss.
totalTimeSpecifies the amount of time it took before the task was canceled. The time has the format hh:mm:ss.sssssss.
See common custom dimensions

Task failed

Occurs when the execution of a task's main codeunit or failure codeunit fails because of an exception thrown by the AL runtime.

General dimensions

The following table explains the general dimensions of this trace.

DimensionDescription or value
messageThe messages will depend on whether the error occurred in the main codeunit or failure codeunit.

Main codeunit
Task {taskId} main codeunit {codeunitObjectId} failed. It will not be retried and the failure codeunit {failureCodeunitObjectId} will be run. Reason: Exception is not retriable.

Task {taskId} main codeunit {codeunitObjectId} failed. It will be retried. Reason: Exception is retriable.

Task {taskId} main codeunit {codeunitObjectId} failed. It will not be retried. Reason: Exception is retriable but the maximum number of attempts has been reached.

Failure codeunit
Task {taskId} failure codeunit {failureCodeunitObjectId} failed. It will not be retried. Reason: Exception is not retriable.

Task {taskId} failure codeunit {failureCodeunitObjectId} failed. It will be retried. Reason: Exception is retriable

Task {taskId} failure codeunit {failureCodeunitObjectId} failed. It will not be retried. Reason: Exception is retriable but the maximum number of attempts has been reached.
severityLevel3

Custom dimensions

DimensionDescription or value
eventIdLC0045
attemptNumberSpecifies the retry attempt on the codeunit. 0 indicates the initial run of the codeunit, not a retry.
isRunningFailureCodeunitTrue if the failure codeunit was run; otherwise, False.
retryMessageExplains whether the codeunit will be retried and why.
codeunitObjectIdSpecifies the ID of the task's main codeunit.
failureCodeunitObjectIdSpecifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.
failureReasonSpecifies the exception that was thrown as a result of the error.
isReadySpecifies whether the task is in the ready state. True indicates that the task is in the ready state. False indicates that the task isn't in the ready state.
notBeforeSpecifies the earliest date and time that was scheduled to run.
resultFailure
serverExecutionTimeSpecifies the amount of time it took the server to run the codeunit. The time has the format hh:mm:ss.sssssss.
sessionIdSpecifies the unique identifier of the session in which the task's codeunit was run.
sqlExecutesSpecifies the number of SQL statements that were executed before the task failed.
sqlRowsReadSpecifies the number of table rows that were read by the SQL statements before the task failed.
taskIdSpecifies the unique identifier assigned to the task.
timeoutSpecifies the timeout that was set on the task. The time has the format hh:mm:ss.sssssss.
totalTimeSpecifies the amount of time it took to run the codeunit before it failed. The time has the format hh:mm:ss.sssssss.
See common custom dimensions

Analyzing task execution failures

When a task fails, the failureReason field in customDimensions includes the exception that was thrown by the AL runtime.

Sample KQL code (failed tasks)

This KQL code can help you get started analyzing task failures:

// Task failed
traces
| where timestamp > ago(60d) // adjust as needed
| where customDimensions has 'LC0045' // for performance
| where customDimensions.eventId == 'LC0045'
| project timestamp
// in which environment/company did it happen
, aadTenantId = customDimensions.aadTenantId
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType
, companyName = customDimensions.companyName
// what codeunit to run
, codeunitObjectId = customDimensions.codeunitObjectId
, failureCodeunitObjectId = customDimensions.failureCodeunitObjectId
// task info
, formatId = customDimensions.formatId
, isReady = customDimensions.isReady
, languageId = customDimensions.languageId
, notBefore = customDimensions.notBefore
, taskId = customDimensions.taskId
, timeout = customDimensions.timeout
// execution info
, failureReason = customDimensions.failureReason // this contains the name of the exception thrown by the AL runtime

Task completed

Occurs when the execution of a task's main codeunit or failure codeunit succeeds with no errors.

There's no event emitted for task started. You can infer the task-start time by subtracting the totalTime from the task completed timestamp.

General dimensions

The following table explains the general dimensions of this trace.

DimensionDescription or value
messageTask {taskId} main codeunit {codeunitObjectId} completed. - This message indicates that the task was fully executed successfully.

Task {taskId} failure codeunit {failureCodeunitObjectId} completed. - This message indicates that an error occurred in the task, but it was successfully handled by the failure codeunit.
severityLevel1

Custom dimensions

DimensionDescription or value
eventIdLC0043
isRunningFailureCodeunitTrue if the failure codeunit was run; otherwise, False.
attemptNumberSpecifies the retry attempt on the codeunit. 0 indicates the initial run of the codeunit, not a retry.
codeunitObjectIdSpecifies the ID of the task's main codeunit.
failureCodeunitObjectIdSpecifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.
isReadySpecifies whether the task is in the ready state. True indicates that the task is in the ready state. False indicates that the task isn't in the ready state.
notBeforeSpecifies the earliest date and time that was scheduled to run.
resultSuccess
serverExecutionTimeSpecifies the amount of time it took the server to run the codeunit. The time has the format hh:mm:ss.sssssss.
sessionIdSpecifies the unique identifier of the session in which the task was run.
sqlExecutesSpecifies the number of SQL statements that were executed.
sqlRowsReadSpecifies the number of table rows that were read by the SQL statements.
taskIdSpecifies the unique identifier assigned to the task.
timeoutSpecifies the timeout that was set on the task. The time has the format hh:mm:ss.sssssss.
totalTimeSpecifies the amount of time it took to run the codeunit. The time has the format hh:mm:ss.sssssss.
See common custom dimensions

Task timeout changed because it was exceeding the max timeout value

INTRODUCED IN: Version 22.0

Occurs if the timeout defined on a task exceeds the maximum timeout allowed by the server. The task is then assigned the timeout that's equal to the maximum timeout allowed by the server.

Note

The maximum timeout is determined by the MaxTaskSchedulerSessionTimeout setting on the Business Central Server instance. The default maximum is 48 hours. For Business Central on-premises, you can configure this setting. Learn more in Configure Business Central Server.

General dimensions

The following table explains the general dimensions of this trace.

DimensionDescription or value
messageTask {taskId} timeout changed to: {timeout} because it was exceeding the max timeout value.
severityLevel1

Custom dimensions

DimensionDescription or value
eventIdLC0057
codeunitObjectIdSpecifies the ID of the task's main codeunit.
failureCodeunitObjectIdSpecifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.
isReadySpecifies whether the task is in the ready state. True indicates that the task is in the ready state. False indicates that the task isn't in the ready state.
notBeforeSpecifies the earliest date and time the task was scheduled to run.
taskIdSpecifies the unique identifier assigned to the task.
timeoutSpecifies the timeout that was set on the task. The time has the format hh:mm:ss.sssssss.
See common custom dimensions

Task scheduler and performance

Scheduled tasks or job queue entries that are set to run on a recurring schedule can impact the performance of Business Central under either of the following conditions:

  • They run too frequently.

    Consider how often the task or job needs to run. Especially for polling scenarios, you might have better and more performant ways to react, such as using webhooks.

  • They run heavy jobs while many users are also using Business Central.

    Consider running them outside working hours. This might decrease locking and deadlock issues both for users and for the task or job itself.

Task Scheduler
Telemetry overview
Enabling Telemetry
Alert on Telemetry