Consumo de recursos de consulta

2025-05-26

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer

Este documento descreve as informações de consumo de recursos retornadas como parte de uma resposta de consulta Kusto.

Ao executar uma consulta, o serviço retorna não apenas os resultados da consulta, mas também informações detalhadas sobre os recursos consumidos durante a execução da consulta.

Compreender os dados de consumo de recursos de consulta ajuda a otimizar o desempenho da consulta, identificar gargalos e planejar a alocação apropriada de recursos. Ao monitorar essas métricas ao longo do tempo, você pode tomar decisões informadas sobre design de consulta, configuração de cluster e organização de dados para garantir o desempenho ideal e a eficiência de custos de suas consultas Kusto.

Os dados de consumo de recursos são retornados no QueryResourceConsumption objeto como parte da resposta da consulta, normalmente no formato JSON. Você pode encontrar o objeto em Ferramentas de monitoramento ou por acesso programático.

Estrutura do objeto QueryResourceConsumption

O QueryResourceConsumption objeto normalmente inclui as seguintes seções principais:

QueryHash: Um identificador exclusivo para a estrutura de consulta. Esse hash representa a consulta sem seus valores literais, permitindo a identificação de padrões de consulta semelhantes, mesmo quando os valores literais específicos diferem. Por exemplo, consultas como Events | where Timestamp > datetime(2023-01-01) e Events | where Timestamp > datetime(2023-02-01) teriam o mesmo QueryHash, pois compartilham a mesma estrutura, diferindo apenas nos valores literais datetime.
ExecutionTime: Tempo total de execução em segundos
resource_usage: Repartição pormenorizada dos recursos utilizados
input_dataset_statistics: Estatísticas sobre as entradas de dados processadas
dataset_statistics: Estatísticas sobre o conjunto de dados resultante
cross_cluster_resource_usage: Informações sobre recursos utilizados em agrupamentos, quando relevante

Detalhes de utilização de recursos

A seção de uso de recursos fornece informações detalhadas sobre os recursos consumidos durante a execução da consulta. Inclui as seguintes subsecções:

resource_usage.cache.shards: Informações sobre o uso do cache
resource_usage.cpu: Informações sobre o uso da CPU
resource_usage.memory: Informações sobre o uso da memória
resource_usage.network: Informações sobre o uso da rede
input_dataset_statistics: Informações sobre o conjunto de dados de entrada

Uso do cache

A resource_usage.cache.shards seção fornece informações sobre como a consulta utilizou o cache:

Objeto	Propriedade	Descrição
`hot`		Dados servidos a partir do hot cache
	`hitbytes`	Quantidade de dados recuperados com êxito do hot cache em bytes
	`missbytes`	Quantidade de dados não encontrados no hot cache em bytes
	`retrievebytes`	Quantidade de dados recuperados do armazenamento para satisfazer falhas em bytes
`cold`		Dados servidos a partir do cache frio
	`hitbytes`	Quantidade de dados recuperados com êxito do cache frio em bytes
	`missbytes`	Quantidade de dados em bytes não encontrada no cache frio em bytes
	`retrievebytes`	Quantidade de dados recuperados do armazenamento para satisfazer falhas em bytes
`bypassbytes`		Quantidade de dados que ignoraram o cache em bytes
`results_cache_origin`		Informações sobre a consulta original cujos resultados foram armazenados em cache e reutilizados
	`client_request_id`	Identificador exclusivo da solicitação original que preencheu o cache
	`started_on`	Carimbo de data/hora quando a consulta original que preencheu o cache foi executada
`partial_query_results`		Estatísticas de cache por estilhaço, se ativado
	`hits`	Número de resultados de consulta em nível de fragmento encontrados no cache
	`misses`	Número de resultados de consulta em nível de fragmento ausentes do cache

Utilização da CPU

A resource_usage.cpu seção fornece informações sobre o consumo de CPU:

Objeto	Propriedade	Descrição
`user`		Tempo de CPU no modo de usuário
	`kernel`	Tempo de CPU no modo kernel
	`total cpu`	Tempo total de CPU consumido
	`breakdown`	Maior detalhamento do uso da CPU
	`query execution`	Tempo de CPU para execução de consultas
	`query planning`	Tempo de CPU para planejamento de consultas

Utilização da memória

A resource_usage.memory seção fornece informações sobre o consumo de memória:

Objeto	Propriedade	Descrição
`peak_per_node`		Pico de uso de memória por nó em bytes

Utilização da rede

A resource_usage.network seção fornece informações sobre o uso da rede:

Objeto	Propriedade	Descrição
`inter_cluster_total_bytes`		Total de bytes transferidos dentro do cluster
`cross_cluster_total_bytes`		Total de bytes transferidos entre clusters

