title | description | author | ms.topic | ms.devlang | ms.search.keywords | ms.date | ms.author | ms.reviewer |
---|---|---|---|---|---|---|---|---|
Analyzing Task Scheduler Telemetry |
Learn about the task scheduler telemetry in Business Central |
jswymer |
conceptual |
al |
administration, tenant, admin, environment, sandbox, telemetry |
12/15/2023 |
jswymer |
jswymer |
[!INCLUDE2021_releasewave2.md]
[!INCLUDEazure-ad-to-microsoft-entra-id]
[!INCLUDEtask_scheduler_telemetry]
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.
Occurs when a task was created by a TaskScheduler.CreateTask
method call in AL code.
The following table explains the general dimensions of this trace.
Dimension | Description or value |
---|---|
message | Task {taskId} created: {codeunitObjectId} scheduled to run after {notBefore}. Ready to run: {isReady} |
severityLevel | 1 |
Dimension | Description or value |
---|---|
eventId | LC0040 |
codeunitObjectId | Specifies the ID of the task's main codeunit. |
failureCodeunitObjectId | Specifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit. |
isReady | Specifies 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. |
notBefore | Specifies the earliest date and time the task was scheduled to run. |
taskId | Specifies the unique identifier assigned to the task. |
timeout | Specifies 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. |
The following table explains other custom dimensions that are common to all task scheduler traces.
Dimension | Description or value |
---|---|
aadTenantId | Specifies 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. |
companyName | Specifies the display name of the [!INCLUDEprod_short] company in which the task was run. |
component | Dynamics 365 Business Central Server. |
componentVersion | Specifies the version number of the component that emits telemetry (see the component dimension.) |
environmentType | Specifies the environment type for the tenant, such as Production, Sandbox, Trial. See Environment Types |
formatId | Specifies the regional setting of the session. The value is a culture identifiers (LCIDs), such as 1033 for English - United States. |
languageId | Specifies the language version of Business Central on which the task is run. The value is a culture identifiers (LCIDs), such as 1033 for English - United States. |
telemetrySchemaVersion | Specifies the version of the [!INCLUDEprod_short] telemetry schema. |
Occurs when a task is set to the ready state by TaskScheduler.SetTaskReady method call in AL code. A task can't be run until it's in the ready state.
The following table explains the general dimensions of this trace.
Dimension | Description or value |
---|---|
message | Task {taskId} ready: {codeunitObjectId} set ready to run after {notBefore}. |
severityLevel | 1 |
|Dimension|Description or value| |---------|-----|-----------| |eventId|LC0041| |codeunitObjectId|Specifies the ID of the task's main codeunit.| |failureCodeunitObjectId|Specifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.| |isReady|True| |notBefore|Specifies the earliest date and time that was scheduled to run.| |taskId|Specifies the unique identifier assigned to the task.| |timeout|Specifies 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||
Occurs when a task is deleted by a TaskScheduler.CancelTask method call in AL code.
The following table explains the general dimensions of this trace.
Dimension | Description or value |
---|---|
message | Task {taskId} removed: {codeunitObjectId}. |
severityLevel | 1 |
|Dimension|Description or value| |---------|-----|-----------| |eventId|LC0042| |codeunitObjectId|Specifies the ID of the task's main codeunit.| |failureCodeunitObjectId|Specifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.| |isReady|Specifies 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.| |notBefore|Specifies the earliest date and time that was scheduled to run.| |taskId|Specifies the unique identifier assigned to the task.| |timeout|Specifies the timeout that was set on the task. The time has the format hh:mm:ss.sssssss.| |See common custom dimensions||
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.
The following table explains the general dimensions of this trace.
Dimension | Description or value |
---|---|
message | The messages will depend on whether the error occurred in the main codeunit of 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. |
severityLevel | 2 |
|Dimension|Description or value| |---------|-----|-----------| |eventId|LC0044| |attemptNumber|Specifies the run attempt on the codeunit. 0 indicates the first run of the codeunit. Any value other than 0 indicates a retry.| |cancelReason|Specifies why the task was canceled.| |cancelReasonMessage|Specifies the exception that caused the cancellation.| |codeunitObjectId|Specifies the ID of the task's main codeunit.| |failureCodeunitObjectId|Specifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.| |isReady|True| |notBefore|Specifies the earliest date and time to the task was scheduled to run.| |result|Canceled | |serverExecutionTime|Specifies the amount of time it took the server to run the codeunit. The time has the format hh:mm:ss.sssssss.| |sessionId|Specifies the unique identifier of the session in which the task's codeunit was run.| |sqlExecutes|Specifies the number of SQL statements that were executed by the codeunit before the task was canceled.| |sqlRowsRead|Specifies the number of table rows that were read by the SQL statements before the task was canceled.| |taskId|Specifies the unique identifier assigned to the task.| |timeout|Specifies the timeout that was set on the task. The time has the format hh:mm:ss.sssssss.| |totalTime|Specifies the amount of time it took before the task was canceled. The time has the format hh:mm:ss.sssssss.| |See common custom dimensions||
Occurs when the execution of task's main codeunit or failure codeunit fails because of an exception thrown by the AL runtime.
The following table explains the general dimensions of this trace.
Dimension | Description or value |
---|---|
message | The messages will depend on whether the error occurred in the main codeunit ot 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 {codeunitObjectId} 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. |
severityLevel | 3 |
|Dimension|Description or value| |---------|-----|-----------| |eventId|LC0045| |attemptNumber|Specifies the retry attempt on the codeunit. 0 indicates the initial run of the codeunit, not a retry.| |codeunitObjectId|Specifies the ID of the task's main codeunit.| |failureCodeunitObjectId|Specifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.| |failureReason|Specifies the exception that thrown as a result of the error.| |isReady|Specifies 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.| |notBefore|Specifies the earliest date and time that was scheduled to run.| |result|Failure | |serverExecutionTime|Specifies the amount of time it took the server to run the codeunit. The time has the format hh:mm:ss.sssssss.| |sessionId|Specifies the unique identifier of the session in which the task's codeunit was run.| |sqlExecutes|Specifies the number of SQL statements that were executed before the task failed.| |sqlRowsRead|Specifies the number of table rows that were read by the SQL statements before the task failed.| |taskId|Specifies the unique identifier assigned to the task.| |timeout|Specifies the timeout that was set on the task. The time has the format hh:mm:ss.sssssss.| |totalTime|Specifies the amount of time it took to create the company. The time has the format hh:mm:ss.sssssss.| |See common custom dimensions||
When a task fails, the failureReason
column in the CustomDimensions will include the name of the exception that was thrown by the AL runtime.
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
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.
The following table explains the general dimensions of this trace.
Dimension | Description or value |
---|---|
message | Task {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. |
severityLevel | 1 |
|Dimension|Description or value| |---------|-----|-----------| |eventId|LC0043| |attemptNumber|Specifies the retry attempt on the codeunit. 0 indicates the initial run of the codeunit, not a retry.| |codeunitObjectId|Specifies the ID of the task's main codeunit.| |failureCodeunitObjectId|Specifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.| |isReady|Specifies 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.| |notBefore|Specifies the earliest date and time that was scheduled to run.| |result| Success| |serverExecutionTime|Specifies the amount of time it took the server to run the codeunit. The time has the format hh:mm:ss.sssssss.| |sessionId|Specifies the unique identifier of the session in which the task was run.| |sqlExecutes|Specifies the number of SQL statements that were executed.| |sqlRowsRead|Specifies the number of table rows that were read by the SQL statements.| |taskId|Specifies the unique identifier assigned to the task.| |timeout|Specifies the timeout that was set on the task. The time has the format hh:mm:ss.sssssss.| |totalTime|Specifies the amount of time it took to run the codeunit. The time has the format hh:mm:ss.sssssss.| |See common custom dimensions||
INTRODUCED IN: Version 22.0
Occurs if the timeout defined on a task exceeds that 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
For Business Central online, the maximum timeout allowed is 23:59:59. For Business Central on-premises, the maximum timeout allowed is determined by the MaxTaskSchedulerSessionTimeout
setting on the Business Central server instance (for more information, see Configure Business Central Server.
The following table explains the general dimensions of this trace.
Dimension | Description or value |
---|---|
message | Task {taskId} timeout changed to: {timeout} because it was exceeding the max timeout value. |
severityLevel | 1 |
|Dimension|Description or value| |---------|-----|-----------| |eventId|LC0057| |attemptNumber|Specifies the retry attempt on the codeunit. 0 indicates the initial run of the codeunit, not a retry.| |codeunitObjectId|Specifies the ID of the task's main codeunit.| |failureCodeunitObjectId|Specifies the ID of the task's failure codeunit. 0 indicates that there's no failure codeunit.| |isReady|Specifies 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.| |notBefore|Specifies the earliest date and time that was scheduled to run.| |result| Success| |serverExecutionTime|Specifies the amount of time it took the server to run the codeunit. The time has the format hh:mm:ss.sssssss.| |sessionId|Specifies the unique identifier of the session in which the task was run.| |sqlExecutes|Specifies the number of SQL statements that were executed.| |sqlRowsRead|Specifies the number of table rows that were read by the SQL statements.| |taskId|Specifies the unique identifier assigned to the task.| |timeout|Specifies the timeout that was set on the task. The time has the format hh:mm:ss.sssssss.| |totalTime|Specifies the amount of time it took to run the codeunit. The time has the format hh:mm:ss.sssssss.| |See common custom dimensions||
[!INCLUDEtask_job_queue_performance]
Task Scheduler
Telemetry overview
Enabling Telemetry
Alert on Telemetry