The Axe DevTools for Web Usage Service

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.

The usage service consists of two parts:

1. A client that posts usage events to the usage service (via the metrics library, typically called by Axe DevTools APIs or the CLI)
2. 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 for Web is being used within your organization. For reference information about the structure of usage events, see The Usage Service Event Reference.

Quick Start

You can start tracking usage by following these steps:

1. Confirm that usage tracking is enabled. It is enabled by default, so unless you have set AXE_TRACK_USAGE to false, usage events are already being posted to the Deque REST usage service whenever you run the CLI or your own code that uses the Axe DevTools for Web APIs.
2. (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
3. (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. This variable is supported by the CLI and the Node.js APIs only. See The Usage Service Event Reference for more information.
4. (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.)
5. (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.
6. 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.

Viewing Your Usage Data in Axe Reports

If your organization uses Axe Reports, its usage metrics (the Usage by Month and Scanned URLs reports) are populated from the usage events described in this article. They are not populated by the JSON accessibility results you upload with the CLI's bulk-reports subcommand: sending usage events and uploading results are separate processes.

For your scans to appear in the Axe Reports usage metrics, each machine that runs a scan needs the following:

1. Usage tracking left enabled: it is on by default, so make sure AXE_TRACK_USAGE is not set to false and that --enable-tracking false is not passed to the CLI.
2. Usage events sent to Deque's public usage service: leave AXE_METRICS_URL at its default of https://usage.deque.com. If you point the client at your own server, Deque never receives the events and Axe Reports has nothing to display.
3. AXE_ORGANIZATION set to your organization's ID. Axe Reports uses this value to associate usage events with your organization; without it, your events can't be matched to your account.
4. AXE_USER_ID set to an identifier for the person running the scan, such as an email address. Axe Reports counts unique users from this value.
5. (Optional) AXE_DEPARTMENT set to the scanning user's department. The Usage by Month report can group usage by department; events without this variable are grouped under No Department.

For example, using the CLI:

AXE_TRACK_USAGE=true AXE_ORGANIZATION=<your-organization-id> AXE_USER_ID=name@example.com axe https://broken-workshop.dequelabs.com/

The usage metrics are available only to Axe Reports administrators, and only for organizations whose Axe Reports access includes Axe DevTools for Web. For information about reading the reports themselves, see Working with Usage Reports in the Axe Reports documentation.

Environment Variables

You can use environment variables to control how the usage service operates and to customize the events it reports. Environment variables fall into two categories:

• Usage service control: Enable or disable usage tracking, set the reporting URL, include test results in event data, and set the user's distinct ID.
• Event customization: Modify the properties on the usage events sent to the service, such as the user's organization, department, job role, and other identifying information.

For a complete reference of all available environment variables, see Controlling the Usage Service via Environment Variables.

See Also

For more information about the properties contained in the usage events, see The Usage Service Event Reference.

For a reference of the environment variables available to control the usage service and customize events, see Controlling the Usage Service via Environment Variables.

For information about reading the usage metrics in Axe Reports, see Working with Usage Reports in the Axe Reports documentation.