Fixes AB#3584247: PBI-1 — Broker Telemetry Schema Data Model & Core Interfaces

[Copilot]

Introduces the foundational telemetry schema data model in common4j that replaces the two-timestamp BrokerPerformanceMetrics aggregate with a structured, per-phase event timeline for broker authentication flows.

New package: com.microsoft.identity.common.java.broker.telemetry

• EventTag — 24-entry enum in 6 categories (BrokerEntry, BrokerDispatch, BrokerCache, BrokerNetwork, BrokerResponse, CommonStrategy) with compact @SerializedName values (e.g. "bre.recv")
• ExecutionEvent — single timed event: tag, elapsed ms from flow start, thread ID, optional diagnostic/error codes
• PerformanceRecord — container for the ordered event list plus start time (ISO 8601) and total duration
• TelemetrySchema — top-level schema with correlation ID, auth outcome, device/power metadata, and an embedded PerformanceRecord
• EventCollector — thread-safe accumulator (CopyOnWriteArrayList); timestamps events relative to construction; snapshot via toTelemetrySchema()
• ITelemetrySchemaProvider — var telemetrySchema: TelemetrySchema? interface mirroring IBrokerPerformanceMetricsProvider
• TelemetryHelper — @JvmStatic addEventSafely(collector?, tag, …) null-safe facade

val collector = EventCollector(correlationId)
collector.addEvent(EventTag.BrokerRequestReceived)
collector.addEvent(EventTag.BrokerCacheHit)
val schema: TelemetrySchema = collector.toTelemetrySchema()
// schema.performanceRecord.executionFlow has 2 events; round-trips through Gson cleanly

Modified files

