$queryStats (aggregation)
Nesta página
- Definição
- Requisitos
- Sintaxe
- Campos de comando
- Controle de acesso
- Comportamento
- Como $queryStats rastreia estatísticas de query
- Como os Grupos $queryStats Retornaram documento
- Como $queryStats transforma dados usando transformIdentifiers
- $queryStats Log Entries
- Saída
- collectionType
- forma de query
- Exemplos
- Exemplo não transformado
- Exemplo transformado
- Collection de dados do MongoDB Atlas
Novidades na versão 7.0.12: (Também disponível a partir de 6.0.7)
Definição
Aviso
O estágio de agregação $queryStats
não é suportado e não é garantido que seja estável em uma versão futura. Não crie uma funcionalidade que dependa de um formato de saída específico desse estágio, pois a saída pode mudar em uma versão futura.
Retorna estatísticas de tempo de execução para query registradas.
$queryStats
coleta e reporta métricas para queries do aggregate()
, find()
e distinct()
. O $queryStats
não coleta informações para queries que usam Queryable Encryption.
Requisitos
O estágio $queryStats
é ativado em sistemas hospedados no MongoDB Atlas com uma camada do cluster de pelo menos M10.
Para executar o estágio $queryStats
, seu pipeline deve atender aos seguintes requisitos:
O pipeline deve ser executado no banco de dados
admin
.$queryStats
deve ser o primeiro estágio do pipeline.
Sintaxe
db.adminCommand( { aggregate: 1, pipeline: [ { $queryStats: { transformIdentifiers: { algorithm: <string>, hmacKey: <binData> /* subtype 8 - used for sensitive data */ } } } ], cursor: { } } )
Importante
Você não pode executar $queryStats
em uma collection específica. Para obter exemplos completos, consulte Exemplos.
Campos de comando
$queryStats
usa os seguintes campos:
Campo | necessidade | Tipo | Descrição |
---|---|---|---|
transformIdentifiers | Opcional | Documento | Especifica opções de transformação adicionais para a saída $queryStats . |
transformIdentifiers .algorithm | Obrigatório ao especificar o objeto transformIdentifiers | String | O tipo de transformação de hash aplicada às informações de namespace e nomes de campo na saída. O único valor algorithm suportado no momento é hmac-sha-256 . |
transformIdentifiers .hmacKey | Obrigatório ao especificar o objeto transformIdentifiers | BinData | A entrada de chave privada na transformação HMAC. |
Controle de acesso
Se a sua implementação impuser controle de acesso, o usuário executando o $queryStats
deverá ter as seguintes permissões:
Para executar o
$queryStats
sem a opçãotransformIdentifiers
, o usuário deve ter a ação de privilégioqueryStatsRead
.Para executar o
$queryStats
com a opçãotransformIdentifiers
, o usuário deve ter as ações de privilégio doqueryStatsRead
equeryStatsReadTransformed
.
O role clusterMonitor
integrado fornece os privilégios queryStatsRead
e queryStatsReadTransformed
. O exemplo a seguir concede a função clusterMonitor
no reconhecimento de data center admin
:
db.grantRolesToUser( "<user>", [ { role: "clusterMonitor", db: "admin" } ] )
Comportamento
As seções a seguir descrevem detalhes comportamentais do estágio $queryStats
.
Como $queryStats rastreia estatísticas de query
As estatísticas do estágio $queryStats
são rastreadas em uma collection virtual armazenada na memória. O limite de memória para a collection virtual é de 1% da memória total do sistema.
Como os Grupos $queryStats Retornaram documento
$queryStats
agrupa queries com propriedades comuns no mesmo documento de saída. O documento resultante é chamado de entrada de estatísticas de query.
$queryStats
agrupa query semelhantes normalizando valores de campo fornecidos pelo usuário para seus tipos de dados. Por exemplo, um filtro especificado como { item: 'card' }
é normalizado para { item :
'?string'}
. $queryStats
também normaliza os valores de algumas opções de query, como hint
e comment
.
$queryStats
preserva valores literais para opções como readConcern
e readPreference
.
Para obter a lista completa de opções incluídas em uma entrada de estatísticas de query, consulte localizar a forma de query do comando.
Como $queryStats transforma dados usando transformIdentifiers
Quando uma chave HMAC é especificada para a opção transformIdentifiers
, o $queryStats
utiliza a chave HMAC para aplicar uma função de hash HMAC-SHA-256 nos seguintes dados:
Nomes dos campos do documento
Nomes de coleção
nomes de banco de dados
$queryStats
não aplica a transformação HMAC aos seguintes dados:
Palavras-chave MQL, como nomes de operadores (por exemplo,
$gte
).Nomes de parâmetros como o parâmetro
partitionBy
em$setWindowFields
.Valores do campo.
$queryStats
normaliza os valores de campo em uma query para seus tipos de dados (como número ou string) quando a query é registrada.$queryStats
nunca armazena valores de campo que contêm dados do usuário.
Para obter um exemplo de saída transformada, consulte Exemplo transformado.
$queryStats Log Entries
O MongoDB registra $queryStats
operações nos registros de sistema. Por padrão, o MongoDB registra apenas a invocação de operações $queryStats
, não a saída da operação. Para operações do $queryStats
que incluem a opção transformIdentifiers
, você pode especificar se a saída transformada está incluída na entrada de registro.
Para saber como controlar o comportamento de registro do $queryStats
, consulte Alternar saída de registro do $queryStats.
Saída
$queryStats
retorna uma matriz de entradas de estatísticas de consulta. Algumas propriedades de entrada de estatísticas de query contêm valores literais e algumas propriedades são normalizadas para agrupar queries comuns.
As entradas de estatísticas de query contêm os seguintes documentos de nível superior:
Documento | Descrição |
---|---|
key | A combinação exclusiva de atributos que definem uma entrada na saída de estatísticas de query. O
Cada combinação única de atributos cria uma entrada separada na collection virtual do |
asOf | A hora UTC em que $queryStats leu esta entrada da collection virtual $queryStats . asOf não retorna necessariamente o mesmo horário UTC para cada resultado. Internamente, a estrutura de dados é particionada e cada partição será lida em um ponto individual no tempo. |
metrics | Contém métricas agregadas de tempo de execução associadas a cada entrada de estatísticas de query. Cada entrada de estatísticas de query registra estatísticas para cada query que compartilha a mesma chave. |
Cada documento na array de saída contém os seguintes campos:
Campo | Tipo | Literal ou Normalizado | Descrição |
---|---|---|---|
key | Documento | literal | Contém a forma de query e atributos de query adicionais que agrupam um conjunto de queries |
key.queryShape | Documento | literal | Contém atributos usados para agrupar queries semelhantes. Para obter mais informações, consulte Forma de query. |
key.client | Documento | literal | Descreve as informações do cliente associadas à chave |
key.client.application | Documento | literal | O nome do aplicativo cliente |
key.client.driver | Documento | literal | Descreve o driver usado para emitir a query |
key.client.driver.name | String | literal | Nome do driver usado para emitir a query. Os valores possíveis incluem mongosh e nodejs . |
key.client.driver.version | String | literal | Número da versão do driver usado para emitir a query |
key.client.os | Documento | literal | Descreve o sistema operacional usado pelo cliente que emitiu a query |
key.client.os.type | String | literal | Tipo do sistema operacional |
key.client.os.name | String | literal | Nome do sistema operacional |
key.client.os.architecture | String | literal | Arquitetura do sistema operacional. Os valores possíveis incluem arm64 e x86_64 . |
key.client.os.version | String | literal | Número da versão do sistema operacional |
key.readConcern | Documento | literal | A referência de leitura para a chave |
key.collectionType | String | literal | O tipo de coleção para o qual a query foi emitida. Para obter mais informações, consulte Tipo de coleção. |
key.hint | Documento ou string | Normalizado | O índice que foi usado como dica para a query |
key.batchSize | String | Normalizado | O tamanho do lote da chave. O tamanho do lote especifica o número de documentos a serem devolvidos em cada lote da resposta da instância MongoDB. |
key.comment | String | Normalizado | Comentário associado à chave |
key.maxTimeMS | String | Normalizado | valor maxTimeMS associado à chave |
key.noCursorTimeout | Boolean | Normalizado | Opção noCursorTimeout associada à chave |
key.allowPartialResults | String | literal | Opção allowPartialResults associada à chave |
key.readPreference | String | literal | preferência de leitura associada à chave |
key.apiVersion | String | literal | A versão da API estável associada à chave. Consulte API estável. |
key.apiStrict | Boolean | literal | O valor do parâmetro apiStrict associado à chave. Consulte stable API. |
key.apiDeprecationErrors | Boolean | literal | O valor do parâmetro apiDeprecationErrors associado à chave. Consulte stable API. |
keyHash | String | literal | Uma representação em hash dos valores no key . Cada valor keyHash único corresponde a uma entrada única no armazenamento de memória $queryStats . |
metrics | Documento | literal | Descreve estatísticas de tempo de execução para a chave |
metrics.lastExecutionMicros | Número longo | literal | Tempo de execução de execução para a query mais recente para todas as queries com a chave fornecida |
metrics.execCount | Número longo | literal | Número de vezes que a query com a chave fornecida foi executada |
metrics.keysExamined | Documento | literal | Descreve o número de chaves examinadas por queries |
metrics .keysExamined .sum | Inteiro | literal | Número total de chaves examinadas |
metrics .keysExamined .max | Número longo | literal | Número máximo de chaves examinadas |
metrics .keysExamined .min | Número longo | literal | Menor número de chaves examinadas |
metrics .keysExamined .sumOfSquares | NumberDecimal | literal | Soma dos quadrados do número de chaves examinadas. Um valor |
metrics.docsExamined | Documento | literal | Descreve o número de documentos examinados por queries |
metrics .docsExamined .sum | Inteiro | literal | Número total de documentos examinados na query |
metrics .docsExamined .max | Número longo | literal | Número máximo de documentos examinados |
metrics .docsExamined .min | Número longo | literal | Número mínimo de documentos examinados |
metrics .docsExamined .sumOfSquares | NumberDecimal | literal | Soma de quadrados do número de documentos examinados. Um valor |
metrics.hasSortStage | Boolean | literal | true quando o MongoDB deve classificar os documentos depois de recebê-los de um cursor. |
metrics.usedDisk | Boolean | literal | true quando a query grava dados em arquivos temporários devido a restrições de memória. |
metrics.fromMultiPlanner | Boolean | literal | true quando o planejador de query avalia vários planos antes de escolher o plano de execução vencedor para a query. |
metrics.fromPlanCache | Boolean | literal | true quando o planejador de query é capaz de usar um plano a partir do cache do plano. |
metrics.totalExecMicros | Documento | literal | Descreve o tempo total gasto executando query com a chave fornecida. Se a query resultou em Todos os subcampos de |
metrics .totalExecMicros .sum | Número longo | literal | Tempo total gasto executando query com a chave fornecida |
metrics .totalExecMicros .max | Número longo | literal | Maior tempo gasto executando uma query com a chave fornecida |
metrics .totalExecMicros .min | Número longo | literal | Menor tempo gasto executando uma query com a chave fornecida |
metrics .totalExecMicros .sumOfSquares | NumberDecimal | literal | Soma dos quadrados do tempo total de execução de todas as query com a chave fornecida. Um valor alto de sumOfSquares indica alta variação nos tempos de execução da query. |
metrics .firstResponseExecMicros | Documento | literal | Descreve o tempo gasto desde quando uma query dentro da chave começou a ser processada até quando o servidor retorna o primeiro lote de resultados Todos os subcampos de |
metrics .firstResponseExecMicros .sum | Número longo | literal | Quantidade combinada de tempo gasto desde o início do processamento da query até quando o servidor retorna o primeiro lote de resultados |
metrics .firstResponseExecMicros .max | Número longo | literal | Maior tempo gasto desde o início do processamento de query até quando o servidor retorna o primeiro batch de resultados |
metrics .firstResponseExecMicros .min | Número longo | literal | O menor tempo gasto desde o início do processamento da query até quando o servidor retorna o primeiro lote de resultados |
metrics .firstResponseExecMicros .sumOfSquares | NumberDecimal | literal | Soma dos quadrados do tempo gasto desde o início do processamento da query até quando o servidor retorna o primeiro lote de resultados. Um valor alto de |
metrics.docsReturned | Documento | literal | Descreve o número de documento retornados por query dentro da chave |
metrics .docsReturned .sum | Número longo | literal | Número total de documento retornados por query com a chave fornecida |
metrics .docsReturned .max | Número longo | literal | Número máximo de documentos retornados por uma query com a chave fornecida |
metrics .docsReturned .min | Número longo | literal | Menor número de documentos retornados por uma query com a chave fornecida |
metrics .docsReturned .sumOfSquares | NumberDecimal | literal | Soma dos quadrados do número de documentos retornados por uma query dentro da chave. Um valor alto de |
metrics.firstSeenTimestamp | Data | literal | Tempo em que uma query com a chave fornecida foi usada pela primeira vez desde a última reinicialização |
metrics.lastSeenTimestamp | Data | literal | Hora em que uma query com a chave fornecida foi usada mais recentemente |
collectionType
O campo key.collectionType
indica o tipo de collection em que a query registrada foi emitida. O collectionType
pode ser um dos seguintes valores:
Campo | Descrição |
---|---|
changeStream | A query era uma operação de change stream. |
collection | A query foi emitida em uma collection padrão. |
nonExistent | A query foi emitida em uma collection que não existe. |
timeseries | A query foi emitida em uma coleção de séries temporais. |
view | A query foi emitida em uma visualização. |
virtual | A query foi emitida em uma collection virtual. As seguintes operações ocorrem em collections virtuais: |
forma de query
O key.queryShape
contém atributos de query utilizados para agrupar queries semelhantes. Os campos em key.queryShape
variam de acordo com o comando que resultou na entrada das estatísticas da consulta. $queryStats
cria entradas de estatísticas de query para comandos aggregate
, find
e distinct
.
Cada propriedade de forma de query corresponde a uma opção de query. Por exemplo, key.queryShape.sort
corresponde à especificação sort()
para a forma de query.
encontre a forma de query de comando
A tabela a seguir descreve as propriedades da forma de query para comandos find
.
Campo | Tipo | Literal ou Normalizado |
---|---|---|
key.queryShape.filter | Documento | Normalizado |
key.queryShape.sort | Documento | literal |
key.queryShape.projection | Documento | Normalizado |
key.queryShape.skip | Inteiro | Normalizado |
key.queryShape.limit | Inteiro | Normalizado |
key.queryShape.singleBatch | Boolean | literal |
key.queryShape.max | Documento | Normalizado |
key.queryShape.min | Documento | Normalizado |
key.queryShape.returnKey | Boolean | literal |
key.queryShape.showRecordId | Boolean | literal |
key.queryShape.tailable | Boolean | literal |
key.queryShape.oplogReplay | Boolean | literal |
key.queryShape.awaitData | Boolean | literal |
key.queryShape.collation | Documento | literal |
key.queryShape.allowDiskUse | Boolean | literal |
key.queryShape.let | Documento | Normalizado |
forma de query de comando agregada
A tabela a seguir descreve as propriedades da forma de query para comandos aggregate
.
Campo | Tipo | Literal ou Normalizado |
---|---|---|
key.queryShape.pipeline | Array | Normalizado |
key.queryShape.explain | Boolean | literal |
key.queryShape.allowDiskUse | Boolean | literal |
key.queryShape.collation | Documento | literal |
key.queryShape.hint | string ou documento | Normalizado |
key.queryShape.let | Documento | Normalizado |
forma de query de comando distinta
A tabela a seguir descreve as propriedades da forma de query para comandos distinct
.
Campo | Tipo | Literal ou Normalizado |
---|---|---|
key.queryShape.key | String | literal |
key.queryShape.collation | Documento | Normalizado |
key.queryShape.query | Documento | Normalizado |
Exemplos
Para executar os exemplos nesta seção, comece com os seguintes dados:
db.products.insertMany( [ { item: "card", qty: 15 }, { item: "envelope", qty: 20 }, { item: "stamps" , qty: 30 } ] )
Em seguida, execute estes comandos:
db.products.find( { item: "card" } ) db.products.aggregate( [ { $match: { qty: { $gt: 20 } } } ] )
Os seguintes exemplos mostram a saída do $queryStats
utilizando diferentes tipos de transformação de dados:
Exemplo não transformado
Entrada:
db.getSiblingDB("admin").aggregate( [ { $queryStats: { } } ] )
Saída:
[ { key: { queryShape: { cmdNs: { db: 'test', coll: 'products' }, command: 'find', filter: { item: { '$eq': '?string' } } }, client: { driver: { name: 'nodejs|mongosh', version: '5.1.0' }, os: { type: 'Darwin', name: 'darwin', architecture: 'arm64', version: '22.6.0' }, platform: 'Node.js v16.19.1, LE (unified)', version: '5.1.0|1.8.0', application: { name: 'mongosh 1.8.0' } }, collectionType: 'collection' }, keyHash: 'dsoJ+LHAru0z6MJ1/IygJnnLTrlpVYYmPnlmNZbZrLI=', metrics: { lastExecutionMicros: Long("4254"), execCount: Long("1"), totalExecMicros: { sum: Long("4254"), max: Long("4254"), min: Long("4254"), sumOfSquares: Decimal128("18096516") }, firstResponseExecMicros: { sum: Long("4254"), max: Long("4254"), min: Long("4254"), sumOfSquares: Decimal128("18096516") }, docsReturned: { sum: Long("1"), max: Long("1"), min: Long("1"), sumOfSquares: Decimal128("1") }, firstSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z"), latestSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z") }, asOf: Timestamp({ t: 1694695007, i: 0 }) }, { key: { queryShape: { cmdNs: { db: 'test', coll: 'products' }, command: 'aggregate', pipeline: [ { '$match': { qty: { '$gt': '?number' } } } ] }, apiVersion: '1', client: { driver: { name: 'nodejs|mongosh', version: '5.1.0' }, os: { type: 'Darwin', name: 'darwin', architecture: 'arm64', version: '22.6.0' }, platform: 'Node.js v16.19.1, LE (unified)', version: '5.1.0|1.8.0', application: { name: 'mongosh 1.8.0' } }, collectionType: 'collection', cursor: { batchSize: '?number' } }, keyHash: '2QLBfL0m1lliStdN4XvBjqVBtZQ6ffaB2L1pJ99twT8=', metrics: { lastExecutionMicros: Long("350"), execCount: Long("3"), totalExecMicros: { sum: Long("3084"), max: Long("2499"), min: Long("235"), sumOfSquares: Decimal128("6422726") }, firstResponseExecMicros: { sum: Long("3084"), max: Long("2499"), min: Long("235"), sumOfSquares: Decimal128("6422726") }, docsReturned: { sum: Long("3"), max: Long("1"), min: Long("1"), sumOfSquares: Decimal128("3") }, firstSeenTimestamp: ISODate("2023-11-29T21:16:17.796Z"), latestSeenTimestamp: ISODate("2023-11-29T21:17:12.385Z") }, asOf: Timestamp({ t: 1701292827, i: 0 }) } ]
Exemplo transformado
Entrada:
db.getSiblingDB("admin").aggregate( [ { $queryStats: { transformIdentifiers: { algorithm: "hmac-sha-256" , hmacKey: BinData(8, "87c4082f169d3fef0eef34dc8e23458cbb457c3sf3n2") } } } ] )
Saída:
[ { key: { queryShape: { cmdNs: { db: 'Mtrt3iG7dsX5c5uCSIhSVlcu5qD3u3xx2EQnS1dJLxM=', coll: '3oJE6AyOuf8h5NqWiXETxulFlPm3QUXbMnMjL2EqAU4=' }, command: 'find', filter: { 'VWVRow7Ure92ajRPfrpWiU8OtDeWcLePFIq0+tooBng=': { '$eq': '?string' } } }, client: { driver: { name: 'nodejs|mongosh', version: '5.1.0' }, os: { type: 'Darwin', name: 'darwin', architecture: 'arm64', version: '22.6.0' }, platform: 'Node.js v16.19.1, LE (unified)', version: '5.1.0|1.8.0', application: { name: 'mongosh 1.8.0' } }, collectionType: 'collection' }, keyHash: 'q4vxam+wbk8tTrl8D0MDFH1LQAbI8fWspfkGKhEUROk=', metrics: { lastExecutionMicros: Long("4254"), execCount: Long("1"), keysExamined: { sum: Int("5"), max: Long("5"), min: Long("5"), sumOfSquares: Decimal128("25") }, docsExamined: { sum: Long("1"), max: Long("1"), min: Long("1"), sumOfSquares: Decimal128("1") }, hasSortStage: false, usedDisk: false, fromMultiPlanner: false, fromPlanCache: true, totalExecMicros: { sum: Long("4254"), max: Long("4254"), min: Long("4254"), sumOfSquares: Decimal128("18096516") }, firstResponseExecMicros: { sum: Long("4254"), max: Long("4254"), min: Long("4254"), sumOfSquares: Decimal128("18096516") }, docsReturned: { sum: Long("1"), max: Long("1"), min: Long("1"), sumOfSquares: Decimal128("1") }, firstSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z"), latestSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z") }, asOf: Timestamp({ t: 1694695712, i: 0 }) }, { key: { queryShape: { cmdNs: { db: 'Mtrt3iG7dsX5c5uCSIhSVlcu5qD3u3xx2EQnS1dJLxM=', coll: '3oJE6AyOuf8h5NqWiXETxulFlPm3QUXbMnMjL2EqAU4=' }, command: 'aggregate', pipeline: [ { '$match': { 'RVqrwNEPotzdKnma/T7s4YcgNvpqO29BMDoni2N4IMI=': { '$gt': '?number' } } } ] }, apiVersion: '1', client: { driver: { name: 'nodejs|mongosh', version: '5.1.0' }, os: { type: 'Darwin', name: 'darwin', architecture: 'arm64', version: '22.6.0' }, platform: 'Node.js v16.19.1, LE (unified)', version: '5.1.0|1.8.0', application: { name: 'mongosh 1.8.0' } }, collectionType: 'collection', cursor: { batchSize: '?number' } }, keyHash: 'HEhpQTYB+/wVoHLkOkMd+EC2jguQlMJ1N/vTE7+b8Js=', metrics: { lastExecutionMicros: Long("350"), execCount: Long("3"), keysExamined: { sum: Int("5"), max: Long("5"), min: Long("5"), sumOfSquares: Decimal128("25") }, docsExamined: { sum: Long("1"), max: Long("1"), min: Long("1"), sumOfSquares: Decimal128("1") }, hasSortStage: false, usedDisk: false, fromMultiPlanner: false, fromPlanCache: true, totalExecMicros: { sum: Long("3084"), max: Long("2499"), min: Long("235"), sumOfSquares: Decimal128("6422726") }, firstResponseExecMicros: { sum: Long("3084"), max: Long("2499"), min: Long("235"), sumOfSquares: Decimal128("6422726") }, docsReturned: { sum: Long("3"), max: Long("1"), min: Long("1"), sumOfSquares: Decimal128("3") }, firstSeenTimestamp: ISODate("2023-11-29T21:16:17.796Z"), latestSeenTimestamp: ISODate("2023-11-29T21:17:12.385Z") }, asOf: Timestamp({ t: 1701293302, i: 0 }) }, ]
Collection de dados do MongoDB Atlas
O MongoDB Atlas usa periodicamente $queryStats
para coletar dados anônimos sobre suas query, o que ajuda a melhorar os produtos MongoDB. Seus dados também podem ser usados para fazer sugestões de funcionalidades com base no uso. O MongoDB mantém os dados coletados com $queryStats
por quatro anos.
Quando o Atlas executa o $queryStats
em seu sistema, ele usa uma chave HMAC exclusiva por organização do Atlas para transformar seus dados e evitar a coleta de informações confidenciais.