Monitorar eventos de aplicativos

Visão geral

Neste guia, você pode aprender como configurar e configurar o monitoramento no driver MongoDB Node.js.

O monitoramento envolve a coleta de informações sobre as atividades de um programa em execução, que você pode usar com uma biblioteca de gerenciamento de desempenho de aplicação .

Monitorar o driver Node.js permite que você entenda o uso e o desempenho dos recursos do driver, e pode ajudá-lo a tomar decisões informadas ao projetar e depurar seu aplicação.

Neste guia você aprenderá como executar estas tarefas:

Monitorar eventos de comando
Monitorar eventos de descoberta e monitoramento do servidor (SDAM)
Monitorar eventos do pool de conexões

Este guia mostra como usar informações sobre a atividade do driver no código. Para saber como registrar eventos no driver, consulte o guia de registro do driver do Node.js.

Monitorar eventos

Você pode monitorar eventos usando o driver Node.js assinando-os em seu aplicação.

Um evento é qualquer ação que ocorra dentro do driver durante sua operação. O driver Node.js inclui funcionalidade para ouvir um subconjunto desses eventos.

O driver Node.js organiza os eventos que ele define nas seguintes categorias:

Eventos de comando
Eventos de descoberta e monitoramento de servidores (SDAM)
Eventos do pool de conexões

As seções a seguir mostram como monitorar cada categoria de evento.

Eventos de comando

Um evento de comando é um evento relacionado a um comando do banco de dados MongoDB. Você pode acessar um ou mais eventos de monitoramento de comando usando o driver e inscrevendo-os em seu aplicativo.

Para saber mais sobre os comandos do banco de dados MongoDB, consulte o guia Comandos do banco de dados no Manual do servidor.

Observação

O monitoramento de comandos está desabilitado por padrão. Para habilitar o monitoramento de comandos, passe a opção monitorCommands como true para o construtor MongoClient .

Exemplo

O exemplo a seguir demonstra a conexão com um conjunto de réplicas e a assinatura de um dos eventos de monitoramento de comandos criados pela implantação do MongoDB:

/* Subscribe to an event */
const { MongoClient } = require("mongodb");
// Replace the following with your MongoDB deployment's connection string
const uri = "mongodb+srv://<clusterUrl>/?replicaSet=rs&writeConcern=majority";
const client = new MongoClient(uri, { monitorCommands:true });
// Replace <event name> with the name of the event you are subscribing to
const eventName = "<event name>";
// Subscribes to a specified event and print a message when the event is received
client.on(eventName, event => console.log(event));
async function run() {
  try {
    // Establishes and verifies connection to the "admin" database
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully");
  } finally {
    // Closes the database connection on completion or error
    await client.close();
  }
}
run().catch(console.dir);

Descrições de evento

Você pode se inscrever em qualquer um dos seguintes eventos de monitoramento de comandos:

Nome do evento	Descrição
`commandStarted`	Criado quando um comando é iniciado.
`commandSucceeded`	Criado quando um comando é bem-sucedido.
`commandFailed`	Criado quando um comando falhou.

As seções a seguir mostram amostras de saída para cada um dos comandos anteriores. Seu resultado pode ser diferente dependendo do comando que você executa e das opções que você define.

commandStarted

CommandStartedEvent {
  name: 'commandStarted',
  address: 'localhost:27017',
  connectionId: 812613,
  serviceId: undefined,
  requestId: 1534,
  databaseName: 'app',
  commandName: 'find',
  command: {
    find: { firstName: "Jane", lastName: "Doe" }
  },
  serverConnectionId: 27177n
}

commandSucceeded

CommandSucceededEvent {
  name: 'commandSucceeded',
  address: 'localhost:27017',
  connectionId: 812613,
  serviceId: undefined,
  requestId: 1534,
  commandName: 'find',
  duration: 15,
  reply: {
    cursor: {
      firstBatch: [
        {
          _id: ObjectId("5e8e2ca217b5324fa9847435"),
          firstName: "Jane",
          lastName: "Doe"
        }
      ],
      _id: 0,
      ns: "app.users"
    },
    ok: 1,
    operationTime: 1586380205
  },
  serverConnectionId: 27096n,
  databaseName: 'app'
}

commandFailed

CommandFailedEvent {
  name: 'commandFailed',
  address: 'localhost:27017',
  connectionId: 812613,
  serviceId: undefined,
  requestId: 1534,
  commandName: 'find',
  duration: 11,
  failure: Error("something failed"),
  serverConnectionId: 27208n,
  databaseName: 'app'
}

Eventos de descoberta e monitoramento de servidores