Estatísticas do conjunto de dados de entrada

A input_dataset_statistics seção fornece detalhes sobre os dados de origem processados:

Objeto	Propriedade	Descrição
`extents`		Informações sobre extensões de dados
	`total`	Número total de extensões em todas as tabelas referenciadas pela consulta
	`scanned`	Número de extensões digitalizadas (examinadas por nós de consulta)
	`scanned_min_datetime`	Data/hora mínima dos dados digitalizados
	`scanned_max_datetime`	Data/hora máxima dos dados digitalizados
`rows`		Informações sobre linhas de dados
	`total`	Número total de linhas em todas as tabelas referenciadas pela consulta
	`scanned`	Número de linhas digitalizadas (examinadas por nós de consulta)
`rowstores`		Informações sobre dados rowstore
	`scanned_rows`	Número de linhas digitalizadas a partir de repositórios de linhas
	`scanned_values_size`	Tamanho dos valores verificados a partir de repositórios de linhas
`shards`		Informações sobre consultas de estilhaços
	`total`	Número total de fragmentos em todas as tabelas referenciadas pela consulta
	`scanned`	Número de fragmentos digitalizados (examinados por nós de consulta)
`external_data`		Informações sobre dados externos (se aplicável)
	`downloaded_items`	Número de itens baixados de fontes de dados externas
	`downloaded_bytes`	Número de bytes baixados de fontes de dados externas
	`iterated_artifacts`	Número de artefatos iterados de fontes de dados externas

Integração com ferramentas de monitorização

Os dados QueryResourceConsumption podem ser coletados e analisados ao longo do tempo para identificar tendências e anomalias no desempenho da consulta. Estes dados estão disponíveis através de:

Resultados da execução da consulta
.show queries saída de comando
Logs de diagnóstico exportados para soluções de monitoramento

O monitoramento desses dados pode ajudar a identificar oportunidades de otimização de consultas e controlar o impacto das alterações em seus modelos de dados ou padrões de consulta.

Resultados da execução da consulta

Você pode acessar o arquivo JSON bruto dos dados QueryResourceConsumption diretamente dos resultados da execução da consulta. As informações são exibidas na grade de resultados localizada abaixo do editor de consultas.

Execute uma consulta no painel de consulta.
Navegue até a guia Estatísticas dos resultados da consulta.
Exiba a seção Visualização JSAN bruta e selecione a opção Exibir JSON completo para percorrer o JSON bruto.

Acesso programático

Em aplicativos cliente, você pode acessar as informações QueryResourceConsumption programaticamente:

// Example of accessing QueryResourceConsumption in C#
var dataSet = kustoClient.ExecuteQuery(query);
var resourceConsumption = GetQueryResourceConsumption(dataSet.Tables[2], false);
Console.WriteLine($"Execution time: {resourceConsumption.ExecutionTime}");
Console.WriteLine($"Memory peak: {resourceConsumption.ResourceUsage.Memory.PeakPerNode}");

Para obter mais informações, consulte Criar um aplicativo para executar comandos de gerenciamento.

Exemplos

Dados em Hot Cache: Este exemplo mostra uma consulta que foi servida inteiramente a partir do cache quente (hitbytes: 517324, missbytes: 0) e teve um tempo de execução mínimo (0,0045931 segundos). Todos os dados foram encontrados no hot cache, resultando em uma execução de consulta muito rápida.

{
  "QueryHash": "add172cd28dde0eb",
  "ExecutionTime": 0.0045931,
  "resource_usage": {
    "cache": {
      "shards": {
        "hot": {
          "hitbytes": 517324,
          "missbytes": 0,
          "retrievebytes": 0
        },
        "cold": {
          "hitbytes": 0,
          "missbytes": 0,
          "retrievebytes": 0
        },
        "bypassbytes": 0
      }
    },
    "cpu": {
      "user": "00:00:00",
      "kernel": "00:00:00",
      "total cpu": "00:00:00",
      "breakdown": {
        "query execution": "00:00:00",
        "query planning": "00:00:00"
      }
    },
    "memory": {
      "peak_per_node": 1580848
    },
    "network": {
      "inter_cluster_total_bytes": 27384,
      "cross_cluster_total_bytes": 0
    }
  },
  "input_dataset_statistics": {
    "extents": {
      "total": 1,
      "scanned": 1,
      "scanned_min_datetime": "2016-03-17T08:24:02.6259906Z",
      "scanned_max_datetime": "2016-03-17T08:24:02.6259906Z"
    },
    "rows": {
      "total": 59066,
      "scanned": 59066
    },
    "rowstores": {
      "scanned_rows": 0,
      "scanned_values_size": 0
    },
    "shards": {
      "queries_generic": 1,
      "queries_specialized": 0
    }
  },
  "dataset_statistics": [
    {
      "table_row_count": 10,
      "table_size": 11473
    }
  ],
  "cross_cluster_resource_usage": {}
}

