Edit

Analytics best practices

  • Article

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Analytics is the reporting platform for Azure DevOps, which allows you to gain insights from your data and make data-driven decisions. Analytics is optimized for fast read-access and server-based aggregations, and it provides various tools to visualize and analyze your data. In this article, we share some best practices for using Analytics in Azure DevOps.

Prerequisites

  • To view Analytics data and query the service, you need to be a member of a project with Basic access or greater. By default, all project members are granted permissions to query Analytics and define Analytics views.
  • To learn about other prerequisites regarding service and feature enablement and general data tracking activities, see Permissions and prerequisites to access Analytics.

Get familiar with the Analytics metadata

Query the Analytics metadata to gain familiarity with the entity types, entity sets, properties, and enumerated lists. For more information, see Query the Analytics service, Analytics OData metadata, and Entities and properties reference for Azure Boards.

Structure your query to return the data you need

To query the minimum data set you need to create your report, follow these practices:

Choose the entity set to support your report

While there are several EntitySets supported in the Analytics data model, only a few are used to generate reports.EntitySets used to build reports fall into three categories:

  • Current: Contains information about the current configuration of the EntityTypes contained within the EntitySet.
  • Snapshot: Composite entities that combine historical and date-related data. Snapshot entities are intended to be used to support aggregation reports.
  • Revision: Contains historical information. For example, WorkItemRevision maintains data about the history of work items.

Here's a quick reference for the EntityTypes to specify to support reports. For a description of each of these EntityTypes, see Data model for Analytics.

Azure DevOps data Current Snapshot Revision
Azure Boards WorkItems WorkItemSnapshot
WorkItemBoardSnapshot		 WorkItemRevisions
Azure Pipelines Pipelines
PipelineTasks		 ParallelPipelineJobsSnapshot
PipelineRuns, PipelineRunActivityResults
Azure Pipelines and Tests TestResultsDaily TestRuns
Azure Test Plans Tests
TestConfiguration
TestPoints
WorkItems		 TestResultsDaily
TestPointHistorySnapshot

Specify query parts in the order they're executed

The recommended order for the various query parts is to specify them in the following order, which is the order in which they're evaluated. For a description of each query part, see Query the Analytics service, Query options.

  1. $apply
  2. $filter
  3. $orderby
  4. $expand
  5. $select
  6. $skip
  7. $top

All queries must contain an $apply or $select clause, otherwise you might receive a warning message.

Limit the columns you request in your query

You specify columns of data to return using the $select clause. With customization, work items can have numerous fields associated with them. The more properties or fields that a query references, the more expensive it's to process. Consider the report you want to generate and make sure you're only requesting the fields you need.

For example, to return the ID, Work Item Type, Title, and State fields for a filtered set of work items, specify the following $select clause: $select=WorkItemId, WorkItemType, Title, State.

To look up the list of properties and their corresponding field names, see Entities and properties reference for Azure Boards.

Create preview queries

Preview queries are queries that return a single record or small subset of records. By creating a preview query, you can refine your query to ensure that you're requesting the data that you need. By starting with a minimal query, you can build up your query to ensure that you're specifying the records you want and the column data you need.

By using the apply=aggregate($count as Count), you can identify the number of records you're requesting. For example, the following syntax queries the number of work items for the Fabrikam Fiber project.

https://analytics.dev.azure.com/content-learn/Content/_odata/v4.0-preview/WorkItems? $apply=aggregate($count as Count)

The response returns a total of 1415 work items.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam Fbier/_odata/v4.0-preview/$metadata#WorkItems(Count)",
   "value": [
  {
     "@odata.id": null,
   "Count": 1415
  }
  ]
}

Limit queries to projects you have access to

Project-scope queries return information about a single project, whereas organization-scope queries are designed to return information that cross project boundaries. Organization scoped queries require broader user permissions or careful scoping restrictions to ensure that your query isn't blocked due to a lack of project permissions.

If you have access to one or more projects, but not all projects, and you submit an organization-scoped query, you receive an error message.

"VS403496: The query results include data in one or more projects for which you do not have access. Add one or more projects filters to specify the project(s) you have access to in 'WorkItems' entity. If you're using $expand or navigation properties, project filter is required for those entities. More information can be found here: https://go.microsoft.com/fwlink/?LinkId=786441."

To learn more, see Project and organization-scoped queries.

Review warning and error messages

Analytics reviews each query it receives for violations to its rules. It returns warning messages when it detects a violation. We recommend that you review these messages to correct or improve the query structure.

Rate limits and throttling

Queries made to Analytics for Azure DevOps Services are subject to rate limits. If too many queries are sent that request the return of large amounts of data within a short time frame, the service might be subject to throttling. For more information, see Rate and usage limits.

You can review usage for the service and for individuals by going to Organization Settings>Usage and exercising the filters. For example, the following image shows the usage by Jamal Hartnett to the Analytics service.

Screenshot of Usage page for a single user and Analytics.