|
| 1 | +# OpenTelemetry Mongoose Instrumentation for Node.js |
| 2 | +[](https://www.npmjs.com/package/opentelemetry-instrumentation-mongoose) |
| 3 | + |
| 4 | +This package is heavily based on [@wdalmut/opentelemetry-plugin-mongoose](https://github.com/wdalmut/opentelemetry-plugin-mongoose). |
| 5 | +This module provides automatic instrumentation for [`mongoose`](https://mongoosejs.com/) and follows otel [DB Semantic Conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/database.md). |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +``` |
| 10 | +npm install --save opentelemetry-instrumentation-mongoose |
| 11 | +``` |
| 12 | + |
| 13 | +## Usage |
| 14 | +For further automatic instrumentation instruction see the [@opentelemetry/instrumentation](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-instrumentation) package. |
| 15 | + |
| 16 | +```js |
| 17 | +const { NodeTracerProvider } = require('@opentelemetry/node'); |
| 18 | +const { registerInstrumentations } = require('@opentelemetry/instrumentation'); |
| 19 | +const { SequelizeInstrumentation } = require('opentelemetry-instrumentation-mongoose'); |
| 20 | + |
| 21 | +registerInstrumentations({ |
| 22 | + traceProvider, |
| 23 | + instrumentations: [ |
| 24 | + new MongooseInstrumentation({ |
| 25 | + // see under for available configuration |
| 26 | + }) |
| 27 | + ] |
| 28 | +}); |
| 29 | +``` |
| 30 | + |
| 31 | +### Mongoose Instrumentation Options |
| 32 | + |
| 33 | +Mongoose instrumentation has few options available to choose from. You can set the following (all optional): |
| 34 | + |
| 35 | +| Options | Type | Description | |
| 36 | +| -------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------- | |
| 37 | +| `suppressInternalInstrumentation` | `boolean` | Mongoose operation use mongodb under the hood. Setting this to true will hide the underlying mongodb spans (if instrumented). | |
| 38 | +| `responseHook` | `MongooseResponseCustomAttributesFunction` | Hook called before response is returned, which allows to add custom attributes to span. | |
| 39 | +| `dbStatementSerializer` | `DbStatementSerializer` | Mongoose instrumentation will serialize `db.statement` using the specified function. |
| 40 | + |
| 41 | +### Custom `db.statement` Serializer |
| 42 | + |
| 43 | +By default, this instrumentation does not populate the `db.statement` attribute. |
| 44 | +If you pass `dbStatementSerializer` while using this plugin, the return value of the serializer will be placed in the `db.statement`. |
| 45 | + |
| 46 | +Serializer meets the following interfaces: |
| 47 | +```ts |
| 48 | +interface SerializerPayload { |
| 49 | + condition?: any; |
| 50 | + options?: any; |
| 51 | + updates?: any; |
| 52 | + document?: any; |
| 53 | + aggregatePipeline?: any; |
| 54 | +} |
| 55 | + |
| 56 | +type DbStatementSerializer = (operation: string, payload: SerializerPayload) => string; |
| 57 | +``` |
| 58 | +Please make sure `dbStatementSerializer` is error proof, as errors are not handled while executing this function. |
| 59 | + |
| 60 | +--- |
| 61 | + |
| 62 | +This extension (and many others) was developed by [Aspecto](https://www.aspecto.io/) with ❤️ |
0 commit comments