Dados de tabelas externas: este exemplo mostra uma consulta que processou dados externos. Observe o alto tempo de execução (159,88 segundos) e a utilização significativa da CPU (mais de 1 hora de tempo total da CPU). A seção de dados externos mostra que 6.709 itens foram baixados, totalizando aproximadamente 87,7 GB. Isso é típico para consultas que precisam buscar grandes quantidades de dados de fontes externas, o que é significativamente mais lento do que consultar dados no armazenamento interno do Kusto.

{
  "QueryHash": "529656ef4099485b",
  "ExecutionTime": 159.8833962,
  "resource_usage": {
    "cache": {
      "shards": {
        "hot": {
          "hitbytes": 0,
          "missbytes": 0,
          "retrievebytes": 0
        },
        "cold": {
          "hitbytes": 0,
          "missbytes": 0,
          "retrievebytes": 0
        },
        "bypassbytes": 0
      }
    },
    "cpu": {
      "user": "01:01:13.5312500",
      "kernel": "00:00:44.9687500",
      "total cpu": "01:01:58.5000000",
      "breakdown": {
        "query execution": "01:01:58.5000000",
        "query planning": "00:00:00"
      }
    },
    "memory": {
      "peak_per_node": 26834528
    },
    "network": {
      "inter_cluster_total_bytes": 6745,
      "cross_cluster_total_bytes": 0
    }
  },
  "input_dataset_statistics": {
    "extents": {
      "total": 0,
      "scanned": 0,
      "scanned_min_datetime": "0001-01-01T00:00:00.0000000Z",
      "scanned_max_datetime": "0001-01-01T00:00:00.0000000Z"
    },
    "rows": {
      "total": 0,
      "scanned": 0
    },
    "rowstores": {
      "scanned_rows": 0,
      "scanned_values_size": 0
    },
    "shards": {
      "queries_generic": 0,
      "queries_specialized": 0
    },
    "external_data": {
      "downloaded_items": 6709,
      "downloaded_bytes": 87786879356,
      "iterated_artifacts": 6709
    }
  },
  "dataset_statistics": [
    {
      "table_row_count": 2,
      "table_size": 44
    }
  ],
  "cross_cluster_resource_usage": {}
}

Dados do cache frio: este exemplo mostra uma consulta que recuperou dados do cache frio (cold.hitbytes: 127209). Observe que de 1.250 extensões totais, apenas 1 foi digitalizada, e de 50.000 linhas totais, apenas 40 foram digitalizadas. Isso sugere uma consulta eficiente que usa filtragem apropriada. O acesso ao cache frio normalmente é mais lento do que o hot cache, mas mais rápido do que a recuperação de dados diretamente do armazenamento.

{
  "QueryHash": "480873c9b515cea8",
  "ExecutionTime": 1.4233768,
  "resource_usage": {
    "cache": {
      "shards": {
        "hot": {
          "hitbytes": 0,
          "missbytes": 0,
          "retrievebytes": 0
        },
        "cold": {
          "hitbytes": 127209,
          "missbytes": 0,
          "retrievebytes": 0
        },
        "bypassbytes": 0
      }
    },
    "cpu": {
      "user": "00:00:00",
      "kernel": "00:00:00",
      "total cpu": "00:00:00",
      "breakdown": {
        "query execution": "00:00:00",
        "query planning": "00:00:00"
      }
    },
    "memory": {
      "peak_per_node": 2098656
    },
    "network": {
      "inter_cluster_total_bytes": 250676,
      "cross_cluster_total_bytes": 0
    }
  },
  "input_dataset_statistics": {
    "extents": {
      "total": 1250,
      "scanned": 1,
      "scanned_min_datetime": "2024-01-08T07:13:13.6172552Z",
      "scanned_max_datetime": "2024-01-08T07:13:13.6172552Z"
    },
    "rows": {
      "total": 50000,
      "scanned": 40
    },
    "rowstores": {
      "scanned_rows": 0,
      "scanned_values_size": 0
    },
    "shards": {
      "queries_generic": 1,
      "queries_specialized": 0
    }
  },
  "dataset_statistics": [
    {
      "table_row_count": 10,
      "table_size": 123654
    }
  ],
  "cross_cluster_resource_usage": {}
}

