# opentelemetry-instrumentation-mongoose

> open telemetry instrumentation for the `mongoose` module

Latest version **0.34.0** (published 2022-11-21) · Apache-2.0 license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install opentelemetry-instrumentation-mongoose
pnpm add opentelemetry-instrumentation-mongoose
yarn add opentelemetry-instrumentation-mongoose
bun add opentelemetry-instrumentation-mongoose
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.34.0 |
| Published | 2022-11-21 |
| First published | 2021-02-16 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 148.6 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 168 |
| Author | Aspecto |
| Maintainers | aspecto-release-bot |
| Keywords | mongoose, mongodb, opentelemetry |

## Links

- npm: https://www.npmjs.com/package/opentelemetry-instrumentation-mongoose
- Repository: https://github.com/aspecto-io/opentelemetry-ext-js
- Issues: https://github.com/aspecto-io/opentelemetry-ext-js/issues
- npm.io page: https://npm.io/package/opentelemetry-instrumentation-mongoose

## Dependencies (3)

- [@opentelemetry/core](https://npm.io/package/@opentelemetry/core.md) ^1.8.0
- [@opentelemetry/instrumentation](https://npm.io/package/@opentelemetry/instrumentation.md) ^0.34.0
- [@opentelemetry/semantic-conventions](https://npm.io/package/@opentelemetry/semantic-conventions.md) ^1.8.0

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [@temporal-architect/claude-plugin](https://npm.io/package/@temporal-architect/claude-plugin.md) — 335 weekly downloads

## Recent versions

- 0.34.0 (latest) — 2022-11-21
- 0.0.0-2022-07-11--08-09 (alpha) — 2022-07-11
- 0.4.1-aws-import-one-serivce.0 (canary) — 2021-04-28
- 0.32.0 — 2022-10-18
- 0.29.0 — 2022-06-28
- 0.28.0 — 2022-06-02
- 0.27.1 — 2022-04-13
- 0.0.0-2022-04-13--14-32 — 2022-04-13
- 0.27.0 — 2021-12-27
- 0.0.0-2021-12-26--12-31 — 2021-12-26
- 0.0.0-2021-12-26--12-22 — 2021-12-26
- 0.0.0-2021-12-22--14-33 — 2021-12-22
- 0.0.0-2021-12-21--15-57 — 2021-12-21
- 0.0.0-2021-12-20--13-41 — 2021-12-20
- 0.0.0-2021-12-15--16-17 — 2021-12-15
- … 46 more at https://npm.io/package/opentelemetry-instrumentation-mongoose/versions

## README

# OpenTelemetry Mongoose Instrumentation for Node.js
[![NPM version](https://img.shields.io/npm/v/opentelemetry-instrumentation-mongoose.svg)](https://www.npmjs.com/package/opentelemetry-instrumentation-mongoose)

This package is heavily based on [@wdalmut/opentelemetry-plugin-mongoose](https://github.com/wdalmut/opentelemetry-plugin-mongoose).  
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).  

## Installation

```
npm install --save opentelemetry-instrumentation-mongoose
```

## Usage
For further automatic instrumentation instruction see the [@opentelemetry/instrumentation](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-instrumentation) package.

```js
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { MongooseInstrumentation } = require('opentelemetry-instrumentation-mongoose');

registerInstrumentations({
  tracerProvider,
  instrumentations: [
    new MongooseInstrumentation({
      // see under for available configuration
    })
  ]
});
```

### Mongoose Instrumentation Options

Mongoose instrumentation has few options available to choose from. You can set the following (all optional):

| Options        | Type                                   | Description                                                                                     |
| -------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `suppressInternalInstrumentation` | `boolean` | Mongoose operation use mongodb under the hood. Setting this to true will hide the underlying mongodb spans (if instrumented). |
| `responseHook` | `MongooseResponseCustomAttributesFunction` | Hook called before response is returned, which allows to add custom attributes to span.      |
| `dbStatementSerializer` | `DbStatementSerializer` | Mongoose instrumentation will serialize `db.statement` using the specified function.
| `moduleVersionAttributeName` | `string` | If passed, a span attribute will be added to all spans with key of the provided `moduleVersionAttributeName` and value of the patched module version |
| `requireParentSpan` | `boolean` | Set to true if you do not want to collect traces that start with mongoose |

### Custom `db.statement` Serializer

By default, this instrumentation does not populate the `db.statement` attribute.  
If you pass `dbStatementSerializer` while using this plugin, the return value of the serializer will be placed in the `db.statement`.

Serializer meets the following interfaces:
```ts
interface SerializerPayload {
    condition?: any;
    options?: any;
    updates?: any;
    document?: any;
    aggregatePipeline?: any;
}

type DbStatementSerializer = (operation: string, payload: SerializerPayload) => string;
```
Please make sure `dbStatementSerializer` is error proof, as errors are not handled while executing this function.

## Difference from [opentelemetry-plugin-mongoose](https://github.com/wdalmut/opentelemetry-plugin-mongoose)

* This lib is using the opentelemetry instrumentation api, as opposed to the old plugin api.
* This lib is using the latest opentelemetry version, as opposed to 0.6.0.
* Strictly follows opentelemetry database client [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/database.md).
* Has the ability to suppress internal instrumentation.
* Provides statement serializer and a response hook.
* Contains several bug fixes.

---

This extension (and many others) was developed by [Aspecto](https://www.aspecto.io/) with ❤️

---
_Source: https://npm.io/package/opentelemetry-instrumentation-mongoose · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._