fabric-monitoring-dmv

Imported from ThomazRossito/ai-data-agents (plugins/ai-data-agents/skills/fabric-monitoring-dmv/SKILL.md). Install upstream with npx skills add ThomazRossito/ai-data-agents --skill fabric-monitoring-dmv. Copyright stays with the author.

SKILL: fabric-monitoring-dmv

Fonte: Microsoft Fabric XMLA Endpoint (pyadomd, Power BI API) Atualizado: Abril 2026 Uso: Leia este arquivo ANTES de monitorar modelos semanticos Fabric via DMV.

Overview

Monitora modelos semanticos Fabric e capacidade programaticamente via DMV (Dynamic Management Views) -- executa queries TMSCHEMA contra endpoint XMLA, monitora refreshes, consulta saude de modelo e capacidade utilizada via REST API.

O Problema

Monitoramento manual de modelo semantico Fabric (saude, partitions, memoria, refresh status) requer conexao direta a endpoint XMLA com pyadomd ou DAX Studio, e nao escala para multiplos modelos. Alem disso, rastrear historico de refresh e correlacionar com capacidade consumida requer multiplas fontes de dados (DMV + Power BI API).

A Solucao

Esta skill encapsula monitoramento completo:

• Conexao via XMLA endpoint com credenciais SPN ou User
• Queries DMV (TMSCHEMA_TABLES, TMSCHEMA_PARTITIONS, TMSCHEMA_MEASURES, etc)
• Monitoramento de refresh (status, tempo, historico)
• Consultas DAX customizadas contra modelo
• Analise de tamanho de modelo, partitions, overhead de memoria
• Integracao com Power BI API para refresh scheduling

Resultado: Observabilidade completa de modelo semantico com 1-2 queries encapsuladas.

Dependências e Versões

⚠️ Breaking change em v19.82.0 (ADOMD): O pacote NuGet foi renomeado. O novo pacote multi-runtime é Microsoft.AnalysisServices.AdomdClient (sem sufixo). Os pacotes legados .retail.amd64 (Framework) e .NetCore.retail.amd64 (Core) ainda existem no NuGet para compatibilidade, mas prefira o novo pacote unificado para projetos novos.

Instalação pyadomd:

pip install pyadomd

O pyadomd requer que o DLL do ADOMD.NET esteja no sys.path antes do import:

from sys import path
path.append(r'C:\Program Files\Microsoft.NET\ADOMD.NET\150')
from pyadomd import Pyadomd

XMLA Endpoint — Mudanças de Plataforma (2025)

⚠️ Breaking change em junho 2025: A partir de 9 de junho de 2025, todos os SKUs de capacidade Fabric e Power BI passaram a ter XMLA leitura e escrita habilitados por padrão. Antes dessa data, capacidades no modo padrão só permitiam leitura, e admins precisavam habilitar manualmente o modo read/write. Se seu código verificava/forçava essa configuração, revise.

Limitações de DMV via XMLA Endpoint

⚠️ Restrição confirmada (sem versão específica — comportamento atual): DMVs do tipo $SYSTEM.DISCOVER_* não são suportados via XMLA endpoint no Fabric/Power BI Premium. Apenas as famílias abaixo funcionam:

• $SYSTEM.TMSCHEMA_* — metadados do modelo tabular (tabelas, partitions, measures, colunas, etc.)
• $SYSTEM.DMSCHEMA_* — schema de mineração de dados
• $SYSTEM.MDSCHEMA_* — schema multidimensional

O DMV $SYSTEM.DISCOVER_M_EXPRESSIONS em particular não é suportado via XMLA; para obter expressões M, use o Tabular Object Model (TOM) diretamente.

DMVs do tipo $SYSTEM.DISCOVER_STORAGE_TABLE_COLUMN_SEGMENTS, $SYSTEM.DISCOVER_DB_CONNECTIONS e similares retornam erro de permissão via XMLA endpoint — eles exigem permissão de server admin do Analysis Services, que não é concedida ao contexto Fabric.

Quick Start

Exemplo mais comum -- conectar a XMLA, obter partitions enriquecidas e status de refresh:

from monitoring_dmv import (
    set_dmv_connection_string_spn,
    dmv_fetch_partitions_enriched,
    get_semantic_model_refreshes
)

