fabric-monitoring-dmv

name	fabric-monitoring-dmv
description	Monitoramento de modelos semânticos Fabric via DMV/TMSCHEMA no endpoint XMLA — refreshes, saúde do modelo e capacidade.
updated_at	"2026-04-23T00:00:00.000Z"
source	web_search

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.

Componente	Versão atual	Notas
pyadomd (PyPI)	0.1.1	Estável; sem breaking changes recentes
Microsoft.AnalysisServices.AdomdClient (NuGet)	19.113.7	Pacote multi-runtime recomendado
ADOMD AccessToken property	desde 19.67.0	Permite OAuth token externo sem senha inline
ADOMD SPN Profiles	desde 19.82.0	Para cenários multi-tenant; não funciona em PPU

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:

Parametro	Tipo	Obrigatorio	Descricao
client_id	str	Sim	Application ID do SPN
client_secret	str	Sim	Client secret do SPN
tenant_id	str	Sim	Tenant ID do Azure
workspace_name	str	Sim	Nome do workspace Fabric
semantic_model_name	str	Sim	Nome do modelo semantico

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:

Parametro	Tipo	Obrigatorio	Descricao
user_email	str	Sim	Email do usuario AAD
password	str	Sim	Senha do usuario
workspace_name	str	Sim	Nome do workspace Fabric
semantic_model_name	str	Sim	Nome do modelo semantico

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="[e-mail]",
    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:

Parametro	Tipo	Obrigatorio	Descricao
conn_str	str	Sim	Connection string

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:

Parametro	Tipo	Obrigatorio	Descricao
conn_str	str	Sim	Connection string XMLA
query	str	Sim	Query DMV (DAX/MDX)

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:

Parametro	Tipo	Obrigatorio	Descricao
workspace	str	Sim	ID ou nome do workspace
semantic_model	str	Sim	ID ou nome do modelo
top	int	Nao	Max resultados (padrao: todos)

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:

Parametro	Tipo	Obrigatorio	Descricao
workspace	str	Sim	ID ou nome do workspace
semantic_model	str	Sim	ID ou nome do modelo
type	str	Nao	Full, DataOnly, Calculate, Automatic, etc
notify_option	str	Nao	MailOnCompletion, NoNotification
commit_mode	str	Nao	transactional ou partialBatch (enhanced)
max_parallelism	int	Nao	Grau de paralelismo (enhanced)
retry_count	int	Nao	Tentativas em caso de falha (enhanced)
objects	list	Nao	Tables/partitions selecionadas (enhanced)

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

Issue	Solution
Pyadomd nao importa	Instale: pip install pyadomd. Adicione o path do Microsoft.AnalysisServices.AdomdClient.dll ao sys.path antes do import. Pacote NuGet recomendado: Microsoft.AnalysisServices.AdomdClient ≥ 19.113.7.
Connection timeout (401)	Token expirado ou SPN sem permissao. Renew credenciais. TLS 1.2+ obrigatório — atualize o AdomdClient se necessário.
Query retorna vazio	Modelo pode ser Import vs DirectLake. Verifique estrutura com TMSCHEMA_TABLES.
Partition nao encontrada	Modelo pode estar em modo DirectLake (sem partitions). Verifique TMSCHEMA_PARTITIONS.
XMLA endpoint desabilitado	Desde junho 2025, XMLA read/write é padrão em todos os SKUs Fabric/Power BI. Se ainda estiver desabilitado, verifique configurações de capacidade no admin portal.
Refresh retorna 202	Refresh aceito; monitorar com get_semantic_model_refreshes() ate conclusao.
DMV query syntax error	Usar sintaxe DAX/DMV com $SYSTEM. prefix. DMV não suporta JOIN, GROUP BY, LIKE, CAST ou CONVERT.
DMV retorna 403 (DISCOVER_*)	$SYSTEM.DISCOVER_* DMVs não são suportados via XMLA Fabric (exigem server admin do AS). Use apenas TMSCHEMA_*, DMSCHEMA_* ou MDSCHEMA_*.
DISCOVER_M_EXPRESSIONS não suportado	Este DMV não é suportado via XMLA endpoint. Use Tabular Object Model (TOM) para obter expressões M.
User credentials prompt	Interactive login necessario. Configure SPN para automacao.
Refresh retorna "via API" em vez de "via enhanced API"	Inclua pelo menos um parametro enhanced no payload: commitMode, maxParallelism, retryCount ou objects. Workspace deve ser Premium/PPU/Fabric.
SPN retorna 403 no refresh	Refresh via SPN só funciona em workspaces Premium, PPU ou Fabric. Em workspaces Pro/Shared, use master user account como workaround.
Warnings de refresh ausentes na resposta da API	Esperado: os endpoints Get Refresh History e Get Refresh Execution Details não retornam warnings. Consulte o Fabric Monitoring Hub para inspeção detalhada.