Resultados do Cache de Consulta: Este exemplo demonstra uma consulta servida a partir do cache de resultados da consulta. Observe a presença da results_cache_origin seção , que indica que os resultados foram recuperados de um resultado de consulta previamente armazenado em cache. O tempo de execução extremamente rápido (0,0039999 segundos) mostra o benefício do cache de resultados de consulta, já que nenhum processamento de dados foi necessário. O cache contém informações sobre a solicitação original que preencheu o cache (client_request_id) e quando ele foi executado inicialmente (started_on). Observe que nenhum dado foi verificado a partir de extensões ou linhas, conforme indicado por zeros na input_dataset_statistics seção , confirmando que os resultados foram recuperados diretamente do cache de consulta.

{
  "ExecutionTime": 0.0039999,
  "resource_usage": {
    "cache": {
      "shards": {
        "hot": {
          "hitbytes": 0,
          "missbytes": 0,
          "retrievebytes": 0
        },
        "cold": {
          "hitbytes": 0,
          "missbytes": 0,
          "retrievebytes": 0
        },
        "bypassbytes": 0
      },
      "results_cache_origin": {
        "client_request_id": "KE.DF.RunQuery;95b6d241-e684-4a43-91c8-da0d6a854e3e",
        "started_on": "2025-04-22T08:22:24.4719143Z"
      }
    },
    "cpu": {
      "user": "00:00:00.0156250",
      "kernel": "00:00:00",
      "total cpu": "00:00:00.0156250",
      "breakdown": {
        "query execution": "00:00:00.0156250",
        "query planning": "00:00:00"
      }
    },
    "memory": {
      "peak_per_node": 53440160
    },
    "network": {
      "inter_cluster_total_bytes": 13233,
      "cross_cluster_total_bytes": 0
    }
  },
  "input_dataset_statistics": {
    "extents": {
      "total": 0,
      "scanned": 0,
      "scanned_min_datetime": "0001-01-01T00:00:00.0000000Z",
      "scanned_max_datetime": "0001-01-01T00:00:00.0000000Z"
    },
    "rows": {
      "total": 0,
      "scanned": 0
    },
    "rowstores": {
      "scanned_rows": 0,
      "scanned_values_size": 0
    },
    "shards": {
      "queries_generic": 0,
      "queries_specialized": 0
    }
  },
  "dataset_statistics": [
    {
      "table_row_count": 10,
      "table_size": 12121
    }
  ],
  "cross_cluster_resource_usage": {}
}

Resultados do Cache de Consulta Parcial (Per-Shard): Este exemplo ilustra uma consulta que se beneficiou do cache por nível de estilhaço, conforme indicado pela partial_query_results seção . O cache mostra 1 acerto e 0 erros, o que significa que a consulta foi capaz de recuperar resultados pré-computados para o fragmento sem ter que reprocessar os dados. Ao contrário do exemplo de cache de consulta completa, o mostra que os input_dataset_statistics dados foram tecnicamente "digitalizados" (59.066 linhas), mas isso provavelmente foi apenas uma operação de metadados, uma vez que o cálculo real foi recuperado do cache. Observe o tempo de execução muito rápido (0,0047499 segundos), demonstrando a vantagem de desempenho do cache de consulta parcial. O cache por estilhaço é particularmente útil para consultas que acessam repetidamente as mesmas partições de dados com as mesmas condições de filtragem.

{
  "QueryHash": "da3c6dc30e7b203d",
  "ExecutionTime": 0.0047499,
  "resource_usage": {
    "cache": {
      "shards": {
        "hot": {
          "hitbytes": 0,
          "missbytes": 0,
          "retrievebytes": 0
        },
        "cold": {
          "hitbytes": 0,
          "missbytes": 0,
          "retrievebytes": 0
        },
        "bypassbytes": 0
      },
      "partial_query_results": {
        "hits": 1,
        "misses": 0
      }
    },
    "cpu": {
      "user": "00:00:00.0156250",
      "kernel": "00:00:00",
      "total cpu": "00:00:00.0156250",
      "breakdown": {
        "query execution": "00:00:00.0156250",
        "query planning": "00:00:00"
      }
    },
    "memory": {
      "peak_per_node": 1580848
    },
    "network": {
      "inter_cluster_total_bytes": 27428,
      "cross_cluster_total_bytes": 0
    }
  },
  "input_dataset_statistics": {
    "extents": {
      "total": 1,
      "scanned": 1,
      "scanned_min_datetime": "2016-03-17T08:24:02.6259906Z",
      "scanned_max_datetime": "2016-03-17T08:24:02.6259906Z"
    },
    "rows": {
      "total": 59066,
      "scanned": 59066
    },
    "rowstores": {
      "scanned_rows": 0,
      "scanned_values_size": 0
    },
    "shards": {
      "queries_generic": 0,
      "queries_specialized": 0
    }
  },
  "dataset_statistics": [
    {
      "table_row_count": 10,
      "table_size": 11473
    }
  ],
  "cross_cluster_resource_usage": {}
}

Práticas recomendadas para consultas Kusto Query Language