# Ottertrail documentation > Ottertrail is web analytics, product analytics, error tracking, session replay, and monitoring for small software teams, in one tool. Each customer runs an instance of their own. --- # What is Ottertrail Section: Introduction. Source: https://docs.ottertrail.app/introduction/what-is-ottertrail/ > What Ottertrail does, which data it collects, and how it treats visitors' data. Ottertrail collects data about your websites, apps, and servers, and shows it in one dashboard. It is for small software teams that want one tool in place of several. ## What it does | Area | What you get | | --- | --- | | Web analytics | Pageviews, visitors, visits, referrers, campaign (UTM) tags, countries, devices, page speed (Web Vitals), and heatmaps of clicks and scroll depth. | | Product analytics | Custom events, a funnel, a retention report, and goals. | | Users | The activity of each signed-in user that your app names. | | Errors | Browser errors and server exceptions, grouped, with source maps for minified code. | | Session replay | A recording of the moments before an error, masked in the visitor's browser. | | Monitoring | Traces, logs, and metrics from your servers over OpenTelemetry, with services, database queries, and hosts. | | Uptime and alerts | HTTP checks, and alert rules that send email or signed webhooks. | ## How it collects data - **From browsers.** A small script, the tracker, runs on your pages. It sends pageviews, custom events, errors, and Web Vitals to your Ottertrail instance, and, when you turn heatmaps on, clicks and scroll depth. The tracker stores nothing on the visitor's device: no cookies and no local storage. - **From your servers.** Your servers send events, source maps, and OpenTelemetry data with the project's secret key. Any OpenTelemetry SDK or Collector can send to Ottertrail. You do not install an Ottertrail agent. ## How it treats visitors - Ottertrail does not store or log visitors' IP addresses. It uses the address in memory to find the visitor's country, region, and city, and then discards it. - An anonymous visitor gets an ID that changes every day. Ottertrail cannot connect one visitor's visits on two different days. - Your app can name its signed-in users. Ottertrail then links their events by your own user ID. See [Name signed-in users](/users/naming-users/). ## One instance for each customer Each customer runs an instance of Ottertrail of their own. No other customer shares its server or its data. You can run an instance on your own server: see [Install Ottertrail](/get-started/install/). An instance holds your projects and your team. See [How an instance is organised](/introduction/instances-and-projects/). ## Where to go next - **Set it up.** [Get started](/get-started/) lists the steps, from [installing an instance](/get-started/install/) to data in the dashboard. It also has a prompt that gives the same steps to a coding agent. - **Find your way in the dashboard.** Read [The dashboard](/introduction/the-dashboard/). - **Send data from your app.** The [tracker reference](/reference/tracker/) lists every option. [Send telemetry](/monitoring/sending-telemetry/) covers your servers. - **Run your instance.** The Self-hosting pages cover the [settings](/self-hosting/configuration/), [updates](/self-hosting/updating/), [backups](/self-hosting/backups/), and [security](/self-hosting/security/). --- # How an instance is organised Section: Introduction. Source: https://docs.ottertrail.app/introduction/instances-and-projects/ > Instances, projects, keys, environments, and the people who use the dashboard. ## The instance An instance is one installation of Ottertrail, with its own address, such as `https://analytics.example.com`. The instance holds: - Your **projects**. - The **dashboard users**: an owner, admins, and members. - The **instance settings**: a display name, a timezone, and whether the location data updates itself. - The **notification channels** that alerts and storage warnings go to. The owner and admins open the instance's **Settings** from the workspace menu. It has four tabs: **General** (the name and the timezone) and **Location data** for the owner, and **Storage** and **Notification channels** for the owner and admins. See [Storage](/self-hosting/storage/), [Location data](/self-hosting/location-data/), and [Notification channels](/uptime-and-alerts/channels/). The timezone sets where each day starts in every report. Anonymous visitor IDs also change at midnight in this timezone. The owner sets the timezone during setup and can change it later. ## Projects A project is one website or app. Everything that Ottertrail stores belongs to one project: events, errors, replays, traces, logs, metrics, and uptime checks. Each project has two keys: | Key | Form | Where it goes | What it allows | | --- | --- | --- | --- | | Public key | `pk_` and 32 hex characters | In your pages, on the tracker's script tag | Sending browser events only. It cannot read data. | | Secret key | `sk_` and 32 hex characters | On your servers and in your build, never in a page | Server-side events, source map uploads, OpenTelemetry data, and user ID signatures | A project also has a list of **allowed hostnames**, such as `example.com` and `www.example.com`. The instance accepts browser events only from pages on these hostnames. The match is exact: `example.com` does not allow `www.example.com`. A new project accepts no browser events until you add its hostnames. ## Environments and releases The same app can run in several places: the live site, a staging site, or a developer's computer. Each event can name its **environment**, such as `staging`, and its **release**, such as `1.4.2`. An event without an environment counts as `production`. Reports show one environment at a time, so test traffic does not mix into the live numbers. The tracker sets both with script attributes. See the [tracker reference](/reference/tracker/). Servers set them in their OpenTelemetry resource attributes. See [Send telemetry](/monitoring/sending-telemetry/). ## People Nobody can sign up to an instance. The owner creates the first account with a one-time setup link from the server. Other people join by invitation links that an owner or admin makes in the dashboard. | Role | What it can do | | --- | --- | | Owner | Everything. There is one owner. Only the owner changes the instance settings. | | Admin | Everything except the instance settings and changes to the owner. Admins see the Storage and Notification channels tabs. | | Member | Only the projects and areas that an owner or admin gives them. | A member gets access to each area at a level: none, view, or manage. The areas are web analytics, product analytics, errors, replays, users, monitoring, and uptime and alerts. Members never see project keys, project settings, or the instance settings. The next pages explain [the dashboard](/introduction/the-dashboard/), [the overview](/introduction/overview/), and [project settings](/introduction/project-settings/). --- # The dashboard Section: Introduction. Source: https://docs.ottertrail.app/introduction/the-dashboard/ > The workspace and a project's menu, and how reports, lists, and settings work on every screen of the dashboard. The dashboard is the website of your instance, at its own address, such as `https://analytics.example.com`. Every screen in it is one of three kinds: a report, a list with details, or settings. This page explains each kind once. The pages for each feature link here. ## The workspace and a project The dashboard has two levels. - **The workspace** holds what belongs to the whole instance. Its menu, under the instance's name, has **Projects** (the list of projects), **Members** and **Settings** for the owner and admins, and **Design system**, a reference of the dashboard's parts. - **A project** holds one website or app. Inside a project, the sidebar shows the project's own menu: **Overview** first, then the modules (Web analytics, Speed, Heatmaps, Users, Errors, Replays, Traces, Logs, Metrics, Services, Databases, Hosts, Uptime, Alerts, Product analytics), and the project's **Settings** last. A member sees only the pages of the areas they were given. See [Members and roles](/team/members-and-roles/). At the top of a project's menu, the project switcher opens another project, and **All projects** returns to the workspace. The switcher keeps the page you are on: from one project's web analytics for the last 90 days, it opens the other project's web analytics for the last 90 days. The header shows the project's name and the page's title. At the foot of the sidebar are your name, your email address, **Sign out**, and a badge that says whether the API answers. A project opens on its [overview](/introduction/overview/). A member without any of the overview's areas lands on the first page they may open. The instance's home page opens the project that this browser showed last. Ctrl B (⌘ B on a Mac), or the button at the left of the header, collapses the sidebar to icons. The browser remembers the choice. ## Reports Web analytics, Speed, Heatmaps, Product analytics, Services, Databases, Hosts, Metrics, and the Overview are reports. A report reads from top to bottom: 1. **The filter bar**, pinned under the header. It holds the period, the environment (once another environment than production has events), the active filters, and, at the end, the days the report covers and the instance's timezone. The days follow the instance's timezone, not your browser's. 2. **A row of figures.** Under a figure, its change from the period before: an arrow and a size, such as "12%". A change shows only when the counts behind it are large enough, because a few events make any percentage look large. A figure whose period before had nothing reads "New". Colour does not mark a change as good or bad. 3. **Short charts**, wide and low. **Show the numbers** opens the chart's data as a table. Where a chart can show more than one measure, a row of buttons beside its title switches between them, and the chosen button is filled. 4. **Tables**, side by side when the content area is wide enough, most first. Many lists show their first 10 rows, and **Show all** opens the full list with a search. In a table whose rows each open a page, such as the metrics, the hosts, a database's query shapes, or a service's routes, a click anywhere on a row opens it. The period, the environment, and the filters are in the page's address. A copied link opens the same view, and the Back button returns to the view before. See [Web analytics reports](/web-analytics/reports/) for the filters and the periods of the main report. ## Lists and details Errors, Replays, Traces, Logs, Users, Uptime, and Alerts are lists with details. The list is on the left, and the selected item is on the right. You can drag the border between them. - Nothing is selected when you arrive. The right pane shows a summary of the list: counts, what needs attention, or, when the list is empty, how to start. - Click anywhere on a row to show the item on the right. The keyboard and screen readers use the item's name, which is the row's link or button. - A button or switch inside a row, such as an alert rule's switch or a check's Pause, does only its own action. - Ctrl-click (⌘-click on a Mac) or a middle click on a row opens the item's own page in a new tab, and leaves the list as it was. - The selected item is in the page's address, so a reload keeps it, and a link opens it. - Filters at the top narrow the list. These keys work while the focus is not in a text field, an open list, a menu, or a dialog: | Key | What it does | | --- | --- | | `j` | Selects the next item. With nothing selected, it selects the first. | | `k` | Selects the previous item. | | `Esc` | Clears the selection and shows the summary again. | | `e` | On Errors only: resolves the selected error group, or reopens it. | The filter bar lists the keys on wide screens. Every item also has a page of its own, for a link to send to a teammate. Quick actions on a row, such as turning an alert rule off or pausing a check, apply at once. When you delete the selected item, the next item in the list is selected. ## The save rule Project settings, the instance's Settings, and a member's access are forms in sections. Each form has a Save bar at the foot of the screen, and every form follows the same rule: - Save stays disabled until you change something in the section. It is disabled again when you undo the change. - While there is a change, the bar says "Unsaved changes" and shows **Discard**. Discard puts back the saved values. - A tab with unsaved changes shows an **Unsaved** badge. Moving between tabs keeps your edits. - While the request runs, the bar says "Saving…". A failed save shows the reason and keeps your edits. - If someone else changes the same section while you edit it, the bar says so and offers **Load the new values**. - Leaving the page with unsaved changes asks first: "Leave without saving?", with **Stay on this page** and **Leave and discard**. Closing or reloading the browser tab gets the browser's own question. Actions that cannot be undone, such as deleting a project or replacing a key, are not part of a form. Each one asks for confirmation in a dialog first. ## On a phone The dashboard works at any width, from a phone to a wide screen. - In a window under 60rem wide (960 pixels at the default font size), the sidebar is a menu behind the button at the left of the header. Choosing a page closes it. - On a phone, the filter bar scrolls away with the page, the figures sit in two columns, and wide tables scroll inside themselves with the first column pinned. - In a window under 64rem wide, a list fills the screen, and choosing an item opens the item's own page. Back returns to the list. When the window grows wider again, the selected item shows beside the list as before. - The row of settings tabs scrolls sideways. --- # The overview Section: Introduction. Source: https://docs.ottertrail.app/introduction/overview/ > The project's first page, with ten widgets on errors, uptime, servers, speed, goals, users, and traffic, and how to arrange them. **Overview** is the first page in a project's menu, and the page a project opens on. It sums up the project on one screen: whether something is broken, and whether the business is moving. Each widget links to the page that explains its figures. ## The widgets The widgets are in this order by default. The first four show whether the product is healthy. The next five show whether the business is moving. The last one explains the traffic. | Widget | What it shows | | --- | --- | | Needs attention now | Alerts firing now, checks that are down, and TLS certificates that expire within 14 days or have expired, when no alert covers them yet. With nothing wrong, how many checks are up. | | New and returning errors | Occurrences, error groups first seen in the period, regressed groups, and the unresolved groups with the most users. | | Uptime and response time | Each check's state, its uptime in the period, its incidents, and its last response time. | | Server requests, failures and p95 | The five busiest services: requests, the share that failed, and the 95th percentile duration. | | Page speed | LCP, INP, and CLS at the 75th percentile for each kind of device, with a rating. | | Main goal | The project's main goal: visitors, conversion, and times reached. Without a main goal, the new signed-in users. | | Traffic | Visitors, visits, and pageviews, and visitors per day. | | Goals and conversion | Each goal's visitors, times reached, and conversion. | | Signed-in users | Active and new signed-in users, and the week 1 and week 4 retention of the last six weekly cohorts. | | Top sources and pages | The five sources and the five pages with the most visitors. | On a wide screen, the widgets sit in two columns. On a phone, they sit in one column, and a wide table scrolls inside its widget. ## The period and the comparison The overview shows **Last 7 days** by default. **Today** and **Last 30 days** are the other choices. Each figure is compared with the period right before. A period that is still running is compared up to the same moment of the period before. The filter bar shows both ranges and the instance's timezone. - A change shows only when the larger of the two counts behind it reaches a minimum: 10 for errors, and 20 for page loads, requests, visitors, and users. - A figure whose period before had nothing reads "New". - A change is an arrow and a size. Colour marks only what a rule or a threshold calls bad: a firing alert, a check that is down, a poor Web Vitals rating, or a regressed error. Server changes are not judged; your [alert rules](/uptime-and-alerts/alert-rules/) do that. - Uptime shows incidents only. There is no uptime target. - Page speed rates a device only from 20 page loads. Below that, it says "Too few page loads to rate". A device's rating is the worst rating of its three metrics. - Visitors count a person once for each day they visited, as everywhere in web analytics. - Sources and pages are not compared with the period before. The bounce rate and the visit duration are on the [web analytics report](/web-analytics/reports/), not on the overview. The overview shows production, the default environment. It has no environment picker yet. ## The main goal The Main goal widget starts the business figures. The owner or an admin chooses the main goal in the project's **Settings**, on the **General** tab, from the project's goals. The widget's **Choose the main goal** link opens that tab. Goals are added on the web analytics report. See [Goals](/product-analytics/goals/). Without a main goal, the widget shows the new signed-in users: those whose first event fell in the period. Deleting the goal that is the main goal clears the setting. ## Who sees what Each widget belongs to an area: uptime and alerts, errors, monitoring, web analytics, or product analytics. A member sees only the widgets of the areas they were given. The others are not shown at all. A member with none of these areas sees "Nothing on your overview", with links to the pages they can open, and the project opens on their first page instead. See [Members and roles](/team/members-and-roles/). ## Arrange your overview 1. Select **Edit overview**. 2. Use **Move up**, **Move down**, and **Hide** or **Show** on each widget. Each change applies and is saved at once. 3. Select **Done**. **Reset to default** puts back the default order. The dashboard does not load a hidden widget's data. Your layout belongs to you and this project. It follows you to any browser. Other people's overviews do not change. Each widget loads on its own. If one fails, it shows the error with **Retry**, and the other widgets stay. A widget with nothing to show says why: nothing set up yet, with a link to the page that explains how, or nothing in the period. Not available yet: settings for each widget (which goal, services, or checks), a default layout for a whole project, an overview across projects, and an environment picker. --- # Project settings Section: Introduction. Source: https://docs.ottertrail.app/introduction/project-settings/ > The seven tabs of a project's Settings page, what each one holds, and the Danger zone. Each project has its own **Settings** page, the last item in the project's menu. The owner and admins open it. Members do not see it. The page has seven tabs. The chosen tab is in the page's address, so a link can open a tab directly. A new project opens on **Install**. Links elsewhere in the dashboard open the right tab, such as "Source maps settings" under a stack trace, or "Choose the main goal" on the overview. | Tab | What it holds | More | | --- | --- | --- | | **Install** | The tracker snippet and the public key to copy, **Copy setup prompt** for a coding agent, whether events arrive, and the **Heatmaps** setting. | [Add the tracker](/get-started/add-the-tracker/), [Heatmaps](/web-analytics/heatmaps/#turn-on-heatmaps) | | **General** | The project's name, its allowed sites, how long it keeps events, and its main goal. | Below | | **Your server** | The secret key, and the switch that accepts only user IDs signed by your server. | [Signed user IDs](/users/signed-user-ids/), [Server-side events](/product-analytics/server-side-events/) | | **Spam and bots** | Ignoring visits from data centers, blocked addresses, blocked referrers, and deleting spam visits. | [Spam and bots](/web-analytics/spam-and-bots/) | | **Source maps** | The releases with source maps, their files and sizes, and how to upload. | [Source maps](/errors/source-maps/) | | **Session replay** | Off or Around errors, and the project's stored replays. | [Turn on session replay](/session-replay/turning-it-on/) | | **Danger zone** | Replacing the keys, and deleting the project. | Below | Each form on these tabs has its own Save bar and follows [the save rule](/introduction/the-dashboard/#the-save-rule). Save stays disabled until you change something, **Discard** undoes your edits, a tab with unsaved edits shows **Unsaved**, and leaving the page with unsaved edits asks first. On the Install tab, only the Heatmaps section is a form. The Danger zone has no form. ## General - **Name**: the project's name in the sidebar and the project switcher. - **Allowed sites**: one hostname per line. The instance accepts events only from pages on these hostnames, compared exactly. `example.com` and `www.example.com` are separate entries, and there are no wildcards. You can paste a full address: the form keeps only its hostname. A change applies within a minute. **Open on your site**, on the Heatmaps report, opens pages on these hostnames too. - **Keep events**: Forever (the default), 6 months, 1 year, 2 years, or 5 years. When you choose a shorter time than before, the form says before you save that older events will be deleted for good within a few hours. Heatmap data is kept 90 days, whatever this setting. - **Main goal**: the goal that the [overview](/introduction/overview/) starts its business figures with. Without one, the overview starts with new signed-in users. Goals are added on the web analytics report. See [Goals](/product-analytics/goals/). Select **Save changes** to save the tab. ## Danger zone The Danger zone holds three changes that cannot be undone. Each one asks for confirmation first. | Action | What happens | | --- | --- | | **Replace public key** | The project gets a new public key and keeps its data. Pages with the old snippet can no longer send events, so put the new snippet on your site right after. The Install tab shows it at once. | | **Replace secret key** | Servers that use the old secret key are refused at once, and user IDs signed with it no longer count. Give your servers the new key. | | **Delete project** | Deletes the project and every event it has received. Type the project's name to confirm. Its reports cannot be opened from that moment, and the instance deletes its events from the database within a minute, and from the disk usually within 6 hours. | Deleted events can stay in your [backups](/self-hosting/backups/) until you delete those backups. --- # Get started Section: Get started. Source: https://docs.ottertrail.app/get-started/ > The steps from an empty server to data in the dashboard, and a prompt that gives the same steps to a coding agent. To use Ottertrail, you install an instance, create a project, and add the tracker to your site. ## Set up with a coding agent If you use a coding agent, copy this prompt into it. Replace the two values in angle brackets first: - **Instance URL:** the address where you open your Ottertrail dashboard, such as `https://analytics.example.com`. - **Public key:** the key that starts with `pk_`. It is in the project's settings in the dashboard, beside the install snippet. ```text Add Ottertrail to this app. Read the instructions for agents at https://docs.ottertrail.app/llms.txt before you change anything. This project's Ottertrail instance is and its public key is . Add the tracker to every page. Name signed-in users, with the signature made on the server. Report the errors the app catches. Upload source maps when the app builds. Send the server's traces, logs and errors over OpenTelemetry. Read the secret key from the OTTERTRAIL_SECRET_KEY environment variable. Never put it in client code or in a commit. ``` The prompt tells the agent to read the secret key from the `OTTERTRAIL_SECRET_KEY` environment variable. The secret key starts with `sk_`, and it is in the project's settings too. Set the variable where your servers and your build run. Keep the key out of your repository. Agents can also read these docs as plain text: [`/llms.txt`](https://docs.ottertrail.app/llms.txt) lists every page, and [`/llms-full.txt`](https://docs.ottertrail.app/llms-full.txt) holds them all in one file. ### The agent skill Some coding agents load instructions as a skill. The Ottertrail skill gives the same steps in that format. It is in the `skills/ottertrail/` folder of the documentation's repository. You can install it when that repository is public. ## Set up by hand 1. [Install Ottertrail](/get-started/install/) on a Linux server with Docker Compose. 2. Do [the first start](/get-started/first-start/): create the owner account and download the location data. 3. [Create a project and add the tracker](/get-started/add-the-tracker/): allow your site's hostnames, and add the tracker snippet to your site. The [tracker reference](/reference/tracker/) lists every option. 4. Optional: [name signed-in users](/users/naming-users/), [report errors](/errors/browser-errors/), [upload source maps](/errors/source-maps/), and [send telemetry from your servers](/monitoring/sending-telemetry/). --- # Install Ottertrail Section: Get started. Source: https://docs.ottertrail.app/get-started/install/ > Install a self-hosted Ottertrail instance on a Linux server with Docker Compose, from a GitHub release. An Ottertrail instance runs on one server with Docker Compose. The install is a folder with four files from a GitHub release and a settings file, `.env`. You do not need a copy of the source code. ## What you need - A Linux server with Docker Engine and **Docker Compose 2.23.1 or later**. Run `docker compose version` to see your version. - About **8 GB of memory**. ClickHouse, the database for events and telemetry, uses at most 40% of it. - A domain or subdomain for the instance, such as `analytics.example.com`. Point its DNS `A` record (and `AAAA` record for IPv6) at the server. - Ports **80 and 443** open to the internet. Caddy, the web server in the stack, uses them to get a TLS certificate from Let's Encrypt. Browsers send events to port 443. No other port must be open, except SSH. - Outgoing HTTPS, so that the worker can download the location data from DB-IP and the cloud providers. Without it, the instance works, but events have no location and visits from data centers are not recognised. See [Location data](/self-hosting/location-data/). :::note[Podman] Podman works with Docker Compose. `podman compose` runs Docker Compose when it is installed. The separate tool `podman-compose` cannot run Ottertrail's Compose file, because it skips the settings files inside it. ::: ## What runs | Service | What it does | Open to the internet | | --- | --- | --- | | `caddy` | Gets and renews the TLS certificate, redirects HTTP to HTTPS, and passes requests to the API. | Ports 80 and 443 | | `api` | Serves the dashboard, the tracker script, and the API. | No | | `worker` | Runs uptime checks, evaluates alert rules, sends notifications, deletes expired data, joins session replays, checks the disk, and keeps the location data current. | No | | `migrate` | Updates the database schemas, then stops. | No | | `postgres` | PostgreSQL: accounts, projects, and settings. | No | | `clickhouse` | ClickHouse: events, errors, traces, logs, and metrics. | No | | `garage` | Garage, an S3-compatible object store for source maps and session replays. Optional. | No | ## Download the release files 1. Make a folder for the instance, and go into it: ```sh mkdir ottertrail && cd ottertrail ``` 2. Download the Compose file, the example settings, and the backup scripts from the latest release: ```sh curl -fLO https://github.com/ottertrail/ottertrail/releases/latest/download/compose.yaml curl -fLO https://github.com/ottertrail/ottertrail/releases/latest/download/example.env curl -fLO https://github.com/ottertrail/ottertrail/releases/latest/download/backup.sh curl -fLO https://github.com/ottertrail/ottertrail/releases/latest/download/restore.sh ``` 3. Make the scripts executable: ```sh chmod +x backup.sh restore.sh ``` 4. Make your settings file from the example, and make it private: ```sh cp example.env .env chmod 600 .env ``` Each release's `compose.yaml` runs the image of that release, `ghcr.io/ottertrail/ottertrail`, for `linux/amd64` and `linux/arm64`. ## Fill in the settings The `.env` file holds the passwords and keys of your instance. Keep it private. 1. Set `OTTERTRAIL_DOMAIN` to your domain, without `https://`: ```sh OTTERTRAIL_DOMAIN=analytics.example.com ``` 2. Make a different random value for each of these six settings. Run the command one time for each setting: ```sh openssl rand -hex 32 ``` Put the values in `POSTGRES_PASSWORD`, `CLICKHOUSE_PASSWORD`, `AUTH_SECRET`, `OBJECT_STORE_SECRET_ACCESS_KEY`, `GARAGE_RPC_SECRET`, and `GARAGE_ADMIN_TOKEN`. Use hex values: they are safe inside the database URL. `GARAGE_ADMIN_TOKEN` is optional. With it, the dashboard shows how much Garage really stores, and the instance keeps a quota on Garage's bucket. See [Storage and warnings](/self-hosting/storage/). 3. Make the object store's access key ID. Garage needs this form: ```sh printf 'GK%s\n' "$(openssl rand -hex 12)" ``` Put the value in `OBJECT_STORE_ACCESS_KEY_ID`. The example settings turn on Garage, the object store on the same server, for source maps and session replays. To use Cloudflare R2, Amazon S3, or no object store, read [Object storage](/self-hosting/object-storage/) before the first start. Alert email is optional. See `SMTP_URL` in the [configuration reference](/self-hosting/configuration/). Every other setting is in the same reference. ## Start the instance Go on to [The first start](/get-started/first-start/). --- # The first start Section: Get started. Source: https://docs.ottertrail.app/get-started/first-start/ > Start the instance, create the owner account with the setup link, and check that the location data arrived. Do these steps one time, after you [install Ottertrail](/get-started/install/). Run each command in the instance's folder, next to `compose.yaml` and `.env`. ## Start the services 1. Start the stack: ```sh docker compose up -d ``` Compose downloads the images. Then it starts the databases, `migrate`, the API, the worker, and Caddy. 2. Look at the state of the services: ```sh docker compose ps ``` `migrate` must show `Exited (0)`. `api` must show `healthy`. With Garage, `garage` must show `healthy` too. If a required setting is empty, Compose stops before it starts anything, and it names the setting: `set … in .env`. If an object store key is empty, `migrate` or `garage` stops instead. Read the service's log to find the cause: ```sh docker compose logs migrate docker compose logs garage ``` Fill in the setting, then run `docker compose up -d` again. ## Create the owner account 1. Make the setup link: ```sh docker compose exec api node dist/setup.mjs ``` The command prints a link such as `https://analytics.example.com/setup#token=…`. 2. Open the link in your browser within one hour. The link works one time. 3. Enter your **Name** and **Email**. 4. Enter an **Instance name**. It shows at the top of the dashboard's sidebar. Use your company or team name, for example. 5. Enter a **Password** of at least 12 characters, and the same password in **Confirm password**. 6. Check the **Timezone**. Your browser's timezone is selected. Reports count days in this timezone. 7. Select **Create account**. The dashboard signs you in as the owner. The page also says whether email for alerts is set up on the server. Alert email is optional: alerts can go to webhooks without it. See `SMTP_URL` in the [configuration reference](/self-hosting/configuration/#alert-email). If the link expires, run the command again. The new link replaces the old one. After the owner exists, the command refuses to make a link. You can change the instance name and the timezone later: open **Settings** from the workspace menu, on the **General** tab. Only the owner sees this tab. ## The location data Ottertrail finds each visitor's country, region, and city in a location database from DB-IP. It also ignores browsers that run in cloud and hosting providers' data centers, from a list of their address ranges. Neither file comes with the image. You do not need to download them. The worker downloads both files when it first starts, and the API loads them within 10 minutes, without a restart. Until then, the instance stores events without a location, and it does not recognise visits from data centers. After that, the worker keeps both files current by itself: the location database each month, and the data-center ranges each week. The server must reach DB-IP and the providers over HTTPS. To check that the files arrived, open **Settings**, then the **Location data** tab. Each file shows **Loaded** when the API uses it. On an instance without internet access, the owner turns the automatic updates off there, and updates the files by hand. See [Location data](/self-hosting/location-data/). ## Next steps - Create a project in the dashboard, and add its tracker snippet to your site. See [Add the tracker](/get-started/add-the-tracker/). The [tracker reference](/reference/tracker/) lists every option. - Invite your teammates. See [Invitations](/team/invitations/). - Choose the notification channels for [storage warnings](/self-hosting/storage/), so that you hear before the disk is full. - Plan your [backups](/self-hosting/backups/). Ottertrail does not make backups automatically. - Read the [security notes](/self-hosting/security/). --- # Create a project and add the tracker Section: Get started. Source: https://docs.ottertrail.app/get-started/add-the-tracker/ > Create a project in the dashboard, allow your site's hostnames, and add the tracker snippet. A project is one website or app. Each project has its own snippet, keys, and data. The owner and admins can create projects. ## 1. Create a project 1. Open **Projects** in the sidebar. The list shows each project with its last event, its allowed sites, how long it keeps events, and when it was created. 2. Select **New project**. 3. Enter a **Name**, such as "Main site". 4. Under **Allowed sites**, enter your site's hostnames, one per line, such as `example.com` and `www.example.com`. You can also add them later. 5. Select **Create project**. The new project opens on the **Install** tab of its Settings. ## 2. Allow your site's hostnames The project accepts events only from pages on its allowed sites. A project without any accepts nothing: the Install tab then says "No allowed sites yet", and the Projects page says "None: events are refused". To change the list, open the project's **Settings**, then the **General** tab. Under **Allowed sites**, enter one hostname per line: - Matches are exact. `example.com` does not allow `www.example.com`. List both if both serve pages. - Wildcards such as `*.example.com` are not supported. List each subdomain. - You can paste a whole address, such as `https://example.com/pricing`. The form keeps only its hostname. - Internationalized names are stored in their ASCII form: `bücher.example` becomes `xn--bcher-kva.example`. - To test on your own computer, add `localhost`. Then select **Save changes**. The form follows [the save rule](/introduction/the-dashboard/#the-save-rule). A change applies within a minute. ## 3. Add the snippet The **Install** tab has the snippet to copy: ```html ``` Copy it into the `` of every page of your site. In most sites that is one layout or template. - `src` loads the tracker from your instance. - `data-key` is the project's public key. It is not a secret: it only lets pages on the allowed sites send events, and it cannot read data. - `data-host` is where the events go. - Keep `defer`, so the script does not hold up the page. The tracker records pageviews and how long each page is visible. It sets no cookies and stores nothing on the visitor's device. It also reports JavaScript errors and measures [Web Vitals](/web-analytics/web-vitals/). To record where visitors click and how far they scroll, see [Heatmaps](/web-analytics/heatmaps/). The [tracker reference](/reference/tracker/) lists every attribute. Under the snippet, "Environment, release, and user (optional)" names three attributes you can add later: - `data-environment="staging"` on a test or staging site, so its events never mix with the live site's. See [Environments and releases](/web-analytics/environments-and-releases/). - `data-release="1.4.2"`, your app's version. - `data-user-id="42"`, your own ID for the signed-in user. See [Name signed-in users](/users/naming-users/). If you use a coding agent, **Copy setup prompt** copies instructions for it with this instance's address and the public key. It never includes the secret key. See [Get started](/get-started/). ## 4. Check that events arrive Until the first event arrives, the Install tab shows **Waiting for the first event**. It checks again every 10 seconds. Open your site in a browser. Within about 10 seconds the badge turns into **Receiving events**, with the time of the last event. Then open **Web analytics** in the project's menu to see the visit. If nothing arrives: - **Check the hostname.** The page's hostname must be in the allowed sites exactly. Events from another hostname are refused with 403, which you can see in the browser's network tools. - **Use a normal browser.** Visits from `curl`, headless browsers, and servers in a cloud are ignored as bots. See [Spam and bots](/web-analytics/spam-and-bots/). - **Check your blocked addresses.** If your own address is in the project's "Blocked addresses", your visits are ignored. - **Look in the browser's console.** The tracker writes a warning there when `data-key` or `data-host` is missing, or when `data-environment` is not valid. ## Next steps - [Name signed-in users](/users/naming-users/) - [Send custom events](/product-analytics/custom-events/) - [Report errors from the browser](/errors/browser-errors/) - [Send telemetry from your servers](/monitoring/sending-telemetry/) --- # Web analytics reports Section: Web analytics. Source: https://docs.ottertrail.app/web-analytics/reports/ > The numbers on the Web analytics page: visitors, visits, pageviews, bounce rate, time engaged, sources, breakdowns, and filters. Open a project, then **Web analytics** in its menu. The page shows what the tracker recorded on your site for one period: how many people came, where they came from, and what they looked at. Every number is computed from the stored events when you open the page, and the page loads its data again every minute while it is open. The page is a report, laid out as the other reports are: the filter bar at the top, a row of figures, a chart, then tables. See [Reports](/introduction/the-dashboard/#reports) for the parts all reports share. To see this page, a member needs the web analytics area. The Goals table at the bottom needs the product analytics area too. See [Members and roles](/team/members-and-roles/). ## The filter bar - **The period:** Today, Last 7 days (the default), Last 30 days, Last 90 days, Last 12 months, or "Custom range…" for days you choose. A custom range covers at most 366 days. - **The environment:** a second picker shows once another environment than `production` has events in the period. See [Environments and releases](/web-analytics/environments-and-releases/). - **The filters:** the active filters, or a line that says how to add one. - **The days and the timezone:** the days the page covers, such as "10 to 16 Nov 2026", and the instance's timezone. ### Days in the instance's timezone A report covers whole days in the instance's timezone, not in your browser's. The owner sets the timezone in the instance's Settings. A day that is 23 or 25 hours long, when clocks change for daylight saving, counts correctly. Days without data show as zero. The last day of a period that ends today is not over yet. An event can also arrive up to 24 hours after it happened, and the report places it when it happened, so a recent day can still grow a little. ### Custom range "Custom range…" opens a dialog with the first and last day. Click the first day in the calendar, then the last. You can also type the days, day first (`DD/MM/YYYY`). The fields add the slashes for you. A custom range keeps your filters. Choosing a preset period again removes them. ## The figures | Figure | What it counts | | --- | --- | | Visitors | Distinct visitors. A visitor is recognized for one day only, so a person who comes on 3 days counts 3 times. | | Visits | Visits that started in the period. A visit ends after 30 minutes without an event. | | Pageviews | Pages viewed. A change only to the query string or the fragment is not a new pageview. | | Views per visit | Pageviews in those visits, divided by the visits. | | Bounce rate | The share of visits with one pageview and no custom event. A long read of one page is still a bounce. | | Visit duration | The average time from a visit's first event to its last. A bounce counts as 0 seconds unless the page reported how long it was visible. | | Time engaged | The average time per visit that pages were visible. Time in a background tab or with the phone locked does not count. | Visitors and pageviews count the events in the period. Visits, the bounce rate, and the durations count the visits that started in it. A visit from 23:50 to 00:20 counts on the first day, while its pageview at 00:05 counts on the second. Ottertrail sets no cookies, so it tells visitors apart by a daily ID. The count is an estimate: one person counts twice when their address changes during the day (a phone that moves from Wi-Fi to mobile data, a VPN), and several people count once when they share an address and the same browser version. A visit in progress at midnight counts as two visits. Definitions of a bounce differ between tools, so bounce rates from different tools are not comparable. ### The change from the period before Under each figure, an arrow and a size show its change from the period right before: as many days, in the same timezone, with the same filters. The bounce rate changes in points ("6 pts"), the others in percent ("12%"). - A period that is still running is compared up to the same moment of the period before. At 15:00, the last 7 days are compared with the 7 days before them up to 15:00 on their last day. The note under the figures names the days compared and that time. - A change shows only when the counts reach 20 in either period. With fewer, a percentage would mislead. - "New" means the period before had none. - The arrows are not colored. Up is not always better: a higher bounce rate is worse. Only the figures are compared. The chart and the tables show the current period only. ## The chart The chart shows visitors per day. Choose Visits or Pageviews beside its title to show those instead. Hover over the chart to see all three numbers for the nearest day. "Show the numbers" opens the same data as a table. A one-day period draws no line. With the keyboard, Tab moves to the chart, and the arrow keys, Home, and End move between days. A screen reader reads each day with its three numbers. ## The tables The tables list the most visitors first, with a bar for each row's visitors. Some have buttons in their header that switch the list. | Table | Lists | | --- | --- | | Pages | Top pages (views and visitors per path), Entry (the first page of each visit), and Exit (the last page) | | Sources | Sources, and Campaigns (the `utm_campaign` tag) | | Locations | Countries, Regions, and Cities | | Devices | Devices, Browsers, and Systems (operating systems) | | Releases | The release of each visit's first event. See [Environments and releases](/web-analytics/environments-and-releases/). | | Custom events | Each event that your site sends with `track()`, its visitors, and how often it happened. See [Custom events](/product-analytics/custom-events/). | | Goals | Each goal's visitors, conversion, and events. See [Goals](/product-analytics/goals/). | In the Pages table, each path has a small heatmap icon after it, named "Heatmap of" and the path. It opens the page's [heatmap](/web-analytics/heatmaps/) for the same period and environment. Selecting the path itself still filters this page. Each table shows its first 10 rows. When it shows all 10, "Show all" opens the whole list in a dialog: 50 rows at a time, "Load more" for the next, and a search by name. A missing value, such as a visit without a location, shows as "Unknown". A visit without a campaign shows as "No campaign". ### Sources A visit's source is the first of these that exists: 1. The `utm_source` tag of the page's address, such as `?utm_source=newsletter`. 2. The referring site's hostname without `www.`: a link from `https://www.google.com/search` counts as `google.com`. An Android app sends its package name, such as `com.google.android.gm`. 3. "Direct / none": no referrer, as with a typed address, a bookmark, or an app that sends none. A referrer on one of the project's own allowed sites is not a source. It means the visit began on a page of your own site, such as a tab left open for more than 30 minutes, so it counts as direct. The five UTM tags (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`) are the only parts of the query string that Ottertrail keeps. The rest of the query string, and the fragment, never reach the reports. ### Locations and devices The country, region, and city come from the visitor's IP address, looked up on your instance when the event arrives. The address itself is never stored. A country is close to a fact. Regions and cities are estimates: mobile networks, VPNs, and iCloud Private Relay show where traffic leaves the network, not where the person is. A region or city keeps its country, such as "Springfield, US", because the same names exist in several countries. The browser, operating system, and device come from the browser's User-Agent. Only the operating system's name and the browser's major version are kept, because browsers now report fixed versions. An iPad that presents itself as a Mac counts as a tablet when it reports a touchscreen. ## Filters Select a name in any table to filter the page by it: a source, a country, a page, "Unknown", and so on. Every figure, the chart, and every table then count only the visits that match. Custom events cannot be used as filters yet. - A filter by a table row keeps exactly the visits that row counted. - A filter by a page keeps the visits with a pageview of that path, and counts all their pages. So a filter by `/pricing` shows what else the visitors who saw the pricing page looked at. - Several filters must all match. Active filters show in the filter bar, each with a button to remove it, and "Clear filters" removes them all. Filters are in the page's address, so you can link to a filtered view, reload it, and leave it with Back. A new period keeps the filters. Switching to another project keeps the period but drops the filters, because a page or campaign belongs to one project. When nothing matches, the page says so and offers to clear them. ## When there is nothing to show - A project without any events shows how to install the snippet. See [Create a project and add the tracker](/get-started/add-the-tracker/). - A period without events offers the last 12 months. - A period without events in another environment than `production` names the environment and suggests another. - If a load fails, the last numbers stay on the page, with the error and a Retry button. ## On a phone On a phone the figures sit two to a row, and each table row stacks, with its numbers labelled. See [On a phone](/introduction/the-dashboard/#on-a-phone). ## Not available yet - Hourly detail for one day. - A comparison in the chart and the tables. Only the figures are compared. - Custom events and event properties as filters on this page. --- # Environments and releases Section: Web analytics. Source: https://docs.ottertrail.app/web-analytics/environments-and-releases/ > Keep staging traffic out of the live numbers, and see which release each visit used. You may run the same site in several places: the live site, a staging site, a developer's machine. Each event says which place sent it (its **environment**) and which version of your site (its **release**). Reports show one environment at a time, so a test site never mixes into the live numbers. ## Name them on the script tag Add `data-environment` and `data-release` to the tracker's script tag: ```html ``` Both are optional. Every event from the page carries them. | Attribute | Rule | Without it | | --- | --- | --- | | `data-environment` | 1 to 64 letters, digits, `.`, `_`, or `-`, starting with a letter or digit, such as `production`, `staging`, or `pr-142`. Ottertrail stores it in lower case, so `Staging` and `staging` are one environment. | Events count as `production`. | | `data-release` | 1 to 200 characters, without spaces or control characters, as you name your versions: `1.4.2`, `web@2026.11.17+3f2a9c1`, a commit hash. Stored as you send it. | Events have no release. | The tracker checks both values as the instance does: - With an invalid environment, the tracker sends nothing and writes a warning in the browser's console. Its events would otherwise count as `production`. - With an invalid release, the tracker leaves the release out, writes a warning, and sends the events. So leave `data-environment` out on the live site, and set it on every other site. Set `data-release` from your build, so that it changes with each version. Source maps and errors use the same release: see [Upload source maps](/errors/source-maps/). Server-side events name their environment and release in the request body. See [Server-side events](/product-analytics/server-side-events/). ## Choose the environment in a report Reports show `production` unless you choose another environment. Once another environment has events in the period, the filter bar shows a second picker with the environments that have events, most events first. While another environment than `production` is shown, the picker stays, so there is always a way back. - The environment goes in the page's address as `env=staging`. It is left out for `production`. - Switching the environment keeps the period and the filters. - An environment is not a filter. It decides where the report looks, as the project does. Events of other environments never mix in. The Web analytics, Speed, Product analytics, Users, and Errors pages, and the monitoring pages, also show one environment at a time. Visits are worked out for one environment at a time too: a developer who opens the live site and then the staging site makes two visits, not one. ## The Releases table On the Web analytics page, the Releases table lists the release of each visit's first event, most visitors first. Select a release to filter the page by it: every figure and table then counts the visits that started on that release. While no visit in the period names a release, the table says how to add `data-release` instead of listing every visit as "Unknown". Once some do, visits without a release show as "Unknown". See [Web analytics reports](/web-analytics/reports/) for the other tables and filters. --- # Spam and bots Section: Web analytics. Source: https://docs.ottertrail.app/web-analytics/spam-and-bots/ > Which visits Ottertrail ignores as bots and spam, the project's Spam and bots settings, and deleting spam that got in. A project's public key is in every page of your site, so anyone can copy it and send events. Some events arrive that no person caused: crawlers, scripts, test runs, and referrer spam (visits that exist only to put a site's name in your list of sources). Ottertrail keeps most of them out of your numbers, and lets you delete what got in. ## What is ignored Ottertrail answers most caught events as if they were stored (202), so a sender has no reason to send them again. Those events are not stored, and they do not use up the project's event budget. The limit on events per client address is the exception: it answers 429 with a time to wait, and the tracker sends the events again then. Ottertrail stores nothing about the sender. | Measure | What it catches | Can you change it? | | --- | --- | --- | | Bots | Browsers that say they are automated in their User-Agent: search engine crawlers, link previews, monitoring tools, headless browsers, and HTTP libraries such as `curl`. A request without a User-Agent counts as a bot too. | No | | Data centers | Browser events from the addresses of cloud and hosting providers (below). | Yes: "Ignore visits from data centers" | | Blocked addresses | Browser events from addresses and ranges that you list, such as your office's. | Yes: "Blocked addresses" | | Referrer spam | Visits whose referrer is a known spam domain, or a domain that you list. | Your own list: "Blocked referrers" | | Events per client address | A client that sends events as fast as it can is held at 20 events a second, after a burst of 200. | No | | A daily cap per visitor | After one visitor has sent 5,000 events in a day, the rest of that day's events are not stored. A person sends a few dozen to a few hundred. | No | None of these applies to [server-side events](/product-analytics/server-side-events/). They come from your own server. ### Data centers People browse from homes, offices, and phones. Scrapers, headless browsers, and test runs run on servers rented from a cloud or hosting provider, often with the User-Agent of an ordinary browser. So a browser event from such an address is ignored like a bot. The address is checked when the event arrives and never stored. The list holds the published ranges of Amazon Web Services, Google Cloud, Microsoft Azure, Oracle Cloud, DigitalOcean, Akamai Cloud (Linode), and Vultr, and the networks of Hetzner, OVHcloud, Scaleway, Contabo, Alibaba Cloud, Tencent Cloud, and Huawei Cloud. While automatic location data updates are on (the default), your instance downloads the ranges again every week. See [Location data](/self-hosting/location-data/). Privacy relays, such as iCloud Private Relay, and CDNs, such as Cloudflare and Fastly, are not on the list. ### Referrer spam A browser batch with an event whose referrer is a listed domain, or a subdomain of one, is not stored. The whole batch goes, because its other events (time on the page, Web Vitals) belong to the same spam visit. A listed `semalt.com` catches `www.semalt.com`, but not `notsemalt.com`. The domains come from three lists: 1. A community list of known referrer spam domains, which ships with each Ottertrail release. Your instance never downloads it. 2. A short list of Ottertrail's own additions, which also ships with each release. 3. The project's own "Blocked referrers". A referrer on one of the project's own allowed sites is never spam, whatever a list holds. ## The Spam and bots tab Open the project's **Settings**, then the **Spam and bots** tab. The owner and admins can see and change it. Members cannot. The tab has a form with three settings, and "Delete spam" below it. The form follows [the save rule](/introduction/the-dashboard/#the-save-rule): "Save changes" stays disabled until you change something, and it saves all three settings together. A change applies from the next event. ### Ignore visits from data centers On by default. Turn it off if your visitors browse from a cloud: remote desktops such as Amazon WorkSpaces or Windows 365, some VPNs, and corporate proxies that run at these providers. With it off, bots that run in data centers count too. ### Blocked addresses One IPv4 or IPv6 address or range per line, at most 100, such as `203.0.113.7`, `198.51.100.0/24`, or `2001:db8::/48`. - A range can be at most a `/8` of IPv4 or a `/16` of IPv6. A wider range would block a large part of the internet by one wrong digit. - Ranges written as `start-end`, and addresses with a zone (`fe80::1%eth0`), are refused. - **Add my address** adds the address that your instance sees your browser come from. For an IPv6 address it adds its `/64`, since the same browser may use another address of that block tomorrow. If the address is already listed, it says so. Save to apply it. These are the only IP addresses that Ottertrail stores, and only because you typed them. Only the owner and admins see the list, it is never stored with events, and it is deleted with the project. Blocked addresses also drop session replay uploads from those addresses. Server-side events are never blocked. ### Blocked referrers One domain per line, at most 100. Each also blocks its subdomains. Known referrer spam is already ignored on every project, so list only what gets past it. - Write the domain without a scheme, a path, or a port. Ottertrail stores it in lower case, and internationalized names in their ASCII form. - A domain needs at least two labels. A common public suffix, such as `co.uk`, is refused, because it would block every site under it. - The project's own sites, or a parent of one, are refused: the field says the entry "would block your own site". - IP addresses are refused. Both lists are checked as you type, once you leave the field or try to save. A wrong line is named under the field, and Save sends nothing while one is wrong. ## Delete spam The rules above work from the next event. Spam that came before a rule, or that no rule catches, can be deleted afterwards, as whole visits. Deleting spam is permanent. It is outside the save rule: nothing is deleted until you confirm. 1. Choose the **First day** and **Last day**. The days are in the instance's timezone, and the last week is chosen at first. The period can cover at most 92 days, cannot end after today, and cannot start before the project's retention keeps events. 2. Enter at least one filter: **Referrer domain** (it also matches its subdomains), **Page path** (the exact path, as reports show it), or **Country** (a two-letter code, such as `DE`). Each filter you enter must match. "Count visits" stays disabled until you enter one, because without a filter every visit of the period would go. 3. Select **Count visits**. The tab says what a delete would take, for example: "12 visits match, with 40 events: 20 pageviews, 3 custom events, 2 errors, and 15 other events (time on page, Web Vitals). 1 session replay goes with them." 4. Select **Delete visits**. It stays disabled until there is a count of the filters as they are now: change a filter, and you count again. 5. The dialog names the counts and asks you to type the number of visits. Type it, then select **Delete permanently**. Afterwards the tab says how many visits and events were deleted, and the reports no longer count them. ### What is deleted - A visit goes when one of its events in the period matches every filter given. - The whole visit goes: its pageviews, custom events, errors, time on page, Web Vitals, and the session replays of its errors. Events of such a visit that fall just outside the period go too. - Server-side events belong to no visit and are never deleted here. - A visit still going on keeps the events that arrive after the delete. When the period ends today, the tab says so. Delete again later to take the rest. A delete takes at most 10,000 visits. When more match, the tab asks for a shorter period or narrower filters, so that you delete in parts. If the visits found no longer match the number you typed, nothing is deleted, and you count again. If a delete stops partway, the dialog shows the message: count again, then delete what is left. Deleted events can stay in backups until those backups are deleted. ## Testing your own site Some ways of testing send events that Ottertrail ignores: - **`curl` and HTTP libraries** announce themselves in the User-Agent, so their events count as bots. To send a test event with `curl`, pass a browser's User-Agent with `-A "Mozilla/5.0 …"`. - **Headless browsers** say `HeadlessChrome` in their User-Agent. Give automated browser tests a normal User-Agent. - **Tests in CI** usually run in a data center. GitHub Actions runners, for example, run in Azure. Tests that should count need a project with "Ignore visits from data centers" off. Use a separate project for them, or `data-environment`, so they stay out of the live numbers. - **Your own address** in "Blocked addresses" blocks your own tests too. ## Visits that the filters drop The measures also drop some visits that people made: - People in a cloud: remote desktops, some VPNs, and corporate proxies at the listed providers. Turn off "Ignore visits from data centers" if your visitors browse that way. - **Behind a proxy without `TRUST_PROXY`,** every request seems to come from the proxy's address, which may be in a cloud. Then every event is ignored. See [Configuration](/self-hosting/configuration/). - **A site that forwards its events through its own server** sends them all from that server's address, which is usually in a cloud. Such forwarding is not supported: every visitor would share the server's address, location, and visitor ID. - **Many people behind one address,** such as an office, a school, or a mobile carrier's shared address, share one limit of events per client address. On a busy site their events wait and are sent again. A short peak loses nothing, but a long one can. - **A blocked referrer catches only the first page.** A spam visit's later pages carry your own pages as referrers, so a bot that browses on leaves those pages behind. Delete them with "Delete spam". - **The lists know only the domains someone reported,** and bots on home connections, or at providers not listed, still count. ## Not available yet - A count of the caught bots and spam for each project over time. - Recognizing bots that pretend to be browsers from home connections or unlisted providers. - A limit of events per client address set for each project, for sites whose visitors share an address. --- # Web Vitals Section: Web analytics. Source: https://docs.ottertrail.app/web-analytics/web-vitals/ > How fast each page load felt, on the Speed page: LCP, INP, CLS, FCP, and TTFB. The tracker measures how fast each page load felt in your visitors' browsers. The **Speed** page, in a project's menu, shows the results. You need nothing beyond the tracker's snippet. ## What is measured | Metric | What it measures | Good up to | Poor above | | --- | --- | --- | --- | | Largest Contentful Paint (LCP) | When the main content appeared | 2.5 s | 4 s | | Interaction to Next Paint (INP) | How quickly the page responded to clicks, taps, and key presses | 200 ms | 500 ms | | Cumulative Layout Shift (CLS) | How much the content moved while loading | 0.1 | 0.25 | | First Contentful Paint (FCP) | When the first text or image appeared | 1.8 s | 3 s | | Time to First Byte (TTFB) | When the server's response started to arrive | 0.8 s | 1.8 s | LCP, INP, and CLS are the Core Web Vitals. FCP and TTFB help explain LCP: the main content cannot appear before the server responds and the browser starts to display the page. The thresholds are Google's. A value between "good" and "poor" needs improvement. The tracker sends one measurement for each page load, when the page is first hidden or left. A value not measured by then is left out: INP when the visitor did not interact, LCP when the page was hidden before its main content showed. A page that the browser restores from its back/forward cache is a new page load with its own values. ## The Speed page The Speed page is a report: the filter bar, then the figures, a chart, and two tables. See [Reports](/introduction/the-dashboard/#reports) for the parts all reports share. To see it, a member needs the web analytics area. - **The filter bar:** the period, the environment once there is a choice, and the device: All devices, Desktop, Mobile, or Tablet. - **The Core Web Vitals:** LCP, INP, and CLS, each at the 75th percentile (p75), with its rating (Good, Needs improvement, or Poor), a bar of the shares of good, needs improvement, and poor page loads, and how many page loads were measured. INP counts only page loads with an interaction. - **Measurements before LCP:** FCP and TTFB at the 75th percentile, with their ratings. - **LCP per day (p75):** a chart with a gap for each day without page loads. "Show the numbers" opens a table of every day. - **By device** and **Pages** (the 20 pages with the most measured loads): each row has its loads and the p75 of LCP, INP, and CLS, each with a rating icon. A page load counts for the page the visitor landed on. ### The 75th percentile The p75 is the value that 75% of page loads were at least as fast as. It shows what most visitors felt, without one very slow load pulling it up. A rating is of the value as shown, so "2.5 s" is never rated as over 2.5 seconds. The shares in a bar are rounded one by one, so the three can add up to 99% or 101%. ### Single-page apps The values belong to the page load, not to each page that a single-page app shows without a page load. The values count for the page the visitor landed on. Its INP and CLS include clicks and shifts on later pages of the app, until the page is first hidden. An early redirect, such as from `/` to `/en/`, does not lose the measurement. ## When the Web Vitals script does not load The tracker loads a second script, `v.js`, from beside its own address to measure Web Vitals. The Speed page stays empty when it does not load: - **A pinned tracker:** if the script tag has an `integrity` attribute, the tracker does not load `v.js`, because `v.js` cannot be pinned with it. - **A strict Content Security Policy:** the tracker gives `v.js` the script tag's `nonce`. A page that requires Trusted Types refuses `v.js`. Turn Web Vitals off there. Without page loads, the Speed page explains these cases itself. ## Turning Web Vitals off Add `data-vitals="off"` to the script tag. The tracker then does not download `v.js`, and sends no Web Vitals: ```html ``` Web Vitals are not web analytics: they make no visit, pageview, or custom event, and they are not part of a user's activity. `vitals` is a reserved event name: `track("vitals")` is refused. ## Not available yet - A comparison with the period before, as the Web analytics page has. - FCP and TTFB by device and by page. - Values of their own for the pages that a single-page app shows without a page load. --- # Heatmaps Section: Web analytics. Source: https://docs.ottertrail.app/web-analytics/heatmaps/ > Where visitors click on a page and how far they scroll, the Heatmaps report, and the heatmap drawn over your live site. Heatmaps show where visitors click on one page of your site and how far down they scroll. The **Heatmaps** report gives the figures for a page, a period, an environment, and a kind of device. **Open on your site** draws the same data over your live page, for you only. Heatmaps are off by default. A page sends heatmap data only when the project's setting is on and the tracker's script tag asks for it. ## What is recorded For each pageview that is recorded: - **Clicks, by element.** Each click with the main mouse button or a tap, up to 100 a pageview. Clicks after the 100th are only counted. A click made with the keyboard has no position, so it is not recorded. For each click, the tracker sends: - the element, as its place in the page: the tag names from the page's body down to the element, with a number when the element has siblings of the same tag, such as `body>main>section:2>div>a`; - the element's name, when your site gave it one with `data-ottertrail-name` ([below](#naming-elements)); - where in the element the click fell, as a share of its width and height; - the width and height of the window and the height of the page; - whether the click was a rage click; - the minute it happened. Times are kept to the minute, so the order of one visitor's clicks within a minute cannot be read back. - **Scroll depth.** One value a pageview: the deepest point the bottom of the window reached, as a share of the page's height. With it, the fold: the share of the page that showed without scrolling. - **Rage clicks.** A click is a rage click when it is the third or later of 3 or more clicks within 1 second and 30 pixels of each other. Rage clicks often mean that something did not respond. - **The page.** Its path, as for pageviews, and the environment and release of the script tag. In a single-page app, clicks and scroll depth belong to the path they happened on. A click inside a link, a button, a form field, a label, or an element with a role such as button, tab, or checkbox counts for that element. So a click on a button's icon counts for the button. Only standard HTML and SVG tag names are sent. Any other tag, such as a custom element ``, is sent as `x`, because a site's own tag names can contain words. ### What is never recorded - The text of any element, and anything typed or chosen in a form. - `id`, `class`, `href`, `src`, `title`, `alt`, `aria-*`, and every other attribute, except `data-ottertrail-name`. - Query strings (other than the UTM tags, as for pageviews) and fragments. - A visitor ID or a session ID. A heatmap record cannot be linked to a visitor, a visit, or a user. - Mouse movement. Ottertrail records clicks and scrolling only. The tracker stores nothing on the visitor's device for heatmaps: no cookies and no local storage. ## Turn on heatmaps Two switches are needed, as for session replay. ### 1. The project's setting 1. Open the project's **Settings**, and stay on the **Install** tab. 2. Under **Heatmaps**, turn on **Record clicks and scroll depth**. 3. Select **Save changes**. Only the owner and admins can change project settings. The setting follows [the save rule](/introduction/the-dashboard/#the-save-rule). While the setting is off, the instance refuses heatmap data, and the page stops sending it until it is loaded again. ### 2. The script tag Once the setting is saved, the snippet on the Install tab includes `data-heatmaps="on"`. Put the new snippet on your site, or add the attribute to the tag you already have: ```html ``` With the attribute, the tracker loads `h.js` from beside its own address, with the tag's `nonce` when it has one. **Copy setup prompt** on the Install tab also tells a coding agent to add the attribute while the setting is on. - If the script tag has an `integrity` attribute, the tracker cannot load `h.js`, and no heatmap data is recorded. The console says so. - The setting needs the tag, and the tag needs the setting. Neither works alone. ### Sample fewer pageviews Every pageview is recorded by default. To record a share of them, add `data-heatmaps-sample` with a value from 0 to 1: ```html ``` With `0.25`, about one pageview in four is recorded. The tracker decides for each pageview on its own, a page change in a single-page app included, and keeps nothing about the choice: a reload decides again. A value outside 0 to 1 writes a warning in the console, and every pageview is recorded. A page outside the sample does not download `h.js`. ## Naming elements A place in the page, such as `… > section:2 > div > button`, is exact but hard to read, and it changes when the page's layout changes. Give the elements that matter a name of your own with `data-ottertrail-name`: ```html Start free ``` - The report lists clicks under the name. A click inside a named element counts under the nearest name above it, so a name on a menu groups the clicks on its links. The place below the name shows when you hover the row. - A name has 1 to 64 letters, digits, spaces, `.`, `_`, `:`, `/`, or `-`, and starts with a letter or a digit. The tracker ignores any other value. - The name is sent as you wrote it. Name parts of the page, such as `pricing-table`, and never put personal data in a name. - Name what you want to read, such as calls to action, menus, and forms. You do not need to name every element. ## Blocked and masked areas Session replay's markers keep areas out of heatmaps too. A click inside an element with `data-ottertrail-block` or `data-ottertrail-mask` is not recorded at all, not even as a click on an outer element. Use them for areas where the place of a click says too much, such as a PIN keypad or a signature pad: ```html
``` - `data-ottertrail-unmask` does not bring clicks back inside a blocked or masked area. - The markers also work inside an open shadow root. The tracker cannot see inside a closed shadow root, so put the marker on its host element. See [Masking and privacy](/session-replay/masking-and-privacy/) for what the markers do in replays. ## Devices A page often has another layout on a phone, so the report shows one kind of device at a time. The tracker sorts each pageview by the width of the window, in CSS pixels: | Device | Window width | | --- | --- | | Mobile | Under 768 pixels | | Tablet | 768 to 1,023 pixels | | Desktop | 1,024 pixels and wider | **All devices** in the report adds them together. ## How long data is kept Heatmap data is kept for 90 days, whatever the project's setting for events. Older clicks describe an older layout of the page. The report reads at most the last 90 days: a period that begins earlier starts at the first day kept, and the report says so. Deleting a project deletes its heatmap data. Deleting spam visits does not reach heatmap data, which has no visitor ID: it leaves with the 90 days. ## Consent Heatmaps follow page analytics: they have no consent setting of their own. This is how Ottertrail is built: - Nothing is stored on the visitor's device. - A heatmap record holds less than a pageview: no visitor ID, no text of the page, and no address beyond the path. - Session replay is different, because it records what was on the screen. It can wait for the visitor's consent. See [Turn on session replay](/session-replay/turning-it-on/#consent). This describes Ottertrail's design. It is not legal advice, and it does not say what the law requires for your site. Check your own obligations. If your privacy notice describes your analytics, it can say that they include clicks and scrolling. ## The Heatmaps report Open a project, then **Heatmaps** in its menu, after Speed. To see it, a member needs the web analytics area at View. See [Members and roles](/team/members-and-roles/). The page is a report, laid out as the other reports are ([Reports](/introduction/the-dashboard/#reports)). The filter bar holds the period, the environment (once there is a choice), the page, the device, and the days with the instance's timezone. - **The page.** The picker lists the pages with heatmap data in the period, most first, up to 100. Type part of a path to search all of them. Without a choice, the report shows the first page with data. - **The device.** Desktop, Tablet, Mobile, or All devices. Without a choice, the report shows the device with the most pageviews for that page and period. Your own choice stays when you change the page or the period, and goes in the page's address. - **The figures.** **Pageviews with heatmap data** (the pageviews that sent a scroll depth), **Clicks**, **Rage clicks**, and **Median scroll depth**, with the share of pageviews that reached the bottom. When a pageview passed 100 clicks, a line says how many clicks were not recorded. There is no change from the period before. - **How far visitors scrolled.** A bar for each tenth of the page, from the top (10%) to the bottom, as long as the share of pageviews that reached it. A line across the bars marks the average fold: how much of the page showed without scrolling. **Show the numbers** opens the data as a table. - **Most-clicked elements.** Up to 100 elements, most clicks first: the element's name or the last steps of its place in the page, its clicks, its share of all the page's clicks in the period, and its rage clicks. An element with rage clicks has a **Rage clicks** badge. - **Rage-click hotspots.** Up to 20 elements with the most rage clicks, and the spot inside each that was clicked on average, such as "48%, 30%": 48% across and 30% down. Scroll depth arrives when a visitor leaves the page, and clicks arrive at once. So a period that includes today has a **Today still arriving** badge, and a page can show clicks before it shows a scroll depth. On the Web analytics report, each row of the Pages table (Top pages, Entry, and Exit) has a small heatmap icon after its path. It opens the page's heatmap for the same period and environment. See [Web analytics reports](/web-analytics/reports/#the-tables). ### When there is nothing to show - **The setting is off and nothing was collected:** the page says that heatmaps are off. The owner and admins get **Turn on heatmaps**, which opens the Install tab. Members are told to ask an owner or admin. - **The setting is off, with data from before:** the report shows, with a note that no new data arrives. - **The setting is on, without data in the period:** the page reminds you to add `data-heatmaps="on"` to the snippet, and that data arrives as visitors view pages. - **A page or device without data:** the page offers the devices and pages that have some. - **A failed load:** the page says so, with **Retry**. A failed refresh keeps the last report. ### On a phone On a phone, the filters stack, the figures sit two to a row, and each table row stacks, with its numbers labelled. ## Open the heatmap on your site **Open on your site**, beside the page's path, opens that page of your site in a new window, with the heatmap drawn over it. You see your page as it is now, with its real text, and the clicks over the elements they went to. ### How to use it 1. On the Heatmaps report, choose the page and the device. 2. If the project has several allowed sites, choose the site in the **Site** list. 3. Select **Open on your site**. A new window opens, as wide as the device shown: 1280 pixels for Desktop and for All devices, 820 for Tablet, 390 for Mobile. Browsers may ignore the size. The device mode of the browser's developer tools gives an exact width. 4. In the window, the panel shows the heatmap. Choose another period or device there if you like. Close the panel with ×, or press Escape inside it, to remove the overlay. The line under the button names the address it opens and the width. Pages open with `https`. For `localhost` and `127.0.0.1`, the page opens with plain `http`, and a **Port** field appears, because allowed sites have no port. The page must be one of the project's allowed sites and have the tracker on it. Without any allowed site, the report says to add your site's hostname, with **Add your site's hostname** for the owner and admins. See [Project settings](/introduction/project-settings/). If the browser blocks the new window, the report says to allow pop-ups for the page and try again. ### What you see - **Clicks.** Each element in the report that the page has gets an outline, a label with its clicks and rage clicks, and coloured spots where in it the clicks fell. The spots show which part of the element was clicked, in a grid of 8 by 8, not single clicks. - **Scroll reach.** A band down the right edge of the window, shaded by the share of pageviews that reached each part of the page, with the share written every 25%. - **The panel.** The page's path, the period (Last 7 days, Last 30 days, or Last 90 days), the device, the pageviews, clicks, and rage clicks, and **Not on this page**: the elements in the data that the page does not have now, with their clicks. The overlay lets every click and scroll through to the page, so you can use the page as usual. It follows the page as you scroll, resize the window, or open a menu or a tab that adds or shows elements. It reads the environment of the tracker's tag, `data-environment`, or production without one. ### Your visit is not counted A page opened from **Open on your site** sends nothing to Ottertrail for that page load: no pageview, custom event, error, Web Vitals, replay, or heatmap click. The panel says so: "Only you see this overlay, and this visit is not counted." - Other analytics tools on the page still count your visit. - The tracker holds the page load's events for up to 5 seconds, until the overlay's answer. If the link proves not to be a valid one, the page load is counted as any visit, a few seconds late. If a valid link's answer comes after the 5 seconds, what was sent by then stays counted, nothing more is sent, and the panel leaves out its note. - Only you see the overlay. Visitors to the same page see nothing. ### What the link can and cannot do The dashboard makes a link only when you select the button. The link carries a token in the address's fragment (`#ottertrail-heatmap=…`). A fragment is never sent to a server, and the tracker removes it from the address as soon as it starts. - **It works once, within 5 minutes.** After that, the panel says that the link expired or was already used. Open it again from the dashboard. - **The overlay then has a session of 30 minutes.** It keeps the session in memory only. After 30 minutes, the panel says that the session ended. - **It ends when you sign out,** when your password is reset, and when your dashboard session ends. - **It follows your access.** Every read checks your role and areas again, as the dashboard does. If you lose the web analytics area or the project, the next read fails, and the panel says that your account cannot view the project's heatmaps. - **It reads heatmap figures only:** the clicks per element, the scroll reach, and the totals of the project's pages. It cannot read keys, settings, events, replays, or anything about one visitor. The project's public key plays no part. - **It works only on the project's allowed sites.** The instance answers the overlay only for a page on one of the project's allowed hostnames. A member with the web analytics area sees the project's allowed hostnames on the Heatmaps report, so that **Open on your site** can name the site. Members still do not see the project's settings. If someone else uses a link before you, they get the session, and your window says that the link was already used. A link that reached the wrong person shows at most the heatmap figures of that project, for 30 minutes, while you may see them and stay signed in. ### Limits - **Redirects.** Browsers keep the fragment across a redirect. If the page sends the browser elsewhere before the tracker runs, such as a page behind a login that redirects to an identity provider, the link goes to that other site. Open a page that loads without a redirect. - **A pinned tracker.** If the script tag has an `integrity` attribute, the tracker cannot load the overlay script, `o.js`. There is no overlay, and the page load is counted as usual. - **Trusted Types.** If the page requires Trusted Types for scripts, there is no overlay. The page load is counted after the tracker's 5 seconds. - **Elements it cannot find.** Elements inside frames or closed shadow roots, and content drawn on a canvas, are not found. An element that the page no longer has, after a redesign, in an A/B test, or for some visitors only, is listed under **Not on this page**. When two elements have the same name and place, the first is drawn. - **Changes it does not see.** A menu that opens on hover only, or a CSS animation, can leave the outlines where the element was until the next scroll, resize, or change to the page. - **Scroll reach** is for the whole document. A page that scrolls inside a box shows the document's scroll. - **The wait.** While the tracker waits for the overlay's answer, it keeps the first 200 events of the page load. If you close the page during the wait, it sends them as any page does when it closes, within the browser's limit of 64 KiB for those requests, so events with very long error stacks can be left out. The Heatmaps report itself works on every site, whatever these limits. ## Not available yet - A comparison with the period before. - Dead clicks (clicks that change nothing), clicks followed by an error, and pages grouped by a pattern, such as `/products/*`. --- # Custom events Section: Product analytics. Source: https://docs.ottertrail.app/product-analytics/custom-events/ > Send your own events with properties, and break them down in reports. Pageviews say which pages people open. Custom events say what they do there: sign up, start a trial, invite a teammate. Your site sends them, with details of its own (properties), and the **Product analytics** page counts and breaks them down. ## Send an event with `track()` Once the tracker has loaded, call `window.ottertrail.track()` with a name and, optionally, properties: ```js window.ottertrail?.track("signup", { plan: "free" }); ``` Calls made before the script has loaded are lost, so write `?.`: a call then does nothing when the tracker is missing, instead of throwing an error. The event goes with the page's other events, within a second. It carries the page, the environment and release of the script tag, and the signed-in user's ID when there is one (see [Name signed-in users](/users/naming-users/)). To send events that a browser should not send, such as payments, see [Server-side events](/product-analytics/server-side-events/). ### Names - 1 to 200 characters. The tracker removes control characters and cuts longer names. - Choose names that stay the same, such as `signup` or `invite_sent`. Reports group events by their exact name. ### Properties Properties are a flat object of details: - At most 30 keys, each up to 100 characters. - Values are strings (up to 500 characters), numbers, `true`, `false`, or `null`. Nested objects and arrays are not allowed. - At most 8 KB in total. The tracker cleans properties before it sends them: it keeps flat values only, at most 30 keys, and cuts strings to 500 characters. A property that is different on every event, such as an order ID, has as many values as there are events, and its table shows only the 10 most frequent. ### Reserved names `pageview`, `engagement`, `error`, and `vitals` are the tracker's own events. `track()` refuses them and writes a warning in the browser's console. So a page cannot add to its own pageviews. To report an error, use `captureError()`. See [Report errors from the browser](/errors/browser-errors/). ## The Events tab Open **Product analytics** in a project's menu. It opens on the **Events** tab, beside **Funnel** and **Retention**. The page is a report, with the period and, once there is a choice, the environment in its filter bar. See [Reports](/introduction/the-dashboard/#reports). The table lists the product events of the period, most frequent first (the top 100): | Column | What it counts | | --- | --- | | Events | How many times the event happened | | Visitors | Distinct daily visitor IDs that sent it. One browser counts once a day, and again the next day. Server-side events have no visitor. | | Users | Distinct signed-in users that sent it. Only events sent while someone was signed in count. | In the example, `invite_sent` has 0 visitors and 9 users: it comes from the site's server. Before your site sends any event, the tab shows how to send one, from the browser or from your server, with an example to copy. ## One event and its properties Select an event's name to open its page. It shows the event's events, visitors, and users, a chart of events per day ("Show the numbers" opens it as a table), and its properties. The **Properties** section lists the 30 most common properties of the event, each with its 10 most frequent values, two tables side by side. "On 140 events" under a property's name says how many of the events carry it. ### Filter by a property Select a value to show only the events with that value. Every figure, the chart, and every property table then count those events. Select a value in another table to add a second filter: several filters must all hold, at most five. - Values are compared as text. A string is compared as it is. A number, `true`, `false`, and `null` are compared as JSON writes them, such as `3` or `true`. - An event without the property never matches, even a filter for an empty value. - Active filters show in the filter bar, each with a button to remove it. - Filters go in the page's address, such as `p.plan=team`, so you can link to the filtered view and reload it. When no event matches, the page says so. ## On the Web analytics page The **Custom events** table on the Web analytics page lists each event with its visitors and how often it happened, for the page's period and filters. A custom event in a visit also means the visit is not a bounce. See [Web analytics reports](/web-analytics/reports/). To count the visitors who sent an event, as a share of all visitors, add a [goal](/product-analytics/goals/). ## Not available yet - Custom events and their properties as filters on the Web analytics page. - Comparisons other than "equals". - Calls to `track()` before the tracker has loaded. They are lost. --- # Server-side events Section: Product analytics. Source: https://docs.ottertrail.app/product-analytics/server-side-events/ > Send events from your own server, such as payments, with the secret key. Some events are better sent by your server than by a browser: a payment, a cancelled subscription, a renewal. A browser can neither block nor fake them, and they can carry details that a page should not see. Your server sends them to `POST /api/server-events` with the project's secret key. ## When to send from the server Send an event from the server when: - it happens on the server, such as a webhook from your payment provider; - it must be counted even when the visitor uses an ad blocker or closes the tab; - it must not be faked by someone who copies your public key. Each server-side event belongs to a signed-in user of your app. For what anonymous visitors do in the browser, use [`track()`](/product-analytics/custom-events/). ## The secret key Open the project's **Settings**, then the **Your server** tab. The owner and admins can see it. Members cannot. - The secret key (`sk_…`) is hidden until you select **Show**. Then you can copy it. - Below it, "Send events from your server" has an example request to copy. - Keep the key on your server, for example in the `OTTERTRAIL_SECRET_KEY` environment variable. Never put it in a page or in your repository. The endpoint sends no CORS headers, so a page cannot even read its answers. - If the key ends up where it should not, replace it in the **Danger zone** tab. Servers with the old key are refused at once. ## Send an event ```sh curl https://analytics.example.com/api/server-events \ -H "Authorization: Bearer $OTTERTRAIL_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "v": 1, "environment": "production", "release": "api@2.3.0", "events": [{ "id": "8c1f0a52-3d4e-4f60-9b7a-1c2d3e4f5a6b", "name": "subscription_started", "occurredAt": 1794823396705, "userId": "42", "path": "/checkout", "properties": { "plan": "team" } }] }' ``` - **`id`:** a new UUID for each event. - **`name`:** any name except the tracker's own: `pageview`, `engagement`, and `vitals` are refused. - **`occurredAt`:** when it happened, in milliseconds since 1970, by your server's clock. - **`userId`:** required. Your app's ID for the user, the same ID the browser sends (see [Name signed-in users](/users/naming-users/)). It needs no signature: only your server has the secret key. - **`path`:** optional. A path that starts with `/`. Without one, the user's page shows the event by its name only. - **`properties`:** optional, with the same rules as in the browser. - **`environment`** and **`release`:** optional, for every event of the request. Without an environment, the events count as `production`. See [Environments and releases](/web-analytics/environments-and-releases/). A request holds 1 to 50 events and at most 64 KB. The whole format and every answer are in the [HTTP API reference](/reference/http-api/). ## Where the events show - **The user's page,** under **Users**: the event in the user's activity, with its name, properties, and path. See [The Users page](/users/the-users-page/). - **Product analytics:** the Events tab counts the event, with its users. Its Visitors column stays 0, because a server-side event has no visitor. A funnel counted by users, and the retention report, include it too. See [Funnels](/product-analytics/funnels/) and [Retention](/product-analytics/retention/). They do not show in web analytics, which counts what browsers send, and they do not count toward [goals](/product-analytics/goals/), which count visitors. No location, browser, or device is recorded: the request comes from your server, not the user's device. ## Retries and timestamps The instance trusts your server's clock, so keep it right. - An `occurredAt` more than 5 minutes in the future is refused with 400. - An event that happened more than 24 hours ago is not stored. The answer counts it in `tooOld`. - The answer is 202 only after the events are written. Its body is `{ "stored", "tooOld" }`. When a request fails, send it again only after 429 or 503, and after the seconds in `Retry-After`. Other errors will fail again. A retry is stored once only when it sends the same `id` **and** the same `occurredAt` as the first attempt. Make both when the event happens, keep them with the event, and send them unchanged on every attempt. A sender that stamps the time again on each attempt stores its retries twice. ## Limits - Requests from each IP address: a burst of 600, then 50 a second. - Server-side events share the project's event budget with its browser events. A flood of browser events, which anyone with the public key can send, can hold your server's events back too (429, to send again). - The [spam and bot checks](/web-analytics/spam-and-bots/) do not apply: not the data centers, blocked addresses, referrer spam, the limit of events per client address, or the daily cap per visitor. See [Limits](/reference/limits/) for the rest. --- # Funnels Section: Product analytics. Source: https://docs.ottertrail.app/product-analytics/funnels/ > See how many users go through an ordered series of steps. A funnel counts how many people go through a series of steps in order, such as viewing the pricing page, then signing up, then paying, and where the others stop. Open **Product analytics** in a project's menu, then the **Funnel** tab. ## Define the steps A funnel has two to five steps. Each step is one of: - **Page:** a pageview of exactly this path, such as `/pricing`, without its query or fragment. - **Event:** a custom event of this name, typed or picked from the project's events. **Add a property filter** narrows it to the events where one property has one value, such as `plan` = `team`. See [Custom events](/product-analytics/custom-events/) for how values are compared. 1. Set step 1 and step 2. Until two steps are set, the tab offers an example made from the project's own events ("Use this example"). 2. Select **Add a step** for more, up to five. The arrow buttons beside a step move it up or down, and its delete button removes it. 3. Select **Show funnel**. The fields are checked first, and a field with a problem is marked. Two steps in a row must not be able to match the same event: the same page twice, or the same event name twice, unless both filter one property by different values. One event would count for both steps, so such a funnel always converts. Put another step between them, such as a page. The steps go in the page's address, so a link shows exactly the funnel you viewed. ## Who is counted, and for how long Two choices under the steps apply at once: - **Count by:** Visitors (the default) or Users. - **Visitors** are daily visitor IDs. A visitor's ID changes every day, so a visitor can be followed for at most one day. - **Users** are your app's IDs for signed-in users. Only events sent while someone was signed in count, including [server-side events](/product-analytics/server-side-events/). A user can be followed for up to 30 days. - **Conversion window:** 5 minutes, 30 minutes, 1 hour, 1 day (the default), and, for users only, 7, 14, or 30 days. Windows longer than a day are disabled while you count visitors. ## How conversion is counted - Someone reaches a step after doing all the steps before it, in order. Other events between the steps are allowed. - Every step must happen within the conversion window, counted from that person's step 1. - Step 1 must happen in the period. Later steps may happen after the period ends, within the window. - A person counts once, at the furthest step they reached. - The funnel counts one environment, `production` unless you choose another. The result, under **Conversion**, shows the overall conversion (who did the last step, as a share of who did step 1), the people at step 1 and at the last step, and then each step: its count, its share of step 1 ("Of step 1"), and its share of the step before ("Of the step before"), as bars with the numbers written out. ## Saved funnels Save a funnel to open it again later. The **Saved funnels** table, above the steps, lists the project's saved funnels by name, each with its steps and who it counts for how long (such as "Visitors, within 1 day"). A project can save up to 50 funnels. - **Save funnel** saves the funnel shown, under a name that you type. Select Show funnel first: Save funnel acts on the funnel shown, not on steps you have not shown yet. - Select a saved funnel's name to show it, in the page's current period and environment. A saved funnel holds its steps, who it counts, and its window. It does not hold the period or the environment. - When you change the funnel shown, the tab says that it differs from the saved one. **Save changes** saves over it, and **Save as new funnel** saves a copy under a new name. - A saved funnel's pencil button renames it. Its delete button deletes it, after a confirmation. Only the definition goes: the events stay. Save changes stays disabled while there is nothing new to save, as in [the save rule](/introduction/the-dashboard/#the-save-rule). If someone changed the same funnel since you opened it, for example in another tab, your change is refused, and the tab loads the saved version again, so neither change is lost without a word. A saved funnel stores no data of its own. A funnel saved today also counts past events, and deleting one loses only its definition. To save, rename, and delete funnels, a member needs to manage the product analytics area. To view funnels, view is enough. ## Not available yet - The time between steps, and who dropped off at each step. - Suggested property names in the step editor. --- # Retention Section: Product analytics. Source: https://docs.ottertrail.app/product-analytics/retention/ > See how many signed-in users come back after their first visit. The retention report shows how many of your users come back, week after week. Open **Product analytics** in a project's menu, then the **Retention** tab. ## Why retention counts signed-in users only Ottertrail sets no cookies. It recognizes an anonymous visitor for one day only, so a visitor who comes back next week counts as a new visitor. Retention needs the same person across weeks, so it counts **signed-in users** only, by the ID that your app gives them. Until your site names its signed-in users, the tab explains how: `data-user-id` on the script tag, and `identify()` when someone signs in without a page load. See [Name signed-in users](/users/naming-users/). [Server-side events](/product-analytics/server-side-events/) always carry a user ID, so they count too. ## Read the table - **Each row is a cohort:** the signed-in users whose first event in this environment fell in that week. **First week** names the week by its Monday, and **Users** says how many users it holds. - **Each column is a week after it:** Week 0 is the cohort's own week, always 100%. Week 1 is the week after, and so on, up to 12 weeks. - **Each cell** is the share of the cohort that came back in that week. Hover over it to see "x of y users". The shade follows the legend under the table, "Share of the cohort", and the number is always written. - **A share in italics with an asterisk** is for the current week. It is not over, so its share can still increase. A user came back in a week when they sent any event that week, except time on page and Web Vitals: a pageview, a custom event, an error, or a server-side event. ### Details - A user's first event is looked for across all the events the project keeps, not only the period. So a cohort leaves out users who were seen before it, even long ago. When the project's retention deletes a user's first events, the user's cohort can move later. - The period picks which cohorts show: the latest 13 whose first week overlaps the period. Each cohort's weeks run to the current week, whatever the period. - Weeks start on Monday in the instance's timezone. - Events can arrive up to a day late, so a week's shares can still increase for a day after it ends. - The report counts one environment, `production` unless you choose another. On a phone, the table scrolls sideways inside the page, with the First week column pinned. ## Not available yet - Retention by a chosen event, instead of any event. - Retention by day or by month. --- # Goals Section: Product analytics. Source: https://docs.ottertrail.app/product-analytics/goals/ > Count the visitors who reach a page or send an event, as a share of all visitors. A goal is a page or an event that counts as a success, such as viewing `/pricing` or signing up. The Web analytics page counts, for each goal, the visitors who reached it and their share of all visitors. ## Add a goal The **Goals** table is at the bottom of the **Web analytics** page. To add and delete goals, a member needs to manage the product analytics area. To see them, view is enough. 1. Select **Add goal**. 2. Give the goal a name, such as "Signed up". Each goal of a project needs its own name. 3. Under **Reached when**, choose the type: - **Event:** a custom event of this name. The page's custom events are suggested as you type. **Add a property filter** narrows it to the events where one property has one value, such as `plan` = `team`. - **Page:** a pageview of exactly this path, without its query or fragment. 4. Select **Add goal** in the dialog. The fields are checked as a funnel step's are (see [Funnels](/product-analytics/funnels/)). If the name is taken, or the project already has 20 goals, the dialog says so. At 20 goals, Add goal is disabled, with the reason beside it. An event goal counts events from browsers only. An event from your server has no visitor, so it never reaches a goal. To follow signed-in users through server-side events, use a [funnel counted by users](/product-analytics/funnels/). A goal stores no data of its own. It counts from the events already stored, so a goal added today also counts past visits. ## Where goals show The Goals table lists the goals in the order they were added. For each goal: | Column | What it shows | | --- | --- | | Goal | The name, and what reaches it in plain words, such as "Viewed /pricing" or "signup where plan = team" | | Visitors | The visitors who reached the goal. As in the figures at the top, a visitor counts once a day. | | Conversion | Those visitors as a share of the page's visitors, with a bar from 0 to 100%. Below 10% it has one decimal. | | Events | How many times the goal was reached | The numbers follow the page's period, environment, and filters. A filtered page counts the goals among its own visits only: filter by a source, and you see how many visitors from that source reached each goal. See [Web analytics reports](/web-analytics/reports/). The project's [overview](/introduction/overview/) shows the goals too, compared with the period before. ## The main goal One goal can be the project's main goal. The overview's business figures start with it. The owner or an admin chooses it in the project's **Settings**, on the **General** tab, under **Main goal**. Without one, the overview shows new signed-in users instead. Deleting the goal clears the setting. ## Delete a goal Select the delete button on the goal's row, then confirm. Only the goal's definition goes. Its counts come from your events each time, and the events stay. ## Not available yet - Goals counted by signed-in user instead of by visitor. - A goal's trend over time on the Web analytics page. --- # Name signed-in users Section: Users. Source: https://docs.ottertrail.app/users/naming-users/ > Tell Ottertrail which of your users is signed in, on page loads and in single-page apps. Visitors are anonymous by default. When a user signs in to your app, your app can give Ottertrail that user's ID. Every event from then on carries the ID, and the user's activity shows on the Users page. See [The Users page](/users/the-users-page/). ## Choose the ID Use your app's own ID for the user, such as the user's ID in your database. - Do not use an email address or a name. An ID means nothing outside your app. - The ID has 1 to 200 characters, without control characters. - Ottertrail stores the ID as you send it. The tracker removes spaces at the start and end. A user ID is personal data, even when it is only a number. Say in your privacy notice that you send it. Ottertrail deletes it with the project's events, when the project's retention removes them, or when you delete the project. ## On each page load The tracker keeps the ID in memory only. It stores nothing on the device. So put the ID on the script tag of every page that a signed-in user sees: ```html ``` Leave `data-user-id` out when nobody is signed in. If the project accepts only signed user IDs, add `data-user-signature` too. See [Sign user IDs](/users/signed-user-ids/). ## In a single-page app A single-page app can sign a user in or out without a page load. Tell the tracker when that happens. 1. When a user signs in, call `identify()` with the ID: ```js window.ottertrail?.identify("42"); ``` With a signature, give it as the second argument: ```js window.ottertrail?.identify("42", signature); ``` 2. When the user signs out, call `reset()`: ```js window.ottertrail?.reset(); ``` Events after `identify()` carry the ID. Events after `reset()` are anonymous again. On the next full page load, the script tag gives the ID again. ## What counts as the user's activity - Only events that carry the user's ID count as the user's. Anonymous events before a sign-in are not added to the user, even in the same visit. Another person can use the same computer. - Ottertrail never merges two different user IDs. - Users are listed for one environment at a time, as reports are. The environment picker appears once another environment has known users. ## When the ID is not valid If the ID is empty, has more than 200 characters, or has a control character, the tracker sends the events without an ID. It writes a warning in the browser's console. It does not keep the ID of the user before, because that user can be signed out. --- # Sign user IDs Section: Users. Source: https://docs.ottertrail.app/users/signed-user-ids/ > Make your server sign each user ID, so that nobody can send events that claim to be another user. The public key is in every page, so anyone can copy it. Without signatures, anyone with the key can send events that claim to be any user. A project can require that your own server signs each user ID. Only your server has the secret key, so only your server can make a valid signature. ## How the signature works The signature is the HMAC-SHA256 of the user ID, as UTF-8 text. The key is the project's full secret key, `sk_…`, as text. Write the result in hex: 64 hex digits, in upper or lower case. Ottertrail makes the same signature and compares the two. ## Sign the ID on your server 1. Read the secret key from an environment variable, such as `OTTERTRAIL_SECRET_KEY`. Never put it in a page or in client code. The owner and admins find the key in the project's Settings, on the **Your server** tab, behind **Show**. 2. When your server renders a page for a signed-in user, sign that user's ID. 3. Put the ID and the signature on the script tag. Node.js: ```js import { createHmac } from "node:crypto"; const signature = createHmac("sha256", process.env.OTTERTRAIL_SECRET_KEY) .update(userId) .digest("hex"); ``` Python: ```python import hashlib import hmac import os signature = hmac.new( os.environ["OTTERTRAIL_SECRET_KEY"].encode(), user_id.encode(), hashlib.sha256, ).hexdigest() ``` Go: ```go mac := hmac.New(sha256.New, []byte(os.Getenv("OTTERTRAIL_SECRET_KEY"))) mac.Write([]byte(userID)) signature := hex.EncodeToString(mac.Sum(nil)) ``` PHP: ```php $signature = hash_hmac('sha256', $userId, getenv('OTTERTRAIL_SECRET_KEY')); ``` Ruby: ```ruby signature = OpenSSL::HMAC.hexdigest("SHA256", ENV.fetch("OTTERTRAIL_SECRET_KEY"), user_id) ``` ## Give the signature to the tracker On the script tag: ```html ``` In a single-page app, get the signature from your server when the user signs in. Then give it as the second argument of `identify()`: ```js window.ottertrail?.identify("42", signature); ``` ## Require signatures Only the owner and admins can change project settings. 1. Open the project's **Settings**, and choose the **Your server** tab. 2. Under **Signed user IDs**, turn on **Only accept user IDs signed by your server**. 3. Select **Save changes**. The switch is part of the tab's form, so it takes effect only when you save. Until then, the form shows "Unsaved changes" and **Discard**. See [The save rule](/introduction/the-dashboard/#the-save-rule). The new rule applies from the next event. To stop requiring signatures, turn the switch off and save again. When the setting is on: - An event with a valid signature keeps its user ID. - An event without a valid signature is stored without its user ID, as an anonymous event. The answer counts these events in `unverifiedUsers`. - A signature that is not 64 hex digits makes the API refuse the whole batch (400). The tracker leaves such a signature out and writes a warning in the console. When the setting is off, Ottertrail accepts user IDs as they come. ## Limits of a signature A page shows the signature of its own user. Whoever sees that page can send events as that user, that is, as themselves. They cannot sign any other ID. If you replace the project's secret key, signatures made with the old key stop counting. Make new signatures with the new key. --- # The Users page Section: Users. Source: https://docs.ottertrail.app/users/the-users-page/ > The list of the users your site names, and each user's own page with their events, errors, and replays. Open **Users** in the project's menu. The page lists the users your site names with `data-user-id` or `identify()` (see [Name signed-in users](/users/naming-users/)). Anonymous visitors are not listed. The page shows one environment at a time, production by default. The environment picker appears in the filter bar once another environment has known users. It works like the other list and detail screens: the list on the left, the selected user on the right. See [Lists and details](/introduction/the-dashboard/#lists-and-details). ## The list The list holds the known users, most recently seen first, 50 at a time. **Load more** loads the next 50. Each row shows: - The user ID. - When the user was last seen. Hover for the exact time. - How many events the user has. **Search by user ID**, in the filter bar, finds users whose ID contains the text you type. Case does not matter. While your site names no user, the page explains how to add `data-user-id` and how to call `identify()` and `reset()`, with an example to copy. ## The summary When you open the page, nothing is selected, and the right pane sums up the users loaded: - **Users:** how many. - **Seen in 24 hours** and **Seen in 7 days.** - **New in 7 days:** users first seen in the last 7 days. - **Most events:** the five users with the most pageviews and custom events. While more users wait behind **Load more**, a figure can be higher than it shows, and it reads as at least that many (such as "50+"). ## Select a user Click a row to show the user's page beside the list. The selection goes in the address (`?user=…`). **Open the user's page** opens it on its own. | Key | Does | | --- | --- | | `j` | Selects the next user. With nothing selected, the first. | | `k` | Selects the previous user. | | `Esc` | Clears the selection and shows the summary again. | ## A user's page A user's page (`/projects//users/`) is the same as the pane beside the list. Links to a user open it, and so does a row on a phone. It shows: - When the user was first and last seen, their number of events, and the environment. Times are in the instance's timezone. - **Replays:** the user's latest 10 session replays in the environment. Each has its time (a link to the replay's page), its length, its error's type, and the pages visited. When there are none, a line says so. - The user's activity, newest first, under a heading for each day: pageviews, custom events, and errors, 100 at a time, with **Load more**. Each event shows its time, its page or its name and properties, and the browser, operating system, place, and release. An error shows its type and message, with a link to its group on the Errors page. An error with a replay has **Play replay**, which opens the replay's page, or "Replay arriving…" while the replay is on its way. Server-side events and server errors that carry the user's ID are part of the activity too. See [Server-side events](/product-analytics/server-side-events/) and [Server errors](/errors/server-errors/). Only events that carry the user's ID count. Browsing before the user signed in is not added, because someone else may have used the device. For an ID with no events in the environment, the page says "No events from this user". ## Who sees users User IDs point at real people, so users are an area of their own. The owner and admins see the Users page. A member sees it only with access to the users area. See [Members and roles](/team/members-and-roles/). - A member without the errors area sees a user's errors as text, without links. - A member without the users area still sees user IDs as text on errors and replays, without links to the user's page. ## On a phone Under 64rem wide, the list fills the screen and a row opens the user's own page. See [On a phone](/introduction/the-dashboard/#on-a-phone). ## Not available yet - Deleting one user's events, for a person who asks to be forgotten. Today their events are deleted with the project, or when the project's retention removes them. - Details about a user beyond the ID, such as a name or a plan. - A user's visits. --- # Report errors from the browser Section: Errors. Source: https://docs.ottertrail.app/errors/browser-errors/ > Which browser errors the tracker reports automatically, and how to report the errors your app catches with captureError. The tracker reports errors from your pages. Ottertrail groups them, and the Errors page shows each group with its occurrences, the users it affects, and when it was first and last seen. See [Resolving errors](/errors/resolving/) for the page, and [How errors are grouped](/errors/grouping/) for the groups. ## Errors the tracker reports by itself - **Uncaught exceptions** on the page. - **Unhandled promise rejections.** When the reason is an `Error`, Ottertrail gets its name, message, and stack. Another value is reported with the type `UnhandledRejection` and no stack. The tracker does not report these: - `Script error.` without a stack. The browser hides the details of errors in scripts from another origin. To see them, load those scripts with `crossorigin="anonymous"`, and send CORS headers from their server. - Errors that come from browser extensions. - Errors that happen before the tracker runs. The tracker loads with `defer`. - Failed images and scripts. To turn automatic reports off, add `data-errors="off"` to the script tag. `captureError()` still works. ## Report an error your app catches Call `captureError()` with the error: ```js try { await saveCart(cart); } catch (error) { window.ottertrail?.captureError(error); showMessage("We could not save your cart."); } ``` You can add properties, as for a custom event: ```js window.ottertrail?.captureError(error, { step: "checkout", plan: "team" }); ``` - Ottertrail marks these errors as handled. The error's page shows them as **Caught**. - If the value is not an `Error`, Ottertrail reports it with the type `Error` and the value's text as the message. - Properties follow the rules of custom event properties. See the [tracker reference](/reference/tracker/). ## What each error carries Each error belongs to the page and the signed-in user of the moment it happened, with the environment and release of the page. It holds: | Field | Limit | | --- | --- | | Type, such as `TypeError` | 1 to 200 characters | | Message | Up to 2,000 characters | | Stack | Up to 16,000 characters | The tracker cuts longer values to these limits. ## Limits for each page load A broken page can throw the same error in a loop. So for each page load, the tracker sends: - Each identical error (the same type, message, and stack) one time. - 25 errors at most. A navigation inside a single-page app does not start a new count. ## Stacks from minified code The stack of minified code points at the built files. Upload your source maps, and Ottertrail shows your own files and lines. See [Upload source maps](/errors/source-maps/). --- # Upload source maps Section: Errors. Source: https://docs.ottertrail.app/errors/source-maps/ > Upload your build's source maps with the secret key, so that error stacks show your own files and lines. A source map tells where each position in a minified file came from in your source files. Upload your maps to Ottertrail, and the error page shows your stack as `src/cart.ts:3:10`, with the lines around it, in place of a position in a minified file. ## Before you start - The instance needs an object store. Without one, source maps are off: uploads answer 503, and the project's Source maps tab says that the operator turns them on with `OBJECT_STORE_URL`. See [Object storage](/self-hosting/object-storage/). - Set `data-release` on the tracker's script tag. Ottertrail uses an error's release to find the maps of the same build. It cannot map an error without a release. - Keep the project's secret key in your CI's secrets, for example as `OTTERTRAIL_SECRET_KEY`. The owner and admins find the key in the project's Settings, on the **Your server** tab. ## Build the maps without publishing them A source map can hold your source code. Build the maps, but do not serve them to browsers. For example, in Vite: ```js // vite.config.js export default { build: { sourcemap: "hidden", }, }; ``` `"hidden"` writes the maps without the comment that tells browsers where to find them. Delete the map files from the build output after you upload them, or keep them out of your deploy. ## Upload one map Send one request for each minified file and release: ```sh curl -fsS -X PUT \ -H "Authorization: Bearer $OTTERTRAIL_SECRET_KEY" \ -H "Content-Type: application/json" \ --data-binary @dist/assets/index-4f3a.js.map \ "https://analytics.example.com/api/source-maps?release=1.4.2&path=/assets/index-4f3a.js" ``` - `release` is the same value as `data-release` on the pages of that build. - `path` is the minified file's path as the browser loads it, without the origin. Use percent-encoding, and no `.` or `..` segments. A path can have up to 1,024 characters. - You can compress the body with gzip. Then add `-H "Content-Encoding: gzip"`. The answer is 201 for a new map. It is 200 when the map replaces the release's earlier map of the same file. ## Upload a whole build in CI 1. Build your app with the release name that the pages use. 2. For each `.js.map` file in the output, upload it with the path of its `.js` file. 3. Delete the map files before you deploy. This shell loop uploads each map under `dist/` for one release: ```sh RELEASE="1.4.2" cd dist for map in $(find . -name '*.js.map'); do file="${map#.}" curl -fsS -X PUT \ -H "Authorization: Bearer $OTTERTRAIL_SECRET_KEY" \ -H "Content-Type: application/json" \ --data-binary @"$map" \ "https://analytics.example.com/api/source-maps?release=$RELEASE&path=${file%.map}" done ``` Change the paths if your site serves the files from another folder than the build output's root. If the answer is 503 with a `Retry-After` header, the instance is busy. Wait that many seconds, then send the upload again. ## What Ottertrail accepts | Rule | Limit | | --- | --- | | Format | A source map of version 3, with `sources` and `mappings`. Index maps (`sections`) are refused. | | Size | 25 MiB, after it is unpacked | | Lines and segments | 100,000 lines and 1,000,000 segments | | Release | 1 to 200 characters, without spaces | | Storage | `SOURCE_MAP_STORAGE_BYTES` for the whole instance, 1 GiB by default. An upload past it answers 409. | ## See and delete your maps The project's Settings have a **Source maps** tab. The owner and admins see it. It shows: - How much of the instance's room for maps is used, by all projects together, such as "14 MB of 1 GB used". - The releases that have maps, by their latest upload, with **Newest first** or **Oldest first**. Each row has the release, the number of files, their size, and when the last map was uploaded. At most 100 releases are listed. A note says how many there are in all when there are more. - For each release, a button that lists its files with their sizes, and a button that deletes its maps. - Behind **Show how to upload**, the rules above and a `curl` example. The secret key shows there only as a placeholder. When the project has no maps yet, these show at once. Deleting asks first. The release's maps are deleted for good. The errors stay, and the stacks of that release show minified code again, until you upload its maps again. ## How long maps stay Maps stay until someone deletes them on the Source maps tab. Their age and the project's event retention do not remove them, because an old release can still run in browsers. When the instance runs out of room for maps, choose **Oldest first** and delete the releases that no longer run. Deleting a project deletes its maps. Maps are in the instance's backups, with the rest of the object store. If a restore leaves the object store out, the maps are listed but cannot be read: upload the maps of the releases still in use again. See [Backups](/self-hosting/backups/). ## What Ottertrail maps - Only the latest occurrence of a group is mapped. Its stack shows on the error's page, with a line that says which release's maps were used, or why the stack could not be mapped. See [Resolving errors](/errors/resolving/). - A frame matches a map when the path of the frame's URL is the map's `path`. - Frames that no map covers, such as another site's script, stay as the browser reported them. - Server stacks are never mapped. - Maps do not change how errors are grouped. See [How errors are grouped](/errors/grouping/). --- # How errors are grouped Section: Errors. Source: https://docs.ottertrail.app/errors/grouping/ > How Ottertrail puts occurrences of one bug in one group. One bug can throw thousands of times. Ottertrail puts all occurrences of one bug in one group, and the Errors page lists groups, not single errors. Each group has a fingerprint, worked out by Ottertrail when the error arrives. A sender cannot set it. ## What the fingerprint uses Occurrences with the same fingerprint are one group. The fingerprint uses three things: 1. **The type,** such as `TypeError`. 2. **The message, without the parts that change from one occurrence to the next:** - UUIDs, and hex IDs of 8 characters or more, count as one value. - URLs count as one value. - Numbers of 4 digits or more count as one value. Shorter numbers stay, because a status such as `404` or `500` often tells two failures apart. - Runs of spaces count as one space. 3. **The file of the stack's top frame,** without its origin, query string, fragment, and the content hash that bundlers put in file names. So `index-BfK3x9A2.js` and `index-C7d1e0F4.js` are the same file. So `Order 51234 failed` and `Order 51288 failed` are one group, and `Request failed with status 404` and `Request failed with status 500` are two. ## Why function names and line numbers are left out In minified code, function names and line numbers change with every build. If the fingerprint used them, each release would start new groups for old bugs, and a bug you resolved would come back as a new error after each deploy. This has a cost: - Two different bugs with the same type and message, in the same file, share a group. - [Source maps](/errors/source-maps/) do not change the grouping. They show your own files and lines on the error's page, but the fingerprint still uses the stack as the browser reported it. ## One bug in two browsers Browser engines word the same failure in different ways. For the same bug, Chrome reports `Cannot read properties of undefined (reading 'total')`, and Safari reports `undefined is not an object (evaluating 'cart.total')`. The messages differ, so one bug makes one group for each engine. Resolve each group when you fix the bug. ## Server stacks Exceptions from your servers are grouped by the same rule. Ottertrail reads the top frame from stacks of Node.js, Python, Ruby, Go, Java and other JVM languages, and .NET. The top frame is where the exception was raised: - For Java and other JVM languages, Ottertrail uses the class (such as `com.example.shop.CartService`) in place of the file, because a file name such as `CartService.java` can be the same in every package. - For .NET, it uses the file when the build kept it, and otherwise the type. - For Go, it skips the frames of the Go runtime and of OpenTelemetry. A server's frame keeps the path that its runtime gives it. So a different build path, or a new version of a library (such as `…/python3.12/site-packages/…`), can start a new group for the same error. See [Server errors](/errors/server-errors/). ## Versions of the rule Each fingerprint starts with the number of the rule that made it, `1-` today. If the rule changes, the new rule gets a new number. Old and new groups never mix, and old occurrences stay in the groups they were given. Planned: grouping by the original files and functions that source maps give. This is not available yet. --- # Resolving errors Section: Errors. Source: https://docs.ottertrail.app/errors/resolving/ > The Errors page and an error's own page: mark a group resolved, reopen it, and see when it comes back. Open **Errors** in the project's menu. The page lists the error groups of one environment and a period, with the list on the left and the selected group on the right. It works like the other list and detail screens. See [Lists and details](/introduction/the-dashboard/#lists-and-details). ## The list The filter bar at the top holds the period, the environment (once the project has more than one), and three choices: | Choice | Shows | | --- | --- | | **Unresolved** | The groups that need work, regressed groups included. This is the default. | | **Resolved** | The groups someone marked resolved, which have not happened again since. | | **All** | Every group seen in the period. | Each row shows: - The type and the message. Hover over a cut message to see all of it. - A **Regressed** or **Resolved** badge, when the group has that status. - When the group was last seen (hover for the exact time), and under it, when it was first seen. - Occurrences, users, and visitors in the period. The list is in order of last seen, latest first, and cannot be sorted by another column. It reads the 1,000 groups seen most recently. When the period has more, a note says so: choose a shorter period to see older groups. ## The summary When you open the page, nothing is selected, and the right pane sums up the list: - How many groups are unresolved, new in the period, and regressed. Under **All**, how many are resolved too. Under **Resolved**, how many are resolved and new. - **Most users affected:** the five groups that affect the most known users. When the list stops at 1,000 groups, each figure reads as at least that many (such as "2+"). When the project has no errors yet, the page explains what the tracker reports by itself, how to report caught errors with `captureError()`, and how `data-errors="off"` turns automatic reports off. See [Report errors from the browser](/errors/browser-errors/). ## Select a group Click a row to show the group beside the list. The selection goes in the address (`?error=…`), so you can share it. **Open the error's page** opens the group's own page. | Key | Does | | --- | --- | | `j` | Selects the next group. With nothing selected, the first. | | `k` | Selects the previous group. | | `e` | Resolves or reopens the selected group, if you may change it. | | `Esc` | Clears the selection and shows the summary again. | When `e` takes the selected group out of the list (for example, a resolved group under **Unresolved**), `j` and `k` carry on from where it was. ## Statuses | Status | Means | | --- | --- | | **Unresolved** | Nobody has marked the group resolved. Every new group starts here. | | **Resolved** | Someone marked the group resolved, and it has not happened since. | | **Regressed** | The group happened again after someone resolved it. It counts as unresolved, so it is back under **Unresolved**, with the badge. | The status belongs to the project, not to one environment. A group resolved and then seen again in staging shows as regressed in production's list too. ## Resolve and reopen Under the group's message, **Resolve** marks the group resolved. A resolved group shows **Reopen** in its place, which marks it unresolved again. Or press `e` while the group is selected. - A resolved group says who resolved it, and when. - A regressed group says that it was seen again after it was resolved, by whom, and when. - The owner, admins, and members who manage errors see these buttons. Other members see the status only. See [Members and roles](/team/members-and-roles/). Resolving does not delete anything. The group's occurrences stay, and a new occurrence regresses the group. To be told when a resolved group comes back, add an alert rule (see [the Alert rules card](#alert-rules)). ## The group's page The group's own page (`/projects//errors/`) shows the same as the pane beside the list. It is the page that links open, and the page that a row opens on a phone. **All errors** goes back to the list. From top to bottom: ### The counts - **Occurrences** in the period. - **Users:** the distinct user IDs your site sent (see [Name signed-in users](/users/naming-users/)). - **Visitors:** the distinct anonymous visitors. A visitor's ID changes every day, so a visitor who hits the error on three days counts three times. - **First seen** and **Last seen**, over all the time the project keeps its events, in this environment. First seen tells a new error from an old one. ### The stack trace The stack of the latest occurrence, top frame first. A line above it says how Ottertrail read it: - **Mapped:** "Mapped to your original files with the source maps of release …". Each mapped frame shows its original file, line, and column, the lines of source around it when the map holds them (the line of the error is marked), and the minified location in small text. - **Not mapped,** with the reason: the occurrence has no release, no frame is in a file that a map could be for, the release has no maps for the stack's files, the maps do not cover the frames, source maps are off on this instance, or the maps could not be read just now. When maps are missing, the line names the files to upload and links to the project's Source maps settings. Three or more frames in a row without a source map, often a library's, fold behind **Show N more frames, without a source map**. **Show the stack as the browser reported it** opens the raw stack. When the browser gave no stack, the card says so. See [Upload source maps](/errors/source-maps/). ### Latest occurrences The latest 20 occurrences in the period, newest first, with: - The time, and **Caught** for an error reported with `captureError()`. - The user, as a link to the user's page, or **Anonymous**. - The page, browser, operating system, and release. - **Replay:** **Play replay** when a replay is ready, **Arriving…** while it is on its way (the page sends it about 10 seconds after the error), or **No replay**. See [Replays of errors](/session-replay/error-replays/). ### Occurrences per day A line chart of the period, with **Show the numbers** for a table of the same counts. ### Where it happens The top 5 pages, browsers, operating systems, and releases of the group's occurrences. For a server's exception, routes and services take the place of pages, browsers, and operating systems. See [Server errors](/errors/server-errors/). ### Alert rules The **Alert rules** card lists the rules that watch this group, each with its state and what it watches: rules for regressed errors, and spike rules for this group or for all errors, in its environment or in all. "No rule watches it yet." when there are none. A rule's link opens it on the Alerts page. **Add an alert rule** opens the Alerts page with the form of a spike rule filled in for this group and its environment. A rule for new errors never shows here, because it watches groups that do not exist yet. See [Alert rules](/uptime-and-alerts/alert-rules/). ### A group with no occurrences in the period The page says "No occurrence in this period", with links to all errors and to the last 12 months. ## On a phone Under 64rem wide, the list fills the screen and a row opens the group's own page. See [On a phone](/introduction/the-dashboard/#on-a-phone). ## Not available yet - Counts on the three choices. **Unresolved** cannot tell "no errors" from "all resolved". - Ignoring a group, merging two groups, searching messages, and "resolved in the next release". --- # Server errors Section: Errors. Source: https://docs.ottertrail.app/errors/server-errors/ > Exceptions from your servers, sent over OpenTelemetry, in the same error list. Exceptions on your servers show in the same Errors list as the browser's, grouped by the same rule. You send them over OpenTelemetry (OTLP), with your traces and logs. Nothing of Ottertrail's own runs on your servers. To set up sending, see [Send telemetry](/monitoring/sending-telemetry/). ## Exceptions on spans and in log records OpenTelemetry records an exception in one of two ways. Ottertrail turns both into an error: - **On a span:** a span event named `exception`, with `exception.type` or `exception.message`. Ottertrail takes the first 10 such events of a span. - **In a log record:** a log record with `exception.type` or `exception.message` among its attributes. Only records that Ottertrail stores make errors. A span or log record that is refused makes none. ## What each error holds | Field | Comes from | | --- | --- | | Type | `exception.type`. `Error` when only a message is given. Up to 200 characters. | | Message | `exception.message`. Up to 2,000 characters. | | Stack | `exception.stacktrace`. Up to 16,000 characters. | | Environment, release, service | The resource's `deployment.environment.name`, `service.version`, and `service.name`. Without an environment, `production`. | | Route | The span's `http.route`. For a log record, its own `http.route`, if it has one. | | User | The record's `user.id`, or the older `enduser.id` (see below). | | Trace and span | The span's trace ID and span ID. A log record without a trace has none. | Ottertrail cuts longer values to these limits, the same limits as the browser's errors. A server has no visitor, browser, operating system, or location. So a server's error counts towards a group's users, but never its visitors. ### Caught or not The error page marks an error **Caught** when it was handled: - An exception on a span counts as caught, unless the span's status is `ERROR`. - An exception in a log record counts as caught when its severity is below error (`severity_number` 1 to 16). From error up (17 to 24), or without a severity, it counts as not caught. ### Time An exception on a span takes the time of its span event when that falls within the span, and otherwise the span's start. One in a log record takes the record's time. Ottertrail trusts your servers' clocks and does not correct them. ### Retries A retried request makes the same errors, and Ottertrail keeps each one once. Ottertrail answers only after it has stored both the telemetry and the errors. If it cannot, it answers 503, and your exporter sends the request again. ## Users from user.id When a span or log record has a `user.id` attribute (or `enduser.id`), the error belongs to that user, and shows on the user's page. The ID follows the same rules as the browser's: 1 to 200 characters, without control characters. Another value is left out. Use the same IDs that your pages give the tracker, so that a user's browser errors and server errors are together. See [Name signed-in users](/users/naming-users/). A server's user ID is not signed. It comes with the project's secret key, which only your servers have. ## On the error's page A group of server exceptions shows: - A **Server** card with the latest occurrence's service, trace ID, and span ID. - **Service** and **Trace** columns in the latest occurrences. - Routes and services under **Where it happens**, in place of pages, browsers, and operating systems. Each trace ID is a link that opens the trace on the span where the exception happened. See [Traces](/monitoring/traces/). Errors are kept as long as the project's events. Traces are kept 30 days by default. So an old error can outlive its trace, and then the trace's page says the trace is no longer kept. A group can hold both browser and server occurrences, when the same type, message, and file appear in both. Then the columns of the latest occurrences and the tables under **Where it happens** cover both. ## Grouping Server exceptions are grouped by the same fingerprint as browser errors: the type, the message, and the top frame's file. Ottertrail reads stacks of Node.js, Python, Ruby, Go, Java and other JVM languages, and .NET. See [How errors are grouped](/errors/grouping/). ## Stacks are not mapped A server's stack is shown as your server sent it. [Source maps](/errors/source-maps/) are for browser code, and Ottertrail never applies them to a server's stack. ## Alerts Alert rules for new, regressed, and spiking errors watch server errors too. See [Alert rules](/uptime-and-alerts/alert-rules/). --- # Replays of errors Section: Session replay. Source: https://docs.ottertrail.app/session-replay/error-replays/ > Ottertrail records the moments before an error, and never whole sessions. Find replays and play them back. A replay shows what a visitor saw and did on your site in the moments before an error: the page, their clicks, scrolling, and typing. Ottertrail records only around errors. It never records whole sessions, or a sample of them: a page that has no error sends nothing. Replays are off until you turn them on. See [Turn on session replay](/session-replay/turning-it-on/). The visitor's browser masks text, typed values, images, and media before anything is sent. See [Masking and privacy](/session-replay/masking-and-privacy/). ## What a replay holds A replay is not a video. The recorder takes a copy of the page's HTML, then records each change with its time: elements added and removed, changed text, clicks, scrolling, and the window's size. The player builds the page again from these. - **Before the error:** the page records all the time, into memory only. It keeps the last 30 to 60 seconds, and drops older parts. - **After the error:** the page records 10 more seconds, to show what the error did to the page. Then it sends the recording. - **One replay for each page load.** Later errors on the same page load share the replay while it is still recording. Errors after it was sent get none. A replay does not hold: - What a `` draws, the frames of a `