# 1. Construir connection string
conn_str = set_dmv_connection_string_spn(
    client_id="00000000-0000-0000-0000-000000000001",
    client_secret="your-secret",
    tenant_id="00000000-0000-0000-0000-000000000002",
    workspace_name="analytics",
    semantic_model_name="SalesModel"
)

# 2. Obter partitions enriquecidas
partitions_df = dmv_fetch_partitions_enriched(conn_str)
print(f"Partitions: {len(partitions_df)}")
print(partitions_df[['TableName', 'Name', 'RefreshedTime']])

# 3. Obter historico de refresh
refreshes = get_semantic_model_refreshes(
    workspace="analytics",
    semantic_model="SalesModel",
    top=10
)
print(f"Ultimos refreshes: {refreshes}")

Common Patterns

1. set_dmv_connection_string_spn -- Connection com SPN

Constrói connection string para XMLA endpoint com Service Principal.

Parametros:

Fluxo interno:

1. Validar parametros nao vazios
2. Construir connection string com formato XMLA/ADOMD
3. Retorna string pronta para pyadomd

Formato da connection string SPN (ADOMD ≥ 19.67.0):

Data Source=powerbi://api.powerbi.com/v1.0/myorg/<WorkspaceName>;
Initial Catalog=<ModelName>;
User ID=app:<client_id>@<tenant_id>;
Password=<client_secret>

💡 Alternativa com AccessToken (ADOMD ≥ 19.67.0): Se você já possui um token OAuth (ex: obtido via azure-identity), pode passar diretamente via propriedade AccessToken no objeto AdomdConnection, evitando expor client_secret na connection string.

Exemplo:

from monitoring_dmv import set_dmv_connection_string_spn

conn_str = set_dmv_connection_string_spn(
    client_id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    client_secret="secret123",
    tenant_id="bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
    workspace_name="DataLake",
    semantic_model_name="FactSales"
)
# conn_str: Data Source=powerbi://api.powerbi.com/v1.0/myorg/DataLake;Initial Catalog=FactSales;...

2. set_dmv_connection_string_user -- Connection com User

Constrói connection string com credenciais de usuario (AAD).

⚠️ Aviso: Autenticação interativa (usuário/senha inline) não funciona em ambientes headless (ex: pipelines CI/CD, Databricks Jobs). Para automação, prefira SPN (set_dmv_connection_string_spn).

Parametros:

Fluxo interno:

1. Construir connection string com user_email e password
2. Retorna string pronta para pyadomd

Exemplo:

from monitoring_dmv import set_dmv_connection_string_user

conn_str = set_dmv_connection_string_user(
    user_email="analyst@company.com",
    password="userpassword",
    workspace_name="DataLake",
    semantic_model_name="FactSales"
)

3. dmv_fetch_partitions_enriched -- Obter partitions com metadata

Consulta TMSCHEMA_PARTITIONS e enriquece com nomes de tabelas.

Parametros:

Fluxo interno:

1. Executar DMV query: SELECT * FROM $SYSTEM.TMSCHEMA_PARTITIONS
2. Executar DMV query: SELECT * FROM $SYSTEM.TMSCHEMA_TABLES para nomes
3. Merge (join) com TableID para preencher TableName
4. Retorna DataFrame sorted por TableName, RefreshedTime descendente

⚠️ Limitação DMV: JOIN não é suportado na sintaxe DMV — o merge é feito em Python (pandas), não na query. Nunca tente usar JOIN direto na DMV query; ela retornará erro de sintaxe.

Exemplo:

from monitoring_dmv import dmv_fetch_partitions_enriched

partitions = dmv_fetch_partitions_enriched(conn_str)
for _, row in partitions.iterrows():
    print(f"{row['TableName']} | {row['Name']} | {row['RefreshedTime']}")

4. evaluate_dmv_queries -- Executar query DMV customizada

Executa query DMV customizada contra modelo semantico.

Parametros:

Fluxo interno:

1. Conectar a XMLA endpoint via pyadomd
2. Executar query
3. Retorna DataFrame com resultados

