monitoring

Note: This API isn't intended for use when extending sites in Wix Studio or the Wix Editor, when coding in Blocks, or in self-managed headless projects. It requires the Wix runtime, so it isn't available when you host your own project. Studio Two sites can use this API.

The monitoring submodule lets you report errors, log messages, and track performance in your code.

Important: Where your reports go depends on the type of project:

  • Wix apps built with the legacy CLI report to Sentry, using the setup described below. For setup and configuration requirements, see Monitoring Your App.
  • Studio Two sites report to the Logs page in the site dashboard, under Developer Tools > Logs, and don't need any setup. See About Logs in Studio Two.
  • Wix-managed headless projects built with Wix's Astro integration report to Wix Logs in the project's dashboard instead, and don't need a Sentry DSN. See Monitor a Headless Project under Project Development for how monitoring works in a headless project.

For apps that report to Sentry, Wix reports unhandled errors to your Sentry project automatically after it recognizes the changes to your wix.config.json file.

Important: For apps built with the legacy CLI, before making calls to the methods defined below, make sure you have the latest version of @wix/essentials and the Wix CLI installed.

Import statement

Copy

Initializing a monitoring client

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

Copy

Methods

captureException()

Captures an exception and reports it.

Syntax

Copy

Parameters

NameTypeDescription
errorErrorThe error to capture.
captureContextCaptureContext(Optional) Additional context to attach to the report.
captureContext.levelstring(Optional) Event severity level. Options: info, warning, error. Default: error.
captureContext.tagsobject(Optional) Key-value pairs to attach to the report. For how Sentry uses tags, see usage and limitations.
captureContext.contextsobject(Optional) Groups of related values to attach to the report. For how Sentry uses contexts, see usage and limitations.

Example

Copy

captureMessage()

Captures a message and reports it.

Syntax

Copy

Parameters

NameTypeDescription
messagestringMessage to capture.
captureContextCaptureContext(Optional) Additional context to attach to the report.
captureContext.levelstring(Optional) Event severity level. Options: info, warning, error. Default: info.
captureContext.tagsobject(Optional) Key-value string pairs to attach to the report. For how Sentry uses tags, see usage and limitations.
captureContext.contextsobject(Optional) Groups of related values to attach to the report. For how Sentry uses contexts, see usage and limitations.

Example

Copy

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.

Wix records breadcrumbs only for reports that go to Sentry. In Studio Two sites, this method has no effect.

Syntax

Copy

Parameters

NameTypeDescription
breadcrumbBreadcrumbBreadcrumb details. Learn more about these properties
breadcrumb.messagestringBreadcrumb message.
breadcrumb.typestring(Optional) Breadcrumb type.
breadcrumb.categorystring(Optional) Breadcrumb category.
breadcrumb.levelstring(Optional) Breadcrumb severity level. Options: info, warning, error.
breadcrumb.dataobject(Optional) Additional data to attach to the breadcrumb.

Example

Copy

startSpan()

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

Syntax

Copy

Parameters

NameTypeDescription
spanOptionsSpanOptionsSpan options.
spanOptions.namestringSpan name.
spanOptions.tagsTags(Optional) Key-value string pairs to attach to the span.
callback(span: Span | undefined) => TCallback function to execute with the span.

Example

Copy

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().

Syntax

Copy

Parameters

NameTypeDescription
spanOptionsSpanOptionsSpan options.
spanOptions.namestringSpan name.
spanOptions.tagsTags(Optional) Key-value string pairs to attach to the span.

Example

Copy

endSpanManual()

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

Syntax

Copy

Parameters

NameTypeDescription
spanOptionsSpanOptionsSpan options.
spanOptions.namestringSpan name.

Example

Copy

Additional context

This section applies to reports that go to Sentry. For the fields in a Studio Two log entry, see Log Entry Structure in Studio Two.

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:

NameDescription
app.idYour app ID.
extension.idYour unique extension ID.
extension.nameYour extension name. For backend extensions this could also be the name of an endpoint or webhook.
extension.typeExtension type. For backend extensions types include: cli-api, cli-event, cli-service-plugin.
platformPlatform where the error originated. Possible Values: BACKEND, DASHBOARD, SITE_EDITOR, SITE_VIEWER.
urlURL of the site where the error originated. Only relevant for site extensions.

Last updated: 11 November 2026

Did this help?