Telemetry

Basics

To receive telemetry event data from ADAL, a singleton Telemetry object is provided. A reference to this object can be attained by calling Telemetry.getInstance().

Events are published [via the callback pattern] to an IDispatcher interface. Users of this library who wish to receive telemetry data are expected to supply their own implementation of this interface by calling Telemetry#registerDispatcher(IDispatcher, Boolean).

registerDispatcher(IDispatcher, boolean) accepts two arguments:

• IDispatcher dispatcher : the dispatcher implementation to receive telemetry events
• boolean aggregationRequired : flag used to turn aggregation of events on/off

To capture telemetry data, add the following to your application subclass:

// Get a reference to the Telemetry singleton
private static final Telemetry sTelemetry = Telemetry.getInstance();

// Flag to turn event aggregation on/off
private static final boolean sTelemetryAggregationIsRequired = true;
static {
    sTelemetry.registerDispatcher(new IDispatcher() {
        @Override
        public void dispatchEvent(Map<String, String> events) {
            // Events from ADAL will be sent to this callback
              for(Map.Entry<String, String> entry: events.entrySet()) {
                    Log.d(TAG, entry.getKey() + ": " + entry.getValue());
                }
        }
    }, sTelemetryAggregationIsRequired);
}

Personal Identifiable Information (PII) & Organizational Identifiable Information (OII)

By default, ADAL telemetry does not capture or log any PII or OII. The library does allow app developers to turn this on through a setter in the Telemetry class. By turning on PII or OII, the app takes responsibility for safely handling highly-sensitive data and complying with any regulatory requirements.

// By default, PII and OII is not captured

// PII and OII will be captured
sTelemetry.setAllowPii(true);

// PII and OII will NOT be captured 
sTelemetry.setAllowPii(false)

Event Aggregation

Using the aggregationRequired flag, users of ADAL can toggle between two modes of event dispatch: aggregated and non-aggregated. If aggregationRequired is set to true, all events generated per-request are collapsed into a single event prior to dispatch. If false, events are not collapsed prior to dispatch, and users of the library are instead served distinct events representing the various phases of an authentication request.

Please note: Telemetry data is verbose, and applications with large and active user bases generate proportionally large quantities of telemetry data. For this reason, it is advised that users of this library set aggregationRequired == true

Sample Events

Below you will find sample telemetry events - for readability, this data is a presented as JSON, although consumers of this library are free to collect data using other schemas.

Aggregated

{
	"Microsoft.ADAL.correlation_id Value": "f50311ba-7b15-4a28-813b-2f4a77276826",
	"Microsoft.ADAL.is_frt": "",
	"Microsoft.ADAL.login_hint": "+soK2KCefj3mxyJKdO8Z8knXq5jDyp1vaFqgGXoXPlI=",
	"Microsoft.ADAL.is_rt": "",
	"Microsoft.ADAL.tenant_id": "Hh+oQ57BV4gKSp8urSNGyMHFUVZzXuhIJ9QPLQIzHvw=",
	"Microsoft.ADAL.device_id": "gGvkO0ZW1G8yp+ZujF6dle4W1Bkz+peSLEHUsJ7eUSk=",
	"Microsoft.ADAL.application_name": "com.microsoft.aad.adal.sample",
	"Microsoft.ADAL.application_version": "1.0",
	"Microsoft.ADAL.authority_type": "Microsoft.ADAL.aad",
	"Microsoft.ADAL.is_successful": "true",
	"Microsoft.ADAL.authority_validation_status": "Microsoft.ADAL.authority_validation_status_not_done",
	"Microsoft.ADAL.cache_event_count": "1",
	"Microsoft.ADAL.api_id": "104",
	"Microsoft.ADAL.idp": "live.com",
	"Microsoft.ADAL.client_id": "f1048c32-84e4-4833-b8a5-f0a475f1c27a",
	"Microsoft.ADAL.response_time": "128",
	"Microsoft.ADAL.request_id": "6e653e42-a86d-4147-a1ff-f1752fa47f57",
	"Microsoft.ADAL.is_mrrt": "",
	"Microsoft.ADAL.user_id": "+soC2CCefj3mxyJKdO8Z8knXq5jDyp1vaFqgGXoXPlI="
}

