OpenTelemetry MongoDB Instrumentation for Node.js

This module provides automatic instrumentation for the mongodb module.

If total installation size is not constrained, it is recommended to use the @opentelemetry/auto-instrumentations-node bundle with @opentelemetry/sdk-node for the most seamless instrumentation experience.

Compatible with OpenTelemetry JS API and SDK 1.0+.

Installation

npm install --save @opentelemetry/instrumentation-mongodb

Supported Versions

• mongodb version >=3.3.0 <8

Usage

OpenTelemetry MongoDB Instrumentation allows the user to automatically collect trace data and export them to their backend of choice, to give observability to distributed systems.

To enable a specific instrumentation, pass it to registerInstrumentations(). This is commonly done via NodeSDK for fully setting up all OpenTelemetry SDK components:

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { MongoDBInstrumentation } = require('@opentelemetry/instrumentation-mongodb');

const sdk = new NodeSDK({
  instrumentations: [
    new MongoDBInstrumentation({
      // see below for available configuration
    }),
  ],
});
sdk.start();
process.once('beforeExit', async () => { await sdk.shutdown(); });

See examples/mongodb for a short example.

Mongo instrumentation Options

Mongodb instrumentation has few options available to choose from. You can set the following:

| Options | Type | Description | | --------------------------- | -------- | ----------- | | enhancedDatabaseReporting | boolean | If true, additional information about query parameters and results will be attached (as attributes) to spans representing database operations. | | responseHook | function | Function for adding custom attributes from db response. See type MongoDBInstrumentationExecutionResponseHook. | | dbStatementSerializer | function | Custom serializer function for the db.statement / db.query.text span attribute. See type DbStatementSerializer. | | requireParentSpan | boolean | Require a parent span in order to create mongodb spans, default when unset is true. |

Semantic Conventions

This instrumentation creates spans with database and network attributes following the OpenTelemetry Semantic Conventions.

The instrumentation-mongodb versions 0.73.0 and later emit the stable v1.33.0+ semantic conventions.

Span attributes:

| Attribute | Description | | -------------------- | ----------- | | db.system.name | 'mongodb' | | db.namespace | The MongoDB database name. | | db.operation.name | The name of the MongoDB command being executed. | | db.collection.name | The MongoDB collection being accessed within the database stated in db.namespace. | | db.query.text | The database query being executed. | | server.address | Remote hostname or similar. | | server.port | Remote port number. |

Metrics collected:

• db.client.connection.count - The number of connections currently in a given state.

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.