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


### 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>



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](../3_getting-started/2_frontend-backend-mapping.md)

## We build for today's developer.
If you're building software in today’s, you want to focus on building software. We challenge ourselves to build developer tooling that’s simple, straightforward but powerful when you need it to be. 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 just shipping it. The only caveat here are processes/work that could affect our customers' software (e.g. building & testing client sdks).



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)



# How to contribute

## Application Architecture

First, you'll want to understand how Highlight is built to make changes. The best way to get a sense of this is to try and make simple dummy changes to different parts of the stack and see how the changes propagate.

-   SDKs `sdk/`

    -   Firstload

    -   Client

    -   highlight-node / other SDKs

-   Public Graph `backend/public-graph/graph/schema.resolvers.go`

-   Private Graph `backend/private-graph/graph/schema.resolvers.go`

-   Workers `backend/worker.go`

    -   Public graph worker `processPublicWorkerMessage`

    -   Async worker `Start`
    

## 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 get started?

You'll want to spin up Highlight locally to get to developing. The best way to do this is by using docker. Check out [the self-hosting instructions](../../2_company/open-source/self-host-hobby.md) for more info.

# Code Style

While we don't fret about whether you prefer tabs or spaces, we want our code to be easy to read and add to. Style preferences are codified and automated as part of CI and automated development workflows (such as `husky` and gomod configurations). 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 deployment starts at $3k / month. Contact us at sales@highlight.io, or message us [on discord](https://community.highlight.io) to get in touch.



# Running Highlight