O driver Node.js cria eventos de topologia , também conhecidos como eventos SDAM, quando há uma alteração no estado da instância ou cluster ao qual você se conectou. Por exemplo, o driver cria um evento quando você estabelece uma nova conexão ou se o cluster optar por um novo nó primary.

Para saber mais sobre eventos de topologia, consulte o guia de replicação no manual do servidor.

As seções a seguir demonstram como registrar as alterações de topologia em seu aplicativo e explorar as informações fornecidas nesses eventos.

Exemplo de inscrição de eventos

Você pode acessar um ou mais eventos SDAM assinando-os em seu aplicação. O exemplo a seguir demonstra a conexão a um conjunto de réplicas e a assinatura de um dos eventos SDAM criados pela implantação do MongoDB :

/* Subscribe to SDAM event */
const { MongoClient } = require("mongodb");
// Replace the following with your MongoDB deployment's connection string
const uri = "mongodb+srv://<clusterUrl>/?replicaSet=rs&writeConcern=majority";
const client = new MongoClient(uri);
// Replace <event name> with the name of the event you are subscribing to
const eventName = "<event name>";
// Subscribes to a specified event and prints a message when the event is received
client.on(eventName, event => {
  console.log(`received ${eventName}: ${JSON.stringify(event, null, 2)}`);
});
async function run() {
  try {
    // Establishes and verifies connection to the database
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully");
  } finally {
    // Closes the database connection on completion or error
    await client.close();
  }
}
run().catch(console.dir);

Descrições de evento

Você pode assinar qualquer um dos seguintes eventos do SDAM:

Nome do evento	Descrição
`serverOpening`	Criado quando uma conexão com uma instância é aberta.
`serverClosed`	Criado quando uma conexão com uma instância é fechada.
`serverDescriptionChanged`	Criado quando um estado de instância muda (como de secundário para primário).
`topologyOpening`	Criado antes de tentar uma conexão com uma instância.
`topologyClosed`	Criado após o fechamento de todas as conexões de instância na topologia.
`topologyDescriptionChanged`	Criado quando a topologia muda, como a eleição de um novo primary ou a desconexão de um proxy mongos .
`serverHeartbeatStarted`	Criado antes de emitir um comando `hello` para uma instância MongoDB.
`serverHeartbeatSucceeded`	Criado quando o comando `hello` retorna com sucesso de uma instância do MongoDB.
`serverHeartbeatFailed`	Criado quando um comando `hello` emitido para uma instância específica do MongoDB não retorna uma resposta bem-sucedida.

Documentos de exemplos de eventos

As seções a seguir mostram amostras de saída para cada tipo de evento SDAM.

serverDescriptionChanged

ServerDescriptionChangedEvent {
  topologyId: 0,
  address: 'localhost:27017',
  previousDescription: ServerDescription {
    address: 'localhost:27017',
    error: null,
    roundTripTime: 0,
    lastUpdateTime: 1571251089030,
    lastWriteDate: null,
    opTime: null,
    type: 'Unknown',
    minWireVersion: 0,
    maxWireVersion: 0,
    hosts: [],
    passives: [],
    arbiters: [],
    tags: []
  },
  newDescription: ServerDescription {
    address: 'localhost:27017',
    error: null,
    roundTripTime: 0,
    lastUpdateTime: 1571251089051,
    lastWriteDate: 2019-10-16T18:38:07.000Z,
    opTime: { ts: Timestamp, t: 18 },
    type: 'RSPrimary',
    minWireVersion: 0,
    maxWireVersion: 7,
    maxBsonObjectSize: 16777216,
    maxMessageSizeBytes: 48000000,
    maxWriteBatchSize: 100000,
    me: 'localhost:27017',
    hosts: [ 'localhost:27017' ],
    passives: [],
    arbiters: [],
    tags: [],
    setName: 'rs',
    setVersion: 1,
    electionId: ObjectID,
    primary: 'localhost:27017',
    logicalSessionTimeoutMinutes: 30,
    '$clusterTime': ClusterTime
  }
}

O campo type do objeto ServerDescription neste evento contém um dos seguintes valores possíveis:

Tipo	Descrição
`Unknown`	Instância desconhecida
`Standalone`	Instância autônomo
`Mongos`	Instância de proxy do Mongos
`PossiblePrimary`	Pelo menos um servidor reconhece isso como o principal, mas ainda não foi verificado por todas as instâncias.
`RSPrimary`	Instância primária
`RSSecondary`	Instância secundária
`RSArbiter`	Instância de árbitro
`RSOther`	Consulte a especificação do RSGhost e do RSOther para mais detalhes
`RSGhost`	Consulte a especificação do RSGhost e do RSOther para mais detalhes

