The axe DevTools HTML Usage Service
An overview of the usage service, which is a REST service that tracks usage of axe DevTools HTML APIs and the CLI
This article provides an overview of the usage service, a service that allows you to track your usage of axe DevTools APIs and the CLI by sending usage events to either Deque's publicly facing servers or your own server. Sending usage metrics to Deque helps us better understand how our users interact with our products so we can continue to improve them.
Sending usage events to the usage service is a separate process from sending JSON accessibility results to axe Reports. See Reporting with the CLI for more information about reporting.
The usage service consists of two parts:
- A client that posts usage events to the usage service (via the metrics library, typically called by axe DevTools APIs or the CLI)
- A REST service, usually hosted by Deque, that responds to POST requests containing usage events
Usage events contain information about an accessibility scan including date and time of the scan, the number of accessibility rules violated, the names of the rules that were violated, and other information. If you set up your own usage service, you can use the information to give insight into how axe DevTools HTML is being used within your organization. For reference information about the structure of usage events, see The Usage Service Event Reference.
By default, axe DevTools does not record usage information. Usage must be enabled to allow collection of usage metrics. Even when enabled, the usage service does not collect any private or personal information on its users as it was built with privacy in mind.
Quick Start
You can start tracking usage by following these steps:
- Set the environment variable AXE_TRACK_USAGE to true to enable usage tracking. Now whenever you run the CLI or your own code that uses the axe DevTools HTML APIs, usage events will be posted to the Deque REST usage service.
- (Optional) Change the URL of the server where usage events will be reported by changing the AXE_METRICS_URL environment variable (the default URL is
https://usage.deque.com). If you change this environment variable you need to create your own usage service that mimics the public-facing usage service provided by Deque. See Setting up an Echo Server - (Optional) Set AXE_INCLUDE_TEST_RESULTS to true to include test results in the data sent to the usage service. Setting this environment variable will populate the testResults object in the applicationProperties object. See The Usage Service Event Reference for more information.
- (Optional) Set the environment variable AXE_DEV_INSTANCE to true on developers' and testers' machines to allow developer and tester accessibility scans to be filtered out. (Usually you'll want to ignore any API usage that occurred during development or testing work.)
- (Optional) Set any other environment variables to customize the events that will be reported to the usage service. See Controlling the Usage Service via Environment Variables.
- Run your accessibility scanning code or a CLI page scan to send usage to the usage service. All of Deque's APIs use the metrics library to create and post events to the usage service as you've configured it.
For a more in depth tutorial showing how to use the usage service with the axe DevTools APIs, see Getting Started with the Usage Service and the APIs. For the same tutorial showing how to use the CLI with the usage service, see Getting Started with the Usage Service and the CLI. These tutorials include steps to set up your own simple server to echo the usage service events to the console so you can see what the metrics library sends to the usage service. You can use this setup to troubleshoot the usage service.
See Also
For more information about the properties contained in the usage events, see The Usage Service Event Reference.