
[highlight.io](https://highlight.io) is monitoring software for the next generation of developers. And it's all [opensource](https://github.com/highlight/highlight) :).

[highlight.io](https://highlight.io) gives you **fullstack** visibility into your application by pairing session replay, error monitoring, and logging, allowing you to tie frontend issues with backend logs and performance issues.

<DocsCardGroup>
    <DocsCard title="Get Started" href="../getting-started/1_overview.md">
        {"Get started with highlight.io. Instrument your frontend & backend."}
    </DocsCard>
</DocsCardGroup>

### About us.

<DocsCardGroup>
    <DocsCard title="Mission & Values." href="./2_company/1_values.md">
        {"Details about our company, our values, and opensource."}
    </DocsCard>
    <DocsCard title="Compliance & Security."  href="./2_company/compliance-and-security.md">
        {"Our security certificates, and contact details."}
    </DocsCard>
    <DocsCard title="Contributing to highlight.io"  href="./2_company/open-source/contributing.md">
        {"Open source, self hosting highlight, and contributing."}
    </DocsCard>
    <DocsCard title="Self hosting highlight.io"  href="./2_company/open-source/self-host-hobby.md">
        {"Open source, self hosting highlight, and contributing."}
    </DocsCard>
</DocsCardGroup>

### Features

<DocsCardGroup>
    <DocsCard title="Sesion Replay." href="./6_product-features/1_session-replay/1_overview.md">
        {"Session replay features, how to get started, etc.."}
    </DocsCard>
    <DocsCard title="Error Monitoring."  href="./6_product-features/2_error-monitoring/1_overview.md">
        {"Error monitoring features, how to get started, etc.."}
    </DocsCard>
    <DocsCard title="Logging."  href="./6_product-features/4_logging/1_overview.md">
        {"Logging features, how to get started, etc.."}
    </DocsCard>
</DocsCardGroup>



<DocsCardGroup>
    <DocsCard title="Get Started" href="../getting-started/1_overview.md">
        {"Integrate highlight.io into your web app."}
    </DocsCard>
</DocsCardGroup>



Our mission is to support developers (like you) to ship with confidence. We do this by giving you the tools you need to **uncover, resolve, and prevent** issues in your web app.

## We build in public.

We strive to build in public in every way we can. This means sharing our roadmap, product specs, and company strategy. We see this as giving you all the more reason to consider joining us in [building highlight](https://careers.highlight.run).

## We prioritize cohesion.

People may think that we're building multiple products (session replay, error monitoring, etc..) but we see it as one. Before we build anything new, we prioritize making it operate seemlessly with everything else. E.g. see our [fullstack mapping guide](../../getting-started/2_frontend-backend-mapping.md).

## We build for today's developer.

If you're building software in today's ecosystem, you probably want to focus on building software. We challenge ourselves to build developer tooling that’s simple, straightforward but powerful if you'd like to dig deeper. highlight.io is built for developers that want to **develop**. Leave the monitoring stuff to us 👍.

## We execute quickly and fail fast.

Given that most of the things we build are zero to one, there's often no better way to learn than to build. It's hard to predict how something will scale or be interacted w/ without building something and getting early feedback. With this philosophy, however, its easy to ship low quality work, which is why we prefer to "cut scope, not quality".

## ABC: Always be chilling....

Though working at highlight.io can be fast-paced at times, we keep a chill atmosphere and regularly spend time with each other in a non-professional sense.

![](/images/ohyeah.gif)



We take compliance and security very seriously at [highlight.io](https://highlight.io). We officially have a Soc2 Type2 report, Gdpr compliance and are currently in the process of attaining HIPAA. If you're evaluating highlight.io at your company and have questions on the security end, please shoot us an email at [security@highlight.io](mailto:security@highlight.io).

![](/images/certs.png)



## Best first issues to take on

It's best to start with issues marked as ["good first issue"](https://github.com/highlight/highlight/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). We mark these issues based on how well-defined and testable they are. If you're interested in a larger project, adding support for new programming languages via a new SDK would always greatly appreciated. If there is a feature you're missing in Highlight, reach out on our [discussions](https://github.com/highlight/highlight/discussions) or on our [discord](https://highlight.io/community) to get a conversation started about the best implementation.

## How do I spin up highlight.io locally?

Check out our development deployment guide to get started:

<DocsCardGroup>
    <DocsCard title="Dev Deployment Guide." href="../../../../getting-started/self-host/dev-deployment-guide.md">
        {"Running a docker version of highlight.io for development."}
    </DocsCard>
</DocsCardGroup>



The highlight.io SDKs are powered by [OpenTelemetry](https://opentelemetry.io/) under the hood, and therefore report data to our deployed opentelemetry [collector](https://otel.highlight.io). For a better understanding of the architecture, take a look at the [architecture page](architecture.md) for a diagram of how data is sent to the collector and the public graph.

In our SDKs, we instantiate the following constructs to exports data over OTLP HTTPS to https://otel.highlight.io:4318/v1/traces and https://otel.highlight.io:4318/v1/logs respectively.

- TracerProvider - sets the global otel sdk configuration for traces
- BatchSpanProcessor - batches traces so they are exported in sets
- OTLPSpanExporter - exports traces to our collector over OTLP HTTPS

- LoggerProvider - sets the global otel sdk configuration for logs
- BatchLogRecordProcessor - batches logs so they are exported in sets
- OTLPLogExporter - exports logs to our collector over OTLP HTTPS

The SDK provides common methods for recording exceptions or logging, but this may depend on the language. For example, in Golang, a logger hook API is provided to be configured by the application, but in Python, we automatically ingest a hook into the built in `logging` package.

## Recording an Error

Data we send over the OpenTelemetry specification is as a [Trace](https://opentelemetry.io/docs/reference/specification/trace/) with attributes set per the [semantic conventions](https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/).
When we create a Trace, we set three additional SpanAttributes to carry the Highlight context:

- highlight.project_id - Highlight Project ID provided to the SDK

- highlight.session_id - Session ID provided as part of the `X-Highlight-Request` header on the network request

- highlight.trace_id - Request ID provided as part of the `X-Highlight-Request` header on the network request

### Reporting an Error as an OTEL Trace

An exception is represented in OpenTelemetry as a Trace Event, per the [semantic convention for exceptions](https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/exceptions/).

Many OpenTelemetry SDK implementations offer a `span.record_exception(exc)` method that automatically populates the semantic convention attributes with the correct values.

```python

# create a trace for the current invocation
with self.tracer.start_as_current_span("highlight-ctx") as span:
    span.set_attributes({"highlight.project_id": _project_id})
    span.set_attributes({"highlight.session_id": session_id})
    span.set_attributes({"highlight.trace_id": request_id})
    try:
        # contextmanager yields execution to the code using the contextmanager
        yield
    except Exception as e:
        # if an exception is raised, record it on the current span
        span.record_exception(e)
        raise

```

### Reporting a Log as an OTEL Trace

If a language's OpenTelemetry SDK does not support sending logs natively, we choose to send the message data as a Trace [Event](https://opentelemetry.io/docs/concepts/signals/traces/#span-events).

- Event name - `log`

- `log.severity` event attribute - the log severity level string

- `log.message` event attribute - the log message payload.

To associate the highlight context with a log, we use the [LogRecord](https://opentelemetry.io/docs/reference/specification/logs/data-model/#log-and-event-record-definition) [Attributes](https://opentelemetry.io/docs/reference/specification/logs/semantic_conventions/) with the following convention:

- highlight.project_id - Highlight Project ID provided to the SDK

- highlight.session_id - Session ID provided as part of the `X-Highlight-Request` header on the network request

- highlight.trace_id - Request ID provided as part of the `X-Highlight-Request` header on the network request

```go

package main

import "github.com/highlight/highlight/sdk/highlight-go"

func RecordLog(log string) {
	span, _ := highlight.StartTrace(context.TODO(), "highlight-go/logrus")
	defer highlight.EndTrace(span)

	attrs := []attribute.KeyValue{
		LogSeverityKey.String("ERROR"),
		LogMessageKey.String(entry.Message),
	}
	span.AddEvent(highlight.LogEvent, trace.WithAttributes(attrs...))
}

```

## Recording a Log

If an SDK supports the experimental logs ingest endpoint (v1/logs), prefer using that. Otherwise, see above for reporting the log as a trace event.

A LogRecord is exported with an associated trace. Specific attributes for the file logging, line number, and more are set based on the [logging semantic convention keys](https://opentelemetry.io/docs/reference/specification/logs/semantic_conventions/).

Here's an example of the interception of python `logging` calls in our [Python SDK](https://github.com/highlight/highlight/blob/93bfea864440a1976ac945ba2b40a34cf3b53479/sdk/highlight-py/highlight_io/sdk.py#L139-L160) to emit an OTEL LogRecord.

```python

attributes = span.attributes.copy()
attributes["code.function"] = record.funcName
attributes["code.namespace"] = record.module
attributes["code.filepath"] = record.pathname
attributes["code.lineno"] = record.lineno
r = LogRecord(
    timestamp=int(record.created * 1000.0 * 1000.0 * 1000.0),
    trace_id=ctx.trace_id,
    span_id=ctx.span_id,
    trace_flags=ctx.trace_flags,
    severity_text=record.levelname,
    severity_number=std_to_otel(record.levelno),
    body=record.getMessage(),
    resource=span.resource,
    attributes=attributes,
)

```



# Application Architecture

Here's the high level structure of the code that you'll want to start tinkering with.

- SDKs `sdk/`

  - Firstload

  - Client

  - highlight-node / other SDKs

- Public Graph `backend/public-graph/graph/schema.resolvers.go` SDK data ingest graphql endpoint, hosted locally at https://localhost:8082/public

- Private Graph `backend/private-graph/graph/schema.resolvers.go` Graphql endpoint for frontend, hosted locally at https://localhost:8082/private

- Workers `backend/worker.go`

  - Public graph worker `processPublicWorkerMessage`

  - Async worker `Start`

## General Architecture Diagram

![](/images/architecture.png)

## Code Structure Diagram

![](/images/software-components.png)

## Kafka Diagram

![](/images/kafka.png)

## InfluxDB Diagram

![](/images/influx.png)

## OpenTelemetry Diagram

![](/images/opentelemetry.png)



# Code Style

Our main priority is to keep our code to be easy to read and add to. We've codified and automated all style preferences as part of CI and development workflows (such as `husky`) so that there is one consistent source of truth. If you have ideas on how to improve our style linting, open a PR and let us know!

# License

Highlight is [Apache 2](https://github.com/highlight/highlight/blob/main/LICENSE) licensed.

By contributing to Highlight, you agree that your contributions will be licensed under its Apache 2 license.



## Our Enterprise Self-hosted Deployment

Interested in deploying Highlight to your own VPC at a larger scale than the [hobby deployment](../open-source/self-host-enterprise.md)? Please contact us in our [discord community](https://community.highlight.io) to get in touch.

## Pricing

Pricing for our self-hosted enterprise deployment starts at $3k / month. Contact us at jay@highlight.io, or message us [on discord](https://community.highlight.io) to get in touch.



## Our Hobby Self-hosted Deployment

Interested in deploying highlight.io on your local machine or on a small remote instance? You're in the right place. Here's a walkthrough on getting this set up:

<DocsCardGroup>
    <DocsCard title="Hobby Deployment Guide" href="../../../getting-started/self-host/self-hosted-hobby-guide.md">
        {"Getting started with our hobby deployment."}
    </DocsCard>
</DocsCardGroup>

## Pricing

Pricing for our self-hosted enterprise deployment starts at $3k / month. Contact us at jay@highlight.io, or message us [on discord](https://community.highlight.io) to get in touch.

# Limitations

We don't recommend hosting Highlight yourself if you have more than 10k monthly sessions or 50k monthly errors. The infrastructure configuration in the docker compose is not meant to scale beyond a small number of sessions, and isn't resilient to an outage or version upgrades.

That being said, if the benefits of self hosting Highlight are signficant enough, you may want to consider an enterprise deployment (see [our Enterprise Self Hosted Docs](./self-host-enterprise.md)).

If you have any questions, don't hesitate to [reach out](https://community.highlight.io)!



Session replay gives your team visibility into how people use your web app and insight into WHY bugs happen. In [highlight.io](https://highlight.io), we focus heavily on "cohesion", or the mapping of sessions, errors and logs across your stack; that way you get an accurate and comprehensive idea of what happens.

## Get Started.

<DocsCardGroup>
    <DocsCard title="Get Started."  href="../../../getting-started/1_overview.md">
        {"Get started with error monitoring by installing highlight.io"}
    </DocsCard>
</DocsCardGroup>

## Features.

Read more about the features we support in Session Replay below:

<DocsCardGroup>
    <DocsCard title="Shadow DOM & Web Components."  href="./shadow-dom-web-components.md">
        {"Support for Shadow DOM & Web Components"}
    </DocsCard>
    <DocsCard title="Proxying through your domain."  href="./request-proxying.md">
        {"Support for proxying highlight.io requests through your domain."}
    </DocsCard>
    <DocsCard title="Canvas & Iframe Recording."  href="./canvas-iframe.md">
        {"Support for Canvas & Iframe Recording"}
    </DocsCard>
    <DocsCard title="Devtools Data."  href="./dev-tools.md">
        {"Capturing of console logs, network requests and errors."}
    </DocsCard>
    <DocsCard title="Tracking Users & Events."  href="./events-and-users.md">
        {"SDK support for tracking users and their corresponding actions throughout a session."}
    </DocsCard>
    <DocsCard title="Live Mode."  href="./live-mode.md">
        {"Support for following a user session in real-time."}
    </DocsCard>
    <DocsCard title="Performance Impact."  href="./performance-impact.md">
        {"The performance impact of the highlight.io snippet."}
    </DocsCard>
    <DocsCard title="Privacy & Redaction."  href="./privacy.md">
        {"Options to redact specific data being recorded in your frontend."}
    </DocsCard>
    <DocsCard title="Rage Clicks."  href="./rage-clicks.md">
        {"Record when users click a specific elemtent frequently."}
    </DocsCard>
    <DocsCard title="Session Search."  href="./session-search.md">
        {"Features that allow you to search for sessions in your app."}
    </DocsCard>
    <DocsCard title="Session Search Deep Linking."  href="./session-search.md">
        {"The URL Schema we use for deep linking sessions."}
    </DocsCard>
</DocsCardGroup>



## Recording `canvas` elements

[highlight.io](https://highlight.io) supports recording canvas (and therefore WebGL) elements, although due to the nature of `canvas`, there are caveats regarding the quality/fidelity of the recording. Read more about how to get started with this in our [getting started docs](../../../getting-started/3_client-sdk/7_replay-configuration/canvas.md).

## Installing highlight.io in an `iframe`

The highlight.io snippet supports recording within an iframe, but given the security limitations, there are caveats. Read more about this in our [sdk configuration docs](../../../getting-started/3_client-sdk/7_replay-configuration/iframes.md#recording-within-iframe-elements).

## Recording Cross-origin `iframe`s

To support recording a cross-origin iframe that you own, we've added functionality into our recording client that allows the iframe to forward its events to the parent session. Read more about this in our [sdk configuration docs](../../../getting-started/3_client-sdk/7_replay-configuration/iframes.md#recording-a-cross-origin-iframe-element).



## Devtools Recording

[highlight.io](https://highlight.io) supports recording all of the resources that you see in the chrome dev-tools window; that is, console messages, network requests and errors. Read more about how to instrument this data in our [sdk configuration docs](../../../getting-started/3_client-sdk/7_replay-configuration/1_overview.md). Here's a sneak peak of what this looks like:

![](/images/devtools.png)



## Identifying Users & Tracking Events

With session replay, it can be useful to identify the actual users and track actions that they perform. By default, your users in [highlight.io](https://highlight.io) remain anonymous, but we offer the option to identify and track actions with our javascript SDK. Read more in our [SDK Configuration](../../../getting-started/3_client-sdk/7_replay-configuration/1_overview.md) guide.

![](/images/user-info.png)



[highlight.io](https://highlight.io) supports tracking users in real-time as they user your web application. When you use highlight.io's Live Mode, the session viewer shows the latest data from users' sessions. It is enabled by default on sessions currently 'live' - eg. when a user is still on the page and sending session data.

While you can view how a session looks to a user in real time, note that some events haven't been processed and will not be visible. Errors, console logs, and network traffic will only be visible when Live Mode is disabled, up to what's most recently processed. In Live Mode, time-scrubbing is disabled since you're always seeing the latest session view.

You can always turn off Live Mode by clicking the toggle button, which will show the session up to the latest data processed. Clicking on the session to write a comment will also disable Live Mode, since comments are associated with a particular timestamp.



## Overview

When building Highlight, we've made technical decisions that prioritize putting your site's performance first. Highlight's performance impact on your site, therefore, is negligible, both from the perspective of your user's real-time experience as well as from a page-load perspective.

## Bundle Size

Highlight's gzipped bundle size is a [mere 11 kb](https://www.npmjs.com/package/highlight.run). From a page load perspective, your team should have no qualms regarding Highlight's impact on page load metrics.

## DOM Interaction Performance

Highlight uses the well-maintained [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) browser API in order to record DOM mutations. When sending these changes to our platform, we buffer events periodically to ensure that

1.  Events aren't being held in memory for a prolonged time

2.  Outgoing network requests aren't interfering with user interactions

## Network

Your client will send Highlight telemetry about every 3 seconds. We've taken extra care in making sure we don't overwhelm your end user's machine:

1.  Only 1 request will be in-flight at a given time

2.  Responsive to your end user's network speed



Due to the nature of Highlight's core product, we keep privacy a top priority. [highlight.io](https://highlight.io) has the necessary [compliance measures](../../3_company/compliance-and-security.md) in place to support your business and beyond that, we've built several ways to redact/mask certain DOM elements while still preserving the structure of your DOM recording. It is important to note that for all of our solutions, all data is sanitized on the client, so sensitive data never reaches our servers/platform. Read more about configuring privacy settings in our [SDK Configuration](../../../getting-started/3_client-sdk/7_replay-configuration/1_overview.md) section.



Rage clicks are the equivalent of spamming a close elevator button when you just want to get up to your apartment. But, instead of a close elevator button, it's a space on your application. And instead of getting to your apartment, users usually _rage click_ when a button isn't working as it should.

## How do we identify rage clicks?

A Rage Click is defined as a time periodic in which a user clicks the same area a certain number of times. This can help highlight points of frustration your users have with the app.

By default, we consider user activity as rage clicks when there exists a 2 second or longer period in which a user clicks 5 or more times within a radius of 8 pixels.

## Customizing rage click sensitivity

You'll find fine-grained control over your project's rage click settings in [your project settings page](https://app.highlight.io/settings).

- Elapsed Time (seconds): the maximum time interval during which clicks count toward a rage click.

- Radius (pixels): how close clicks must be to be determined as part of the same rage click.

- Minimum Clicks: the minimum number of nearby clicks required to count as a rage click.

![configuring rage click settings](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/0sgR-VlLcRpAl9SsbDfR-_image.png)

## Alerting for rage clicks

Create a rage click alert [within your project's alerts page](https://app.highlight.io/alerts) to be notified on Slack or via email about a user rage clicking in your app!

![creating a rage click alert](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/XxyLN8kFXtefRgFf1BBUI_image.png)



## Request Proxying

With tools that run from your browser, you run the risk of having requests blocked by ad blockers and chrome extensions. [highlight.io](https://highlight.io) supports [proxying requests](../../../getting-started/3_client-sdk/7_replay-configuration/proxying-highlight.md) through your own domain.



# Searching by Identifier

In [highlight.io](https://highlight.io), you can search for a session by any of the data you send us (via the SDK) throughout a session. The data you send us can be in the form of [track](../../../getting-started/3_client-sdk/7_replay-configuration/tracking-events.md) or [identify](../../../getting-started/3_client-sdk/7_replay-configuration/identifying-sessions.md) calls.

# Searching by User Clicks

When using Highlight, you might be interested in querying for sessions where a user clicked a certain HTML element. Highlight records users' clicks on the page as two queryable properties: `clickSelector` and `clickInnerText`.

1.  `clickSelector` is the HTML Element's target's selector, concatinating the element's `tag`, `id ` and `class` values.

2.  `clickTextContent `is the HTML Element's target's `textContent` property. Only the first 2000 characters are sent.
    1.  This property was added in `highlight.run@^4.2.3`.

You can also visualize what Highlight is tracking by looking at your site's console logs when you click an element of interest. For example, clicking a particular `p` element in [https://app.highlight.io/](https://app.highlight.io/1/sessions?query=and) prints the following in the console logs.

![A sample console message on click.](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/yP5u4tqGinXhIyonAuXV1_image.png)

You can then use the session filters to search for text in the two fields.

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/2ckH93jnzBYqpCeeTWOXT_image.png)



The queries you build when searching for sessions are reflected in the URL parameters. You can share these URLs with others to deep link to search results, or even create them programatically.

## Syntax

`/sessions?query={and|or}||{property1},{operator1},{valueA},{valueB}`

- Highlight supports `and` and `or` queries

- User properties:

  - `user_{your_property_name}`

- Track properties:

  - `track_{your_property_name}`

- Sessions built-in properties (these are automatically populated by Highlight):

  - `user_identifier `

  - `session_browser_version`

  - `session_browser_name`

  - `session_device_id`

  - `session_environment`

  - `session_os_name`

  - `session_os_version`

  - `session_referrer`

  - `session_reload`

  - `session_visited-url`

  - `custom_app_version`

  - `custom_created_at`

  - `custom_active_length`

  - `custom_viewed`

  - `custom_processed`

  - `custom_first_time`

  - `custom_starred`

- Operators:

  - `is`

  - `is_not`

  - `contains`

  - `not_contains`

  - `exists`

  - `not_exists`

  - `matches` (uses Lucene regex syntax)

  - `not_matches` (uses Lucene regex syntax)

  - `between` (for active_length)

  - `not_between` (for active_length)

  - `between_date` (for created_at)

  - `not_between_date` (for created_at)

## Examples

Viewing sessions for a particular user:

`/sessions?query=and||user_identifier,is,alice@example.com`

Excluding sessions from your organization:

`/sessions?query=and||user_identifier,not_contains,@yourdomain.com`

Viewing sessions for a particular page in your app:

`/sessions?query=and||session_visited-url,contains,/your/path/name`

Multiple properties

`/sessions?query=or||user_identifier,is,Bob||user_email,is_not,alice@example.com`



## Shadow DOM & Web Components

[highlight.io](https://highlight.io) supports both [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) and [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) out of the box.



Error monitoring in [highlight.io](https://highlight.io) is different than most tools, in that we emphasize the mapping between your frontend and backend. Keep reading to learn more about our feature set and get started.

## Get started.

<DocsCardGroup>
    <DocsCard title="Get Started."  href="../../../getting-started/1_overview.md">
        {"Get started with session replay by installing highlight.io"}
    </DocsCard>
</DocsCardGroup>

## Features.

<DocsCardGroup>
    <DocsCard title="Grouping Errors."  href="./grouping-errors.md">
        {"Logic for grouping errors to mitigate repetition."}
    </DocsCard>
    <DocsCard title="Sourcemaps."  href="./sourcemaps.md">
        {"Configure sourcemaps for your frontend errors."}
    </DocsCard>
    <DocsCard title="Versioning Errors."  href="../../../getting-started/3_client-sdk/7_replay-configuration/versioning-sessions-and-errors.md">
        {"Send highlight.io metadata so you can version errors across deploys."}
    </DocsCard>
</DocsCardGroup>



Highlight groups errors together based on their error message and stack trace. When an error is thrown, Highlight finds the closest matching error and adds the new error instance to it.

An error is matched if:

- It has the same error message OR

- It has the same top stack frame and 3 of the next 4 stack frames are the same (in any order)

A stack frame is matched if:

- It has the same filename, function name, line number, and column number OR

- It has the same source code and context (if sourcemaps are enabled)

If there is no match with an existing error, a new error group is created instead.

## Grouping Rules

If your errors are in JSON form, you can add JSONPath expressions in your [project settings](https://app.highlight.io/settings) to select parts of your errors that you want to group on. For example, if your errors look like:

```json
{
    "type": "StackOverflowError",
    "user": "alice",
    "message": "Oh no! You got an error on line 41!!"
}

{
    "type": "StackOverflowError",
    "user": "bob",
    "message": "Oh no! You got an error on line 50!!"
}
```

They would not be grouped together since the errors are not an exact match and since they were thrown at different lines in your code. In this case, if you wanted to group all errors of the same type into the same error group, you can add an expression `$.type` in your project settings.



[highlight.io](https://highlight.io) has first-party support for enhancing minified stacktraces in javacript. We also support options for sending sourcemaps to us in the case that your sourcemaps aren't public. Read more about it in our [getting started doc](../../../getting-started/3_client-sdk/7_replay-configuration/sourcemaps.md)



Below are several highlight.io features that might be worth taking a look at.

<DocsCardGroup>
    <DocsCard title="Alerts."  href="./alerts.md">
        {"Get alerts for sessions, errors, new users and more!"}
    </DocsCard>
    <DocsCard title="Comments."  href="./comments.md">
        {"Collaborate on bugs throughout your web app."}
    </DocsCard>
    <DocsCard title="Digests."  href="./digests.md">
        {"Get a weekly digest of sessions that are worth watching."}
    </DocsCard>
    <DocsCard title="Environments."  href="./environments.md">
        {"Version resources so that you know what environment events happened in."}
    </DocsCard>
    <DocsCard title="Segments."  href="./segments.md">
        {"Create search filters so searching for sessions & errors is easy!"}
    </DocsCard>
</DocsCardGroup>



Alerts are a way to keep your team in the loop as to what is happening on your app. Below is a description of the common components of Alerts, and more specific parameters are included in subsequent sections. To get started, visit [app.highlight.io/alerts)(https://app.highlight.io/alerts). The basic parameters for an alert look like the following image:

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/NqoXlpImTuC1Hc_41ekn5_5d8b382-alerts-basic.png)

## Connecting a Slack Channel

If you haven't already integrated Highlight with Slack, clicking the "Channels To Notify" dropdown will prompt you to select a channel. Once this is done, you can add any number of channels to be pinged when an alert is thrown.

## Excluding Environments

You may want to exclude certain environments from generating alerts. For example, in your team's dev environment, it's unlikely that you want to be notified of every error. You can do this by adding an excluded environment option.

Learn more about [Environments](../3_general-features/environments.md).



Comments can be made by you or anyone on your team on sessions and errors.

## Session Comments

Session comments can be made by clicking anywhere on the session replay. Session comments are special because they connect a comment to a position on the screen and the current time. This is extremely powerful because now when you create a comment, you don't have to write more to provide the location/time context.

### Notifications

If you tag your team when creating a comment (learn more [Slack Integration](../../7_integrations/slack-integration.md)), Highlight will send them a message via email or Slack. Those messages will contain your comment text and a screenshot of the session at the current time.

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/gsYvSrZkPZwf-M-P75jKp_brandbird-1.png)

## Collaboration

You can tag a teammate in a comment by typing `@` and then picking your teammate. When you tag a teammate, they will receive a notification with the message you wrote.

### Replies

Want to have a conversation relevant to what you're looking at? You can also reply to Session or Error comments on the side panel or directly via the popup.

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/W0rMORhS-yYiCNY__ZCRA_image.png)

When participating in a comment, you become subscribed to future replies. Subsequent replies will notify you via Slack (learn more [Slack Integration](../../7_integrations/slack-integration.md)) or email. Any Slack channel or user tagged is also automatically subscribed.

### Slack Integration

You can tag Slack users or channels in comments after connecting Highlight with Slack (learn more [Slack Integration](../../7_integrations/slack-integration.md)). When you tag a Slack user or channel, Highlight will send them a message with your comment and a link to where the comment was made.

### Linear Integration

You can create issues in Linear as you add comments. Within a comment, select "Create a Linear issue" from the issues dropdown. On the next page, you'll be prompted to optionally edit the issue title and description. Once you save the comment, an issue is created and linked to in Linear.



Highlight Digests are a weekly email summary of interesting sessions, errors, and user activity.

## Getting Started

You don't have to do anything to start receiving digests. If your project has 50+ sessions recorded in the past week, a digest will automatically be emailed to all workspace members. Digests are sent every Monday around 9am PST.

## Features

### User activity

This section shows aggregate user activity stats for last week and the change from the prior week. This includes total users (the count of unique users), total sessions, total errors, and average time spent (average active time per session).

![](https://static.highlight.io/assets/docs/user_activity.png)

### Active sessions

This section shows the top 5 sessions ordered by active time.

![](https://static.highlight.io/assets/docs/active_sessions.png)

### Erroneous sessions

This section shows the top 5 sessions ordered by error count.

![](https://static.highlight.io/assets/docs/error_sessions.png)

### New errors

This section shows the top 5 errors originating in the last week, ordered by the count of unique affected users.

![](https://static.highlight.io/assets/docs/new_errors.png)

### Frequent errors

This section shows the top 5 errors ordered by their frequency. Ignored errors are excluded.

![](https://static.highlight.io/assets/docs/frequent_errors.png)



Environments can be assigned to sessions and errors by setting the environment option in [H.init()](../../../sdk/client.md#Hinit). With the assignment, you can know search and filter sessions and errors based on the environment they come from.

Environments are also used to determine whether [Alerts](../3_general-features/alerts.md) are created.

## Example

```typescript
H.init('<YOUR_PROJECT_ID>', {
  environment: process.env.ENVIRONMENT,
})
```



Segments are a set of search filters that applies to sessions or errors. Segments are useful if you want to quickly view sessions or errors that relate to a certain population of your users.



Logging is currently in beta. If you'd like to try out our logging feature, hit us up in [our community](https://highlight.io/community) or send us an email at [jay@highlight.io](mailto:jay@highlight.io)!



Read more about highlight.io's integrations! Have a questions or want to request a new integration? Hit us up in our [community](https://highlight.io/community).

<DocsCardGroup>
    <DocsCard title="Amplitude."  href="./amplitude-integration.md">
        {"Instrument highlight.io to send amplitude events."}
    </DocsCard>
    <DocsCard title="Mixpanel."  href="./mixpanel-integration.md">
        {"Instrument highlight.io to send mixpanel events."}
    </DocsCard>
    <DocsCard title="Clickup."  href="./clickup-integration.md">
        {"Create clickup tickets within highlight.io"}
    </DocsCard>
    <DocsCard title="Front."   href="./front-integration.md">
        {"View highlight.io sessions directly in your front inbox."}
    </DocsCard>
    <DocsCard title="Linear."  href="./linear-integration.md">
        {"Create linear tickets within highlight.io"}
    </DocsCard>
    <DocsCard title="Segment."  href="./segment-integration.md">
        {"Instrument highlight.io to send segment events."}
    </DocsCard>
    <DocsCard title="Height."  href="./height-integration.md">
        {"Create height tickets within highlight.io"}
    </DocsCard>
    <DocsCard title="Intercom."  href="./intercom-integration.md">
        {"Access highlight.io sessions within your intercom dashboard."}
    </DocsCard>
    <DocsCard title="Slack."   href="./slack-integration.md">
        {"Send highlight.io alerts to slack."}
    </DocsCard>
    <DocsCard title="Vercel."  href="./vercel-integration.md">
        {"Automate uploading of sourcemaps and integration"}
    </DocsCard>
    <DocsCard title="Discord."  href="./discord-integration.md">
        {"Create discord tickets within highlight.io"}
    </DocsCard>
</DocsCardGroup>



We've made it easy to use Amplitude with Highlight. When you initialize Highlight, you can set your Amplitude API Key.

```typescript
H.init('<YOUR_PROJECT_ID>', {
  integrations: {
    amplitude: {
      apiKey: '<AMPLITUDE_API_KEY>',
    },
  },
})
```

## API

### `logEvent()`

Calling [`H.track()`](../../sdk/client.md#Hinit) will forward the data to Amplitude's [`logEvent()`](https://amplitude.github.io/Amplitude-JavaScript/#amplitudeclientlogevent).

```typescript
H.track('signup_button_clicked', {
  firstTime: true,
  impressions: 10,
})

// The Highlight track call is equivalent to this logEvent call
amplitudeClient.logEvent('signup_button_clicked', {
  firstTime: true,
  impressions: 10,
  // This property is added by Highlight. This shows you the session where this event happened.
  highlightSessionURL: 'https://app.highlight.io/sessions/123',
})
```

### `setUserId()` and `identify()`

Calling [`H.identify()`](../../sdk/client.md#Hinit) will forward the data to Amplitude's [`setUserId()`](https://amplitude.github.io/Amplitude-JavaScript/#amplitudeclientlogevent) and [`identify()`](https://amplitude.github.io/Amplitude-JavaScript/Identify/).

```typescript
H.identify('eliza@corp.com', {
  planType: 'premium',
  verified: false,
})

// The Highlight identify call is equivalent to setUserId and identify.
amplitudeClient.setUserId('eliza@corp.com')
amplitudeClient.identify(new amplitude.Identify().set('planType', 'premium').set('verified', false))
```

If you want to disable this behavior, you can set `enabled: false` for the integration:

```typescript
H.init('<YOUR_PROJECT_ID>', {
  integrations: {
    amplitude: {
      enabled: false,
    },
  },
})
```



When you enable the ClickUp integration, Highlight will allow creating Tasks from the session replay and errors viewer. Track bugs or enhancements for your app as you triage frontend and backend errors or watch your users' replays.

To get started, go to the [integrations](https://app.highlight.io/integrations) and click the "Connect" button in the ClickUp section.

## Features

1.  [Comments](../6_product-features/3_general-features/comments.md) can create a ClickUp task filled out with the body of the comment and link back to the Session.

2.  [Grouping Errors](../6_product-features/2_error-monitoring/grouping-errors.md) shows a shortcut to create a ClickUp task pre-populated with the error linking to the full context of how the error occurred.



By connecting Highlight with Discord, Highlight can send you and your team real-time messages based on different sessions, errors and more.

To get started, go to [app.highlight.io/integrations](https://app.highlight.io/alerts) and click the toggle to turn on the discord integration.

![](/images/discord-integration-toggle.png)

Once you do this, you will see an option to add discord channels on any of the alerts found at [https://app.highlight.io/alerts](https://app.highlight.io/alerts). It'll look like this:

![](/images/discord-alert-view.png)



If you are running Highlight in Electron, a Desktop based JS framework, you can benefit from the additional functionality that tracks main process window events to stop and start Highlight recording when your app is minimized.

Please ensure you are using Highlight SDK version [highlight.run@4.3.4.](https://www.npmjs.com/package/highlight.run/v/4.3.4) or higher. Call `configureElectronHighlight` with a `BrowserWindow` object to instrument Electron events.

```Text
const mainWindow = new BrowserWindow(...)
configureElectronHighlight(mainWindow)
```

Under the hood, the function will forward the `focus` and `blur` events to your renderer process so that the highlight recording SDK can track them.

```Text
mainWindow.on('focus', () => {
    mainWindow.webContents.send('highlight.run', { visible: true });
});
window.on('blur', () => {
    mainWindow.webContents.send('highlight.run', { visible: false });
 });
```

This will stop all highlight recording when the app is not visible and resume the session when the app regains visibility to help minimize performance and battery impact that Highlight may have on Electron users.



Do you use [Front.com](https://app.frontapp.com/) to communicate with your customers? Add the Highlight plugin and view Highlight sessions right from the conversation.

![See Highlight Sessions from Front](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/aZFnCEkEtEJpP1zA75J9r_front-highlight-v2.png)

Simply visit [https://app.frontapp.com/settings/tools](https://front.com/integrations/highlight) and add the Highlight plugin in one click.

Click the [Get Started](https://app.frontapp.com/settings/integrations/native/edit/highlight) button to add Highlight to your Front workspace.



When you enable the Height integration, Highlight will allow creating Tasks from the session replay and errors viewer. Track bugs or enhancements for your app as you triage frontend and backend errors or watch your users' replays.

To get started, go to the [integrations](https://app.highlight.io/integrations) and click the "Connect" button in the Height section.

## Features

1.  [Comments](../6_product-features/3_general-features/comments.md) can create a Height task filled out with the body of the comment and link back to the Session.

2.  [Grouping Errors](../6_product-features/2_error-monitoring/grouping-errors.md) shows a shortcut to create a Height task pre-populated with the error linking to the full context of how the error occurred.



Highlight makes it easy to send events to Intercom. If you have both Highlight and Intercom already configured, then you're all set. We've already set things up for you in the background.

If you want to disable this integration, you can set `enabled: false` for the integration in your client config:

```typescript
H.init('<YOUR_PROJECT_ID>', {
  integrations: {
    intercom: {
      enabled: false,
    },
  },
})
```

## Messaging

Whenever a user sends you a message on Intercom, Highlight will add a [custom user attribute](https://www.intercom.com/help/en/articles/179-send-custom-user-attributes-to-intercom) called `highlightSessionUrl` to the user. This is the URL for the latest session created by that user. This is helpful to see what the user was doing that led up to the user sending a message.

## API

### `trackEvent`

Calling [`H.track`](../../sdk/client.md#Hinit) will forward the data to Intercom's [`Intercom('trackEvent')`](https://developers.intercom.com/installing-intercom/docs/intercom-javascript#section-intercomtrackevent).

```typescript
H.track('signup_button_clicked', {
  firstTime: true,
  impressions: 10,
})

// The Highlight track call is equivalent to this Intercom call
Intercom('trackEvent', 'signup_button_clicked', {
  firstTime: true,
  impressions: 10,
})
```



When you enable the Linear integration, Highlight will allow creating Issues from the session replay and errors viewer. Track bugs or enhancements for your app as you triage frontend and backend errors or watch your users' replays.

To get started, go to the [integrations](https://app.highlight.io/integrations) and click the "Connect" button in the Linear section.

## Features

1.  [Comments](../6_product-features/3_general-features/comments.md) can create a Linear issue filled out with the body of the comment and link back to the Session.

2.  [Grouping Errors](../6_product-features/2_error-monitoring/grouping-errors.md) shows a shortcut to create a Linear task pre-populated with the error linking to the full context of how the error occurred.



We've made it easy to use Mixpanel with Highlight. If you don't already have Mixpanel initialized in your app, you can have Highlight initialize it for you by specifying your Mixpanel Project Token in the config.

```typescript
H.init('<YOUR_PROJECT_ID>', {
  integrations: {
    mixpanel: {
      projectToken: '<MIXPANEL_PROJECT_TOKEN>',
    },
  },
})
```

Whenever you call [`H.track()`](../../sdk/client.md#Htrack) or [`H.identify()`](../../sdk/client.md#Hinit) it will forward that data to Mixpanel's `track` and `identify` calls. If you want to disable this behavior, you can set `enabled: false` for the integration:

```typescript
H.init('<YOUR_PROJECT_ID>', {
  integrations: {
    mixpanel: {
      enabled: false,
    },
  },
})
```

## API

### `track()`

Calling [`H.track()`](../../sdk/client.md#Htrack) will forward the data to Mixpanel's `track()`. Highlight will also add a Mixpanel property called `highlightSessionURL` which contains the URL to the Highlight session where the track event happened.

### `identify()`

Calling [`H.identify()`](../../sdk/client.md#Hidentify) will forward the data to Mixpanel's `identify()`.



> If you have an existing codebase calling
>
> [Segment's](https://segment.com/docs/connections/spec/)
>
> `identify()`
>
> and
>
> `track()`
>
> methods, then you won't have to call Highlight's. Highlight will automatically forward data sent to Segment to your Highlight sessions.

```hint
We are currently working with Segment on an official integration where you can enable, configure, and send data to Highlight. If you'd like to use this, then [upvote this feature request](https://highlight.canny.io/feature-requests/p/official-segment-integration).
```

## Enabling the Segment Integration

```javascript
H.init('<YOUR_PROJECT_ID>', {
  enableSegmentIntegration: true,
})
```

Segment's `identify()` calls will now start forwarding to Highlight.

## Enabling Track data forwarding

To forward `analytics.track()` calls to Highlight, you will need to use the `HighlightSegmentMiddleware`. This is available in the `highlight.run` package starting in version `2.10.0`.

```javascript
import { H, HighlightSegmentMiddleware } from 'highlight.run'

H.init('<YOUR_PROJECT_ID>', {
  enableSegmentIntegration: true,
})
analytics.addSourceMiddleware(HighlightSegmentMiddleware)
```



By connecting Highlight with Slack, Highlight can send you and your team real-time messages based on different events that happen on your app and Highlight.

To get started, go to [https://app.highlight.io/alerts](https://app.highlight.io/alerts) and click the "Sync with Slack" button.

## Features

1.  [Comments](../6_product-features/3_general-features/comments.md) will send a Slack message to whoever is tagged in a comment

2.  [Alerts](../6_product-features/3_general-features/comments.md) will send a Slack message to channels or users who want to receive alerts



If you use Vercel to deploy your app, you can install the Vercel Highlight integration here: [https://vercel.com/integrations/highlight/](https://vercel.com/integrations/highlight/)

After linking your Vercel projects to your Highlight projects, Highlight will automatically set the `HIGHLIGHT_SOURCEMAP_API_KEY` environment variable. If you're using `@higlight-run/sourcemap-uploader` or `withHighlightConfig` to upload your sourcemaps, those tools will check for this API key.



Stay up to date with what we work on week over week:

<DocsCardGroup>
    <DocsCard title="Changelog 13" href="./changelog-13.md">
    {"HackerNews Launch, SDK Docs, DocSearch, etc.."}
    </DocsCard>
    <DocsCard title="Changelog 12" href="./changelog-12.md">
    {"Open Source, Smoother UX, & New SDKs!"}
    </DocsCard>
</DocsCardGroup>



## Open Source!

highlight.io is open source at [https://github.com/highlight/highlight](https://github.com/highlight/highlight) (would appreciate a star ⭐️). We've also got lots of updates to share on this front as we grow, so stay tuned!

## Changing the status of an error is now instant!

We're now using `optimisticResponses` in apollo to update the state of an error. When you change the status, this now happens instantly in the UI 🤯.

[PR Link](https://github.com/highlight/highlight/pull/4246)

## Smoother frontend routing logic.

We upgraded react router this week, which has made some significant performance improvements to the app; switching between errors/sessions is now silky smooth.

[PR Link](https://github.com/highlight/highlight/pull/4203)

## New SDKs!!

We now support several more Python SDKs: Flask, Django, Python Azure Functions.

[Python Docs](https://www.highlight.io/docs/general/getting-started/backend-sdk/python)

[Cloudflare Docs](https://www.highlight.io/docs/general/getting-started/backend-sdk/cloudflare)



## The new CommandBar!

Type out "Cmd + K" in your [dashboard](https://app.highlight.io) to search for fields on sessions, errors and more. Here's a sneak peak:

![](/images/cmd-k.png)

## We launched on HackerNews

We launched on hackernews a few days ago, and gained surpassed 1.5k github stars!!! Check out our [launch](https://news.ycombinator.com/item?id=34897645) and if you haven't already, check us out on [github](https://github.com/highlight/highlight).

## Contributing a new SDK:

Interested in adding a new SDK for your for your backend (that isn't support [here](../../getting-started/1_overview.md))? Check out our new docs on [adding an SDK](../3_company/open-source/contributing/adding-an-sdk.md). We're powered by opentelemetry, so adding something for your framework shouldn't be too tough; we're also down to work with you on it!

## Better Doc Search

Thanks to our friends at Algolia, search in our docs is much smoother now! Give it a try with CMD+K.

## New SDKs!!

We've shipped even more SDKS this week:

[Go Fiber](../../getting-started/4_backend-sdk/go.md)

[Python Fast API](../../getting-started/4_backend-sdk/python.md)

## Our new logging product (🤫)

We're making a lot of progress on our new logging product; want to join the beta? Shoot us a message in [discord](https://highlight.io/community)

## Improvements

Self-hosting improvements ([docs](../3_company/open-source/self-host-hobby.md))
Lots of work on logging!



## Our New Signup Flow!

We just shipped a new signup flow on [app.highlight.io](https://app.highlight.io). Feel free to give a try :)

![](/images/signup.png)

## Fixes to Replay Jitters

This week, we made quite a lot of improvements to jitter/jank on the replay timeline. Notably, there was a bug related to inactive periods as well as the timeline UI resetting multiple times.

[PR Link](https://github.com/highlight/highlight/pull/4422)

## New Python Guide Homepage

Our python guides now have a new home; check them out [here](../../getting-started/4_backend-sdk/python/1_overview.md).

## More Logging Updates (🤫)

We're making a lot of progress on our new logging product; want to join the beta? Shoot us a message in [discord](https://highlight.io/community).



Highlight's Full-stack integration allows you to get visibility into errors and issues across your whole stack, not just your frontend. These errors are paired with outgoing requests on your frontend so that you can understand:

- Exactly what happened when a user reports a bug

- Where specific errors are initiated and what caused them

- What backend issues could have caused corresponding frontend bugs.

## For your Frontend

Installing highlight.io in javascript will automatically instrument frontend error collection and session replay. highlight.io supports any framework that uses the [dom](https://www.w3schools.com/js/js_htmldom.asp) under the hood, and we support all modern browsers to date. Take a look at our guides for the following frameworks:

<DocsCardGroup>
    <DocsCard title="React" href="./client-sdk/reactjs.md">
        {"Get started in your React.js app"}
    </DocsCard>
    <DocsCard title="Angular"  href="./client-sdk/angular.md">
        {"Get started in your Angular.js app"}
    </DocsCard>
    <DocsCard title="Gatsby"  href="./client-sdk/gatsbyjs.md">
        {"Get started in your Gatsby app"}
    </DocsCard>
    <DocsCard title="NextJS"  href="./client-sdk/nextjs.md">
        {"Get started in your NextJS app"}
    </DocsCard>
    <DocsCard title="VueJS"  href="./client-sdk/vuejs.md">
        {"Get started in your VueJS app"}
    </DocsCard>
    <DocsCard title="Other HTML"  href="./3_client-sdk/6_other.md">
        {"Get started in any HTML/JS app"}
    </DocsCard>
</DocsCardGroup>

## For your Backend

Highlight also supports reporting errors from your backend and mapping these to corresponding sessions. This gives you and your team a full picture of your application's state. Support frameworks / tech below:

<DocsCardGroup>
    <DocsCard title="Python" href="./backend-sdk/python/overview">
        {"Get started in Python"}
    </DocsCard>
    <DocsCard title="Go" href="./backend-sdk/go/overview">
        {"Get started in Golang"}
    </DocsCard>
    <DocsCard title="JS / TS" href="./backend-sdk/js/overview">
        {"Get started in Javascript"}
    </DocsCard>
</DocsCardGroup>

### Something missing?

We've written up several guides on getting started with highlight.io in your framework of choice. If there's a guide missing for your framework, feel free to [create an issue](https://github.com/highlight/highlight/issues/new?assignees=&labels=external+bug+%2F+request&template=feature_request.md&title=) or message us on [discord](https://highlight.io/community).



## What's this?

In order to make the most out of highlight.io, we suggest instrumenting your frontend & backend so that you can attribute frontend requests with backend errors. See an example below, where you can view an error's details alongside session replay, allowing you to see the full context around it.

![](/images/fullstack-mapping.png)

Below, we detail the requirements to get this working as well how to troubleshoot.

## How can I start using this?

### Turn on `tracingOrigins`

Set the `tracingOrigins` option to an array of patterns matching the location of your backend. You may also simply specify `true`, which will default `tracingOrigins` to all subdomains/domains of the url for your frontend app.

```javascript
H.init("<YOUR_PROJECT_ID>", {
	tracingOrigins: ['localhost', 'example.myapp.com/backend'],
    ...
});
```

### Turn on `networkRecording`

```javascript
H.init("<YOUR_PROJECT_ID>", {
	networkRecording: {
		enabled: true,
		recordHeadersAndBody: true,
	},
	...
});
```

## Backend Changes

Backend changes are dependent on the underlying language/framework used on the server-side codebase. All you need to add is a middleware and code to capture errors.

Below are solutions for what we support today. If you'd like us to support a new framework, feel free to shoot us a message at [support@highlight.io](mailto:support@highlight.io) or drop us a note in our [discord](https://discord.gg/yxaXEAqgwN).

- [Go Backend Integration](4_backend-sdk/go)

- [JS Backend Integration](4_backend-sdk/js)

- [Python Backend Integration](4_backend-sdk/python)

## Troubleshooting

1.  Ensure `tracingOrigins` and `networkRecording` are properly set.

2.  Ensure your backend has `CORS` configured for your frontend hostname, explicitely allowing header `x-highlight-request`.

3.  For debugging the backend sdk of your choice, in order to debug, we suggest enabling verbose logging. For example, in go, add `highlight.SetDebugMode(myLogger)`

4.  If all else fails, please send us an email at support@highlight.io or join the #support channel on our [discord](https://discord.gg/yxaXEAqgwN).



The [highlight.io](https://highlight.io) Javascript SDK does a lot of things. Here's some docs on how to configure it to do what you want.

<DocsCardGroup>
    <DocsCard title="Canvas Recording." href="./canvas.md">
        {"How to enable/disable canvas recording in our client SDK."}
    </DocsCard>
    <DocsCard title="Console Messages."  href="./console-messages.md">
        {"How to enable/disable console message recording in our client SDK."}
    </DocsCard>
    <DocsCard title="Content Security Policy."  href="./content-security-policy.md">
        {"Configuring your CSP to play well with highlight.io."}
    </DocsCard>
    <DocsCard title="Identifying Users."  href="./identifying-sessions.md">
        {"Identifying visitors on your web application."}
    </DocsCard>
    <DocsCard title="Iframe Support."  href="./iframes.md">
        {"How to record a highlight.io session within an iframe."}
    </DocsCard>
    <DocsCard title="Monkey Patches."  href="./monkey-patches.md">
        {"Information about the js methods that highlight.io monkey patches."}
    </DocsCard>
    <DocsCard title="Privacy & Redaction."  href="./privacy.md">
        {"How to redact and strip out sensitive data in a highlight.io session."}
    </DocsCard>
    <DocsCard title="Proxying requests."  href="./proxying-highlight.md">
        {"How to proxy requests through your backend for security purposes."}
    </DocsCard>
    <DocsCard title="React Error Boundary"  href="">
        {"How to proxy requests through your backend for security purposes."}
    </DocsCard>
</DocsCardGroup>



- Pins highlight.run dynamic client version to the highlight.run package version.

# Upgrading from 4.x or older

- We've migrated our lazy-loaded bundled to be served from static.highlight.io instead of static.highlight.run. As a result, if you use custom, change references form static.highlight.run to static.highlight.io.
- There are no breaking API / package behavior changes with this release.



- Ensures that a tab reload that resumes a previous old session (older than 4 hours) starts a new session rather than adding a set of data for the previous one.



- Improves canvas recording efficiency.
- Improves accuracy of recorded iframes.
- Improves recording of scrolling with custom CSS.
- Improves recording of Shadow DOM elements.
- Smoothens replay mouse animation.



- Ensures H.stop() stops recording and that visibility events do not restart recording.
- Simplify CSP requirements by proxying web-vitals script.



- Fix an issue that prevented recording from starting.



- Separate the client web worker to make content security policy more strict.



- Fix an issue with tab visibility switches breaking some recordings.



- Fix typescript definitions in published `highlight.run` npm package.



- Remove randomized URL param from Highlight client script to allow browser caching by client version



- Ensure `<video>` and `<audio>` elements are obfuscated correctly in strict privacy mode or with `highlight-mask` / `highlight-block`.
- Fix a condition where `enableStrictPrivacy` with `highlight-mask` on a `<div>` would cause child elements to not be recorded.



- Resolves an issue with recording events that have listeners calling preventDefault().



- Adds support for cross-origin iframe recording.



- Adds a list of non-retryable errors to prevent the client from unnecessary retries



- Fixes issues in Shadow DOM recording that would omit sections of the DOM.



- Fixes Highlight integration with [Segment V2 (aka @segment/analytics-next)](https://www.npmjs.com/package/@segment/analytics-next).
- Changes iframe recording behavior for cross-origin iframes to ensure `src` is dropped as the `src` cannot be replayed.



## Canvas Recording

Highlight by default does not record the contents of `<canvas>` elements. This is usually why the session replay has blank areas where those areas should be `<canvas>` elements. We provide experimental recording of `<canvas>` contents.

Enable canvas recording by configuring [H.init()](../../../sdk/client.md#Hinit) in the following way:

```javascript
H.init('YOUR_PROJECT_ID', {
  enableCanvasRecording: true,
  samplingStrategy: {
    canvas: 15,
    canvasQuality: 'low',
    canvasMaxSnapshotDimension: 480,
  },
})
```

`samplingStrategy.canvas` is the frame per second rate used to record the HTML canvas. We recommend a value < 5 to ensure recording performance is not impacted at high resolutions.

`samplingStrategy.canvasQuality`: 'pixelated' | 'low' | 'medium' | 'high'. This value represents the image compression quality and will affect the size of the canvas images uploaded.

`samplingStrategy.canvasMaxSnapshotDimension`: max recording resolution of the largest dimension of the canvas.

Snapshotting at full resolution and high FPS can produce too much data for our client to upload on devices with low upload bandwidth. We've found that with a safe assumption of upload speed @, 1 MB/s I can support the above snapshotting settings without a problem at 480p 15 fps.

Even though this feature is experimental, it should not have any impact on your application. We've recently changed our uploading client to use browser web-workers to ensure that data serialization cannot block the rendering of your application. If you run into any issues please let us know!

## WebGL Recording

In the same vain, Highlight is able to record websites that use WebGL. Recording WebGL is disabled by default. To enable WebGL recording, enable canvas recording by following the instructions for [Canvas](./canvas.md) recording.

## Caveats

For both WebGL and canvas recording, [Privacy](../../../general/6_product-features/1_session-replay/privacy.md) controls do not apply to canvas recording right now.



Highlight out of the box shows you the console messages that were logged during a session.

```hint
Console messages are not recorded on `localhost` because Highlight emits debug messages which we prefer not to flood your environment with.
```

## Configuration

- Disabling console recording can be configured with `disableConsoleRecording`.

- You can specify which console methods to record with `consoleMethodsToRecord`.

See [H.init()](../../../sdk/client.md#Hinit) for more information.



```hint
You should keep reading this if your application runs in an environment that enforces content security policies.
```

`Content-Security-Policy` allows you to tell the browser what and how your page can interact with third-party scripts.

Here are the policies you'll need to set to use Highlight:

1.  `script-src`: `https://static.highlight.io`
    1.  This policy is to allow downloading the Highlight runtime code for session recording and error monitoring.
2.  `worker-src`: `blob: https://static.highlight.io`
    1. This policy allows our script to create a web-worker which we use to serialize the recording data without affecting the performance of your application.
3.  `connect-src`: `https://pub.highlight.run`
    1.  This policy is to allow connecting with Highlight servers to send recorded session data.

Your [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) definition may look something like this:

```html
<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; script-src 'self' https://static.highlight.io; worker-src: blob: https://static.highlight.io; connect-src https://pub.highlight.run;"
/>
```



To tag sessions with user-specific identifiers (name, email, etc.), you can call the [`H.identify()`](../../../sdk/client.md#Hinit)method in your app. This will automatically index your sessions so that they can be filtered by these attributes.

```typescript
H.identify('eliza@corp.com', { id: 'ajdf837dj', phone: '867-5309' })
```

## User Display Names

By default, Highlight will show the `identifier` as the user's display name on the session viewer and session feed. You can override this by setting the `highlightDisplayName` or `email` fields in the [`H.identify()`](../../../sdk/client.md#Hidentify) metadata.

## Customer User Avatars

You can replace the placeholder user avatars Highlight uses with an image that you provide. You can do this by setting the `avatar` field in the [`H.identify()`](../../../sdk/client.md#Hidentify) metadata.

The image URL usually comes from your authentication provider (Firebase, Auth0, Active Directory, etc.). You can forward that URL to Highlight.

```hint
## Saving the image

Highlight does not make a copy of the image. Highlight will render the image directly. This means the image will adhere to any authorization policies.
```

```typescript
H.identify('steven@corp.com', { avatar: 'https://<IMAGE_URL>.png' })
```

## API

See the [H.identify()](../../../sdk/client.md#Hidentify) API documentation for more information on how to use it.

## What happens before a user is identified?

All key session information is tracked regardless of whether a session is identified. Highlight will generate an identifier for a user which you can see in the session player unless you set your own by calling [H.identify()](../../../sdk/client.md#Hidentify).

When a user is identified we will attempt to **assign their information to previous sessions** from the same browser. If this happens you will see an indicator in the UI showing the data was inferred for a session and that the session was never explicitly identified.



## Recording within `iframe` elements

- Highlight will recreate an `iframe` with the same src. The `iframe` will not load if the src's origin has a restrictive X-Frame-Options header.

- Highlight only supports recording same-origin iframes because of browsers' same-origin policy. If it's possible to init Highlight within the
  `iframe `, you can record the events within as a separate session in your same project.

- If your
  `iframe ` source becomes invalid after some time or will not render content when inserted in a different domain or website, the recording will not show the correct content that the user saw.

![rendering in a session replay](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/UP4LVunHyPBCzRukQwoh4_image.png)

## Recording a cross-origin `iframe` element

[Cross-origin iframes](https://learn.microsoft.com/en-us/skype-sdk/ucwa/cross_domainiframe) are `<iframe>` elements in your app that reference a domain considered to be of a [different origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy). When your iframe uses a `src` tag pointing to a different origin, the iframe is not accessible from the parent page. However, the iframe can still emit messages that the parent page can hear.

To support cross-origin iframes, we added functionality into our recording client that allows the iframe to forward its events to the parent session. All you need to do is add the Highlight snippet to both the parent window and the iframe.

Ensure you are using [highlight.run](https://www.npmjs.com/package/highlight.run) 5.2.0 or newer. Then, add the following option to the `H.init` call **inside of your iframe**.

```typescript
import { H } from 'highlight.run'

H.init('<YOUR_PROJECT_ID>', {
  isCrossOriginIframe: true,
})
```

Ensure that you add the `H.init` call to both the parent page and the iframe page, but that you only set `isCrossOriginIframe` **in the H.init call of your iframe**. Otherwise your sessions will not be recorded.



All the data that Highlight collects is provded by running the Highlight snippet on your app. When the Highlight snippet runs, it monkey patches browser APIs in order to record things like:

- Errors

- Console messages

- Network requests

- Changes on the page

Here is a list of all the browser APIs that Highlight monkey patches

- `window.sessionStorage.setItem`

- `window.sessionStorage.getItem`

- `window.sessionStorage.removeItem`

- `window.onerror`

- `window.fetch`

- `window.FontFace`

- `window.scroll`

- `window.scrollTo`

- `window.scrollBy`

- `window.scrollIntoView`

- `window.WebGLRenderingContext`

- `window.WebGL2RenderingContext`

- `window.CanvasRenderingContext2D`

- `window.HTMLCanvasElement`

- `window.CSSStyleSheet.prototype.insertRule`

- `window.CSSStyleSheet.prototype.deleteRule`

- `window.CSSGroupingRule`

- `window.CSSMediaRule`

- `window.CSSConditionRule`

- `window.CSSSuportsRule`

- `window.CSSStyleDeclaration.prototype.setProperty`

- `window.CSSStyleDeclaration.prototype.removeProperty`

- `history.pushState`

- `history.replaceState`

- `XMLHttpRequest.prototype.open`

- `XMLHttpRequest.prototype.setRequestHeader`

- `XMLHttpRequest.prototype.send`

- `console.assert`

- `console.clear`

- `console.count`

- `console.countReset`

- `console.debug`

- `console.dir`

- `console.dirxml`

- `console.error`

- `console.group`

- `console.groupCollapsed`

- `console.groupEnd`

- `console.info`

- `console.log`

- `console.table`

- `console.time`

- `console.timeEnd`

- `console.timeLog`

- `console.trace`

- `console.warn`



## Masking Elements

One way to sanitize your recordings is by adding the `highlight-block` CSS class to elements that should be ignored.

```html
<div class="highlight-block">Super secret sauce</div>
```

The Highlight snippet will in-turn measure the dimensions of the ignored element, and when the recording is being replayed, an empty placeholder will replace the content.

![Elements with the highlight-block class will show up as redacted in your recordings](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/s3OAcyrUrqMsWXwDqT9Zj_aff29bb-kapture2021-03-25at140125.gif)

## Obfuscating Elements

Alternatively, you can obfuscate specific HTML elements by adding the `highlight-mask` CSS class. The effect is the same of setting `enableStrictPrivacy` (the randomized text in the photo above) but applies to the specific HTML element that you mask.

```html
<div class="highlight-mask">This is some sensitive data <button>Important Button</button></div>
```

## Ignoring Input

```hint
The following CSS class only works for `<input>` elements. If you are interested in blocking the capture of other HTML elements, see the `highlight-block` class
```

For sensitive input fields that your team would like to ignore user input for, you can add a CSS class `highlight-ignore` that will preserve the styling of the input element, but ignore all user input.

```html
<input class="highlight-ignore" name="social security number" />
```

## Strict Privacy Mode

If you don't want to manually annotate what elements to not record then you can set `enableStrictPrivacy` to `true` when calling [`H.init()`](../../../sdk/client.md#Hinit). Strict Privacy Mode will obfuscate all text and images. The text obfuscation is not reversible and is done on the client.

Here are some examples:

- `<h1>Hello World</h1>` will be recorded as `<h1>1f0eqo jw02d</h1>`

- `<img src="https://my-secrets.com/secret.png" />` will be recorded as `<img src="" />`

```html
<iframe
  height="500px"
  href="https://xenodochial-benz-c14354.netlify.app/"
  width="100%"
  border="none"
  src="https://xenodochial-benz-c14354.netlify.app/"
  style="border:none"
  ><a href="https://xenodochial-benz-c14354.netlify.app/" target="" title="xenodochial-benz-c14354.netlify.app"
    >null</a
  ></iframe
>
```



```hint
Proxying is only available starting on our [Startup tier](https://www.highlight.run/pricing). If you would like use this, you will need to reach out to <support@highlight.run>.


```

If you're not seeing sessions or errors on Highlight, chances are that requests to Highlight are being blocked. This can happen for different reasons such as a third-party browser extensions, browser configuration, or VPN settings.

One way we can avoid this is by setting up proxy from your domain to Highlight. To do this, you will need access to your domain's DNS settings.

## Setting up the proxy

1.  Upgrade to the Startup Tier [https://www.highlight.run/pricing](https://www.highlight.run/pricing)

2.  On your domain, add a `CNAME` record that points `highlight.<YOUR_DOMAIN>` to `pub.highlight.run`

3.  Send us an email (support\@highlight.run) or intercom ticket with your domain

Below is an example email/message that you can send over.

> Hello!
>
> I'd like to use the Highlight Proxy and I've upgraded to the Startup Tier. I've set up an CNAME record for: highlight.piedpiper.com

### Example

You have an app running on `https://piedpiper.com`. Your DNS record will point `highlight.piedpiper.com` to our backend.

## Using the Proxy

In your app where you call [H.init()](../../../sdk/client.md#Hinit), you will need to set `backendUrl` to the DNS record you just created. For the example above:

```javascript
H.init('<YOUR_PROJECT_ID>', {
  backendUrl: 'https://highlight.piedpiper.com',
})
```

You should now see Highlight making requests to `https://highlight.piedpiper.com` instead of `https://pub.highlight.run`.



Highlight ships [`@highlight-run/react`](https://github.com/highlight/react) which can be installed alongside `highlight.run` for additional functionality for React applications.

# Error Boundary

Highlight provides an `ErrorBoundary` to help you provide a better experience for your users when your application crashes. Using an `ErrorBoundary` gives your application an opportunity to recover from a bad state.

```typescript
import { ErrorBoundary } from '@highlight-run/react'

const App = () => (
  <ErrorBoundary showDialog>
    <YourAwesomeApplication />
  </ErrorBoundary>
)
```

## Examples

### Showing the feedback modal when a crash happens

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/2VUVTR1ot591xUfJZSc3m_2022-01-1213-17.png)

```typescript
import { ErrorBoundary } from '@highlight-run/react'

const App = () => (
  <ErrorBoundary showDialog>
    <YourAwesomeApplication />
  </ErrorBoundary>
)
```

### Showing a custom feedback modal when a crash happens

You should use this if you would like to replace the feedback modal with your own styles/branding.

```typescript
import { ErrorBoundary } from '@highlight-run/react'

const App = () => (
  <ErrorBoundary
    showDialog
    customDialog={
      <div>
        <h2>Whoops! Looks like a crash happened.</h2>
        <p>Don't worry, our team is tracking this down!</p>

        <form>
          <label>
            Feedback
            <input type="text" />
          </label>

          <button type="submit">Send Feedback</button>
        </form>
      </div>
    }
  >
    <YourAwesomeApplication />
  </ErrorBoundary>
)
```

## ErrorBoundary API

### `fallback`

A fallback component that gets rendered when the error boundary encounters an error.

## `showDialog`

Enables Highlight's crash report. When the `ErrorBoundary` is triggered, a form will be prompted to the user asking them for optional feedback.

### `dialogOptions`

The strings used for the Highlight crash report.

`user`

Allows you to attach additional user information to the feedback report. If you've called [`H.identify()`](../../../sdk/client.md) in your application before, you won't have to set this, Highlight will infer the user's identity.

`title`

The title for the report dialog.

`subtitle`

The subtitle for the report dialog.

`subtitle2`

The secondary subtitle for the report dialog.

`labelName`

The label for the name field.

`labelEmail`

The label for the email field.

`labelComments`

The label for the verbatim field.

`labelClose`

The label for the close button.

`labelSubmit`

The label for the submit button.

`successMessage`

The label for the success message shown after the crash report is submitted.

`hideHighlightBranding`

Whether to show the Highlight branding attribution in the report dialog.

Default value is `false`.



Highlight out of the box shows you all the network requests durations, response codes, and sizes for a session. If you'd like more data such as the headers and bodies, you can enable recording of network requests and responses by setting `networkRecording.recordHeadersAndBody` (see [NetworkRecordingOptions](../../../sdk/client.md#Hinit)) to `true` when initializing Highlight.

Highlight monkey patches `XmlHttpRequest` and `fetch` to record data from your app's requests/responses including status codes, headers, and bodies.

## Privacy

Out of the box, Highlight will not record known headers that contain secrets. Those headers are:
\- `Authorization`
\- `Cookie`
\- `Proxy-Authorization`

If you have other headers that you would like to redact then you can set `networkRecording.networkHeadersToRedact`.

## Recording Headers and Bodies

Highlight can also record the request/response headers and bodies. You'll be able to see the headers and bodies by clicking on any XHR or Fetch requests in the session Developer Tools.

```typescript
H.init('<YOUR_PROJECT_ID>', {
  networkRecording: {
    enabled: true,
    recordHeadersAndBody: true,
  },
})
```

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/HMhiHwF_jifyGh-RXMJHk_network-recording.gif)

## Redacting URLs

You may have APIs that you know will always return secrets in the headers, body, or both. In this case, you can choose URLs to redact from. If a URL matches one of the URLs you specify, the header and body will not be recorded.

```typescript
H.init('<YOUR_PROJECT_ID>', {
  networkRecording: true,
  urlBlocklist: [
    'https://salted-passwords.com',
    'https://www.googleapis.com/identitytoolkit',
    'https://securetoken.googleapis.com',
  ],
})
```

Out of the box, Highlight will not record these URLs:
\- `https://www.googleapis.com/identitytoolkit`
\- `https://securetoken.googleapis.com`

## Redacting Headers and Bodies

If you are dealing with sensitive data or want to go the allowlist approach then you can configure `networkRecording.headerKeysToRecord` and `networkRecording.bodyKeysToRecord`. Using these 2 configs, you'll be able to explicitly define which header/body keys to record.

This configuration is only available for `highlight.run` versions newer than `4.1.0`.

## API

See [NetworkRecordingOptions](../../../sdk/client.md) for more information on how to configure network recording.



```hint
## Should I continue reading?

If you publicly deploy sourcemaps with your application then you do not need this guide. This guide is for applications that don't ship sourcemaps with their application.
```

When debugging an error in highlight.io, it might be useful to get a stack trace from the original file in your codebase (rather than a minified file) to help understand what is going wrong. In order to do this, highlight.io needs access to the sourcemaps from your codebase. Sourcemaps can be sent to highlight.io in your CI/CD process.

## Sending Sourcemaps to highlight.io

The highlight.io [sourcemap-uploader](https://www.npmjs.com/package/@highlight-run/sourcemap-uploader) can be used during your CI/CD process. Here's an example of using it:

```shell
#!/bin/sh

# Build the app
yarn build

# Upload sourcemaps to highlight.io
# Add --appVersion "..." if you provide a version value in your H.init call.
npx --yes @highlight-run/sourcemap-uploader upload --apiKey ${YOUR_ORG_API_KEY} --path ./build

# Delete sourcemaps to prevent them from being deployed
find build -name '*.js.map' -type f -delete

# Deploy the app
./custom-deploy-script
```

## `Sourcemap-uploader Arguments`

### `apiKey`

The API key for your project. You can find this in the [project settings](https://app.highlight.io/settings/errors#sourcemaps).

## `path`

The path that highlight.io will use to send `.map` files. The default value is `./build`.

## `appVersion`

The version of your current deployment. Please provide the same version value as the value you provide for `version` in [H.init()](../../../sdk/client.md#Hinit). This ensures that we're always using the same set of sourcemaps for your current bundle. If omitted, sourcemaps are uploaded as `unversioned` (make sure [H.init()](../../../sdk/client.md#Hinit) does not have a `version` option provided).

## Generating Sourcemaps

To use the highlight.io [sourcemap-uploader](https://www.npmjs.com/package/@highlight-run/sourcemap-uploader) , you need to be generating [sourcemaps](https://developer.chrome.com/blog/sourcemaps/) for your project. Exactly how to do this depends on your target environment and javascript configuration. Bundlers like [babel](https://babeljs.io/docs/en/options#source-map-options), [webpack](https://webpack.js.org/configuration/devtool/), [esbuild](https://esbuild.github.io/api/#sourcemap), or [rollup](https://rollupjs.org/guide/en/#outputoptions-object) all provide different ways to enable sourcemap generation. Refer to documentation for your specific bundler to generate production-ready sourcemaps or reach out if you need more help!

### Electron App Sourcemaps

Although your electron app configuration may vary, many will chose to use webpack to generate sourcemaps. Refer to the [general webpack sourcemap documentation](https://webpack.js.org/configuration/devtool/) as well as [this useful reference](https://docs.sentry.io/platforms/javascript/guides/electron/sourcemaps/generating/) to configure your build.



A track event is a named event that you've defined. Adding a track event is useful if you want to be able to be alerted (see [Recording Network Requests and Responses](../../../general/6_product-features/3_general-features/alerts.md)) or search for sessions where the user has done an action.

## Example Scenario: A Shopping Cart

You'd like to see what users are doing that cause them to open the shopping cart. In your app, you'll add `H.track()`:

```none
import { H } from 'highlight.run';
import { getSubtotal } from '@utils';

const ShoppingCard = ({ items }) => (
    <Button
        onClick={() => {
            H.track("Shopping Cart Opened", {
                subtotal: getSubtotal(items),
                numberOfItems: items.length
            });
        }}
    >
        Shopping Cart
    </Button>
)
```

## API

See the [Recording Network Requests and Responses](../../../sdk/client.md#Htrack) API documentation for more information on how to use it.



## Why do some parts of the session appear blank?

• For images, videos, and other external assets, Highlight does not make a copy at record time. At replay time, we make a request for the asset. If a request fails, the most common reason is because of authorization failure, the asset no longer existing, or the host server has a restrictive CORS policy

• For iFrames, Highlight will recreate an iframe with the same `src`. The iFrame will not load if the `src`'s origin has a restrictive `X-Frame-Options` header.

• For canvas/WebGL, see [WebGL](./canvas.md) to enable recording

## Why are the correct fonts not being used?

• During a replay, Highlight will make a request for the font file on your server. In the case where the request fails, Highlight will use your fallback font. The most common reason for failing is because your have a restrictive CORS policy for `Access-Control-Origin`. To allow Highlight to access the font files, you'll need to add `app.highlight.io`.



Highlight is shipping improvements multiple times a day. Non-breaking changes will automatically be applied to your applications without any action needed by you.

If Highlight ships a breaking change (new feature, security fix, etc.), we'll need your help to upgrade Highlight in your application. We aim to give 2 weeks notice in the event this happens. We recognize that there will be clients still using older versions of Highlight so we make sure all of our changes are backwards compatible.

## Using a Package Manager

```shell
# with npm
npm install highlight.run@latest

# with yarn
yarn upgrade highlight.run@latest
```

## HTML/CDN

Replace the Highlight snippet in your `index.html` with the one on [https://app.highlight.io/setup](https://app.highlight.io/setup).

## Changelog

To see if a new version has any breaking changes, see [Changelog](https://highlight.canny.io/changelog).


# with yarn
yarn add highlight.run

# with pnpm
pnpm add highlight.run

# with npm 
npm install highlight.run

Install the npm package `highlight.run` in your terminal.

Install the npm package & SDK.

// app.module.ts
    import { NgModule } from '@angular/core';
...

import { H } from 'highlight.run';

H.init('<YOUR_PROJECT_ID>', {
    environment: 'production',
    appVersion: 'commit:abcdefg12345',
	networkRecording: {
		enabled: true,
		recordHeadersAndBody: true,
        urlBlocklist: [
            // insert urls you don't want to record here
        ],
	},
});

@NgModule({
    ...
})
export class AppModule { }


Grab your project ID from [app.highlight.io/setup](https://app.highlight.io/setup) and insert it in place of `<YOUR_PROJECT_ID>`.  
                    To get started, we recommend setting `tracingOrigins` and `networkRecording` so that highlight.io can pass a header to pair frontend/backend errors . Refer to our docs on [SDK configuration](/docs/getting-started/client-sdk/replay-configuration/overview) and [Fullstack Mapping](/docs/getting-started/frontend-backend-mapping) to read more about these options.

Initialize the SDK in your frontend.

Grab your project ID from [app.highlight.io/setup](https://app.highlight.io/setup) and insert it in place of `<YOUR_PROJECT_ID>`.  
                        To get started, we recommend setting `environment`, `appVersion`, and `networkReco: inrding`. Refer to our docs on [SDK configuration](/docs/getting-started/client-sdk/replay-configuration/overview) to read more about these options. 

H.identify('jay@highlight.io', {
    id: 'very-secure-id',
    phone: '867-5309',
    bestFriend: 'jenny'
});

Identify users to tie their sessions/errors to their account. We suggest doing this before/after the authentication flow of your web app. 


The first argument of `identify` will be searchable via the property `identifier`, and the second property is searchable by the key of each item in the object. Read more about this in our [identifying users](/docs/getting-started/client-sdk/replay-configuration/identifying-sessions) section.

Identify users.

Check your [dashboard](https://app.highlight.io/sessions) for a new session. Don't see anything? Send us a message in [our community](https://highlight.io/community) and we can help debug.

Verify installation

# Upload sourcemaps to Highlight
...
npx --yes @highlight-run/sourcemap-uploader upload --apiKey ${YOUR_ORG_API_KEY} --path ./build
...
        

To get properly enhanced stacktraces of your javascript app, we recommend instrumenting sourcemaps. If you deploy public sourcemaps, you can skip this step. Refer to our docs on [sourcemaps](/docs/getting-started/client-sdk/replay-configuration/sourcemaps) to read more about this option.

Configure sourcemaps in CI. (optional)

The next step is instrumenting your backend to tie logs/errors to your frontend sessions. Read more about this in our [backend instrumentation](/docs/getting-started/overview#For-your-backend) section.

Instrument your backend.

Learn how to set up highlight.io with your Angular application.

Before we get started, you should have the latest version of [docker](https://docs.docker.com/engine/install/) (19.03.0+) and [git](https://git-scm.com/downloads) (2.13+) installed. For a local deploy, we suggest [configuring docker](https://docs.docker.com/desktop/settings/mac/#resources) to use at least 16GB of memory and 4 CPUs.

Prerequisites

git clone --recurse-submodules https://github.com/highlight/highlight

Clone the [highlight.io](https://github.com/highlight/highlight) repository and make sure to checkout the submodules with the `--recurse-submodules` flag.

Clone the repository.

Navigate into the `highlight/docker` directory of the repo.

Enter the `highlight/docker` directory.

export COMPOSE_FILE=compose.yml:compose.dev.yml

In the `highlight/docker` directory, set the environment variable `COMPOSE_FILE` as specified. This will enable hot reloading of both our backend and frontend.

Set the environment variable `COMPOSE_FILE` to support hot reloading.

In the `highlight/docker` directory, run `docker compose up --build -d` to start the docker containers.

Start the docker compose containers.

Visit https://localhost:3000 to view the dashboard and go through the login flow; there are no login credentials required.

Visit the dashboard.

After clicking around on the dashboard for a bit, you should see a session appear at https://localhost:3000/1/sessions. Click on the session to view the session details page.

View your first session.

docker ps
docker compose logs -f backend frontend

Having issues? Here's some things ot try. First run the `docker ps` command and ensure that all containers are in a 'healthy' state. As a second step, run `docker compose logs -f backend frontend` to see the logs for the backend and frontend containers. If this doesn't help w/ troubleshooting, please [reach out](https://highlight.io/community).

Troubleshoot the deployment.

Learn how to set up the dev deployment of highlight.io to start contributing.

# with npm
npm install @highlight-run/gatsby-plugin-highlight

# with yarn
yarn add @highlight-run/gatsby-plugin-highlight
    

Install the npm pulugin in your terminal.

Install the gatsby plugin.

module.exports = {
	plugins: [
		{
			resolve: '@highlight-run/gatsby-plugin-highlight',
			options: {
				orgID: '<YOUR_PROJECT_ID>', // Get your project ID from https://app.highlight.io/setup
			},
		},
	],
}
                

Grab your project ID from [app.highlight.io/setup](https://app.highlight.io/setup) and insert it in place of `<YOUR_PROJECT_ID>`.  
                    To get started, we recommend setting `environment`, `appVersion`, and `networkRecording`. Refer to our docs on [SDK configuration](/docs/getting-started/client-sdk/replay-configuration/overview) to read more about these options. 

Initialize the plugin in your gatsby configuration.

Learn how to set up highlight.io with your Gatsby application.

H.init("<YOUR_PROJECT_ID>", {
  tracingOrigins: ['localhost', 'example.myapp.com/backend'],
  networkRecording: {
    enabled: true,
    recordHeadersAndBody: true,
  },
});

This backend SDK requires one of the Highlight frontend SDKs to be installed, so please make sure you've followed the [fullstack mapping guide](../../../getting-started/frontend-backend-mapping#How-can-I-start-using-this) first.

Set up your frontend Highlight snippet.

go get -u github.com/highlight/highlight/sdk/highlight-go

Install the `highlight-go` package with `go get`.

Install the Highlight Go SDK.

import (
  H "github.com/highlight/highlight/sdk/highlight-go"
)

func main() {
  // ...
  H.SetProjectID("<YOUR_PROJECT_ID>")
  H.Start()
  defer H.Stop()
  // ...
}

`H.Start` starts a goroutine for recording and sending backend errors. Setting your project id lets Highlight record errors for background tasks and processes that aren't associated with a frontend session.

Initialize the Highlight Go SDK.

import (
  highlightChi "github.com/highlight/highlight/sdk/highlight-go/middleware/chi"
)

func main() {
  // ...
  r := chi.NewRouter()
  r.Use(highlightChi.Middleware)
  // ...
}

`highlightChi.Middleware` is a [Go Chi](https://github.com/go-chi/chi) compatible middleware.

Add the Highlight middleware.

H.RecordError(ctx, err, attribute.String("key", "value"))

If you want to explicitly send an error to Highlight, you can use the `H.RecordError` method.

Record custom errors. (optional)

func TestErrorHandler(w http.ResponseWriter, r *http.Request) {
  H.RecordError(r.Context(), errors.New("a test error is being thrown!"))
}

Make a call to `H.RecordError` to see the resulting error in Highlight.

Verify your errors are being recorded.

Start sending logs to Highlight! Follow the [logging setup guide](../../../getting-started/backend-logging/go/chi) to get started.

Set up logging.

Learn how to set up highlight.io on your Go chi backend.

import (
  highlightFiber "github.com/highlight/highlight/sdk/highlight-go/middleware/fiber"
)

func main() {
  // ...
  app := fiber.New()
  app.Use(highlightFiber.Middleware())
  // ...
}

`highlightFiber.Middleware()` provides a [Go Fiber](https://github.com/gofiber/fiber) middleware to automatically record and send errors to Highlight.

Add the Highlight Fiber error handler.

Now that you've set up the Middleware, verify that the backend error handling works by consuming an error from your handler. This is as easy as having a route handler return an error.

Start sending logs to Highlight! Follow the [logging setup guide](../../../getting-started/backend-logging/go/fiber) to get started.

Learn how to set up highlight.io on your Go Fiber backend.

import (
  highlightGin "github.com/highlight/highlight/sdk/highlight-go/middleware/gin"
)

func main() {
  // ...
  r := gin.Default()
  r.Use(highlightGin.Middleware())
  // ...
}

`highlightGin.Middleware()` provides is a [Go Gin](https://github.com/gin-gonic/gin) compatible middleware.

Start sending logs to Highlight! Follow the [logging setup guide](../../../getting-started/backend-logging/go/gin) to get started.

Learn how to set up highlight.io on your Go gqlgen backend.

import (
  highlightGorillaMux "github.com/highlight/highlight/sdk/highlight-go/middleware/gorillamux"
)

func main() {
  // ...
  r := mux.NewRouter()
  r.Use(highlightGorillaMux.Middleware)
  // ...
}

`H.NewGraphqlTracer` provides a middleware you can add to your [Golang Mux](https://github.com/gorilla/mux) handler to automatically record and send GraphQL resolver errors to Highlight.

Add the Highlight gqlgen error handler.

Start sending logs to Highlight! Follow the [logging setup guide](../../../getting-started/backend-logging/go/mux) to get started.

import (
  H "github.com/highlight/highlight/sdk/highlight-go"
)

func main() {
  // ...
  server := handler.New(...)
  server.Use(H.NewGraphqlTracer("your-backend-service-name")
  // ...
}

`H.NewGraphqlTracer` provides a middleware you can add to your [GraphQL](https://gqlgen.com/getting-started/) handler to automatically record and send GraphQL resolver errors to Highlight.

Start sending logs to Highlight! Follow the [logging setup guide](../../../getting-started/backend-logging/go/gqlgen) to get started.

# with yarn
yarn add @highlight-run/node

# with pnpm
pnpm add @highlight-run/node

# with npm 
npm install @highlight-run/node

Install the [@highlight-run/node](https://www.npmjs.com/package/@highlight-run/node) package with your package manager.

Install the Highlight JS SDK.

import { H } from '@highlight-run/node'

H.init({projectID: 'YOUR_PROJECT_ID')

Initialize the [Highlight JS SDK](../../../sdk/nodejs) with your project ID.

Initialize the Highlight JS SDK.

import { ApolloServer } from '@apollo/server'
import { ApolloServerHighlightPlugin } from '@highlight-run/node'

// ...

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [ApolloServerHighlightPlugin({ projectID: 'YOUR_PROJECT_ID' })],
})

`ApolloServerHighlightPlugin` is an [Apollo Server](https://www.apollographql.com/docs/apollo-server/) plugin to capture errors in your graphql handlers.

Add the Apollo Server integration.

const parsed = H.parseHeaders(request.headers)
	H.consumeError(error, parsed?.secureSessionId, parsed?.requestId)

If you need to report exceptions outside of a handler, use the Highlight SDK.

Optionally, report manual errors in your app.

const server = new ApolloServer({
  typeDefs,
  resolvers: {
    Query: {
      books: () => {
        throw new Error('a sample error!');
      },
    },
  },
});

You'll want to throw an exception in one of your apollo handlers. Access the API handler and make sure the error shows up in [Highlight](https://app.highlight.run/errors).

Verify that your SDK is reporting errors.

Start sending logs to Highlight! Follow the [logging setup guide](../../../getting-started/backend-logging/js/apollo) to get started.

Learn how to set up highlight.io on your Apollo Server backend.

# with yarn
yarn add @highlight-run/cloudflare

# with pnpm
pnpm add @highlight-run/cloudflare

# with npm 
npm install @highlight-run/cloudflare

Install the [@highlight-run/cloudflare](https://www.npmjs.com/package/@highlight-run/cloudflare) package with your package manager.

import { H } from '@highlight-run/cloudflare'

async function doRequest() {
  return new Response('hello!')
}

export default {
  async fetch(request: Request, env: {}, ctx: ExecutionContext) {
    const hEnv = { HIGHLIGHT_PROJECT_ID: 'YOUR_PROJECT_ID' }
    try {
      const response = await doRequest()
      H.sendResponse(request, hEnv, ctx, response)
      return response
    } catch (e: any) {
      H.consumeError(request, hEnv, ctx, e)
      throw e
    }
  },
}

Use the [Cloudflare Worker SDK](../../../sdk/cloudflare) in your response handler. The `sendResponse` method traces successful requests while `consumeError` reports exceptions. All Highlight data submission uses [waitUntil](https://developers.cloudflare.com/workers/runtime-apis/fetch-event/#waituntil) to make sure that we have no impact on request handling performance.

Add the Cloudflare Worker Highlight integration.

export default {
  async fetch(request: Request, env: {}, ctx: ExecutionContext) {
    H.consumeError(request, { HIGHLIGHT_PROJECT_ID: 'YOUR_PROJECT_ID' }, ctx, new Error('example error!'))
  },
}

You'll want to throw an exception in one of your cloudflare handlers. Access the API handler and make sure the error shows up in [Highlight](https://app.highlight.run/errors).

Start sending logs to Highlight! Follow the [logging setup guide](../../../getting-started/backend-logging/js/cloudflare) to get started.

Learn how to set up highlight.io in Cloudflare Workers.

import * as Highlight from '@highlight-run/node'
// or like this with commonjs
// const Highlight = require('@highlight-run/node')

const app = express()

const highlightErrorHandler = Highlight.Handlers.errorHandler({ projectID: 'YOUR_PROJECT_ID' })

app.get('/', (req, res) => {
  res.send(`Hello World! 0.6273095025116107`)
})

// This should be before any other error middleware and after all controllers (route definitions)
app.use(highlightErrorHandler)
app.listen(8080, () => {
  console.log(`Example app listening on port 8080`)
})

Use the [Node Highlight SDK](../../../sdk/nodejs) in your response handler.

Add the Express.js Highlight integration.

app.get('/', (req, res) => {
  throw new Error('sample error!')
  res.send(`Hello World! 0.6084519229413914`)
})

You'll want to throw an exception in one of your express.js handlers. Access the API handler and make sure the error shows up in [Highlight](https://app.highlight.run/errors).