serverHeatbeatStarted

ServerHeartbeatStartedEvent {
  connectionId: 'localhost:27017'
}

serverHeatbeatSucceeded

ServerHeartbeatSucceededEvent {
  duration: 1.939997,
  reply:{
    hosts: [ 'localhost:27017' ],
    setName: 'rs',
    setVersion: 1,
    isWritablePrimary: true,
    secondary: false,
    primary: 'localhost:27017',
    me: 'localhost:27017',
    electionId: ObjectID,
    lastWrite: {
      opTime: { ts: [Timestamp], t: 18 },
      lastWriteDate: 2019-10-16T18:38:17.000Z,
      majorityOpTime: { ts: [Timestamp], t: 18 },
      majorityWriteDate: 2019-10-16T18:38:17.000Z
    },
    maxBsonObjectSize: 16777216,
    maxMessageSizeBytes: 48000000,
    maxWriteBatchSize: 100000,
    localTime: 2019-10-16T18:38:19.589Z,
    logicalSessionTimeoutMinutes: 30,
    minWireVersion: 0,
    maxWireVersion: 7,
    readOnly: false,
    ok: 1,
    operationTime: Timestamp,
    '$clusterTime': ClusterTime
  },
  connectionId: 'localhost:27017'
}

serverHeatbeatFailed

ServerHeartbeatFailed {
  duration: 20,
  failure: MongoError('some error'),
  connectionId: 'localhost:27017'
}

serverOpening

ServerOpeningEvent {
  topologyId: 0,
  address: 'localhost:27017'
}

servidor fechado

ServerClosedEvent {
  topologyId: 0,
  address: 'localhost:27017'
}

topologiaOpening

TopologyOpeningEvent {
  topologyId: 0
}

topologiaFechada

TopologyClosedEvent {
  topologyId: 0
}

topologiaDescriptionChanged

TopologyDescriptionChangedEvent {
  topologyId: 0,
  previousDescription: TopologyDescription {
    type: 'ReplicaSetNoPrimary',
    setName: null,
    maxSetVersion: null,
    maxElectionId: null,
    servers: Map {
      'localhost:27017' => ServerDescription
    },
    stale: false,
    compatible: true,
    compatibilityError: null,
    logicalSessionTimeoutMinutes: null,
    heartbeatFrequencyMS: 10000,
    localThresholdMS: 15,
    options: Object,
    error: undefined,
    commonWireVersion: null
  },
  newDescription: TopologyDescription {
    type: 'ReplicaSetWithPrimary',
    setName: 'rs',
    maxSetVersion: 1,
    maxElectionId: null,
    servers: Map {
      'localhost:27017' => ServerDescription
    },
    stale: false,
    compatible: true,
    compatibilityError: null,
    logicalSessionTimeoutMinutes: 30,
    heartbeatFrequencyMS: 10000,
    localThresholdMS: 15,
    options: Object,
    error: undefined,
    commonWireVersion: 7
  }
}

O campo type do objeto TopologyDescription neste evento contém um dos seguintes valores possíveis:

Tipo	Descrição
`Single`	Instância autônomo
`ReplicaSetWithPrimary`	Conjunto de réplicas com um primary
`ReplicaSetNoPrimary`	Conjunto de réplicas sem primário
`Sharded`	cluster fragmentado
`Unknown`	topologia desconhecida

Eventos do pool de conexões

Um pool de conexões é um conjunto de conexões TCP abertas que seu driver mantém com uma instância MongoDB. Os pools de conexões ajudam a reduzir o número de negociações de rede que seu aplicativo precisa executar e podem ajudá-lo a ser executado mais rapidamente.

As seções a seguir demonstram como registrar eventos de pool de conexões em seu aplicativo e explorar as informações fornecidas nesses eventos.

Exemplos de inscrições de eventos

Você pode acessar um ou mais eventos do pool de conexões usando o driver assinando-os no seu aplicativo. O exemplo a seguir demonstra a conexão com um conjunto de réplicas e a assinatura de um dos eventos de monitoramento do pool de conexões criados pelo MongoDB deployment:

const { MongoClient } = require("mongodb");
// Replace the following with your MongoDB deployment's connection string
const uri =
  "mongodb+srv://<clusterUrl>/?replicaSet=rs&writeConcern=majority";
