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

[Copilot]

Replaces the two-timestamp BrokerPerformanceMetrics approach with a structured event timeline. This PBI establishes the foundational data model in common4j that all subsequent telemetry PBIs depend on.

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

• EventTag — 24-entry enum across 6 flow categories (BrokerEntry, BrokerDispatch, BrokerCache, BrokerNetwork, BrokerResponse, CommonStrategy) with compact @SerializedName values (e.g. "bre.recv")
• ExecutionEvent — single timed event: tag, relative elapsed timestampMs, threadId, optional diagnosticCode/errorCode
• PerformanceRecord — ordered executionFlow list with startTime (ISO-8601 UTC) and total duration
• TelemetrySchema — top-level envelope: correlationId, auth outcome, power/idle policy flags, nested PerformanceRecord
• EventCollector — thread-safe accumulator (CopyOnWriteArrayList); timestamps are relative elapsed ms from construction
• ITelemetrySchemaProvider — Kotlin var interface (generates getter+setter for Java consumers), mirrors IBrokerPerformanceMetricsProvider
• TelemetryHelper — null-safe @JvmStatic utility; addEventSafely(null, tag) is a no-op

val collector = EventCollector(correlationId)
collector.addEvent(EventTag.BrokerRequestReceived)
collector.addEvent(EventTag.BrokerCacheHit)
val schema: TelemetrySchema = collector.toTelemetrySchema()
// schema round-trips cleanly through Gson

Modified files

• AcquireTokenResult.java / BaseException.java — both now implement ITelemetrySchemaProvider; field + getter/setter follow the mBrokerPerformanceMetrics pattern
• CommandParameters.java — adds @EqualsAndHashCode.Exclude transient EventCollector eventCollector with @Setter
• AuthenticationConstants.Broker — adds BROKER_TELEMETRY_REQUEST and BROKER_TELEMETRY_SCHEMA IPC bundle key constants

Tests

EventCollectorTest covers thread safety (50-thread concurrent writes), null-safety via TelemetryHelper, and event ordering. TelemetrySchemaSerializationTest validates Gson round-trips for all 24 EventTag values and all nested types, including compact field names.

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)
• www.puppycrawl.com
  • Triggering command: /opt/hostedtoolcache/CodeQL/2.25.1/x64/codeql/tools/linux64/java/bin/java /opt/hostedtoolcache/CodeQL/2.25.1/x64/codeql/tools/linux64/java/bin/java -jar /opt/hostedtoolcache/CodeQL/2.25.1/x64/codeql/xml/tools/xml-extractor.jar --fileList=/tmp/codeql-scratch-b2678d0398b00160/dbs/java/working/files-to-index11938045826808067935.list --sourceArchiveDir=/tmp/codeql-scratch-b2678d0398b00160/dbs/java/src --outputDir=/tmp/codeql-scratch-b2678d0398b00160/dbs/java/trap/java (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]

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