Non-aggregated

[{
	"Microsoft.ADAL.stop_time": "1497286400129",
	"Microsoft.ADAL.authority_validation_status": "Microsoft.ADAL.authority_validation_status_not_done",
	"Microsoft.ADAL.correlation_id": "0a24f050-d2c1-4077-8f11-29b9e5985cb7",
	"Microsoft.ADAL.client_id": "f1048c32-84e4-4833-b8a5-f0a475f1c27a",
	"Microsoft.ADAL.start_time": "1497286400129",
	"Microsoft.ADAL.response_time": "0",
	"Microsoft.ADAL.application_name": "com.microsoft.aad.adal.sample",
	"Microsoft.ADAL.device_id": "fFvkO0ZW1G8yp+ZujF6dle4W1Bkz+peSLEHUsJ7eUSk=",
	"Microsoft.ADAL.request_id": "d2c3157c-1746-43f9-8140-04b625dd7c38",
	"Microsoft.ADAL.application_version": "1.0",
	"Microsoft.ADAL.event_name": "Microsoft.ADAL.authority_validation"
}, {
	"Microsoft.ADAL.stop_time": "1497286400239",
	"Microsoft.ADAL.token_type": "Microsoft.ADAL.rt",
	"Microsoft.ADAL.client_id": "f1048c32-84e4-4833-b8a5-f0a475f1c27a",
	"Microsoft.ADAL.start_time": "1497286400133",
	"Microsoft.ADAL.is_rt": "true",
	"Microsoft.ADAL.response_time": "106",
	"Microsoft.ADAL.application_name": "com.microsoft.aad.adal.sample",
	"Microsoft.ADAL.device_id": "gGvkO0ZW1F4yp+ZioF6dle4W1Bkz+peSLEHUsJ7eWEk=",
	"Microsoft.ADAL.request_id": "d2c3157c-1746-43f9-8140-04b625dd7c38",
	"Microsoft.ADAL.application_version": "1.0",
	"Microsoft.ADAL.event_name": "Microsoft.ADAL.token_cache_lookup"
}, {
	"Microsoft.ADAL.stop_time": "1497286400244",
	"Microsoft.ADAL.correlation_id": "0b14f050-d2c1-4077-8f11-29b9e5985cb7",
	"Microsoft.ADAL.login_hint": "+soXlXCefj3mxyJKdO8Z8knXq5jDyp1vaFqgGXoXPlI=",
	"Microsoft.ADAL.tenant_id": "Hh+oW46KV4gKSp8urSNGyMHFUVZzXuhIJ9QPLQIzHvw=",
	"Microsoft.ADAL.application_name": "com.microsoft.aad.adal.sample",
	"Microsoft.ADAL.device_id": "fFvkO0ZW1G8yp+ZujF6dle4W1Bkz+peSLEHUsJ7eUSk=",
	"Microsoft.ADAL.application_version": "1.0",
	"Microsoft.ADAL.event_name": "Microsoft.ADAL.api_event",
	"Microsoft.ADAL.authority_type": "Microsoft.ADAL.aad",
	"Microsoft.ADAL.is_successful": "true",
	"Microsoft.ADAL.api_id": "104",
	"Microsoft.ADAL.idp": "live.com",
	"Microsoft.ADAL.client_id": "f1048c32-84e4-4833-b8a5-f0a475f1c27a",
	"Microsoft.ADAL.authority": "https://login.windows.net/0512f963-2d72-4363-9e3a-5705c5b0f031",
	"Microsoft.ADAL.start_time": "1497286400125",
	"Microsoft.ADAL.response_time": "119",
	"Microsoft.ADAL.request_id": "d2c3157c-1746-43f9-8140-04b625dd7c38",
	"Microsoft.ADAL.user_id": "+soXlXCefj3mxyJKdO8Z8knXq5jDyp1vaFqgGXoXPlI="
}]