const client = new MongoClient(uri);
// Replace <event name> with the name of the event you are subscribing to
const eventName = "<event name>";
// Subscribes to the event
client.on(eventName, (event) =>
  console.log("\nreceived event:\n", event)
);
async function run() {
  try {
    // Establishes and verifies connection
    await client.db("admin").command({ ping: 1 });
    console.log("\nConnected successfully!\n");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

Os eventos de monitoramento do pool de conexões podem ajudá-lo a depurar e compreender o comportamento do pool de conexões do seu aplicativo. O exemplo a seguir usa eventos de monitoramento do pool de conexões para retornar uma contagem de conexões com check-out no pool:

function connectionPoolStatus(client) {
  let checkedOut = 0;
  function onCheckout() {
    checkedOut++;
  }
  function onCheckin() {
    checkedOut--;
  }
  function onClose() {
    client.removeListener('connectionCheckedOut', onCheckout);
    client.removeListener('connectionCheckedIn', onCheckin);
    checkedOut = NaN;
  }
  // Decreases count of connections checked out of the pool when connectionCheckedIn event is triggered
  client.on('connectionCheckedIn', onCheckin);
  // Increases count of connections checked out of the pool when connectionCheckedOut event is triggered
  client.on('connectionCheckedOut', onCheckout);
  // Cleans up event listeners when client is closed
  client.on('close', onClose);
  return {
    count: () => checkedOut,
    cleanUp: onClose
  };
}

Descrições de evento

Você pode assinar qualquer um dos seguintes eventos de monitoramento do pool de conexões:

Nome do evento	Descrição
`connectionPoolCreated`	Criado quando um pool de conexões é criado.
`connectionPoolReady`	Criado quando um pool de conexões estiver pronto.
`connectionPoolClosed`	Criado quando um pool de conexões é fechado antes da destruição da instância do servidor.
`connectionCreated`	Criado quando uma conexão é criada, mas não necessariamente quando é usada para uma operação.
`connectionReady`	Criado após uma conexão ter concluído com êxito um handshake e estar pronta para ser usada em operações.
`connectionClosed`	Criado quando uma conexão é fechada.
`connectionCheckOutStarted`	Criado quando uma operação tenta adquirir uma conexão para execução.
`connectionCheckOutFailed`	Criado quando uma operação falha ao estabelecer uma conexão para execução.
`connectionCheckedOut`	Criado quando uma operação adquire com sucesso uma conexão para execução.
`connectionCheckedIn`	Criado quando uma conexão é verificada novamente no pool depois que uma operação é executada.
`connectionPoolCleared`	Criado quando todas as conexões forem fechadas e o pool de conexões for limpo.

Documentos de exemplos de eventos

As seções abaixo mostram amostras de saída para cada tipo de evento de monitoramento do pool de conexões.

connectionPoolCreated

ConnectionPoolCreatedEvent {
  time: 2023-02-13T15:54:06.944Z,
  address: '...',
  options: {...}
}

connectionPoolReady

ConnectionPoolReadyEvent {
  time: 2023-02-13T15:56:38.440Z,
  address: '...'
}

connectionPoolClosed

ConnectionPoolClosedEvent {
  time: 2023-02-13T15:56:38.440Z,
  address: '...'
}

connectionCreated

ConnectionCreatedEvent {
  time: 2023-02-13T15:56:38.291Z,
  address: '...',
  connectionId: 1
}

connectionReady

ConnectionReadyEvent {
  time: 2023-02-13T15:56:38.291Z,
  address: '...',
  connectionId: 1,
  durationMS: 60
}

connectionClosed

ConnectionClosedEvent {
  time: 2023-02-13T15:56:38.439Z,
  address: '...',
  connectionId: 1,
  reason: 'poolClosed',
  serviceId: undefined
}

connectionCheckOutStarted

ConnectionCheckOutStartedEvent {
  time: 2023-02-13T15:56:38.291Z,
  address: '...',
}

connectionCheckOutFailed

ConnectionCheckOutFailedEvent {
  time: 2023-02-13T15:56:38.291Z,
  address: '...',
  reason: ...,
  durationMS: 60
}

connectionCheckedOut

ConnectionCheckedOutEvent {
  time: 2023-02-13T15:54:07.188Z,
  address: '...',
  connectionId: 1,
  durationMS: 60
}

connectionCheckedIn

ConnectionCheckedInEvent {
  time: 2023-02-13T15:54:07.189Z,
  address: '...',
  connectionId: 1
}

connectionPoolCleared

ConnectionPoolClearedEvent {
  time: 2023-02-13T15:56:38.439Z,
  address: '...',
  serviceId: undefined,
  interruptInUseConnections: true,
}

Documentação da API

Para saber mais sobre qualquer uma das opções ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Monitoramento e registro

cluster