To run our app locally, head to our [github repo](https://github.com/highlight/highlight) and clone the repository. Then follow the steps below.

## Docker Compose

```shell
# ensure git submodules are cloned
git submodule update --init --recursive
cd docker
docker compose up -d --build
```

After a brief frontend load time, the app should be accessible at https://localhost:3000

For deploying on Linux with Docker, we recommend having at least 16 CPU cores, 32GB RAM, 256GB disk.
Reach out to our [community](https://community.highlight.io/) with any questions!

# 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)!



Let's get you up and running with Highlight. You should be done and able to see a recorded session **within 2 minutes!**
## For your client / frontend:

A session in Highlight starts in the client. 

Highlight 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. Beyond that, to make integration even easier, we have official support for the following frameworks:

-   [React.js](./client-sdk/react-js/overview.md)

-   [Next.js](./client-sdk/nextjs.md)

-   [Vue.js](./client-sdk/vuejs.md)

-   [Gatsby.js](./client-sdk/gatsbyjs.md)

-   [HTML](./client-sdk/html.md)

-   [SvelteKit](./client-sdk/sveltekit.md)

-   [Angular](./client-sdk/angular.md)

-   If you don't see your framework above, see our docs for [other frameworks](./client-sdk/other.md).

For in-depth instructions, follow the [Client SDK](./client-sdk/1_client-sdk-overview.md) guide.

## For your backend / server:

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. Support frameworks / tech below:


-   [Firebase](./backend-sdk/firebase.md)

-   [Express](./backend-sdk/express.md)

-   [Go](./backend-sdk/go.md)

-   [Next.js](./backend-sdk/nextjs.md)

-   [Node.js](./backend-sdk/nodejs.md)

-   For requesting other backend frameworks, shoot us a message at [support@highlight.io](mailto:support@highlight.io) or share in our [community](https://discord.gg/yxaXEAqgwN)

For in-depth instructions, follow the [Backend SDK](./backend-sdk/backend-sdk-overview.md) guide.



## What's this?

In order to make the most out of highlight.io's, 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?

Required Highlight `highlight.run` version: `>=2.8.1`

### 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](./backend-sdk/go.md)

- [Next.js Backend Integration](./backend-sdk/nodejs.md)

- [Node.js Backend Integration](./backend-sdk/nodejs.md)

- [Express Backend Integration](./backend-sdk/express.md)

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



Highlight ships `@highlight-run/node` with a plugin `ApolloServerHighlightPlugin` specifically for the apollo server.
The plugin will trace graphql resolver errors and report them to Highlight.

## Usage

The usage of the Apollo plugin requires the [Node.js integration](../../../sdk/nodejs.md) to be configured.
Ensure that `@highlight-run/node` updated to version 2.2.0 or greater. Then, add `ApolloServerHighlightPlugin` to
your `ApolloServer` plugins definition.

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

// ...

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

## Usage on Apollo Server v3 (deprecated)
```hint
The following example is for the deprecated ApolloServer v3 (importing from apollo-server-express).
```

```typescript
import { ApolloServer } from 'apollo-server-express';
import { ApolloServerV3HighlightPlugin } from '@highlight-run/node';

// ...

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

### Verify

To validate your Highlight backend setup, you can have a graphql resolver throw an error and check that the
error is visible on [app.highlight.io](http://app.highlight.io/errors).



## What's this?

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.

## What does it look like?

Below is an example of a backend error (thrown in `go` ) ,mapped to an actual network request on a user's frontend.

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

## Quick Start

### Enable proper flags in your client-side snippet:

As a first step, you must enable the correct options in your client-side code snippet detailed in our [full stack mapping reference](../2_frontend-backend-mapping.md). 

### Make the appropriate 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 shoot us a note in our [discord](https://discord.gg/yxaXEAqgwN).

- [Go Backend Integration](./go.md)

- [Next.js Backend Integration](./nextjs.md)

- [Node.js Backend Integration](./nodejs.md)

- [Express Backend Integration](./express.md)



Highlight ships `@highlight-run/cloudflare` which tracks errors and forwards logs from your Cloudflare Workers.

## Getting Started

This backend SDK requires one of our [Client SDK](../client-sdk/1_client-sdk-overview.md)s to be installed, so please follow the instructions there if you have not done so.

For server-side linking to Highlight sessions, your client-side call to `H.init` should include the `tracingOrigins` setting. See [H.init()](../../../sdk/client.md#Hinit) for more details.

```typescript
H.init('<YOUR_PROJECT_ID>', {
    ...
    tracingOrigins: true,
    ...
});
```

## Adding Highlight to your Cloudflare Worker Backend

First, import the package

```shell
# with npm
npm install @highlight-run/cloudflare

# with yarn
yarn add @highlight-run/cloudflare
```


### Handle errors

When your app throws a backend error, you can log that error to Highlight by calling [H.consumeError()](../../../sdk/cloudflare.md#Hconsume-error). Your cloudflare worker code would look something like this:

```typescript
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
        }
    },
}
```

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.

### Verify

To view and resolve the recorded error, log into [app.highlight.io/errors](https://app.highlight.io/errors) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. You can also view frontend sessions where the error was thrown, and see the individual request which caused the error.

For more details, check out the [SDK docs](../../../sdk/cloudflare.md).



Highlight ships `@highlight-run/node` which can be installed alongside highlight.run for capturing backend errors in applications with Express backends.

## Usage

The usage of this Backend SDK requires one of our [Client SDK](../client-sdk/1_client-sdk-overview.md)s to be installed, so please follow the instructions there if you have not done so.

### The `@highlight-run/node` Package

First, import the package

```typescript
yarn add @highlight-run/node
```

### Adding Highlight to Express

Pass configurations into the errorHandler and Highlight is ready to go!


```hint
Where you place the `app.use(highlightErrorHandler)` definition is important. It must be set
after route handler definitions (`app.get(...)`, etc) and before other error middleware. 
```


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

const app = express()

// define any configurations needed
// <https://docs.highlight.run/api/hinit#w0-highlightoptions>
const highlightOptions = {}
// initialize the handler
const highlightErrorHandler = Highlight.Handlers.errorHandler(highlightOptions)

app.get('/', (req, res) => {
    if (Math.random() < 0.1) {
        throw new Error(`random error ${Math.random()}`)
    }
    res.send(`Hello World! ${Math.random()}`)
})

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

### Verify

To validate your Highlight backend setup, you'll need to setup up a testing route handler that throws an error. See the block above for an example. Add some code to your frontend to make an HTTP request
to `/error`. You should be able to view your
frontend session making the request and find the error
traceback in the errors page.

To view and resolve the recorded error, log into [app.highlight.io](http://app.highlight.io/) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved.



Highlight's `@highlight-run/node` package includes wrappers for Firebase Cloud Functions, which will automatically report backend errors to Highlight and link them to the frontend sessions that caused them.

## Getting Started

This backend SDK requires one of our [Client SDK](../client-sdk/1_client-sdk-overview.md)s to be installed, so please follow the instructions there if you have not done so.

For server-side linking to Highlight sessions, your client-side call to `H.init` should include the `tracingOrigins` setting. See [H.init()](../../../sdk/nodejs.md#Hinit) for more details.

```typescript
H.init('<YOUR_PROJECT_ID>', {
    ...
    tracingOrigins: true,
    ...
});
```

## Adding Highlight to your Backend

Import the `@highlight-run/node` package

```shell
# with npm
npm install @highlight-run/node

# with yarn
yarn add @highlight-run/node
```

### Wrap your Cloud Functions

```javascript
const highlightNode = require('@highlight-run/node')