• AcquireTokenResult.java / BaseException.java — implement ITelemetrySchemaProvider; add mTelemetrySchema field with getter/setter following the existing mBrokerPerformanceMetrics pattern
• CommandParameters.java — add @Setter @EqualsAndHashCode.Exclude private transient EventCollector eventCollector (class-level @Getter covers the getter)
• AuthenticationConstants.Broker — add BROKER_TELEMETRY_REQUEST and BROKER_TELEMETRY_SCHEMA IPC bundle key constants

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• dl.google.com
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -XX:MaxMetaspaceSize=1024m -XX:+HeapDumpOnOutOfMemoryError -Xmx3072m -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en -Duser.variant (dns block)
• identitydivision.pkgs.visualstudio.com
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -XX:MaxMetaspaceSize=1024m -XX:+HeapDumpOnOutOfMemoryError -Xmx3072m -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en -Duser.variant (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Fixes AB#3584247

PBI-1: Telemetry Schema Data Model & Core Interfaces

Follow .github/copilot-instructions.md strictly.

Objective

Create the Broker Telemetry Schema data model and core interfaces in common4j. These platform-neutral (no Android dependency) classes represent structured timing data that the broker will emit during authentication flows, enabling client SDKs to surface per-request performance breakdowns.

Target Repository

Field	Value
Repo	AzureAD/microsoft-authentication-library-common-for-android
Base Branch	dev
Module	common4j

Context

Today the broker emits only two aggregate timestamps (BROKER_REQUEST_RECEIVED_TIMESTAMP, BROKER_RESPONSE_GENERATION_TIMESTAMP) via BrokerPerformanceMetrics. The Telemetry Schema feature replaces this with a structured event timeline — a list of tagged timing events capturing each phase of the broker authentication flow. This PBI creates the foundational data model that all subsequent PBIs depend on.

Technical Requirements

All new files go in package com.microsoft.identity.common.java.broker.telemetry within the common4j module.

1. EventTag.kt — Enum of 24 event tags in 6 categories:

kotlin enum class EventTag(@SerializedName("v") val value: String) { // BrokerEntry (5) BrokerRequestReceived("bre.recv"), BrokerRequestDeserialized("bre.dser"), BrokerAccountLookupStart("bre.als"), BrokerAccountLookupEnd("bre.ale"), BrokerRequestValidated("bre.val"), // BrokerDispatch (3) BrokerControllerSelected("bdi.csel"), BrokerCommandQueued("bdi.cq"), BrokerCommandExecutionStart("bdi.cex"), // BrokerCache (6) BrokerCacheCheckStart("bca.cks"), BrokerCacheCheckEnd("bca.cke"), BrokerCacheHit("bca.hit"), BrokerCacheMiss("bca.miss"), BrokerCacheWriteStart("bca.wrs"), BrokerCacheWriteEnd("bca.wre"), // BrokerNetwork (5) BrokerPrtLoadStart("bne.prt"), BrokerNetworkCallStart("bne.ncs"), BrokerNetworkCallEnd("bne.nce"), BrokerTokenAcquired("bne.tok"), BrokerNetworkCallFailed("bne.nfl"), // BrokerResponse (3) BrokerResponseSerialized("brs.ser"), BrokerResponseSent("brs.snt"), BrokerRequestFailed("brs.fail"), // CommonStrategy (2) CommonHttpRequestExecute("cst.hreq"), CommonHttpResponseReceived("cst.hrsp") }

2. ExecutionEvent.kt — Single timed event:

kotlin data class ExecutionEvent( @SerializedName("t") val tag: EventTag, @SerializedName("ts") val timestampMs: Long, @SerializedName("tid") val threadId: Long = Thread.currentThread().id, @SerializedName("d") val diagnosticCode: Int? = null, @SerializedName("e") val errorCode: Int? = null )

3. PerformanceRecord.kt — Aggregation container:

kotlin data class PerformanceRecord( @SerializedName("version") val version: String = "1.0.0", @SerializedName("start_time") val startTime: String, // ISO 8601 UTC @SerializedName("duration") val duration: Long, // ms @SerializedName("execution_flow") val executionFlow: List<ExecutionEvent> )

4. TelemetrySchema.kt — Top-level schema:

kotlin data class TelemetrySchema( @SerializedName("schema_version") val schemaVersion: String = "1.0.0", @SerializedName("correlation_id") val correlationId: String, @SerializedName("name") val name: String? = null, @SerializedName("version") val version: String? = null, @SerializedName("auth_outcome") val authOutcome: String? = null, @SerializedName("error_code") val errorCode: String? = null, @SerializedName("response_starvation_duration") val responseStarvationDuration: Int? = null, @SerializedName("power_policy") val powerPolicy: Boolean? = null, @SerializedName("device_idle") val deviceIdle: Boolean? = null, @SerializedName("perf") val performanceRecord: PerformanceRecord? = null ) { companion object { const val CURRENT_VERSION = "1.0.0" const val MIN_SUPPORTED_MAJOR = 1 } }

5. EventCollector.kt — Thread-safe event accumulator:

`kotlin
class EventCollector(private val correlationId: String) {
private val events = CopyOnWriteArrayList()
private val startTimeMs: Long = System.currentTimeMillis()

fun addEvent(tag: EventTag, diagnosticCode: Int? = null, errorCode: Int? = null) {
    events.add(ExecutionEvent(
        tag = tag,
        timestampMs = System.currentTimeMillis() - startTimeMs,
        diagnosticCode = diagnosticCode,
        errorCode = errorCode
    ))
}

fun toTelemetrySchema(): TelemetrySchema {
    val duration = System.currentTimeMillis() - startTimeMs
    return TelemetrySchema(
        correlationId = correlationId,
        performanceRecord = PerformanceRecord(
            startTime = Instant.ofEpochMilli(startTimeMs).toString(),
            duration = duration,
            executionFlow = events.toList()
        )
  ...

[github-actions]

✅ Work item link check complete. Description contains link AB#3584247 to an Azure Boards work item.

[github-actions]

❌ Invalid work item number: AB#3584247

#. Work item number must be a valid integer.

Click here to learn more.

[github-actions]

❌ Invalid work item number: AB#3584247

#. Work item number must be a valid integer.

Click here to learn more.