⚠️ Famílias DMV suportadas via XMLA Fabric: Use apenas $SYSTEM.TMSCHEMA_*, $SYSTEM.DMSCHEMA_* ou $SYSTEM.MDSCHEMA_*. Queries contra $SYSTEM.DISCOVER_* retornam erro de permissão. Sintaxe DMV não suporta JOIN, GROUP BY, LIKE, CAST ou CONVERT.

Exemplo:

from monitoring_dmv import evaluate_dmv_queries

# OK: TMSCHEMA_COLUMNS é suportado
query = """
SELECT
    TABLE_NAME as TableName,
    COLUMN_NAME as ColumnName,
    DATA_TYPE as DataType
FROM $SYSTEM.TMSCHEMA_COLUMNS
"""

cols = evaluate_dmv_queries(conn_str, query)
print(cols.head())

# EVITE: $SYSTEM.DISCOVER_STORAGE_TABLE_COLUMN_SEGMENTS retorna 403 via XMLA Fabric
# query = "SELECT * FROM $SYSTEM.DISCOVER_STORAGE_TABLE_COLUMN_SEGMENTS"  # NÃO FAÇA

5. get_semantic_model_refreshes -- Historico de refresh via Power BI API

Obtem historico de operacoes de refresh de um modelo semantico via REST API.

Parametros:

Fluxo interno:

1. Resolver workspace e modelo para IDs
2. GET /v1.0/myorg/groups/{workspaceId}/datasets/{modelId}/refreshes
3. Retorna lista com status, startTime, endTime, duration

💡 Nota de nomenclatura da API: A Power BI REST API ainda usa datasets na URL mesmo para modelos semânticos Fabric (o termo "dataset" não foi renomeado na URL). Isso é esperado e documentado; não troque por semanticmodels.

⚠️ Avisos de refresh não aparecem na resposta da API: Se o refresh foi iniciado via REST API, warnings são gravados no histórico mas os endpoints Get Refresh History e Get Refresh Execution Details não retornam os warnings na resposta JSON. Para inspecionar warnings, use XMLA (resposta inline) ou o Fabric Monitoring Hub.

Exemplo:

from monitoring_dmv import get_semantic_model_refreshes

refreshes = get_semantic_model_refreshes(
    workspace="analytics",
    semantic_model="FactSales",
    top=20
)

for refresh in refreshes:
    print(f"{refresh['startTime']} | {refresh['status']} | {refresh.get('duration')}")

6. refresh_semantic_model -- Iniciar refresh via Power BI API

Inicia refresh de modelo semantico com opcoes customizadas.

⚠️ Breaking change (comportamento confirmado 2025): Para que o refresh seja classificado como "enhanced refresh" (e não refresh simples "via API"), o payload DEVE incluir pelo menos um dos parametros enhanced: commitMode, maxParallelism, retryCount ou objects. Além disso, o workspace DEVE estar em capacidade Premium, PPU ou Fabric — workspaces Shared/Pro não suportam enhanced refresh via SPN. Em Pro/Shared, SPN retorna 403.

Parametros:

Fluxo interno:

1. Resolver workspace e modelo para IDs
2. Construir payload com type, notifyOption e parametros enhanced (se fornecidos)
3. POST /v1.0/myorg/groups/{workspaceId}/datasets/{modelId}/refreshes
4. Retorna 202 Accepted; monitorar com get_semantic_model_refreshes()

Exemplo — refresh simples:

from monitoring_dmv import refresh_semantic_model

refresh_semantic_model(
    workspace="analytics",
    semantic_model="FactSales",
    type="Full",
    notify_option="MailOnCompletion"
)

Exemplo — enhanced refresh (requer Premium/PPU/Fabric):

from monitoring_dmv import refresh_semantic_model

# Inclui commitMode/maxParallelism -> classificado como "via enhanced API"
refresh_semantic_model(
    workspace="analytics",
    semantic_model="FactSales",
    type="Full",
    commit_mode="transactional",
    max_parallelism=2,
    retry_count=1,
    objects=[
        {"table": "FactSales", "partition": "2024"}
    ]
)

💡 Dica: Enhanced refresh não atualiza tile caches automaticamente. Caches só são atualizados quando um usuario acessa o report. Considere isso em pipelines que dependem de caches atualizados imediatamente apos o refresh.

Reference Files

• dmv-queries.md -- Queries DMV comuns (TMSCHEMA), connection strings, DAX queries, refresh monitoring

Common Issues