// Callable function wrapper
exports.exampleCallable = functions.https.onCall(
	highlightNode.Handlers.firebaseCallableFunctionHandler((data, context) => {
		// ... your handler code here
		return { result: 'useful result!' }
	}, {projectID: "YOUR-PROJECT-ID"}),
)
```

```javascript
const highlightNode = require('@highlight-run/node')

// Http function wrapper
exports.exampleHttp = functions.https.onRequest(
	highlightNode.Handlers.firebaseHttpFunctionHandler((req, res) => {
		// ... your handler code here
		res.json({ result: 'useful result!' })
	}, {projectID: "YOUR-PROJECT-ID"}),
)
```

### Verify

To view and resolve the recorded error, log into [app.highlight.io/errors](https://app.highlight.io/errors) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. You can also view frontend sessions where the error was thrown, and see the individual request which caused the error.



Highlight supports several server frameworks written in Go.

`go-chi/chi`
`gin-gonic/gin`

# Usage

First, install and import the go package in your entrypoint.

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

Add the following lines to your application's main (`func main`) function:

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

func main() {
	//...application logic...
	highlight.Start()
	defer highlight.Stop()
	highlight.SetProjectID("YOUR_PROJECT_ID")
	//...application logic...
}

```

This configures highlight to transmit any relevant events or errors as they may happen. You can also customize highlight by using the public highlight methods before calling `Start()`. However, we still need to associate your users' sessions with potential backend errors. We provide middleware packages that help set this up:

### Middleware

Add the following middleware to your router:

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

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

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

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

```

## Instrumenting Handlers

Great! Now we've configured the highlight client and can track sessions from the frontend to the backend. All we need to do now is instrument our backend code to transmit events or errors where relevant.

```go

package main

