Analyzing Incoming Web Services Request Telemetry

INTRODUCED IN: Business Central 2020 release wave 1

Web services telemetry gathers data about SOAP, OData, and API requests through the service. It provides information like the request's endpoint, time to complete, the SQL statements run, and more.

As a developer, you use the data to learn about conditions that you can change to improve performance. The following table provides some examples:

Condition Analysis
A web service request results in a long running SQL query Adjust or fine-tune code.
Web service requests to a specific endpoint read more rows than requests to the other endpoints Consider adding filtering to limit the rows that are read.
Fewer API type requests compared with other types With SOAP and OData requests, computation resources are used on UI elements that aren't relevant. Instead of exposing normal pages as web service endpoints, use the built-in API pages. API pages are optimized for this scenario.
High number of requests to endpoints that include Power BI This condition may indicate excessive Power BI integration.

For more performance guidelines, see Writing efficient Web Services.

Note

Business Central online and on-premises are configured with various limits on web service requests. For example, there is a request timeout and a maximum connections limit. For online, you can't change these limits, but it is helpful to know what the limits are. See Current API Limits. For on-premises, you change the limits on the Business Central Server instance. See Configuring Business Central Server. Web service calls that exceed the timeout limit result in a 408 - Request Timeout. These calls are recorded in Application Insights with a totalTime that is equal to the timeout threshold.

General dimensions

The following table explains the general dimensions included in an incoming Web Services Call trace. The table lists the dimensions that are specific to Business Central.

Dimension Description or value
operation_Name Web Services Call

Note: The use of the operation_Name column was deprecated in version 16.1. In future versions, data won't be stored in this column. So in version 16.1 and later, use the custom dimension column eventID column custom in Kusto queries instead of operation_Name.
message Version 16.1 and later (depending on the type):
  • Web service called (API): {endpoint}
  • Web service called (ODataV4): {endpoint}
  • Web service called (ODataV3): {endpoint}
  • Web service called (SOAP): {endpoint}
Before version 16.1:
  • Received a web service request of type API
  • Received a web service request of type ODataV4
  • Received a web service request of type ODataV3
  • Received a web service request of type SOAP
severityLevel 1

Custom dimensions

The following table explains the custom dimensions included in a Web Services Call trace.

Dimension Description or value
aadTenantId Specifies that Azure Active Directory (Azure AD) tenant ID used for Azure AD authentication. For on-premises, if you aren't using Azure AD authentication, this value is common.
alObjectId Specifies the ID of the AL object that was run by request.[1]
alObjectName Specifies the name of the AL object that was run by the request.[1]
alObjectType Specifies the type of the AL object that was run by the request.[1]
category Specifies the service type. Values include: API, ODataV4, ODataV3, and SOAP.
component Dynamics 365 Business Central Server
componentVersion Specifies the version number of the component that emits telemetry (see the component dimension.)
deprecatedKeys A comma-separated list of all the keys that have been deprecated. The keys in this list are still supported but will eventually be removed in the next major release. We recommend that update any queries that use these keys to use the new key name.
endpoint Specifies the endpoint for the request.
environmentName Specifies the name of the tenant environment. See Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production, Sandbox, Trial. See Environment Types
eventId RT0008

This dimension was introduced in Business Central 2020 release wave 1, version 16.1.
httpHeaders Introduced in version 16.3. Specifies the http headers set in the request. In version 17.3, a truncated version of the Authorization header was introduced to enable querying for the use of basic or token authorization.
httpMethod Introduced in version 16.3. Specifies the HTTP method used in the request. Values include: POST, GET, PUT, PATCH, or DELETE.
httpStatusCode Introduced in version 16.3. Specifies the http status code returned when a request has completed. This dimension further indicates whether request succeeded or not, and why. Use it to verify whether there was an issue with a request even though the request was logged as successful. The dimension displays one of the following values:
  • 200
    OK. The request succeeded.
  • 401
    Access denied. The user who made the request doesn't have proper permissions. For more information, see Web Services Authentication and Assign Permissions to Users and Groups.
  • 404
    Not found. The given endpoint was not valid. For more information, see Publishing a Web Service
  • 408
    Request timed out. The request took longer to complete than the threshold configured for the service. For information about this threshold in Business Central online, see OData request limits. For on-premises, the timeout is determined by the ODataServicesOperationTimeout setting of the Business Central Server. For more information, see Configuring Business Central Server
  • 429
    Too Many Requests. The request exceeded the maximum simultaneous requests allowed on the service. For information about this threshold in Business Central online, see OData request limits. For on-premises, the timeout is determined by the ODataMaxConnections setting of the Business Central Server. For more information, see Configuring Business Central Server


This dimension was introduced in Business Central 2020 release wave 1, version 16.3.
This dimension is not populated for SOAP endpoints.
serverExecutionTime Specifies the amount of time it took the server to complete the request**. The time has the format hh:mm:ss.sssssss.
sqlExecutes Specifies the number of SQL statements that the request executed.[1] [2]
sqlRowsRead Specifies the number of table rows that were read by the SQL statements.[1] [2]
totalTime Specifies the amount of time it took to process the request.[2]

The time has the format hh:mm:ss.sssssss.
telemetrySchemaVersion Specifies the version of the Business Central telemetry schema.

1This dimension isn't relevant for $metadata calls, like https://localhost:7048/BC/ODataV4/$metadata, so it won't be in the trace.

2From telemetrySchemaVersion 0.6 and onwards, this value also includes the CompanyOpen operation.

Example trace

The following code snippet is a CustomDimensions example:

{"telemetrySchemaVersion":"0.6","componentVersion":"16.0.11329.0","environmentType":"Production","deprecatedKeys":"Company name, AL Object Id, AL Object type, AL Object name, AL Stack trace, Client type, Extension name, Extension App Id, Extension version, Telemetry schema version, AadTenantId, Environment name, Environment type, Component, Component version, Telemetry schema version","serverExecutionTime":"00:00:00.3886441","component":"Dynamics 365 Business Central Server","aadTenantId":"common","sqlExecutes":"21","sqlRowsRead":"117","totalTime":"00:00:00.3886441","alObjectType":"Page","alObjectName":"Sales Document Line Entity","alObjectId":"6403","category":"ODataV4","endpoint":"BC/ODataV4/Company()/workflowSalesDocumentLines","httpStatusCode":"200"}

See also

Monitoring and Analyzing Telemetry
Enable Sending Telemetry to Application Insights