Troubleshooting¶

Symptom-first guide. The collector logs a one-line reason for every skipped source, so the notebook's run output is the first place to look.

`FdaInteractions` is empty¶

Check	How
Schema provisioned?	Re-run `01_tables.kql` + `02_policies.kql`, or `Deploy-FdaObservability.ps1 -ProvisionSchema`. `.create-merge` is safe to re-run.
Collector ran?	Look for the `=== FDA_Collector done: graph=… audit=… dax=… curated=… ===` summary in the notebook output.
Any source returning rows?	If all of `graph/audit/dax` are 0, no source is reachable — check identity & permissions below.

Graph isn't contributing. These are DAX orphans (expected when Graph coverage is partial), but if all rows look like this:

FDA_USERS / FDA_USER_GROUP_ID not set, or the group expanded to zero users → the Graph source logs no users … skipped.
Collector app missing AiEnterpriseInteraction.Read.All (application, admin-consented).
The users aren't M365 Copilot licensed, or their experiences don't write to the interaction-history service.

Workspace monitoring isn't contributing, or the join missed:

Monitoring not enabled on the semantic model's workspace → pull_executed_dax logs monitoring query failed (is workspace monitoring enabled?). Enable it (Workspace → Settings → Monitoring).
Collector lacks Viewer on the monitoring KQL database.
Wrong MON_QUERY_URI / MON_DATABASE.
Join window too tight — DAX exists in Raw_ExecutedDax but falls outside ±CORR_WINDOW_SEC. Confirm with the per-user spot-check and widen CORR_WINDOW_SEC if needed.
ExecutingUser in monitoring doesn't match the Graph User (UPN vs object id mismatch).

Collector (service principal)Review app (interactive)Deploy script

Secret resolution order: inline → Key Vault (notebookutils.credentials.getSecret) → FDA_CLIENT_SECRET env var. Outside Fabric, set the env var; inside Fabric, store the secret in Key Vault.
Kusto SP auth needs the app added as Member/Contributor on the workspace and Database Ingestor + Viewer on the KQL DB.
Database Ingestor is required for queued ingestion (USE_QUEUED_INGESTION=True).

First sign-in prompts for account selection; subsequent launches use the cached token silently.
The public-client app must have redirect URI http://localhost and the Kusto https://kusto.fabric.microsoft.com/user_impersonation delegated permission.
The reviewer needs Viewer on the observability KQL database.

Needs Az.Accounts and an interactive Connect-AzAccount.
The signed-in identity needs Database Admin/Ingestor on the KQL DB and Member/Admin on the workspace to create a schedule.

ingest_df tries the primary path (queued or inline) then falls back to the other once. A persistent failure usually means missing Database Ingestor or an unreachable ingest endpoint.
If the azure-kusto-ingest package is absent, the collector uses inline management ingestion automatically (_HAVE_INGEST = False).
The ingest endpoint is derived as https://ingest-<cluster>… when EH_INGEST_URI is blank; set it explicitly if your cluster uses a non-standard DM endpoint.

The Office 365 Management API subscription is started idempotently on first run, but the SP needs ActivityFeed.Read and the tenant's unified audit log must be on (Purview → Audit).
Audit records can lag minutes to ~30 min; the trailing LOOKBACK_HOURS re-scan back-fills them on a later run.

The collector de-dups by InteractionId before append, and the trailing re-scan window means recent interactions are re-evaluated each run — already-curated ids are dropped. If you still see duplicates, confirm you aren't running two schedules against the same Eventhouse.

A tile that calls FdaTopQuestions will error if 02_policies.kql wasn't run (the function won't exist).
If import fails on a schema mismatch, build the dashboard manually from the query pack.

The site is built with mkdocs build --strict, which fails on broken internal links or missing nav files. Run mkdocs build --strict locally before pushing; fix any reported warnings.