// with chi
import (
	"errors"
	"github.com/go-chi/cors"
	"github.com/highlight/highlight/sdk/highlight-go"
	"net/http"

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

func main() {
	highlight.Start()
	defer highlight.Stop()
	highlight.SetProjectID("YOUR_PROJECT_ID")

	r := chi.NewRouter()
	r.Use(middleware.Logger)
	r.Use(highlightChi.Middleware)
	// setup cors if necessary for your frontend
	r.Use(cors.Handler(cors.Options{
		AllowedOrigins: []string{"http://localhost:3001"},
		AllowedHeaders: []string{"X-Highlight-Request"},
	}))

	r.Get("/ping", PingHandler)
	http.ListenAndServe("0.0.0.0:8080", r)
}

var appHealthy = false

func PingHandler(w http.ResponseWriter, r *http.Request) {
	// we can instrument our handlers directly to record events or error
	if !appHealthy {
		highlight.ConsumeError(r.Context(), errors.New("a health check failure occured!"))
	}
	w.Write([]byte("welcome"))
}

// with gin
import (
	"errors"
	"github.com/gin-contrib/cors"
	"github.com/gin-gonic/gin"
	"github.com/highlight/highlight/sdk/highlight-go"
	highlightGin "github.com/highlight/highlight/sdk/highlight-go/middleware/gin"
)

func main() {
	highlight.Start()
	defer highlight.Stop()
	highlight.SetProjectID("YOUR_PROJECT_ID")

	r := gin.Default()
	r.Use(highlightGin.Middleware())
	// setup cors if necessary for your frontend
	r.Use(cors.New(cors.Config{
		AllowOrigins: []string{"http://localhost:3001"},
		AllowHeaders: []string{"X-Highlight-Request"},
	}))

	r.GET("/ping", PingHandler)
	r.Run("0.0.0.0:8080") // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080")
}

var appHealthy = false

func PingHandler(c *gin.Context) {
	// we can instrument our handlers directly to record events or error
	if !appHealthy {
		highlight.ConsumeError(c, errors.New("a health check failure occured!"))
	}
	c.JSON(200, gin.H{
		"message": "Hello, World!",
	})
}
```



See [Next.js SDK](../fullstack-frameworks/next-js/1_overview.md) for the complete Highlight Next.js SDK setup



Highlight ships `@highlight-run/node` which can be installed alongside highlight.run for capturing backend errors and reporting metrics in applications with Node.js backends. This SDK is compatible with many other backend frameworks built on top of Node.js.

## Getting Started

This backend SDK requires one of our [Client SDK](../client-sdk/1_client-sdk-overview.md)s to be installed, so please follow the instructions there if you have not done so.

For server-side linking to Highlight sessions, your client-side call to `H.init` should include the `tracingOrigins` setting. See [H.init()](../../../sdk/client.md#Hinit) for more details.

```typescript
H.init('<YOUR_PROJECT_ID>', {
    ...
    tracingOrigins: true,
    ...
});
```

## Adding Highlight to your Backend

First, import the package

```shell
# with npm
npm install @highlight-run/node

# with yarn
yarn add @highlight-run/node
```

### Initialize the Highlight backend

Somewhere in your app, typically during startup or when handling errors, initialize the Highlight backend with any necessary options. See [H.init()](../../../sdk/client.md#Hinit) for a full list of options.

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

const highlightOptions = {}
if (!H.isInitialized()) {
	H.init(highlightOptions)
}
```

### Handle errors

When your app throws a backend error, you can log that error to Highlight by calling [H.consumeError()](../../../sdk/nodejs.md#Hconsume-error) using the `secureSessionId` and `requestId` parameters from the request's header. Your error handling code will depend on the backend framework you use, but will likely look something like this:

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

const onError = (request, error) => {
	const parsed = H.parseHeaders(request.headers)
	if (parsed !== undefined) {
		H.consumeError(error, parsed.secureSessionId, parsed.requestId)
	}
}
```

### Verify

To view and resolve the recorded error, log into [app.highlight.io/errors](https://app.highlight.io/errors) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. You can also view frontend sessions where the error was thrown, and see the individual request which caused the error.



Highlight ships the [highlight_io](https://pypi.org/project/highlight-io/) pypi module for capturing backend errors in applications with Python backends.

## Usage

The usage of this Backend SDK requires one of our [Client SDK](../client-sdk/1_client-sdk-overview.md)s to be installed, so please follow the instructions there if you have not done so.

## The `highlight_io` Python Module

If you'd like to follow an example, check out our repo for one of a [Flask app](https://github.com/highlight/highlight/blob/main/sdk/highlight-py/examples/app.py) and one of a [backend script](https://github.com/highlight/highlight/blob/main/sdk/highlight-py/examples/script.py).

First, import the package

```bash
poetry add highlight-io
# or with pip
pip install highlight-io
```

If you are uswing a Flask app, you'll need the Flask integration.

```bash
poetry add highlight-io[Flask]
# or with pip
pip install highlight-io[Flask]
```

## Adding Highlight to Flask

Import the Flask integration and setup Highlight with Flask!

```python
from flask import Flask

import highlight_io
from highlight_io.integrations.flask import FlaskIntegration

app = Flask(__name__)
H = highlight_io.H(
    "YOUR-PROJECT-ID", integrations=[FlaskIntegration()], record_logs=True
)
```

## Adding Highlight to Django

Import the Django integration in your `settings.py` file.

```python
import highlight_io
from highlight_io.integrations.django import DjangoIntegration

H = highlight_io.H("YOUR-PROJECT-ID", integrations=[DjangoIntegration()], record_logs=True)
```

## Adding Highlight to Azure Functions

Just add the `@observe_handler` decorator to your functions!

```python
import logging
import azure.functions as func

import highlight_io
from highlight_io.integrations.azure import observe_handler

H = highlight_io.H("YOUR-PROJECT-ID", record_logs=True)


@observe_handler
def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.info("Python HTTP trigger function processed a request.")
    return func.HttpResponse("Hello, world.")
```

## Verify

To validate your Highlight backend setup, you can setup up a testing route handler that throws an error. For example:

```python
import logging
import random
import time

from flask import Flask

import highlight_io
from highlight_io.integrations.flask import FlaskIntegration

app = Flask(__name__)
H = highlight_io.H(
    "YOUR_PROJECT_ID", integrations=[FlaskIntegration()], record_logs=True
)


@app.route("/error")
def hello():
    for idx in range(1000):
        logging.info(f"hello {idx}")
        time.sleep(0.001)
        if random.randint(0, 100) == 1:
            raise Exception(f"random error! {idx}")
    logging.warning("made it outside the loop!")
    return "<h1>Hello, World!</h1>"


if __name__ == "__main__":
    app.run()
```

creates a `/error` route that will randomly throw an error.

To view and resolve the recorded error, log into [app.highlight.io/errors](http://app.highlight.io/errors). Clicking on the error's title will open a page where you can see detailed information and mark it as resolved.



Highlight's `@highlight-run/node` package includes a tRPC compatible error handler, which will automatically report backend errors to Highlight and link them to the frontend sessions that caused them.

## Getting Started

In order to use the backend sdk, we recommend using one of our Client SDKs (with `H.init()`) so that errors are properly matched from your sessions to your backend errors. In your javascript environment, it would look like something like this:

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


The full guide for initializing Highlight in your client can be found [here](../client-sdk/1_client-sdk-overview.md) and more information about setting up frontend/backend mapping for any stack can be found [here](../2_frontend-backend-mapping.md).

Lastly, see [H.init()](../../../sdk/client.md#Hinit) for a full sdk reference.


## Adding Highlight to your Backend

Import the `@highlight-run/node` package

```shell
# with npm
npm install @highlight-run/node

# with yarn
yarn add @highlight-run/node
```

### Handle errors

When you're exporting an API handler, use `Handlers.trpcOnError` as your `onError` function. Here's an example with tRPC + Next.js:

```typescript
// pages/api/trpc/[trpc].ts

import { createNextApiHandler } from '@trpc/server/adapters/next'
import { Handlers } from '@highlight-run/node'

export default createNextApiHandler({
	// ... your config
	onError: Handlers.trpcOnError,
})
```

If you're already doing your own error handling logic in a custom `onError` function, you can call this handler with the `error` and `req` arguments.

```typescript
// pages/api/trpc/[trpc].ts

import { createNextApiHandler } from '@trpc/server/adapters/next'
import { Handlers } from '@highlight-run/node'

export default createNextApiHandler({
	// ... your config
	onError: ({ error, req }) => {
		// ... your own error handling logic here
		Handlers.trpcOnError({ error, req })
	},
})
```

### Verify

To view and resolve the recorded error, log into [app.highlight.io/errors](https://app.highlight.io/errors) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. You can also view frontend sessions where the error was thrown, and see the individual request which caused the error.



```hint
For a more comprehensive tour of our client sdk, visit our [client reference page](../../../sdk/client.md).
```

## Frameworks

Get started with one of these guides if you're using a listed framework:

-   [React.js](./react-js/overview.md)

-   [Next.js](./nextjs.md)

-   [Vue.js](./vuejs.md)

-   [Gatsby.js](./gatsbyjs.md)

-   [HTML](./html.md)

-   [SvelteKit](./sveltekit.md)

-   [Angular](./angular.md)

## Installing the SDK

Install `highlight.run` using your package manager.

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

# with yarn
yarn add highlight.run
```

## Initialize

Initialize Highlight where your application starts.

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

H.init(
	'<YOUR_PROJECT_ID>', // Get this from https://app.highlight.run/setup
)
```

### Example

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

H.init('<YOUR_ORGANZATION_ID>') // Get this from https://app.hgihlight.run/setup

ReactDOM.render(
	<React.StrictMode>
		<App />
	</React.StrictMode>,
	document.getElementById('root'),
)
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on [app.highlight.io/sessions](https://app.highlight/sessions) a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../6_product-features/1_session-replay/privacy.md)

- [Network Request Recording](../../6_product-features/1_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)



-   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 [Content-Security-Policy CSP](../../../9_tips/content-security-policy.md), 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](../../../6_product-features/1_session-replay/cross-origin-iframes.md).



-   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](../../../7_integrations/segment-integration.md) 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.



```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Installing the SDK

Install `highlight.run` using your package manager.

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

# with yarn
yarn add highlight.run
```

## Initialize

Initialize Highlight where your application starts, likely in the Angular `main.ts` file.

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

H.init(
    "<YOUR_PROJECT_ID>", // Get your project ID from https://app.highlight.io/setup
    networkRecording: {
        enabled: true,
        recordHeadersAndBody: true,
    },
    tracingOrigins: true // Optional configuration of Highlight features
);
```

Check out [H.init()](../../../sdk/client.md#Hinit) docs for more details about the options to configure.

If you prefer a full-fledged example, you can also reference our sample [Angular Repo with Highlight Configured](https://github.com/highlight/example-angular).

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on [app.highlight.io/sessions](https://app.highlight/sessions) a few seconds after recording has started.

## Configuration

Integration with [Angular ErrorHandler](https://angular.io/api/core/ErrorHandler) coming soon!

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../6_product-features/1_session-replay/privacy.md)

- [Network Request Recording](../../6_product-features/1_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)



```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Installing the SDK

Install `@highlight-run/gatsby-plugin-highlight` using your package manager.

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

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

## Register Highlight as a Gatsby Plugin

You will need to register the Highlight Gatsby Plugin.

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

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on [app.highlight.io/sessions](https://app.highlight/sessions) a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../6_product-features/1_session-replay/privacy.md)

- [Network Request Recording](../../6_product-features/1_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)


```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Adding the Snippet

Add the snippet to your `index.html`.

```html
<html>
	<head>
		<script src="https://cdn.jsdelivr.net/npm/highlight.run@latest"></script>
		<script>
			window.H.init('<YOUR_PROJECT_ID>') // Get your project ID from https://app.highlight.io/setup
		</script>
	</head>
	<body>
		
	</body>
</html>
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on [app.highlight.io/sessions](https://app.highlight/sessions) a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../6_product-features/1_session-replay/privacy.md)

- [Network Request Recording](../../6_product-features/1_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)


```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Installing the SDK

Install `highlight.run` and `@highlight-run/react` using your package manager.

```shell
# with npm
npm install highlight.run @highlight-run/react

# with yarn
yarn add highlight.run @highlight-run/react
```

## Initialize

Initialize Highlight where your application starts.

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

H.init(
	'<YOUR_PROJECT_ID>', // Get your project ID from https://app.highlight.io/setup
)
```

### Example

```hint
Using the new `/app` directory in Next.js 13? Refer to [this guide](../fullstack-frameworks/next-js/next-13-considerations.md) to ensure you're using a client component.
```

```typescript
import type { AppProps } from 'next/app'
import { H } from 'highlight.run'
import { ErrorBoundary } from '@highlight-run/react'

H.init('<YOUR_PROJECT_ID>') // Get your project ID from https://app.highlight.io/setup

function MyApp({ Component, pageProps }: AppProps) {
	return (
		<ErrorBoundary>
			<Component {...pageProps} />
		</ErrorBoundary>
	)
}
export default MyApp
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on [app.highlight.io/sessions](https://app.highlight/sessions) a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../6_product-features/1_session-replay/privacy.md)

- [Network Request Recording](../../6_product-features/1_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)


```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Adding the Snippet

Add the snippet to your `index.html`.

```html
<html>
	<head>
		<script src="https://unpkg.com/highlight.run"></script>
		<script>
			window.H.init('<YOUR_PROJECT_ID>') // Get your project ID from https://app.highlight.io/setup
		</script>
	</head>
	<body>
		
	</body>
</html>
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on [app.highlight.io/sessions](https://app.highlight/sessions) a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../6_product-features/1_session-replay/privacy.md)

- [Network Request Recording](../../6_product-features/1_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)


```hint
Reference our [client-side sdk docs](../../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Installing the SDK

Install `highlight.run` and `@highlight-run/react` using your package manager.

```shell
# with npm
npm install highlight.run @highlight-run/react

# with yarn
yarn add highlight.run @highlight-run/react
```

## Initialize

Initialize Highlight where your application starts.

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

H.init(
	'<YOUR_PROJECT_ID>', // Get your project ID from https://app.highlight.io/setup
)
```

### Example

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

H.init('<YOUR_PROJECT_ID>') // Get your project ID from https://app.highlight.io/setup

ReactDOM.render(
	<React.StrictMode>
		<ErrorBoundary>
			<App />
		</ErrorBoundary>
	</React.StrictMode>,
	document.getElementById('root'),
)
```

```hint
For more details about our error boundary api, including a short API reference, take a look [here](./react-error-boundary.md).
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on [app.highlight.io/sessions](https://app.highlight/sessions) a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../../6_product-features/1_session-replay/privacy.md)

- [Network Request Recording](../../../6_product-features/1_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../../backend-sdk/backend-sdk-overview.md)



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`.


```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```

## Initialize and Start Highlight

You will need to initialize and start Highlight in your SvelteKit application. You can do so by making the following change in `index.html`.

```html
... %svelte.head%

<script src="https://cdn.jsdelivr.net/npm/highlight.run@latest"></script>
<script>
	window.H.init('<YOUR_PROJECT_ID>')
</script>

...
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on [app.highlight.io/sessions](https://app.highlight/sessions) a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../6_product-features/1_session-replay/privacy.md)

- [Network Request Recording](../../6_product-features/1_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)


```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Installing the SDK


Install `highlight.run` using your package manager.

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

# with yarn
yarn add highlight.run
```

## Initialize

Initialize Highlight where your application starts.

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

H.init(
	'<YOUR_PROJECT_ID>', // Get your project ID from https://app.highlight.io/setup
)
```

### Example

```typescript
import { H } from 'highlight.run'
import { createApp } from 'vue'
import App from './App.vue'

H.init('9me23yd2') // Get your project ID from https://app.highlight.io/setup

createApp(App).mount('#app')
```

## Verify Installation

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on [app.highlight.io/sessions](https://app.highlight/sessions) a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../6_product-features/1_session-replay/privacy.md)

- [Network Request Recording](../../6_product-features/1_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)



```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Adding the Snippet

Add the snippet to your `index.html`.

```html
<html>
	<head>
		<script src="https://unpkg.com/highlight.run"></script>
		<script>
			window.H.init('<YOUR_PROJECT_ID>') // Get your project ID from https://app.highlight.io/setup
		</script>
	</head>
	<body>
		
	</body>
</html>
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on [app.highlight.io/sessions](https://app.highlight/sessions) a few seconds after recording has started.


The Highlight Next.js SDK adds additional features to Highlight, including:

-   server-side error monitoring and linking to Highlight sessions: [Highlight()](../../../../sdk/nextjs.md#Highlight)

-   automatic configuration of source map uploads: [withHighlightConfig()](../../../../sdk/nextjs.md#withHighlightConfig)

-   automatic proxying for Highlight requests using Next.js rewrites: [withHighlightConfig()](../../../../sdk/nextjs.md#withHighlightConfig)

## Getting Started

The features in this SDK require the Highlight client SDK to be installed, so please follow the [Next.js](../../client-sdk/nextjs.md) instructions if you have not yet done so.

For server-side linking to Highlight sessions, your call to `H.init` should include the `tracingOrigins` setting. If you're going to use `withHighlightConfig` and proxy your Highlight requests with a rewrite, you should set `backendUrl`. See [H.init()](../../../../sdk/client.md#Hinit) for more details.

```hint
Using the new `/app` directory in Next.js 13? Refer to [this guide](./next-13-considerations.md) to ensure you're using a client component.
```

```typescript
H.init('<YOUR_PROJECT_ID>', {
    ...
    tracingOrigins: true,
    backendUrl: '/highlight-events',
    ...
});
```


### SDK Setup

Import the `@highlight-run/next` Package

```shell
# with npm
npm install @highlight-run/next

# with yarn
yarn add @highlight-run/next
```

### Wrapping your next.config.js

```hint
In order for Highlight to be aware of your project during build time, you need the `HIGHLIGHT_SOURCEMAP_UPLOAD_API_KEY` variable in your build environment. Refer to our [environment variables doc](../next-js/env-variables.md) to get this set up in your cloud provider of choice.
```

If you want to configure source map uploads during your production builds and enable the Next.js Highlight proxy rewrite, you can wrap your Next.js config with `withHighlightConfig`. See [withHighlightConfig()](../../../../sdk/index.md#withHighlightConfig) for more details.

```javascript
import { withHighlightConfig } from '@highlight-run/next'
export default withHighlightConfig({
	// your next.config.js options here
})
```

### Next.js Backend Errors

If you want to monitor backend errors, this API wrapper will send your errors to Highlight and link them to the session where the network request was made. Define a `withHighlight` wrapper with any common options in a common function file. For example, you can create a `highlight.config.ts` file in the root of your next.js codebase. See [Highlight()](../../../../sdk/nextjs.md#Highlight) for more details.

```typescript
import { Highlight } from '@highlight-run/next'

export const withHighlight = Highlight({projectID: 'YOUR_PROJECT_ID'})
```

You can then wrap each of your handlers in the Next.js `api/` directory with the `withHighlight` function from the previous step.

```typescript
import { withHighlight } from '../highlight.config'

const handler = async (req, res) => {
	res.status(200).json({ name: 'Jay' })
}

export default withHighlight(handler)
```


## On Vercel
If you are running your Next.js app in [Vercel](https://vercel.app/), you can install [our integration](https://vercel.com/integrations/highlight) to automatically inject the `HIGHLIGHT_SOURCEMAP_UPLOAD_API_KEY` environment variable. Add it to your project and configure it from the link above to inject the necessary environment variables.

## Other Cloud Providers
Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on [app.highlight.io/sessions](https://app.highlight/sessions) a few seconds after recording has started.



## highlight.io with the new `app/` directory.

Given that Next.js 13 supports the new app directory and defaults to using server components, its important to make sure that highlight.io is being initialized on the client. In order to do this, we recommend creating a client component within your Next.js `/app` directory, and then importing this component in your layout file of choice.

Take a look at the example below, or for a full project, refer to this [sample github app](https://github.com/highlight/nextjs-13-sample).

```typescript
// app/highlight.tsx
'use client';

import {H} from 'highlight.run';
H.init('<YOUR_PROJECT_ID>', {
  environment: 'production',
  enableStrictPrivacy: false,
});

const Highlight = () => {
  return null;
};

export default Highlight;
```

In the `layout.tsx` file below, keep the imported component within the `<body></body>` component so that client-side hydration works correctly.

```typescript
// app/layout.tsx
import './globals.css'
import Highlight from './highlight';
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head />
      <body>
        <Highlight/>
        {children}
      </body>
    </html>
  )
}
```



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.

## Manual Instrumentation.
<DocsCardGroup>
    <DocsCard title="Identifying Sessions."  href="./identifying-sessions.md">
        {"Identifying sessions so that users' corresponding sessions can be searched for."}
    </DocsCard>
    <DocsCard title="Tracking Events."  href="./tracking-events.md">
        {"Tracking events that users fire throughout your web app so they can be searched."}
    </DocsCard>
    <DocsCard title="Versioning Sessions."  href="./versioning-sessions.md">
        {"Version sessions so that you know what sessions corresponded to what deployment."}
    </DocsCard>
</DocsCardGroup>

## Devtools Recording.
<DocsCardGroup>
    <DocsCard title="Console Message Recording."  href="./console-messages.md">
        {"Configuring how logs printed from your frontend are recorded."}
    </DocsCard>
    <DocsCard title="Network recording."  href="./recording-network-requests-and-responses.md">
        {"Configure how network requests are recorded in your frontend."}
    </DocsCard>
</DocsCardGroup>

## Recording Features.
<DocsCardGroup>
    <DocsCard title="Canvas Recording."  href="./canvas.md">
        {"Record native canvas element in the DOM."}
    </DocsCard>
    <DocsCard title="Iframe Recording."  href="./html-iframe-recording.md">
        {"Record iframes directly in your web application."}
    </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>
</DocsCardGroup>

## Session Discovery
<DocsCardGroup>
    <DocsCard title="Session Search."  href="./session-search.md">
        {"Features that allow you to search for sessions in your app."}
    </DocsCard>
    <DocsCard title="Live Mode."  href="./live-mode.md">
        {"Follow your users live in your web application."}
    </DocsCard>
</DocsCardGroup>


## Canvas Recording
```hint
We are actively working on improving recording of canvas elements. If you have any questions or suggestions please reach out to us at support@highlight.run
```

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.

Ensure you have installed [highlight.run >= 4.3.6](https://www.npmjs.com/package/highlight.run/v/4.3.6). Enable canvas recording by configuring [H.init()](../../../sdk/client.md#Hinit).

```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](../1_session-replay/canvas.md) recording.


## Caveats

For both WebGL and canvas recording, [Privacy](../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.

## Configuration

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

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

```hint
Console messages are not recorded on `localhost` because Highlight emits debug messages which could cause an infinite loop in some situations.
```

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



```hint
Cross-origin iframe support is still in development. If you have any questions or suggestions please reach out to us at support@highlight.io
```

[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.



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



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.

```none
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.



When you use Highlight'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.

![Playback controls for a live session](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/rkMGsKiU5WGQ-uVhEW9Wo_screenshot-from-2022-03-21-16-29-23.png)

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.



Due to the nature of Highlight's core product, we keep privacy as our top priority. We've built a few ways to redact/mask certain DOM elements while still preserving the structure of your DOM recording. It is important to note that for both of the below solutions, all data is sanitized on the client, so sensitive data never reaches our servers/platform.

## 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
>
```



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 fast as it should or at all.

## 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)



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.



Highlight records [Tracking Events](../1_session-replay/tracking-events.md) and other metadata about sessions to make them easy to search and filter. Start with the `Quick Search` that will find the best matches depending on what you're looking for and customize your query further in the panel above the sessions feed.

![Quick Search Input.](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/l6Fxtyklubv4aEFnGY6-b_image.png)

# 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)



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](../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.



When using Highlight, it can be useful to know which app version a session is recorded on. Highlight helps you by letting you tag which app version a session was recorded on.

To tag your sessions with a version, you can set the `version` field in the [`H.init()`](../../../sdk/client.md#Hinit).

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

H.init('<YOUR_PROJECT_ID>', {
	version: process.env.REACT_APP_VERSION,
})

ReactDOM.render(<App />, document.getElementById('root'))
```

## Versioning Errors

`version` is used for errors too, see [Versioning Errors]() for more information.



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.

## 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="./versioning-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.



```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, 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 needs access to the sourcemaps from your codebase. Sourcemaps can be sent to Highlight in your CI/CD process.

## Sending Sourcemaps to Highlight

The Highlight [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
# 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 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 [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.



When using Highlight, it can be useful to know which app version an error is introduced. Highlight helps you by letting you tag which app version an error was thrown in.

To tag your errors with a version, you can set the `version` field in the [`H.init()`](../../../sdk/client.md#Hinit).

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

H.init('<YOUR_PROJECT_ID>', {
	version: process.env.REACT_APP_VERSION,
})

ReactDOM.render(<App />, document.getElementById('root'))
```

## Versioning Sessions

`version` is used for sessions too, see [Versioning Sessions](../1_session-replay/versioning-sessions.md) for more information.



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)
```


Front Integration