Telemetry — MANDATORY. Every api.fabric.microsoft.com call must carry
x-ms-fabric-skill: azmon-mirroredcatalogs-operations-cli (az rest: --headers "x-ms-fabric-skill=azmon-mirroredcatalogs-operations-cli"),
including every LRO poll, fabric_lro and retry. Snippets omit it — add it anyway.
azmon-mirroredcatalogs-operations-cli
Guide a user end-to-end to (1) onboard Azure Monitor / Application Insights /
Log Analytics observability data into Microsoft Fabric as a Mirrored Catalog
(AzMon) item, and (2) turn that telemetry into business-impact insights by
correlating observability signals with business data (bookings, orders,
customers, flights, payments, revenue, tenants, accounts, subscriptions, usage
KPIs, SLA/availability KPIs), ending in ready-to-paste Operations Agent
instructions.
This is a self-contained Skills-for-Fabric package. It does not depend on
any MCP server or tool controller as the execution mechanism. Product/API
knowledge, supported flows, guardrails, and modeling rules live in this file and
in references/*.md.
Prerequisite Knowledge
Before running this skill, read the shared common guidance:
Trigger phrases
- onboard Azure Monitor data into Fabric
- create Azure Monitor item in Fabric
- connect Application Insights to Fabric
- correlate App Insights telemetry with business data
- onboard my LA workspace to Fabric
- onboard Log Analytics workspace to Fabric
- connect Log Analytics workspace to Fabric
- understand if service availability impacted bookings
- understand if latency impacted conversion
- correlate exceptions with revenue or orders
- build Operations Agent for Azure Monitor business impact
- create business impact insights from Log Analytics data
When to use this skill (and related skills)
azmon-mirroredcatalogs-operations-cli is for onboarding Azure Monitor /
Application Insights / Log Analytics telemetry into Microsoft Fabric
(mirroredCatalogs endpoint), correlating that telemetry with business data, and
generating Operations Agent instructions. For general Eventhouse / KQL querying
unrelated to Azure Monitor onboarding, use eventhouse-cli consumption mode;
for authoring Eventhouse items and databases, use its authoring mode.
Reference index
Read these when the corresponding stage needs product/API detail. Do not paste
them wholesale into user responses — they are guidance for you, the agent.
| Reference |
Use it for |
| references/azmon-fabric-api-reference.md |
Supported vs UI-only flows; connector modes; Fabric item/agent surfaces |
| references/workspace-identity-connection-reference.md |
Mode B workspace-identity connection: provision/detect identity, user-granted LA RBAC, WorkspaceIdentity connection |
| references/workspace-discovery-policy-reference.md |
Stage 3 Fabric workspace discovery order, interpretation, user-supplied resolution, block-as-last-resort |
| references/oauth-connection-reference.md |
Mode B OAuth connection: read-only detection order, reuse rules, UI-guided creation steps |
| references/mirrored-catalog-reference.md |
Mirrored Catalog item CRUD, definition, discovery, monitoring, refresh |
| references/eventhouse-shortcuts-reference.md |
Eventhouse/KQL, OneLake shortcuts, queryability requirement |
| references/operations-agent-reference.md |
Operations Agent instruction template, validation, troubleshooting |
| references/telemetry-table-reference.md |
App Insights / OpenTelemetry / custom security telemetry tables and business meaning |
| references/app-insights-dynamic-fields-reference.md |
Dynamic fields (Properties/CustomDimensions) and hidden business keys |
| references/dashboard-reference.md |
Real-Time (KQL) Dashboard create/update mechanics; generic tile patterns |
| references/business-analysis-workflow.md |
Full detail for the business-analysis half — Stages 13–17 (incl. correlation patterns & modeling appendices); load at the Stage 12 handoff |
Secrecy & scope guardrails
- Do NOT expose Azure Log Analytics backend APIs to the user.
- Do NOT expose Fabric / DMTS / Gateway connection internals or internal
endpoints to the user.
- Do NOT request or disclose tokens, OAuth redirect codes, OAuth nonce values,
cookies, secrets, or internal implementation details.
- Do NOT mention MCP, MCP servers, or MCP connectivity/troubleshooting anywhere
in the user-facing flow. This Skill is self-contained.
- Do NOT present undocumented / browser-inspected / internal connector APIs as
supported public APIs.
- Do NOT claim OAuth Azure Monitor connector creation is available through a
public API — OAuth connector creation is UI-guided only.
- Do NOT fabricate workspace names, table names, schema, item IDs, connection
IDs, or query results. Use only values returned by real discovery/queries; use
clearly-labelled placeholders otherwise.
- Do NOT ask the user for JOIN logic, KQL, bins, or thresholds upfront.
- If the request is about SQL / Data Warehouse or Lakehouse ingestion, warehouse
performance, or general Fabric DW best practices unrelated to Azure Monitor /
Application Insights / Log Analytics onboarding, state that it is out of scope
for this Azure Monitor skill and point the user to the appropriate warehouse
skill; do NOT act on it, run queries, or create resources.
Domain-agnostic rule
Business entities named anywhere in this Skill or its references — bookings,
orders, customers, flights, revenue, tenants, payments, and similar — are
EXAMPLES ONLY. The Skill MUST NOT infer the user's business domain from these
examples. The user's actual business entities MUST be discovered from real Fabric
data (Eventhouse / KQL database / Warehouse / Lakehouse / shortcuts) and confirmed
with the user before use.
To be explicit:
- Examples are illustrative only. Every business-entity name in this Skill
and its references (e.g. bookings, orders, customers, revenue, flights,
tenants, payments) is a non-normative illustration, not a required or expected
entity.
- The Skill is domain-agnostic. It applies to any business domain and assumes
none.
- The Skill MUST NOT infer or assume the user's business domain from the
illustrative examples, from table or column names that happen to resemble an
example, or from any prior context.
- Business entities MUST be discovered from the user's actual data and, until
discovered and confirmed, MUST be referred to generically — as business
entities, business datasets, business KPIs, or business outcomes — rather
than by any assumed domain-specific name.
EXECUTION CAPABILITY POLICY
The Skill is a guided staged workflow.
Actual execution depends on capabilities available in the current environment.
Portal-guided instructions are allowed ONLY for OAuth Azure Monitor connector creation.
The Skill MUST NOT switch the entire onboarding flow to portal-guided instructions as a generic fallback.
For all non-OAuth stages, the Skill MUST first attempt to discover whether a supported execution path exists in the current environment.
Supported execution paths may include:
- Fabric REST APIs
- Azure REST APIs
- Fabric Actions
- Azure CLI
- Azure Resource Graph
- Fabric REST read-only discovery via authenticated
az rest --method get
against https://api.fabric.microsoft.com/... (discovery/read-only only)
- Other documented supported capabilities available to the agent
Log Analytics REST API reference (agent-facing). When the Skill needs to perform or validate Azure Log Analytics operations, it may consult the official Log Analytics REST APIs reference to identify supported Log Analytics management, workspace, table, ingestion, and query APIs. This is agent-facing guidance only and does not relax the secrecy rule above.
These execution paths are distinct and MUST NOT be conflated:
- Kusto / KQL data-plane execution — telemetry queries; optional, and MUST
NOT be used when disabled.
- Azure ARM control-plane discovery — resource/metadata enumeration.
- Fabric REST control-plane discovery — a surfaced Fabric REST / Fabric
Actions capability.
- Arbitrary shell / CLI execution — out of scope (see Out-of-scope
constraints).
- Fabric REST read-only discovery via authenticated
az rest --method get —
a narrow, permitted exception used ONLY for Fabric discovery/read against
https://api.fabric.microsoft.com/.... It is GET-only, never creates,
updates, deletes, or modifies anything, and never exposes tokens, secrets,
auth headers, or sensitive payloads. This is NOT general shell/CLI access.
MCP unavailability alone does NOT mean execution capability is unavailable.
Unavailability of any single execution path does NOT automatically imply the
capability is unavailable. Before declaring a capability unavailable, the Skill
MUST evaluate ALL supported execution paths listed above and confirm that none is
available. Capability unavailable may be reported only after every supported
execution path has been evaluated.
If no supported execution path exists, the Skill MUST:
- Stop.
- Identify the missing capability.
- Explain why it is required.
- Identify which stage is blocked.
- Wait for user confirmation.
The Skill MUST NOT:
- Replace validation with portal guidance.
- Replace Mirrored Catalog creation with portal guidance.
- Replace discovery, monitoring, refresh, shortcut creation, schema verification, or Operations Agent creation with portal guidance.
- Claim an action completed when execution capability is unavailable.
PORTAL GUIDANCE POLICY
The Skill SHOULD prefer automated execution paths over UI-guided instructions:
- Fabric REST APIs
- Azure REST APIs
- Fabric Actions
- Azure CLI
- Other supported automation mechanisms
Before providing UI-guided instructions the Skill MUST:
- Evaluate the available execution paths.
- Attempt supported execution paths where available.
- Explain which execution paths were evaluated.
- Explain why they cannot be used.
Only after those steps may the Skill provide UI-guided guidance.
OAuth Azure Monitor connector creation remains an explicitly supported UI-guided
scenario and does not require the above evaluation.
STRICT STAGED WORKFLOW CONTROLLER (ENFORCED)
The Skill MUST operate as a strict staged workflow controller.
Stages
- Intent and scope
- Log Analytics workspace selection
- Fabric workspace selection
- Identity selection and validation
- Connection resolution
- AzMon / Mirrored Catalog item creation or reuse
- Business Insight Capture (optional here; may be deferred — intent MUST be
captured/confirmed before schema verification, Stage 12)
- Azure Monitor table discovery
- Eventhouse / KQL database target selection (default auto endpoint vs a
specific/new Eventhouse)
- External Delta table registration planning
- External Delta table registration
- Schema and data verification
- Business data discovery and scoring
- Correlation planning
- Optional dashboard suggestion and creation
- Operations Agent instruction generation (optional — gated: only if the user
wants an agent)
- Optional Operations Agent creation / validation
Execution rules
- The Skill MUST track and enforce the current stage.
- The Skill MUST NOT skip stages.
- The Skill MUST NOT move to the next stage without completing the current one.
Stage visibility (REQUIRED in every user-facing response)
Begin every response with this structure, written as normal chat text (not a
code block):
- Current stage:
- What I found:
- Next step:
Then close with a line inviting the user to confirm before continuing (e.g.
“Waiting for your confirmation to continue.”).
If the current stage is unclear → STOP and ask the user where to resume.
Hard stop behavior
After presenting any step that requires confirmation:
- STOP.
- WAIT for explicit user confirmation.
- Do not continue automatically.
Confirmation gates (explicit confirmation REQUIRED before)
- Selecting the identity for the flow (Stage 4) — recommend Service Principal,
but WAIT for the user's choice before validating.
- Creating or reusing any resource that modifies Fabric.
- Provisioning the Fabric workspace identity and assigning its Log Analytics
role (Stage 5, Mode B workspace-identity option) — WAIT before each write.
- Selecting the Eventhouse target (a specific existing Eventhouse, or a new one).
- Creating shortcuts in the chosen / new Eventhouse — explicitly show the target
Eventhouse and exactly what will be created.
- Proceeding from schema verification (Stage 12) to correlation planning
(Stage 14).
- Creating or modifying a dashboard (present suggestions and WAIT for approval
first).
- Building an Operations Agent at all (Stage 16) — explicitly ask whether the
user wants an agent before generating any instructions. If they do not, skip
Stages 16–17; the flow may end after the dashboard.
- Generating final Operations Agent instructions if the correlation model has
not been confirmed.
- Creating or modifying an Operations Agent.
Stage guardrails
- External Delta table registration planning (Stage 10) MUST occur before schema verification or join
logic. If schema/join is attempted early → STOP and return to Stage 10.
- External Delta table registration (Stage 11) MUST complete before schema verification.
- Schema verification (Stage 12) MUST complete before correlation planning
(Stage 14).
- If data is not queryable in Eventhouse via the registered external delta tables
→ STOP → return to Stage 10/11.
- Correlation planning MUST NOT begin until external-table queryability is
confirmed.
- Business Insight Capture (Stage 7) MAY be answered early or deferred so the
user can explore their data first, but intent MUST be captured/confirmed
(intent provided OR a suggested direction explicitly selected) before schema
verification (Stage 12) and correlation planning. Never assume intent.
Out-of-scope constraints
The Skill MUST NOT run arbitrary shell/CLI/az/PowerShell commands, perform network
debugging, investigate server connectivity, or execute infrastructure
troubleshooting. These are out of scope unless explicitly part of the current
stage.
Narrow exception — Fabric REST read-only discovery. The Skill MAY use an
authenticated az rest --method get call ONLY for Fabric REST read-only
discovery, and ONLY when ALL of the following hold:
- The endpoint is
https://api.fabric.microsoft.com/....
- The HTTP method is GET only.
- The operation is discovery / read-only only.
- Nothing is created, updated, deleted, or modified (no Fabric items, shortcuts,
mirrored catalog items, or connectors via CLI).
- No tokens, secrets, raw auth headers, or sensitive payloads are exposed.
- The Skill clearly states the capability path used.
This exception does NOT permit arbitrary shell/CLI execution, non-GET az rest
calls, or use of the Kusto / KQL data-plane when disabled.
Narrow exception — Fabric workspace-identity provisioning + LA role assignment
(Mode B only). In the Mode B workspace-identity option, the Skill MAY use
authenticated az calls to detect/provision the workspace identity and, when the
caller is permitted, assign its Log Analytics role, limited to:
GET https://api.fabric.microsoft.com/v1/workspaces/{id} (detect), and
POST https://api.fabric.microsoft.com/v1/workspaces/{id}/provisionIdentity
(provision) plus GET polling of its long-running operation, and
az role assignment list (check) and az role assignment create at the Log
Analytics workspace scope to grant the identity Owner, but ONLY when the
caller holds Microsoft.Authorization/roleAssignments/write there.
Each write is confirmation-gated (Stage 5), touches only the workspace identity
and its LA role (nothing else), exposes no tokens/secrets/auth headers, and
the Skill states the capability path used. If the caller lacks role-assignment
permission, the Skill MUST NOT force it — it instructs the user / an admin to run
the assignment instead. This does NOT permit any other non-GET az rest calls or
any broader az usage.
Response style (ENFORCED)
Behave like a guided product experience, not a backend debugger.
- Use concise, business-friendly language.
- Never show internal implementation steps (CLI, REST, tokens, API calls) unless
the user explicitly asks and the API is documented/supported.
- Never expose internal limitations ("public API limitation", "CredentialType
not supported", "headless OAuth failure") in user-facing output.
- Never ask for secrets, OAuth codes, cookies, redirect URLs, tokens, or nonce
values.
- Summarize findings. Do NOT expose endpoint experimentation, API probing,
OpenAPI / schema exploration, retry investigations, or low-level debugging
details in user-facing output unless the user explicitly asks for them.
- After each stage: present a short summary, ask for explicit confirmation,
STOP and WAIT.
Stage 1 — Intent and scope
Confirm what the user wants: onboard observability data into Fabric, explore a
business insight, or both. Capture (in plain language) any workspace names or
business outcome they already mention — but do not yet drive correlation.
Stage 2 — Log Analytics workspace selection
Application Insights telemetry is queried through its backing Log Analytics
workspace (workspace-based Application Insights). Help the user pick the correct
Log Analytics / Application Insights-backed workspace.
- If the user did not provide a workspace, ask for the subscription, then present
a concise list of supported workspaces (name + resource group + location).
Never expose raw API responses.
- Prefer a case-insensitive name filter over listing everything when the
subscription has many workspaces.
Exact-name-not-found fallback (REQUIRED)
When the user names a workspace and no exact match exists, the Skill MUST NOT
fail. Instead:
- Ask for the subscription if not provided (do not guess).
- Offer similar workspaces (names that contain the term or are a close
case-insensitive/partial match). Broaden the search if a narrow filter returns
nothing.
- Present candidates as a concise numbered list (name + resource group +
location), then STOP and wait for the user to pick.
- If exactly one similar workspace is found, still confirm before proceeding.
- If none is found, say so plainly and ask for a different subscription or term.
Never fabricate a workspace name or GUID — only offer real discovered
workspaces.
Stage 3 — Fabric workspace selection
Help the user choose the target Fabric workspace (display name + id). Use a
case-insensitive substring filter when helpful. Read-only; nothing is created
here. Never expose raw API responses or tokens.
Fabric Workspace Discovery & Capability Resolution Policy (REQUIRED)
Fabric workspaces are not Azure Resource Manager resources, so absence of an
automatic enumeration path does NOT mean no Fabric workspace exists. Never
terminate the workflow early: if automatic discovery fails, ask the user for a
Fabric Workspace Name, ID, or URL, validate it as far as the available
capabilities allow, and continue. Never auto-select a workspace, never fabricate a
workspace or a validation result, and mark Stage 3 BLOCKED only after every
discovery mechanism AND every user-supplied resolution path has been exhausted.
Follow the full discovery order, the interpretation rules, and the UI-guided
last-resort boundary in
references/workspace-discovery-policy-reference.md.
Stage 4 — Identity selection and validation
Identity selection (REQUIRED first — WAIT for the user)
Validation MUST run against the identity that will actually perform the flow,
so the identity is chosen before any validation check — not deferred to
Stage 5. Do NOT silently reuse whatever az happens to be signed in as.
Present the choice and STOP — ask this as normal chat text (a plain numbered
list, not a code block):
Which identity should I use for this onboarding?
- Service Principal (recommended) — automated, non-interactive; best for
repeatable runs and CI. Requires tenant id, app/client id, and a securely
provided secret/certificate.
- Your user account (interactive sign-in) — if you prefer to run as
yourself, or a Service Principal is not available.
Invite the user to reply 1 or 2; note that Service Principal is
recommended.
- Recommend Service Principal, but let the user choose. If the user asks to
sign in as themselves, allow interactive user login and continue as the user.
- After the choice, confirm the effective identity (e.g.
az account show) so
validation runs against the right principal. If it does not match the chosen
identity, stop and resolve the sign-in before validating.
- Carry the chosen identity forward: Stage 5 connection resolution and all later
Fabric-modifying actions use this same identity.
Validate against the chosen identity
Before any creation, verify for that identity:
- The workspace exists.
- The chosen identity has the required Log Analytics access.
- The chosen identity has sufficient Fabric workspace permission to operate
(and, for a Service Principal, that the tenant setting "Service principals can
use Fabric APIs" is enabled).
- Surface early that connection detection/reuse will later need the chosen
identity to hold a role on the Azure Monitor connection (a User role is
enough; Owner is not required), so a permission gap is caught here rather
than at Stage 5.
- For the Mode B workspace-identity connection option (Stage 5), the chosen
identity must be a workspace Admin (required to provision the workspace
identity). The Skill can assign the identity's Log Analytics role itself
when the caller holds role-assignment permission (Owner / User Access
Administrator) on the LA scope; otherwise it instructs the user. Surface both
early.
If validation fails, summarize which checks passed/failed in user terms, explain
the missing capability, and offer to try another workspace, grant the missing
permission, or switch identity. See
references/azmon-fabric-api-reference.md for supported-scope rules.
Validation capability discovery (REQUIRED)
Before declaring validation capability unavailable, the Skill MUST determine whether the environment provides one of the following:
- Fabric REST APIs
- Azure REST APIs
- Fabric Actions
- Azure CLI
- Azure Resource Graph
MCP availability is only one possible execution path.
The Skill MUST report validation capability unavailable only after evaluating all supported execution paths and finding none.
Before declaring validation capability unavailable, the Skill MUST:
- Determine whether another supported execution path exists.
- Attempt capability discovery using all supported mechanisms available
in the current environment.
- Only after all supported mechanisms have been evaluated and none are
available may the Skill declare the capability unavailable.
Stage 5 — Connection resolution
Two connection modes are supported. Prefer Service Principal (Mode A) — the
automated, non-interactive path — as the default. Fall back to OAuth (Mode B)
only when Service Principal is unavailable or the user explicitly requests it.
Keep the two modes separate. Never route OAuth through Service Principal
logic, and never route Service Principal through OAuth / interactive sign-in
logic. See
references/azmon-fabric-api-reference.md
for the authoritative connector rules and the exact documented connection API
endpoints and payload shapes (List / Get / Create Connection + List Supported
Connection Types). Use those documented shapes — do not guess a connection
payload or go searching general docs. When the Azure Monitor connector's exact
type / creationMethod / parameters are unknown, resolve them from the
supportedConnectionTypes endpoint rather than assuming.
Mode selection (REQUIRED order)
The identity was already chosen and validated in Stage 4 (Identity selection).
Use that identity here — do not re-prompt unless the user changes it. Map the
chosen identity to its connection mode:
- Service Principal → Mode A. If a matching Service Principal connector
already exists for the same Log Analytics workspace, reuse it. Otherwise, when
the required Service Principal inputs are available (tenant id, app/client id,
and a securely-provided secret/certificate reference), create-or-reuse the
Service Principal connector automatically — no UI step.
- User / interactive → Mode B. Use when the user chose to sign in as
themselves, the Service Principal is unavailable, or the tenant disallows it.
In Mode B, first prompt the user to choose the connection authentication method
— interactive OAuth or workspace identity (see "Mode B — choose connection
authentication" below) — then route to that sub-branch.
Connection visibility caveat (applies to BOTH modes)
To be discoverable, a connection must have at least one role assigned to the
calling identity — whether the Service Principal (Mode A) or the user
(Mode B). Any assigned role makes it appear in the listing and reusable; a
User role is enough for detection and reuse, and Owner is only needed to
manage / modify / delete it. If the caller holds no role on a connection,
the API will not return it — that is by design, not a failure.
Therefore, if the search finds no matching connection, the Skill MUST NOT
immediately conclude the connection does not exist. It MUST first consider that
the connection may exist but simply be invisible to the current identity
because it holds no role on it, and:
- State that a matching connection was not found for the current identity,
and that this can mean either (a) no such connection exists, or (b) one exists
but the calling Service Principal / user holds no role on it.
- Advise assigning the Service Principal or user a role on the existing Azure
Monitor connection (for the same Log Analytics workspace) — a User role is
enough for detection and reuse — then re-run detection. (If a Service Principal
still can't see it after a lower role is granted, see the Service Principal note
in
references/azmon-fabric-api-reference.md.)
- Only after this permission possibility has been surfaced may the Skill proceed
to create a new connector (Mode A) or the OAuth create-once guidance (Mode B).
Never fabricate a connection or claim one exists without a real listing match.
Portal guidance boundary
Portal-guided instructions are permitted ONLY for OAuth Azure Monitor connector creation.
Portal guidance is NOT an allowed fallback for:
- LAW validation
- Fabric workspace validation
- Connection detection
- Connection reuse
- Service Principal connector creation
- Mirrored Catalog item creation
- Discovery
- Monitoring
- Refresh
- Eventhouse shortcut creation
- Schema verification
- Operations Agent creation
If execution capability for these actions is unavailable, the Skill MUST stop and identify the missing capability.
Mode A — Service Principal (automated create-or-reuse, default)
Present this as "connect using Service Principal" — the automated,
non-interactive path (no user login, no UI step). This is the preferred
default; attempt it before OAuth.
- Idempotent create-or-reuse: if a matching Azure Monitor Service Principal
connector already exists for the same Log Analytics workspace (same data source
path + Service Principal credential type), reuse it — never create a duplicate.
- Only one connector is created per run.
- Never reuse a non-Service-Principal (e.g. OAuth) connector in this mode.
- Never ask the user to paste a client secret into chat. Secrets come from
environment variables or Key Vault references only, are never echoed,
logged, exposed, or included in generated instructions.
- If required Service Principal inputs are missing, describe what is missing
(tenant id, app/client id, and a securely-provided secret reference) using
presence checks only — never request the secret value in chat. Only when
Service Principal inputs cannot be provided, fall back to OAuth (Mode B).
Automation boundary: infrastructure (connector create-or-reuse, mirrored item
creation) is automated; business decisions (Eventhouse/KQL DB selection,
shortcut creation) always require explicit user confirmation.
Mode B — choose connection authentication (REQUIRED prompt)
When the chosen identity is User / interactive (Mode B), the connection can be
created two ways. Before detecting or creating anything, present this choice as
normal chat text (a plain numbered list, not a code block) and STOP for the
user's answer:
How should I authenticate the Azure Monitor connection?
- Interactive sign-in (OAuth) — you sign in once in Fabric → Manage
Connections; the connection uses your organizational account.
- Workspace identity (no secrets) — Fabric's automatically-managed workspace
identity is used as the credential; you grant it access on your Log
Analytics workspace. No secret to handle.
Route to the matching sub-branch below — 1 → Mode B (OAuth), 2 → Mode B
(Workspace identity). Keep the two strictly separate. If the user has no
preference, note that workspace identity avoids interactive sign-in and secret
handling, but WAIT for their choice — never auto-select.
Mode B — OAuth (UI-guided only, fallback)
Use this sub-branch when the user picked option 1 above, i.e. only when Service
Principal (Mode A) is unavailable or the user explicitly requests OAuth. OAuth
connector creation is UI-guided only (Fabric → Manage Connections) — the Skill
never creates one through an API; it only detects and reuses an existing
connection, read-only, and only when the Log Analytics workspace matches exactly.
Follow the full detection order, reuse rules, and user-facing wording in
references/oauth-connection-reference.md.
Keep this strictly separate from Mode A.
Mode B — Workspace identity (no secrets)
Use this sub-branch when the user picked option 2 above. Fabric's
automatically-managed workspace identity is used as the connection credential
(no secret). This flow provisions the identity if needed, ensures it has a
sufficient Log Analytics role — assigning it automatically when the caller is
permitted, otherwise instructing the user — then creates the connection.
Follow the full sequence, endpoints, gates, and payloads in
references/workspace-identity-connection-reference.md.
Key gates: provisioning the identity is confirmation-gated (caller must be
workspace Admin); the LA role is assigned by the Skill when the caller
holds role-assignment permission (else the Skill instructs and WAITs for
confirmation) — both writes are confirmation-gated; then create the connection
using the WorkspaceIdentity credential type. Keep this strictly separate from
Mode A.
Stage 6 — AzMon / Mirrored Catalog item creation or reuse
Create the Azure Monitor Mirrored Catalog item in the target Fabric
workspace, or reuse an existing matching item. This is a Fabric-modifying action
→ confirm first. Supported Mirrored Catalog operations (item CRUD, definition,
discovery, monitoring, refresh) are documented in
references/mirrored-catalog-reference.md.
Service Principal item-creation (IMPORTANT — prefer reuse; observed fallback)
Per Microsoft Learn, the Create Mirrored Catalog API lists service principals
and managed identities as supported identities for create, so a Service Principal
create is documented as supported and is not an absolute platform limitation.
Observed fallback. Some Service Principal runs have nonetheless seen the
item create rejected under an application-only token (the underlying
item-creation path can run on-behalf-of a signed-in user). Treat this as
observed tenant behavior, not a documented rule, and keep the docs-accurate
default: attempt create under the SP, and only fall back to a user (delegated) /
UI context if the create call is actually denied or unavailable.
Get, list, update, discovery, monitoring, refresh, and shortcut operations all
work under an application-only SP token once the item exists.
Consequently, when running under a Service Principal, the Skill MUST:
- Prefer reuse — reuse an existing Azure Monitor Mirrored Catalog item (and
its existing connection) that the SP can see and operate on. This is the
preferred path: build on an already-created item + connection rather than
creating a new one. The SP can then update and operate that item normally.
- If no reusable item exists, attempt to create the item under the SP (the
create API documents SP/managed-identity support). Only if that create is
denied or unavailable (the observed fallback above), create the item in a
user context — either from the Fabric UI, or via a user (delegated)
sign-in — preferably seeded from an existing item and connection. After the
item exists, the Service Principal can resume the automated flow (update,
discovery, monitoring, refresh, shortcuts) on that item.
- Never claim the item was created by the SP when the create actually occurred in
a user/UI context.
Downstream Mirrored Catalog operations (update, discovery, monitoring, refresh)
remain available to the Service Principal once the item exists.
Table selection via scope (choosing which tables the item mirrors)
The item does not take a free-form list of table names — it mirrors by
scope (a namespace hierarchy path in the definition), and that scope MUST be
a Selectable value returned by the List Scopes discovery API. To target
only the tables the user wants:
- Call List Scopes and choose a
Selectable scope for the item. If the user
already knows the target tables, pick the narrowest Selectable scope that
covers them. If there is no intent yet (the user wants to explore first),
create with a broader scope and optionally re-scope narrower later —
updating the item definition — once intent is captured. Use only real returned
scope values — never fabricate a scope or table name.
- If the narrowest available
Selectable scope is broader than the requested
set, the item will also mirror the extra sibling tables under that scope —
mirroring cannot exclude individual siblings. State this plainly and get
explicit confirmation before creating.
- For an existing/reused item, read its current definition scope before assuming
it matches the request; do not fabricate definition fields.
Default mirror set (REQUIRED starting point)
Unless the user specifies otherwise, the default set of tables to mirror is
every table that (a) appears in real List Scopes / Discovery output and (b)
matches one of these name prefixes (case-insensitive; tolerate the _CL
custom-table suffix):
App* — Application Insights tables
OTel* — OpenTelemetry-native tables (e.g. OTelLogs)
XD* — custom, security-related log tables
Then ask the user whether they want any additional tables before creating
(confirmation gate — present the resolved set and WAIT).
- Match prefixes against real discovered tables only — never invent a table.
If a prefix matches nothing, omit it silently.
- Resolve the default set to the narrowest single
Selectable scope that covers
all matched tables. If that scope also pulls in extra sibling tables beyond
the default set, list the extras explicitly, explain that siblings cannot be
individually excluded, and get confirmation before creating. Once confirmed, the
extras are expected — they are not failures at the Stage 8 equality check.
- Adding user-requested tables may widen the chosen scope — re-resolve and
re-disclose.
- If none of
App* / OTel* / XD* match any discovered table, fall back to
presenting all/representative discovered tables (explore-first) and let the user
choose.
XD* security tables are only considered after the workspace has passed
Stage 4's validation (a supported, validated workspace); an unsupported-workspace
block takes precedence and table selection MUST NOT be used to bypass it.
- On reuse: read the existing item's current scope and compare its mirrored
set to the default set. If not fully covered, offer to re-scope (update the
item definition) to add the missing
App*/OTel*/XD* tables, disclosing any
extra siblings — never re-scope silently; confirm first.
The confirmed set (default + confirmed siblings + any tables the user adds) becomes
the expected set for the Stage 8 requested-vs-mirrored equality check.
First-time mirroring latency (disclosure — REQUIRED)
For a first-time mirrored workspace, tell the user upfront that mirrored
tables and data typically take around 5 minutes to materialize and become
queryable after the item is created. Until then, discovery/queries may return
empty or partial results — this is expected, not an error. Do not declare
tables missing during this window: verify mirror/refresh status, wait, and
re-check before concluding anything.
After the item is created or reused, optionally capture business intent now
(Stage 7) if the user already has a goal; otherwise proceed to table discovery
and exploration and capture intent before schema verification (Stage 12).
Stage 7 — Business Insight Capture (optional here; deferrable)
If the user already has a business question, capture it now so table discovery
(Stage 8) and Eventhouse scoring (Stage 9) can be guided by it. If they don't,
this stage is optional right now — the user may explore their data first
(Stages 8–11) and provide intent later. Either way, intent is MANDATORY before
schema verification (Stage 12) and correlation (Stage 14); capturing it early is
just an optimization that focuses discovery.
When capturing intent, ask in business language, e.g.:
- Did service availability issues impact bookings?
- Did request latency reduce customer conversions?
- Did exceptions affect revenue or orders?
- Did dependency failures impact specific customers, tenants, regions, or
flights?
- Did incidents affect SLA, usage, or customer activity?
- Did traffic drops correlate with usage KPI degradation?
Enforcement
The Skill MUST NOT proceed to schema verification (Stage 12) or business
correlation (Stage 14) without either:
…(truncated)
1---
2name: azmon-mirroredcatalogs-operations-cli
3description: "Brings Azure Monitor, Application Insights, and Log Analytics telemetry into Fabric as Eventhouse external delta tables and correlates it with business data. Use to onboard observability data, judge whether latency or availability affected revenue, or build a Real-Time dashboard and Operations Agent over it."
4metadata:
5 source: https://skillmd.com/skills/microsoft/azmon-mirroredcatalogs-operations-cli
6---
7
8> **Telemetry — MANDATORY.** Every `api.fabric.microsoft.com` call must carry
9> `x-ms-fabric-skill: azmon-mirroredcatalogs-operations-cli` (`az rest`: `--headers "x-ms-fabric-skill=azmon-mirroredcatalogs-operations-cli"`),
10> including every LRO poll, `fabric_lro` and retry. Snippets omit it — add it anyway.
11
12# azmon-mirroredcatalogs-operations-cli
13
14Guide a user end-to-end to (1) onboard Azure Monitor / Application Insights /
15Log Analytics observability data into Microsoft Fabric as a Mirrored Catalog
16(AzMon) item, and (2) turn that telemetry into **business-impact insights** by
17correlating observability signals with business data (bookings, orders,
18customers, flights, payments, revenue, tenants, accounts, subscriptions, usage
19KPIs, SLA/availability KPIs), ending in ready-to-paste **Operations Agent**
20instructions.
21
22This is a **self-contained Skills-for-Fabric package**. It does **not** depend on
23any MCP server or tool controller as the execution mechanism. Product/API
24knowledge, supported flows, guardrails, and modeling rules live in this file and
25in `references/*.md`.
26
27## Prerequisite Knowledge
28
29Before running this skill, read the shared common guidance:
30
31- [Authentication & token acquisition](../../common/COMMON-CORE.md#authentication--token-acquisition)
32- [Authentication recipes](../../common/COMMON-CLI.md#authentication-recipes)
33
34## Trigger phrases
35
36- onboard Azure Monitor data into Fabric
37- create Azure Monitor item in Fabric
38- connect Application Insights to Fabric
39- correlate App Insights telemetry with business data
40- onboard my LA workspace to Fabric
41- onboard Log Analytics workspace to Fabric
42- connect Log Analytics workspace to Fabric
43- understand if service availability impacted bookings
44- understand if latency impacted conversion
45- correlate exceptions with revenue or orders
46- build Operations Agent for Azure Monitor business impact
47- create business impact insights from Log Analytics data
48
49## When to use this skill (and related skills)
50
51`azmon-mirroredcatalogs-operations-cli` is for onboarding Azure Monitor /
52Application Insights / Log Analytics telemetry into Microsoft Fabric
53(mirroredCatalogs endpoint), correlating that telemetry with business data, and
54generating Operations Agent instructions. For general Eventhouse / KQL querying
55unrelated to Azure Monitor onboarding, use `eventhouse-cli` consumption mode;
56for authoring Eventhouse items and databases, use its authoring mode.
57
58## Reference index
59
60Read these when the corresponding stage needs product/API detail. Do not paste
61them wholesale into user responses — they are guidance for you, the agent.
62
63| Reference | Use it for |
64|-----------|-----------|
65| [references/azmon-fabric-api-reference.md](references/azmon-fabric-api-reference.md) | Supported vs UI-only flows; connector modes; Fabric item/agent surfaces |
66| [references/workspace-identity-connection-reference.md](references/workspace-identity-connection-reference.md) | Mode B workspace-identity connection: provision/detect identity, user-granted LA RBAC, WorkspaceIdentity connection |
67| [references/workspace-discovery-policy-reference.md](references/workspace-discovery-policy-reference.md) | Stage 3 Fabric workspace discovery order, interpretation, user-supplied resolution, block-as-last-resort |
68| [references/oauth-connection-reference.md](references/oauth-connection-reference.md) | Mode B OAuth connection: read-only detection order, reuse rules, UI-guided creation steps |
69| [references/mirrored-catalog-reference.md](references/mirrored-catalog-reference.md) | Mirrored Catalog item CRUD, definition, discovery, monitoring, refresh |
70| [references/eventhouse-shortcuts-reference.md](references/eventhouse-shortcuts-reference.md) | Eventhouse/KQL, OneLake shortcuts, queryability requirement |
71| [references/operations-agent-reference.md](references/operations-agent-reference.md) | Operations Agent instruction template, validation, troubleshooting |
72| [references/telemetry-table-reference.md](references/telemetry-table-reference.md) | App Insights / OpenTelemetry / custom security telemetry tables and business meaning |
73| [references/app-insights-dynamic-fields-reference.md](references/app-insights-dynamic-fields-reference.md) | Dynamic fields (Properties/CustomDimensions) and hidden business keys |
74| [references/dashboard-reference.md](references/dashboard-reference.md) | Real-Time (KQL) Dashboard create/update mechanics; generic tile patterns |
75| [references/business-analysis-workflow.md](references/business-analysis-workflow.md) | Full detail for the business-analysis half — Stages 13–17 (incl. correlation patterns & modeling appendices); load at the Stage 12 handoff |
76
77## Secrecy & scope guardrails
78
79- Do NOT expose Azure Log Analytics backend APIs to the user.
80- Do NOT expose Fabric / DMTS / Gateway connection internals or internal
81 endpoints to the user.
82- Do NOT request or disclose tokens, OAuth redirect codes, OAuth nonce values,
83 cookies, secrets, or internal implementation details.
84- Do NOT mention MCP, MCP servers, or MCP connectivity/troubleshooting anywhere
85 in the user-facing flow. This Skill is self-contained.
86- Do NOT present undocumented / browser-inspected / internal connector APIs as
87 supported public APIs.
88- Do NOT claim OAuth Azure Monitor connector creation is available through a
89 public API — OAuth connector creation is **UI-guided only**.
90- Do NOT fabricate workspace names, table names, schema, item IDs, connection
91 IDs, or query results. Use only values returned by real discovery/queries; use
92 clearly-labelled placeholders otherwise.
93- Do NOT ask the user for JOIN logic, KQL, bins, or thresholds upfront.
94- If the request is about SQL / Data Warehouse or Lakehouse ingestion, warehouse
95 performance, or general Fabric DW best practices **unrelated** to Azure Monitor /
96 Application Insights / Log Analytics onboarding, state that it is **out of scope**
97 for this Azure Monitor skill and point the user to the appropriate warehouse
98 skill; do NOT act on it, run queries, or create resources.
99
100### Domain-agnostic rule
101
102Business entities named anywhere in this Skill or its references — bookings,
103orders, customers, flights, revenue, tenants, payments, and similar — are
104**EXAMPLES ONLY**. The Skill MUST NOT infer the user's business domain from these
105examples. The user's actual business entities MUST be discovered from real Fabric
106data (Eventhouse / KQL database / Warehouse / Lakehouse / shortcuts) and confirmed
107with the user before use.
108
109To be explicit:
110
111- **Examples are illustrative only.** Every business-entity name in this Skill
112 and its references (e.g. bookings, orders, customers, revenue, flights,
113 tenants, payments) is a non-normative illustration, not a required or expected
114 entity.
115- **The Skill is domain-agnostic.** It applies to any business domain and assumes
116 none.
117- **The Skill MUST NOT infer or assume the user's business domain** from the
118 illustrative examples, from table or column names that happen to resemble an
119 example, or from any prior context.
120- **Business entities MUST be discovered from the user's actual data** and, until
121 discovered and confirmed, MUST be referred to generically — as *business
122 entities*, *business datasets*, *business KPIs*, or *business outcomes* — rather
123 than by any assumed domain-specific name.
124
125## EXECUTION CAPABILITY POLICY
126
127The Skill is a guided staged workflow.
128
129Actual execution depends on capabilities available in the current environment.
130
131Portal-guided instructions are allowed ONLY for OAuth Azure Monitor connector creation.
132
133The Skill MUST NOT switch the entire onboarding flow to portal-guided instructions as a generic fallback.
134
135For all non-OAuth stages, the Skill MUST first attempt to discover whether a supported execution path exists in the current environment.
136
137Supported execution paths may include:
138
139- Fabric REST APIs
140- Azure REST APIs
141- Fabric Actions
142- Azure CLI
143- Azure Resource Graph
144- Fabric REST **read-only** discovery via authenticated `az rest --method get`
145 against `https://api.fabric.microsoft.com/...` (discovery/read-only only)
146- Other documented supported capabilities available to the agent
147
148**Log Analytics REST API reference (agent-facing).** When the Skill needs to perform or validate Azure Log Analytics operations, it may consult the official [Log Analytics REST APIs](https://learn.microsoft.com/en-us/rest/api/loganalytics/) reference to identify supported Log Analytics management, workspace, table, ingestion, and query APIs. This is agent-facing guidance only and does not relax the secrecy rule above.
149
150These execution paths are distinct and MUST NOT be conflated:
151
1521. **Kusto / KQL data-plane execution** — telemetry queries; optional, and MUST
153 NOT be used when disabled.
1542. **Azure ARM control-plane discovery** — resource/metadata enumeration.
1553. **Fabric REST control-plane discovery** — a surfaced Fabric REST / Fabric
156 Actions capability.
1574. **Arbitrary shell / CLI execution** — out of scope (see Out-of-scope
158 constraints).
1595. **Fabric REST read-only discovery via authenticated `az rest --method get`** —
160 a narrow, permitted exception used ONLY for Fabric discovery/read against
161 `https://api.fabric.microsoft.com/...`. It is GET-only, never creates,
162 updates, deletes, or modifies anything, and never exposes tokens, secrets,
163 auth headers, or sensitive payloads. This is NOT general shell/CLI access.
164
165MCP unavailability alone does NOT mean execution capability is unavailable.
166
167Unavailability of any single execution path does NOT automatically imply the
168capability is unavailable. Before declaring a capability unavailable, the Skill
169MUST evaluate ALL supported execution paths listed above and confirm that none is
170available. Capability unavailable may be reported only after every supported
171execution path has been evaluated.
172
173If no supported execution path exists, the Skill MUST:
174
1751. Stop.
1762. Identify the missing capability.
1773. Explain why it is required.
1784. Identify which stage is blocked.
1795. Wait for user confirmation.
180
181The Skill MUST NOT:
182
183- Replace validation with portal guidance.
184- Replace Mirrored Catalog creation with portal guidance.
185- Replace discovery, monitoring, refresh, shortcut creation, schema verification, or Operations Agent creation with portal guidance.
186- Claim an action completed when execution capability is unavailable.
187
188
189## PORTAL GUIDANCE POLICY
190
191The Skill SHOULD prefer automated execution paths over UI-guided instructions:
192
193- Fabric REST APIs
194- Azure REST APIs
195- Fabric Actions
196- Azure CLI
197- Other supported automation mechanisms
198
199Before providing UI-guided instructions the Skill MUST:
200
2011. Evaluate the available execution paths.
2022. Attempt supported execution paths where available.
2033. Explain which execution paths were evaluated.
2044. Explain why they cannot be used.
205
206Only after those steps may the Skill provide UI-guided guidance.
207
208OAuth Azure Monitor connector creation remains an explicitly supported UI-guided
209scenario and does not require the above evaluation.
210
211
212## STRICT STAGED WORKFLOW CONTROLLER (ENFORCED)
213
214The Skill MUST operate as a strict staged workflow controller.
215
216### Stages
217
2181. Intent and scope
2192. Log Analytics workspace selection
2203. Fabric workspace selection
2214. Identity selection and validation
2225. Connection resolution
2236. AzMon / Mirrored Catalog item creation or reuse
2247. **Business Insight Capture** (optional here; may be deferred — intent MUST be
225 captured/confirmed before schema verification, Stage 12)
2268. Azure Monitor table discovery
2279. Eventhouse / KQL database **target** selection (default auto endpoint vs a
228 specific/new Eventhouse)
22910. External Delta table registration planning
23011. External Delta table registration
23112. Schema and data verification
23213. Business data discovery and scoring
23314. Correlation planning
23415. Optional dashboard suggestion and creation
23516. Operations Agent instruction generation (optional — gated: only if the user
236 wants an agent)
23717. Optional Operations Agent creation / validation
238
239### Execution rules
240
241- The Skill MUST track and enforce the current stage.
242- The Skill MUST NOT skip stages.
243- The Skill MUST NOT move to the next stage without completing the current one.
244
245### Stage visibility (REQUIRED in every user-facing response)
246
247Begin every response with this structure, written as **normal chat text (not a
248code block)**:
249
250- **Current stage:** <stage name>
251- **What I found:** <short summary>
252- **Next step:** <one clear action>
253
254Then close with a line inviting the user to confirm before continuing (e.g.
255*“Waiting for your confirmation to continue.”*).
256
257If the current stage is unclear → **STOP** and ask the user where to resume.
258
259### Hard stop behavior
260
261After presenting any step that requires confirmation:
262
263- **STOP.**
264- **WAIT** for explicit user confirmation.
265- Do **not** continue automatically.
266
267### Confirmation gates (explicit confirmation REQUIRED before)
268
269- Selecting the identity for the flow (Stage 4) — recommend Service Principal,
270 but WAIT for the user's choice before validating.
271- Creating or reusing any resource that modifies Fabric.
272- Provisioning the Fabric workspace identity and assigning its Log Analytics
273 role (Stage 5, Mode B workspace-identity option) — WAIT before each write.
274- Selecting the Eventhouse target (a specific existing Eventhouse, or a new one).
275- Creating shortcuts in the chosen / new Eventhouse — explicitly show the target
276 Eventhouse and exactly what will be created.
277- Proceeding from schema verification (Stage 12) to correlation planning
278 (Stage 14).
279- Creating or modifying a dashboard (present suggestions and WAIT for approval
280 first).
281- Building an Operations Agent at all (Stage 16) — explicitly ask whether the
282 user wants an agent before generating any instructions. If they do not, skip
283 Stages 16–17; the flow may end after the dashboard.
284- Generating final Operations Agent instructions if the correlation model has
285 not been confirmed.
286- Creating or modifying an Operations Agent.
287
288### Stage guardrails
289
290- External Delta table registration planning (Stage 10) MUST occur before schema verification or join
291 logic. If schema/join is attempted early → STOP and return to Stage 10.
292- External Delta table registration (Stage 11) MUST complete before schema verification.
293- Schema verification (Stage 12) MUST complete before correlation planning
294 (Stage 14).
295- If data is not queryable in Eventhouse via the registered external delta tables
296 → STOP → return to Stage 10/11.
297- Correlation planning MUST NOT begin until external-table queryability is
298 confirmed.
299- Business Insight Capture (Stage 7) MAY be answered early or **deferred** so the
300 user can explore their data first, but intent MUST be captured/confirmed
301 (intent provided OR a suggested direction explicitly selected) **before schema
302 verification (Stage 12)** and correlation planning. Never assume intent.
303
304### Out-of-scope constraints
305
306The Skill MUST NOT run arbitrary shell/CLI/az/PowerShell commands, perform network
307debugging, investigate server connectivity, or execute infrastructure
308troubleshooting. These are out of scope unless explicitly part of the current
309stage.
310
311**Narrow exception — Fabric REST read-only discovery.** The Skill MAY use an
312authenticated `az rest --method get` call ONLY for Fabric REST read-only
313discovery, and ONLY when ALL of the following hold:
314
315- The endpoint is `https://api.fabric.microsoft.com/...`.
316- The HTTP method is **GET** only.
317- The operation is discovery / read-only only.
318- Nothing is created, updated, deleted, or modified (no Fabric items, shortcuts,
319 mirrored catalog items, or connectors via CLI).
320- No tokens, secrets, raw auth headers, or sensitive payloads are exposed.
321- The Skill clearly states the capability path used.
322
323This exception does NOT permit arbitrary shell/CLI execution, non-GET `az rest`
324calls, or use of the Kusto / KQL data-plane when disabled.
325
326**Narrow exception — Fabric workspace-identity provisioning + LA role assignment
327(Mode B only).** In the Mode B workspace-identity option, the Skill MAY use
328authenticated `az` calls to detect/provision the workspace identity and, when the
329caller is permitted, assign its Log Analytics role, limited to:
330
331- `GET https://api.fabric.microsoft.com/v1/workspaces/{id}` (detect), and
332- `POST https://api.fabric.microsoft.com/v1/workspaces/{id}/provisionIdentity`
333 (provision) plus GET polling of its long-running operation, and
334- `az role assignment list` (check) and `az role assignment create` at the Log
335 Analytics workspace scope to grant the identity **Owner**, but ONLY when the
336 caller holds `Microsoft.Authorization/roleAssignments/write` there.
337
338Each write is confirmation-gated (Stage 5), touches only the workspace identity
339and its LA role (nothing else), exposes no tokens/secrets/auth headers, and
340the Skill states the capability path used. If the caller lacks role-assignment
341permission, the Skill MUST NOT force it — it instructs the user / an admin to run
342the assignment instead. This does NOT permit any other non-GET `az rest` calls or
343any broader `az` usage.
344
345### Response style (ENFORCED)
346
347Behave like a **guided product experience**, not a backend debugger.
348
349- Use concise, business-friendly language.
350- Never show internal implementation steps (CLI, REST, tokens, API calls) unless
351 the user explicitly asks and the API is documented/supported.
352- Never expose internal limitations ("public API limitation", "CredentialType
353 not supported", "headless OAuth failure") in user-facing output.
354- Never ask for secrets, OAuth codes, cookies, redirect URLs, tokens, or nonce
355 values.
356- Summarize findings. Do NOT expose endpoint experimentation, API probing,
357 OpenAPI / schema exploration, retry investigations, or low-level debugging
358 details in user-facing output unless the user explicitly asks for them.
359- After each stage: present a short summary, ask for explicit confirmation,
360 STOP and WAIT.
361
362---
363
364## Stage 1 — Intent and scope
365
366Confirm what the user wants: onboard observability data into Fabric, explore a
367business insight, or both. Capture (in plain language) any workspace names or
368business outcome they already mention — but do not yet drive correlation.
369
370## Stage 2 — Log Analytics workspace selection
371
372Application Insights telemetry is queried through its backing Log Analytics
373workspace (workspace-based Application Insights). Help the user pick the correct
374Log Analytics / Application Insights-backed workspace.
375
376- If the user did not provide a workspace, ask for the subscription, then present
377 a concise list of supported workspaces (name + resource group + location).
378 Never expose raw API responses.
379- Prefer a case-insensitive name filter over listing everything when the
380 subscription has many workspaces.
381
382### Exact-name-not-found fallback (REQUIRED)
383
384When the user names a workspace and no **exact** match exists, the Skill MUST NOT
385fail. Instead:
386
3871. Ask for the subscription if not provided (do not guess).
3882. Offer similar workspaces (names that **contain** the term or are a close
389 case-insensitive/partial match). Broaden the search if a narrow filter returns
390 nothing.
3913. Present candidates as a concise numbered list (name + resource group +
392 location), then STOP and wait for the user to pick.
3934. If exactly one similar workspace is found, still confirm before proceeding.
3945. If none is found, say so plainly and ask for a different subscription or term.
395
396Never fabricate a workspace name or GUID — only offer real discovered
397workspaces.
398
399## Stage 3 — Fabric workspace selection
400
401Help the user choose the target Fabric workspace (display name + id). Use a
402case-insensitive substring filter when helpful. Read-only; nothing is created
403here. Never expose raw API responses or tokens.
404
405### Fabric Workspace Discovery & Capability Resolution Policy (REQUIRED)
406
407Fabric workspaces are **not** Azure Resource Manager resources, so absence of an
408automatic enumeration path does NOT mean no Fabric workspace exists. **Never
409terminate the workflow early**: if automatic discovery fails, ask the user for a
410Fabric Workspace **Name**, **ID**, or **URL**, validate it as far as the available
411capabilities allow, and continue. Never auto-select a workspace, never fabricate a
412workspace or a validation result, and mark Stage 3 BLOCKED only after every
413discovery mechanism AND every user-supplied resolution path has been exhausted.
414
415Follow the full discovery order, the interpretation rules, and the UI-guided
416last-resort boundary in
417[references/workspace-discovery-policy-reference.md](references/workspace-discovery-policy-reference.md).
418
419## Stage 4 — Identity selection and validation
420
421### Identity selection (REQUIRED first — WAIT for the user)
422
423Validation MUST run against the **identity that will actually perform the flow**,
424so the identity is chosen **before** any validation check — not deferred to
425Stage 5. Do NOT silently reuse whatever `az` happens to be signed in as.
426
427Present the choice and STOP — ask this as **normal chat text (a plain numbered
428list, not a code block)**:
429
430Which identity should I use for this onboarding?
431
4321. **Service Principal (recommended)** — automated, non-interactive; best for
433 repeatable runs and CI. Requires tenant id, app/client id, and a securely
434 provided secret/certificate.
4352. **Your user account (interactive sign-in)** — if you prefer to run as
436 yourself, or a Service Principal is not available.
437
438Invite the user to reply **1** or **2**; note that Service Principal is
439recommended.
440
441- **Recommend Service Principal**, but let the user choose. If the user asks to
442 sign in as themselves, allow interactive user login and continue as the user.
443- After the choice, confirm the effective identity (e.g. `az account show`) so
444 validation runs against the right principal. If it does not match the chosen
445 identity, stop and resolve the sign-in before validating.
446- Carry the chosen identity forward: Stage 5 connection resolution and all later
447 Fabric-modifying actions use this same identity.
448
449### Validate against the chosen identity
450
451Before any creation, verify **for that identity**:
452
453- The workspace exists.
454- The **chosen identity** has the required Log Analytics access.
455- The **chosen identity** has sufficient Fabric workspace permission to operate
456 (and, for a Service Principal, that the tenant setting *"Service principals can
457 use Fabric APIs"* is enabled).
458- Surface early that connection detection/reuse will later need the chosen
459 identity to hold **a role** on the Azure Monitor connection (a **User** role is
460 enough; **Owner** is not required), so a permission gap is caught here rather
461 than at Stage 5.
462- For the Mode B **workspace-identity** connection option (Stage 5), the chosen
463 identity must be a workspace **Admin** (required to provision the workspace
464 identity). The Skill can assign the identity's Log Analytics role itself
465 when the caller holds role-assignment permission (**Owner** / **User Access
466 Administrator**) on the LA scope; otherwise it instructs the user. Surface both
467 early.
468
469If validation fails, summarize which checks passed/failed in user terms, explain
470the missing capability, and offer to try another workspace, grant the missing
471permission, or switch identity. See
472`references/azmon-fabric-api-reference.md` for supported-scope rules.
473
474### Validation capability discovery (REQUIRED)
475
476Before declaring validation capability unavailable, the Skill MUST determine whether the environment provides one of the following:
477
478- Fabric REST APIs
479- Azure REST APIs
480- Fabric Actions
481- Azure CLI
482- Azure Resource Graph
483
484MCP availability is only one possible execution path.
485
486The Skill MUST report validation capability unavailable only after evaluating all supported execution paths and finding none.
487
488Before declaring validation capability unavailable, the Skill MUST:
489
4901. Determine whether another supported execution path exists.
4912. Attempt capability discovery using all supported mechanisms available
492 in the current environment.
4933. Only after all supported mechanisms have been evaluated and none are
494 available may the Skill declare the capability unavailable.
495
496## Stage 5 — Connection resolution
497
498Two connection modes are supported. **Prefer Service Principal (Mode A)** — the
499automated, non-interactive path — as the default. Fall back to **OAuth (Mode B)**
500only when Service Principal is unavailable or the user explicitly requests it.
501Keep the two modes **separate**. Never route OAuth through Service Principal
502logic, and never route Service Principal through OAuth / interactive sign-in
503logic. See
504[references/azmon-fabric-api-reference.md](references/azmon-fabric-api-reference.md)
505for the authoritative connector rules **and the exact documented connection API
506endpoints and payload shapes** (List / Get / Create Connection + List Supported
507Connection Types). Use those documented shapes — do **not** guess a connection
508payload or go searching general docs. When the Azure Monitor connector's exact
509`type` / `creationMethod` / `parameters` are unknown, resolve them from the
510`supportedConnectionTypes` endpoint rather than assuming.
511
512### Mode selection (REQUIRED order)
513
514The identity was already chosen and validated in **Stage 4 (Identity selection)**.
515Use that identity here — do not re-prompt unless the user changes it. Map the
516chosen identity to its connection mode:
517
5181. **Service Principal → Mode A.** If a matching Service Principal connector
519 already exists for the same Log Analytics workspace, reuse it. Otherwise, when
520 the required Service Principal inputs are available (tenant id, app/client id,
521 and a securely-provided secret/certificate reference), create-or-reuse the
522 Service Principal connector automatically — no UI step.
5232. **User / interactive → Mode B.** Use when the user chose to sign in as
524 themselves, the Service Principal is unavailable, or the tenant disallows it.
525 In Mode B, first prompt the user to choose the connection authentication method
526 — interactive OAuth or workspace identity (see "Mode B — choose connection
527 authentication" below) — then route to that sub-branch.
528
529### Connection visibility caveat (applies to BOTH modes)
530
531To be **discoverable**, a connection must have **at least one role assigned to the
532calling identity** — whether the **Service Principal** (Mode A) or the **user**
533(Mode B). Any assigned role makes it appear in the listing and reusable; a
534**User** role is enough for detection and reuse, and **Owner** is only needed to
535**manage / modify / delete** it. If the caller holds **no role** on a connection,
536the API will **not** return it — that is **by design**, not a failure.
537
538Therefore, if the search finds **no** matching connection, the Skill MUST NOT
539immediately conclude the connection does not exist. It MUST first consider that
540the connection may exist but simply be **invisible to the current identity
541because it holds no role on it**, and:
542
543- State that a matching connection was not found **for the current identity**,
544 and that this can mean either (a) no such connection exists, or (b) one exists
545 but the calling Service Principal / user holds **no role** on it.
546- Advise assigning the Service Principal or user **a role** on the existing Azure
547 Monitor connection (for the same Log Analytics workspace) — a **User** role is
548 enough for detection and reuse — then re-run detection. (If a Service Principal
549 still can't see it after a lower role is granted, see the Service Principal note
550 in
551 [references/azmon-fabric-api-reference.md](references/azmon-fabric-api-reference.md).)
552- Only after this permission possibility has been surfaced may the Skill proceed
553 to create a new connector (Mode A) or the OAuth create-once guidance (Mode B).
554
555Never fabricate a connection or claim one exists without a real listing match.
556
557### Portal guidance boundary
558
559Portal-guided instructions are permitted ONLY for OAuth Azure Monitor connector creation.
560
561Portal guidance is NOT an allowed fallback for:
562
563- LAW validation
564- Fabric workspace validation
565- Connection detection
566- Connection reuse
567- Service Principal connector creation
568- Mirrored Catalog item creation
569- Discovery
570- Monitoring
571- Refresh
572- Eventhouse shortcut creation
573- Schema verification
574- Operations Agent creation
575
576If execution capability for these actions is unavailable, the Skill MUST stop and identify the missing capability.
577
578### Mode A — Service Principal (automated create-or-reuse, default)
579
580Present this as **"connect using Service Principal"** — the automated,
581non-interactive path (no user login, no UI step). This is the **preferred**
582default; attempt it before OAuth.
583
584- **Idempotent create-or-reuse**: if a matching Azure Monitor Service Principal
585 connector already exists for the same Log Analytics workspace (same data source
586 path + Service Principal credential type), reuse it — never create a duplicate.
587- Only **one** connector is created per run.
588- **Never** reuse a non-Service-Principal (e.g. OAuth) connector in this mode.
589- **Never** ask the user to paste a client secret into chat. Secrets come from
590 **environment variables or Key Vault references** only, are never echoed,
591 logged, exposed, or included in generated instructions.
592- If required Service Principal inputs are missing, describe **what** is missing
593 (tenant id, app/client id, and a securely-provided secret reference) using
594 presence checks only — never request the secret value in chat. Only when
595 Service Principal inputs cannot be provided, fall back to OAuth (Mode B).
596
597Automation boundary: infrastructure (connector create-or-reuse, mirrored item
598creation) is automated; **business decisions** (Eventhouse/KQL DB selection,
599shortcut creation) always require explicit user confirmation.
600
601### Mode B — choose connection authentication (REQUIRED prompt)
602
603When the chosen identity is User / interactive (Mode B), the connection can be
604created two ways. Before detecting or creating anything, present this choice as
605**normal chat text (a plain numbered list, not a code block)** and STOP for the
606user's answer:
607
608How should I authenticate the Azure Monitor connection?
609
6101. **Interactive sign-in (OAuth)** — you sign in once in Fabric → Manage
611 Connections; the connection uses your organizational account.
6122. **Workspace identity (no secrets)** — Fabric's automatically-managed workspace
613 identity is used as the credential; you grant it access on your Log
614 Analytics workspace. No secret to handle.
615
616Route to the matching sub-branch below — **1 → Mode B (OAuth)**, **2 → Mode B
617(Workspace identity)**. Keep the two strictly separate. If the user has no
618preference, note that workspace identity avoids interactive sign-in and secret
619handling, but WAIT for their choice — never auto-select.
620
621### Mode B — OAuth (UI-guided only, fallback)
622
623Use this sub-branch when the user picked option 1 above, i.e. only when Service
624Principal (Mode A) is unavailable or the user explicitly requests OAuth. OAuth
625connector **creation** is UI-guided only (Fabric → Manage Connections) — the Skill
626never creates one through an API; it only **detects and reuses** an existing
627connection, read-only, and only when the Log Analytics workspace matches exactly.
628
629Follow the full detection order, reuse rules, and user-facing wording in
630[references/oauth-connection-reference.md](references/oauth-connection-reference.md).
631Keep this strictly separate from Mode A.
632
633### Mode B — Workspace identity (no secrets)
634
635Use this sub-branch when the user picked option 2 above. Fabric's
636automatically-managed **workspace identity** is used as the connection credential
637(no secret). This flow provisions the identity if needed, ensures it has a
638sufficient Log Analytics role — **assigning it automatically when the caller is
639permitted, otherwise instructing the user** — then creates the connection.
640
641Follow the full sequence, endpoints, gates, and payloads in
642[references/workspace-identity-connection-reference.md](references/workspace-identity-connection-reference.md).
643Key gates: provisioning the identity is confirmation-gated (caller must be
644workspace **Admin**); the LA role is assigned by the Skill when the caller
645holds role-assignment permission (else the Skill instructs and WAITs for
646confirmation) — both writes are confirmation-gated; then create the connection
647using the `WorkspaceIdentity` credential type. Keep this strictly separate from
648Mode A.
649
650## Stage 6 — AzMon / Mirrored Catalog item creation or reuse
651
652Create the Azure Monitor **Mirrored Catalog** item in the target Fabric
653workspace, or reuse an existing matching item. This is a Fabric-modifying action
654→ confirm first. Supported Mirrored Catalog operations (item CRUD, definition,
655discovery, monitoring, refresh) are documented in
656[references/mirrored-catalog-reference.md](references/mirrored-catalog-reference.md).
657
658### Service Principal item-creation (IMPORTANT — prefer reuse; observed fallback)
659
660Per Microsoft Learn, the **Create Mirrored Catalog** API lists **service principals
661and managed identities** as supported identities for create, so a Service Principal
662create is **documented as supported** and is not an absolute platform limitation.
663
664> **Observed fallback.** Some Service Principal runs have nonetheless seen the
665> item **create** rejected under an application-only token (the underlying
666> item-creation path can run **on-behalf-of** a signed-in user). Treat this as
667> **observed** tenant behavior, not a documented rule, and keep the docs-accurate
668> default: attempt create under the SP, and only fall back to a user (delegated) /
669> UI context if the create call is actually **denied or unavailable**.
670
671Get, list, **update**, discovery, monitoring, refresh, and shortcut operations all
672work under an application-only SP token once the item exists.
673
674Consequently, when running under a Service Principal, the Skill MUST:
675
676- **Prefer reuse** — reuse an existing Azure Monitor Mirrored Catalog item (and
677 its existing connection) that the SP can see and operate on. This is the
678 preferred path: build on an already-created item + connection rather than
679 creating a new one. The SP can then **update** and operate that item normally.
680- If no reusable item exists, **attempt to create the item under the SP** (the
681 create API documents SP/managed-identity support). Only if that create is
682 **denied or unavailable** (the observed fallback above), **create the item in a
683 user context** — either from the **Fabric UI**, or via a **user (delegated)
684 sign-in** — preferably seeded from an existing item and connection. After the
685 item exists, the Service Principal can resume the automated flow (update,
686 discovery, monitoring, refresh, shortcuts) on that item.
687- Never claim the item was created by the SP when the create actually occurred in
688 a user/UI context.
689
690Downstream Mirrored Catalog operations (update, discovery, monitoring, refresh)
691remain available to the Service Principal once the item exists.
692
693### Table selection via scope (choosing which tables the item mirrors)
694
695The item does **not** take a free-form list of table names — it mirrors by
696**`scope`** (a namespace hierarchy path in the definition), and that scope MUST be
697a **`Selectable`** value returned by the **List Scopes** discovery API. To target
698only the tables the user wants:
699
700- Call **List Scopes** and choose a `Selectable` scope for the item. If the user
701 already knows the target tables, pick the **narrowest `Selectable` scope** that
702 covers them. If there is no intent yet (the user wants to explore first),
703 create with a **broader scope** and optionally **re-scope** narrower later —
704 updating the item definition — once intent is captured. Use only real returned
705 scope values — never fabricate a scope or table name.
706- If the narrowest available `Selectable` scope is **broader** than the requested
707 set, the item **will also mirror the extra sibling tables** under that scope —
708 mirroring cannot exclude individual siblings. State this plainly and get
709 explicit confirmation before creating.
710- For an existing/reused item, read its current definition scope before assuming
711 it matches the request; do not fabricate definition fields.
712
713### Default mirror set (REQUIRED starting point)
714
715Unless the user specifies otherwise, the **default set of tables to mirror** is
716every table that (a) appears in real **List Scopes / Discovery** output and (b)
717matches one of these name prefixes (case-insensitive; tolerate the `_CL`
718custom-table suffix):
719
720- `App*` — Application Insights tables
721- `OTel*` — OpenTelemetry-native tables (e.g. `OTelLogs`)
722- `XD*` — custom, security-related log tables
723
724Then **ask the user whether they want any additional tables** before creating
725(confirmation gate — present the resolved set and WAIT).
726
727- Match prefixes against **real discovered tables only** — never invent a table.
728 If a prefix matches nothing, omit it silently.
729- Resolve the default set to the **narrowest single `Selectable` scope that covers
730 all matched tables**. If that scope also pulls in **extra sibling tables** beyond
731 the default set, **list the extras explicitly**, explain that siblings cannot be
732 individually excluded, and get confirmation before creating. Once confirmed, the
733 extras are **expected** — they are not failures at the Stage 8 equality check.
734- Adding user-requested tables may widen the chosen scope — re-resolve and
735 re-disclose.
736- If **none** of `App*` / `OTel*` / `XD*` match any discovered table, fall back to
737 presenting all/representative discovered tables (explore-first) and let the user
738 choose.
739- **`XD*` security tables** are only considered **after** the workspace has passed
740 Stage 4's validation (a supported, validated workspace); an unsupported-workspace
741 block takes precedence and table selection MUST NOT be used to bypass it.
742- **On reuse:** read the existing item's current scope and compare its mirrored
743 set to the default set. If not fully covered, offer to **re-scope** (update the
744 item definition) to add the missing `App*`/`OTel*`/`XD*` tables, disclosing any
745 extra siblings — never re-scope silently; confirm first.
746
747The confirmed set (default + confirmed siblings + any tables the user adds) becomes
748the **expected set** for the Stage 8 requested-vs-mirrored equality check.
749
750### First-time mirroring latency (disclosure — REQUIRED)
751
752For a **first-time mirrored workspace**, tell the user upfront that mirrored
753tables and data typically take **around 5 minutes** to materialize and become
754queryable after the item is created. Until then, discovery/queries may return
755empty or partial results — this is **expected**, not an error. Do not declare
756tables missing during this window: verify mirror/refresh status, wait, and
757re-check before concluding anything.
758
759After the item is created or reused, optionally capture business intent now
760(Stage 7) if the user already has a goal; otherwise proceed to table discovery
761and exploration and capture intent before schema verification (Stage 12).
762
763## Stage 7 — Business Insight Capture (optional here; deferrable)
764
765If the user already has a business question, capture it now so table discovery
766(Stage 8) and Eventhouse scoring (Stage 9) can be guided by it. If they don't,
767this stage is **optional right now** — the user may explore their data first
768(Stages 8–11) and provide intent later. Either way, intent is **MANDATORY before
769schema verification (Stage 12)** and correlation (Stage 14); capturing it early is
770just an optimization that focuses discovery.
771
772When capturing intent, ask in business language, e.g.:
773
774- Did service availability issues impact bookings?
775- Did request latency reduce customer conversions?
776- Did exceptions affect revenue or orders?
777- Did dependency failures impact specific customers, tenants, regions, or
778 flights?
779- Did incidents affect SLA, usage, or customer activity?
780- Did traffic drops correlate with usage KPI degradation?
781
782### Enforcement
783
784The Skill MUST NOT proceed to schema verification (Stage 12) or business
785**correlation** (Stage 14) without either:
786
787- (a) user-provided business intent, OR
788- (b) explicit user selection from suggested directions.
789
790Intent may be provided here or after exploration, but it MUST exist before
791Stage 12. Never assume intent.
792
793### Fallback (when the user is unsure / vague / no exact match)
794
795Suggest 3–5 directions, each framed as **observability signal → business
796impact**, and ask the user to choose one:
797
7981. Availability failures → booking completion impact.
7992. Request latency → conversion or checkout drop.
8003. Exceptions → failed orders or revenue at risk.
8014. Dependency failures → customer / tenant / region impact.
8025. Traffic drops → usage KPI degradation.
803
804### Important distinction
805
806Capturing intent early is **allowed but optional** — it MUST exist before schema
807verification (Stage 12). Either way, the Skill MUST NOT generate correlation logic
808yet. Correlation logic only comes after shortcuts exist, schema is verified, data
809is queryable, dynamic fields are inspected, join candidates are validated, and
810data freshness is checked (Stages 10–14).
811
812## Stage 8 — Azure Monitor table discovery
813
814Browse candidate Azure Monitor / Application Insights tables. **If a business goal
815was captured (Stage 7),** filter to the tables relevant to it. **If there is no
816intent yet (explore-first),** present all/representative discovered tables so the
817user can browse. Use only real discovered scope/table values — never fabricate
818table names. Use
819[references/telemetry-table-reference.md](references/telemetry-table-reference.md)
820to explain what each table means in business terms and which tables best fit the
821stated goal (or what each table offers when exploring).
822
823### Discovery API fallback policy (REQUIRED)
824
825The **primary** discovery mechanism is the Mirrored Catalog Discovery APIs. If
826discovery appears incomplete, do NOT immediately conclude tables are missing or
827switch to alternative metadata paths. First:
828
8291. Verify mirror status.
8302. Verify refresh / sync status.
8313. Verify discovery scope.
8324. Retry discovery.
833
834Only after these checks may the Skill evaluate alternative metadata paths. See
835[references/mirrored-catalog-reference.md](references/mirrored-catalog-reference.md).
836
837### Requested-vs-mirrored set-equality check (REQUIRED once a specific table set is requested)
838
839This check applies once a **requested table set exists** — whether specified up
840front or after intent is captured later. When the **default mirror set** (Stage 6)
841or a user-adjusted set is in effect, that set is the **requested set** for this
842check, and any sibling tables disclosed and confirmed under the narrowest-common-
843scope rule are **expected** (compare against the chosen scope's expected contents,
844not a bare table list — do not report confirmed siblings as failures). When the
845user asked for a specific set of
846tables, verify the item mirrors
847**exactly** that set — use **equality, not subset** ("my tables are present" is not
848enough). Compare the **actually-mirrored** table set (from Discovery / Monitoring)
849against the **requested** set and report the result:
850
851- **Extra tables present** → the chosen scope is broader than requested. Report the
852 extras and, if a narrower `Selectable` scope exists, offer to re-scope; otherwise
853 state that the source only exposes a broader scope and the extras are
854 unavoidable.
855- **Requested tables missing** → the mirror may not have materialized yet. Verify
856 mirror/refresh status, run a **Refresh/sync**, wait, then re-check — do not
857 declare them absent prematurely.
858- **Exact match** → confirm and proceed.
859
860Never fabricate the mirrored table set; enumerate it from real Discovery /
861Monitoring results only.
862
863## Stage 9 — Eventhouse / KQL database target selection
864
865Ask the user which Eventhouse should host the LA-table shortcuts. Present these
866options as **normal chat text (not a code block)** and require explicit
867confirmation:
868
869- **A — A specific existing Eventhouse** (e.g. one that already holds business
870 data you want to correlate with). The Skill creates LA-table shortcuts
871 **there**, colocating telemetry with the business data.
872- **B — A new Eventhouse.** The Skill creates it and the LA-table shortcuts;
873 starts empty.
874
875Both options are writable and support the Operations Agent path (they can host
876`IncidentBins` materialization).
877
878Run **Eventhouse Recommendation Mode** to inform the choice — discover available
879Eventhouses, inspect their contents (tables, shortcuts, KQL databases), and score
880each by relevant business tables, relevant telemetry tables, existing shortcuts,
881queryable tables, KQL database availability, and data freshness. **When the
882user's goal is correlating telemetry with existing business data, recommend
883option A** (colocation); otherwise a new Eventhouse is a clean starting point.
884Present as normal chat text:
885
886- **Recommended target:** <A ‹EventhouseName› | B new>
887- **Reason:** <why>
888- **Alternatives:** <list>
889
890The Skill MUST NOT auto-select. Present the recommendation, state exactly what
891will be created, and require explicit confirmation. See
892[references/eventhouse-shortcuts-reference.md](references/eventhouse-shortcuts-reference.md).
893
894## Stage 10 — External Delta table registration planning
895
896Plan **external Delta table registrations** for the resolved table set into the
897**chosen/new Eventhouse** — name the target Eventhouse in the plan header —
898**before** any schema verification or join logic. Present the plan and STOP for
899confirmation.
900
901Key rules (see the shortcuts reference for detail):
902
903- Queryability in a KQL database comes from registering each table as an
904 **external Delta table** pointing at the mirrored item's OneLake
905 `Tables/dbo/<Table>` path — **not** from the Core Shortcuts API (which creates a
906 link only). Query via `external_table('<name>')`.
907- Plan, per table: exact name, OneLake `Tables/dbo/<Table>` path, target KQL
908 database, and that the schema will be read from the table's Delta log.
909
910### Query acceleration policy — external delta tables (MUST — always `true`)
911
912Query acceleration is a **policy on external delta tables** (set via
913`.alter external table … policy query_acceleration`), **not** a shortcut-object
914property. Every registered external delta table gets **acceleration enabled
915(`true`)** — not optional. Include an `Acceleration Enabled (always Yes)` plan-table
916column; if the environment can't support it, surface that rather than registering
917without the policy. Full policy in
918[references/eventhouse-shortcuts-reference.md](references/eventhouse-shortcuts-reference.md#external-delta-table-query-acceleration-policy-must--always-true).
919
920## Stage 11 — External Delta table registration
921
922Only after explicit confirmation, register each table as an **external Delta
923table** in the target KQL database (report which one): read the table's schema
924from its Delta log, map Delta → Eventhouse types, and run `.create external table
925['<Table>'] (<cols>) kind=delta ( h@'<OneLake Tables/dbo/<Table> path>;impersonate' )`
926via `POST {clusterUri}/v1/rest/mgmt`. Then verify with `.show external tables` +
927`external_table('<Table>') | take 1`. The Core Shortcuts API is **not** required
928for queryability (it creates a link only). If a table is not queryable → STOP and
929return to planning / registration. See
930[references/eventhouse-shortcuts-reference.md](references/eventhouse-shortcuts-reference.md)
931for the schema-read, type mapping, and command template.
932
933When registering ANY external delta table, **always enable the query acceleration
934policy (`true`)** per the
935[Query acceleration policy](references/eventhouse-shortcuts-reference.md#external-delta-table-query-acceleration-policy-must--always-true),
936and report the resulting status (expected: enabled).
937
938## Stage 12 — Schema and data verification (REQUIRED before correlation)
939
940Never build correlation logic on assumptions or screenshots. Before proposing any
941join, bin, or threshold, verify against the **actual** KQL database. Business
942intent MUST already be captured/confirmed before this stage — if it was deferred
943at Stage 7, capture it now (using the Stage 7 questions/fallback) before
944proceeding, since the telemetry-source selection below is scored by goal
945relevance. Never assume intent.
946
947### Preconditions
948
9491. Operational telemetry tables are available in the Eventhouse / KQL database.
9502. Business tables are available in the same database or queryable via shortcuts.
9513. Tables are **queryable**, not just visible in OneLake.
9524. Schema retrieved via `getschema`.
9535. Dynamic fields inspected and sampled.
9546. Candidate join keys extracted from top-level **and** dynamic columns.
9557. Join keys validated with **non-zero** match results (when a direct join is
956 proposed).
9578. Data freshness verified.
9589. Time window aligned to the real data range.
95910. Relevant categorical values confirmed from real data where rules depend on
960 them.
961
962### Steps
963
964> **Query convention.** Mirrored telemetry tables are **external tables** — query
965> them via `external_table('<name>')` (they do not appear in `.show tables`);
966> business tables that are **managed** in an Eventhouse use their bare
967> name.
968
9691. **Retrieve real schema.** For each table:
970 `external_table('<TableName>') | getschema | project ColumnName, ColumnType`.
971 Use authoritative column names/types — not names guessed from screenshots or
972 table names.
9732. **Inspect and sample dynamic fields.** Business join keys are often nested in
974 dynamic columns (`Properties`, `CustomDimensions`, `Details`, `Measurements`,
975 `Payload`, `Context`). Sample rows and inspect keys. See
976 [references/app-insights-dynamic-fields-reference.md](references/app-insights-dynamic-fields-reference.md).
9773. **Extract candidate business identifiers** with explicit KQL
978 (`tostring(Properties.BookingId)`, with casing fallbacks via `coalesce`).
9794. **Validate join keys against real data.** Prove a candidate joins — run the
980 join and confirm non-zero matches:
981
982 ```kusto
983 external_table('AppEvents')
984 | extend BookingId = tostring(Properties.BookingId)
985 | where isnotempty(BookingId)
986 | join kind=inner (Bookings | project BookingId = tostring(BookingId)) on BookingId
987 | summarize MatchedRows=count(), DistinctBookings=dcount(BookingId)
988 ```
989
990 Non-zero → **direct join, high confidence**. Zero → the key is wrong or data
991 doesn't overlap; find the real one.
9925. **Check freshness and align the window.**
993 `external_table('<TableName>') | summarize Rows=count(), MinTime=min(TimeGenerated), MaxTime=max(TimeGenerated)`.
994 Do not assume `ago(1h)`; use a window covering the actual data range and
995 explain it in user terms.
9966. **Confirm categorical values** used by rules
997 (`external_table('<Table>') | summarize count() by <field>`) so impact rules
998 use real categories.
999
1000### Telemetry source selection framework (REQUIRED)
1001
1002Telemetry source selection MUST be **data-driven**. Before selecting a correlation
1003model, the Skill MUST inspect ALL candidate telemetry sources discovered (e.g.
1004AppEvents, AppExceptions, AppRequests, AppDependencies, AppTraces, AppPageViews,
1005AppBrowserTimings, AvailabilityResults, and any other telemetry source present) —
1006not just one.
1007
1008Score each candidate telemetry source by:
1009
10101. Business identifiers discovered.
10112. Dynamic-field richness.
10123. Direct-join confidence.
10134. Validated match count.
10145. Business-process context.
10156. Relevance to the selected business goal.
1016
1017Select the highest-scoring telemetry source. The Skill MUST NOT automatically
1018prioritize AppExceptions, and MUST NOT automatically prioritize AppEvents — the
1019winner is whichever source scores highest against real data.
1020
1021### Exit criteria (MANDATORY)
1022
1023Before Stage 14, ALL must hold: schema retrieved via `getschema`; join keys
1024validated with non-zero matches (when a direct join is used); freshness verified
1025and window aligned; relevant categorical values confirmed. If any fails → STOP,
1026do not proceed.
1027
1028### Handoff (MANDATORY)
1029
1030Present a concise summary (verified join keys, match results, business impact if
1031any, data time window). Then ask: "Do you want to continue to business analysis
1032(impact modeling, a dashboard, and optionally an Operations Agent) based on this
1033verified model?" HARD STOP and wait. On confirmation, continue with Stages 13–17
1034as defined in
1035[references/business-analysis-workflow.md](references/business-analysis-workflow.md).
1036
1037## Stages 13–17 — Business-oriented analysis (defined in the reference)
1038
1039The business-oriented analysis half (business data discovery/scoring, correlation
1040planning, an optional Real-Time KQL dashboard, and an optional gated Operations
1041Agent) is defined authoritatively in
1042[references/business-analysis-workflow.md](references/business-analysis-workflow.md)
1043(with Appendices A–B) and loaded only when the user opts in at the Stage 12
1044handoff. On opt-in, **do not work from memory** — open that file and follow
1045Stages 13–17 exactly; the controller still tracks and enforces these stages, their
1046order, hard stops, and confirmation gates (including dashboard-before-agent and
1047the Stage 16 "do we even want an agent?" gate).
1048
1049## Troubleshooting (user-facing)
1050
1051- **"No playbook generated" / cannot compute a field** → the instructions
1052 described fields conceptually. Add the explicit KQL materialization query, add
1053 per-field KQL definitions, ensure alert rules reference actual output columns,
1054 add dynamic-field extraction, and clarify join keys/identifiers. Do not just
1055 reword prose.
1056- **Start succeeds but no Teams alert arrives** → likely no data matched the
1057 rule. Switch to POC/debug thresholds; explain no data may have matched. Do not
1058 imply platform failure without evidence.
1059
1060## Must / Prefer / Avoid
1061
1062### Must
1063- Enforce stages, hard stops, and confirmation gates.
1064- Keep OAuth (UI-guided) and Service Principal (automated create-or-reuse)
1065 strictly separate.
1066- Validate permissions before creation.
1067- Verify schema, dynamic fields, join matches, and freshness before correlation.
1068- Provide explicit KQL in Operations Agent instructions.
1069
1070### Prefer
1071- Service Principal (automated) over OAuth (UI-guided) for connection
1072 resolution; fall back to OAuth only when Service Principal is unavailable.
1073- Direct joins over time-window correlation.
1074- Real discovered values over anything guessed.
1075- Business-language confirmation over technical questions.
1076
1077### Avoid
1078- Do not depend on or mention MCP in the user-facing flow.
1079- Do not present internal/undocumented APIs as supported.
1080- Do not claim OAuth connector creation via public API.
1081- Do not fabricate workspaces, tables, schema, IDs, or query results.
1082- Do not ask for secrets, OAuth codes, tokens, cookies, or nonces.
1083- Do not claim causality when only time-window correlation exists.
1084
1085## Examples
1086
1087### Example 1 — Onboard Azure Monitor observability data, then check business impact
1088**User:** "In my `Observability` workspace, onboard our Azure Monitor / Log Analytics observability data (it holds our Application Insights tables) into Fabric, then tell me whether last week's latency spike hurt checkout conversions."
1089
1090**Skill behavior:** Runs the staged workflow — confirms the target workspace and checks onboarding prerequisites (a reachable Azure Monitor / Log Analytics source or connection), stopping with an explicit list of what is missing if any prerequisite is absent. Once the observability data (including the Application Insights telemetry tables) is onboarded and queryable, it discovers the real business dataset in the workspace, correlates the latency signal against the conversion KPI using discovered keys, and reports a specific business-impact conclusion (or an error if the required data is unavailable). It never fabricates workspace names, tables, or query results, and never exposes tokens or connection internals.
1091
1092### Example 2 — Out-of-scope authoring request
1093**User:** "Create a new Spark notebook and build a Delta table pipeline to load my business dataset."
1094
1095**Skill behavior:** Declines the out-of-scope authoring request, creates nothing in Fabric, and directs the user to the appropriate authoring mode in `spark-cli` rather than taking over the task.