> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: monitoring

## Article: monitoring

## Article Link: https://dev.wix.com/docs/sdk/core-modules/essentials/monitoring.md

## Article Content:

# monitoring

<blockquote class="caution">
<strong>Developer Preview </strong>
  
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

</blockquote>

> **Note:** This API is not intended for use in [site development](https://dev.wix.com/docs/sdk/articles/get-started/about-site-development.md) or when [coding in Blocks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/code-in-blocks/about-coding-in-blocks.md).

The `monitoring` submodule allows you to report errors, log messages, track performance metrics and get notified of uncaught exceptions and unhandled rejections in your application code with [Sentry](https://sentry.io/). 

See [Monitoring Your App](https://dev.wix.com/docs/build-apps/manage-your-app/observability/monitor-your-app-with-sentry.md) for setup and configuration requirements.

  Note that when Wix recognizes the changes to your `wix.config.json` file,  Wix will report unhandled errors to your Sentry project automatically. 
<blockquote class="important">
  <strong>Important:</strong>
  Before making calls to the methods defined below using this solution, make sure you have the latest version of <code><a href="fallback::https://dev.wix.com/docs/sdk/core-modules/essentials/introduction">@wix/essentials</a></code>.md and the <a href="fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/app-development/development-overview.md#keeping-the-cli-up-to-date">Wix CLI</a> installed.
</blockquote>

## Import statement
```js
import { monitoring } from "@wix/essentials";
```

## Initializing a monitoring client

In order to use the monitoring client and report events, you need to initialize it.

```js
const monitoringClient = monitoring.getMonitoringClient();
```

## Methods

### `captureException()`

Captures an exception event and sends it to Sentry.

#### Syntax
```js
function captureException(error: Error, captureContext?: CaptureContext): void;
```

#### Parameters
| Name | Type | Description                                                  |
| ---- | ---- |--------------------------------------------------------------|
| `error` | Error | The error to capture.                                        |
| `captureContext` | CaptureContext | (Optional) Additional context to attach to the Sentry event. |
| `captureContext.level` | string | (Optional) Event severity level. Default: `error`. Options: `info`, `warning`, `error`.                                                                                     |
| `captureContext.tags` | object | (Optional) Key-value pairs to attach to the Sentry event. Learn more about [usage and limitations](https://docs.sentry.io/platforms/javascript/enriching-events/context). |
| `captureContext.contexts` | object | (Optional) Additional context to attach to the Sentry event. Learn more  about [usage and limitations](https://docs.sentry.io/platforms/javascript/enriching-events/context).  |

#### Example
```js
import { monitoring } from "@wix/essentials";

const monitoringClient = monitoring.getMonitoringClient();

try {
  // ... code that might throw an error
} catch (error) {
  monitoringClient.captureException(error, {
      level: 'info',
      tags: {
          feature: "checkout"
      },
      contexts: {
          checkout: {
              id: "1234"
          }
      }
  });
}
```

---

### `captureMessage()`

Captures a message event as an event in Sentry.

#### Syntax
```js
function captureMessage(message: string, captureContext?: CaptureContext): void;
```

#### Parameters
| Name | Type | Description |
| ---- | ---- | ----------- |
| `message` | string | Message to capture. |
| `captureContext` | CaptureContext | (Optional) Additional context to attach to the Sentry event. |
| `captureContext.level` | string | (Optional) Event sverity level. Default: `error`. Options: `info`, `warning`, `error`.  |
| `captureContext.tags` | object | (Optional) Key-value string pairs to attach to the Sentry event. Learn more about [usage and limitations](https://docs.sentry.io/platforms/javascript/enriching-events/tags) . |
| `captureContext.contexts` | object | (Optional) Additional context to attach to the Sentry event. Learn more  about [usage and limitations](https://docs.sentry.io/platforms/javascript/enriching-events/tags).  |

#### Example
```js
import { monitoring } from "@wix/essentials";

const monitoringClient = monitoring.getMonitoringClient();

monitoringClient.captureMessage("User reached checkout", {
    level: 'info',
    tags: {
        feature: "checkout"
    },
    contexts: {
        checkout: {
            id: "1234"
        }
    }
});
```

---

### `addBreadcrumb()`

Records a new breadcrumb which will be attached to future events.
Breadcrumbs will be added to subsequent events to provide more context on user's actions prior to an error or crash.

#### Syntax
```js
function addBreadcrumb(breadcrumb: Breadcrumb): void;
```

#### Parameters
| Name | Type         | Description |
| ---- |--------------| ----------- |
| `breadcrumb` | Breadcrumb | Breadcrumb details. Learn more about these [properties](https://docs.sentry.io/product/issues/issue-details/breadcrumbs/#breadcrumb-attributes)|
| `breadcrumb.message` | string | Breadcrumb message.          |
| `breadcrumb.type` | string | (Optional) Breadcrumb type.       |
| `breadcrumb.category` | string | (Optional) Breadcrumb category.      |
| `breadcrumb.level` | string | (Optional) Breadcrumb severity level. Options: `info`, `warning`, `error`. |
| `breadcrumb.data` | object | (Optional) Additional data to attach to the breadcrumb.    |

#### Example
```js
import { monitoring } from "@wix/essentials";

const monitoringClient = monitoring.getMonitoringClient();

monitoringClient.addBreadcrumb({ message: "User clicked checkout", level: 'info' });
```

---

### `startSpan()`

Starts a new span and executes the provided callback function with the span as an argument.

#### Syntax
```js
function startSpan<T>(spanOptions: SpanOptions, callback: (span: Span | undefined) => T): T;
```

#### Parameters
| Name | Type                             | Description |
| ---- |----------------------------------| ----------- |
| `spanOptions` | SpanOptions | Span options. |
| `spanOptions.name` | string | Span name. |
| `spanOptions.tags` | `Tags` | (Optional) Key-value string pairs to attach to the span. |
| `callback` | `(span: Span \| undefined) => T` | Callback function to execute with the span. |

#### Example
```js
import { monitoring } from "@wix/essentials";

const monitoringClient = monitoring.getMonitoringClient();

monitoringClient.startSpan({ name: "checkout" }, (span) => {
    // ... code to execute
});
```

### `startSpanManual()`

Starts a new span that requires manual completion. Complete this span manually by calling `end()` or `fail()` using the returned span object or by calling [endSpanManual()](#endspanmanual). 

#### Syntax
```js
function startSpanManual<T>(spanOptions: SpanOptions): ManualSpan;
```

#### Parameters
| Name | Type                             | Description |
| ---- |----------------------------------| ----------- |
| `spanOptions` | SpanOptions | Span options. |
| `spanOptions.name` | string | Span name. |
| `spanOptions.tags` | `Tags` | (Optional) Key-value string pairs to attach to the span. |

#### Example
```js
import { monitoring } from "@wix/essentials";

const monitoringClient = monitoring.getMonitoringClient();

const span = monitoringClient.startSpanManual({ name: "checkout" });

try {
    // ... some code
} catch (e) {
    span.fail(e)
}

span.end();

// or
monitoringClient.endSpanManual({ name: "checkout" });

```

### `endSpanManual()`

Ends the most recent span that was started using [startSpanManual()](#startspanmanual). Any older manual spans with the same name will be ignored.

#### Syntax
```js
function endSpanManual<T>(spanOptions: EndSpanOptions): void;
```

#### Parameters
| Name | Type                             | Description |
| ---- |----------------------------------| ----------- |
| `spanOptions` | SpanOptions | Span options. |
| `spanOptions.name` | string | Span name. |

#### Example
```js
import { monitoring } from "@wix/essentials";

const monitoringClient = monitoring.getMonitoringClient();

monitoringClient.startSpanManual({ name: "checkout" });

// ... some code

monitoringClient.endSpanManual({ name: "checkout" });

```

## Additional context
Each report we send to Sentry is enriched with additional information that will help you find the root of the problem. The context object will vary slightly depending on the report, but will generally include the following: 

| Name  | Description                                                                                                                                                                                                         |
| ---- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 
|`app.id` | Your app ID.                                                                                                                                                                                                        |
|`extension.id` | Your unique [extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions.md) ID.                                                                                                       |
|`extension.name` | Your extension name. For [backend extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/about-backend-extensions.md) this could also be the name of an endpoint or webhook.   |
|`extension.type` | Extension type.  For [backend extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/about-backend-extensions.md) types include: `cli-api`, `cli-event`, `cli-service-plugin`. 
| `platform` | Platform where the error originated. Possible Values: `BACKEND`, `DASHBOARD`, `SITE_EDITOR`, `SITE_VIEWER`.
|`url`| URL of the site where the error originated. Only relevant for [site extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/about-site-extensions.md).                         |