From 8382252b61b0e7affec599e9d2ac16063e150577 Mon Sep 17 00:00:00 2001 From: "Eric J. Smith" Date: Wed, 21 Oct 2026 12:28:51 -0500 Subject: [PATCH 1/3] Add the docs rewrite plan for 9.0 Co-Authored-By: Claude Opus 5.5 --- docs/_config.ts | 1 + docs/docs-rewrite-plan.md | 434 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 435 insertions(+) create mode 100644 docs/docs-rewrite-plan.md diff --git a/docs/_config.ts b/docs/_config.ts index 83bb665532..c35954778e 100644 --- a/docs/_config.ts +++ b/docs/_config.ts @@ -16,6 +16,7 @@ site.ignore( "_site", "deno.json", "deno.lock", + "docs-rewrite-plan.md", "news/index.md", "news/2020/2020-11-11-self-hosted-error-monitoring-on-azure.md", "package-lock.json", diff --git a/docs/docs-rewrite-plan.md b/docs/docs-rewrite-plan.md new file mode 100644 index 0000000000..4cd6773229 --- /dev/null +++ b/docs/docs-rewrite-plan.md @@ -0,0 +1,434 @@ +# Docs rewrite plan + +A new set of Exceptionless docs that ships with Exceptionless 9.0.0 and the site rebrand (#2685). This plan does not +follow the current structure. It starts from what the product does today, what readers and AI agents need, and how the +best developer-tool docs are organized. + +## Goals + +1. **Accurate for the release.** Every page matches the code that ships. Nothing describes the removed Angular UI, .NET + Framework-era setup as the default, or features that are not released. +2. **AI first.** Exie, the MCP server, and coding agents are a headline section, and every task page shows how to do it + with AI as well as by hand. The docs themselves are built to be read by agents. +3. **Fast to first event.** A new user goes from sign-up to a test error in the app in a few minutes, by hand or by + pasting one prompt into their coding agent. +4. **Nothing breaks.** Every current docs URL, including the 12 the app links to, still resolves after the rewrite. +5. **Easy to keep current.** Clear page types, explicit nav, single sources for facts like plan limits and MCP tools, + and checks that catch drift. +6. **Ready for many languages.** .NET and JavaScript are the first two clients, not special cases. Adding a language + means adding a data entry and a folder of pages that follow a template; the docs and the marketing site pick it up + without hand edits. + +## What we found + +Research is summarized here; details are in the PR discussion. + +- **Current docs:** 63 published pages and about 34,000 words. 13 pages were rewritten for the Svelte UI in #2685; the + rest range from fine to badly stale. 11 clusters of duplicate content and 12 pages under 150 words. +- **Old UI and stale content:** + - Several pages still describe the Angular UI: project tokens, custom clients, Kubernetes base URL, and the getting + started page. + - The FAQ, .NET configuration, .NET troubleshooting, and self-hosted upgrading pages are mostly .NET Framework or + 2015-2017 content. + - The Kubernetes page includes internal hosted-ops runbook details. +- **Client SDKs:** + - Current versions are Exceptionless.Net 6.2.0 and Exceptionless.JavaScript 3.2.1. + - In 6.2.0, `Exceptionless.AspNetCore`, `.Extensions.Hosting`, and `.Extensions.Logging` require .NET 8+, and + `app.UseExceptionless(Configuration)` is gone. The docs still use it. + - React Native and Expo shipped in 3.2 and are not documented. + - `Exceptionless.Nancy` is deprecated but still listed. + - **Environment support is not released in either SDK.** It is in Exceptionless.Net #371 and Exceptionless.JavaScript + #193, but `environments.md` on main already documents it. +- **Product:** large parts of the product have no docs at all: + - saved views, which replaced the fixed dashboards; + - event detail tabs; + - the command palette, keyboard shortcuts, and guided tours; + - organization and billing settings; + - the account AI Tools and connected applications pages; + - admin system pages. +- **Hosting and redirects:** the site deploys to GitHub Pages, which ignores `_redirects`. Only the HTML redirect stubs + that `postbuild.ts` writes actually redirect, and it only writes them for news URLs. There is no way to redirect a + moved docs page today. +- **Other docs sites:** + - The best developer-tool docs organize navigation by product and platform, and use page types (tutorial, how-to, + reference, explanation) as a writing rule rather than as the nav. + - AI-forward sites put an agent setup prompt next to the quickstart and give MCP its own section with per-client + install steps, scopes, example prompts, and a security section. They also publish llms.txt and Markdown for every + page. + - Patterns to avoid: AI buried under "Resources", MCP docs on a separate site, and instructions aimed at agents inside + llms.txt. + +## Principles + +- **Keep a URL when the page keeps its purpose.** Move or merge only when the structure needs it, and redirect + everything that moves. +- **One page, one type.** A page is a tutorial, a how-to guide, reference, or an explanation. Split pages that mix them, + such as filtering and searching, which is a how-to plus a field reference. +- **One fact, one place.** Plan limits come from `_data/plans.json`. Client configuration values, data exclusions, and + private information each live on one page, and other pages link to them. +- **Hosted first, self-hosted alongside.** Pages describe the hosted service. A self-hosting note appears only where + behavior differs, and the self-hosting section covers running it. +- **Every task page answers "how do I do this with AI?"** with copyable Exie prompts and, where it applies, the MCP tool + an agent would use. +- **Modern setup first.** For example, ASP.NET Core minimal hosting and `appsettings.json` first, with .NET Framework + and `web.config` on a separate legacy page. + +## Information architecture + +The sidebar order is explicit (see [Site changes](#site-changes)). URLs are under `/docs/`. **Keep** means the URL +stays; **New** pages are new; merged and moved pages are in the [redirect map](#redirect-map). + +### 1. Get started + +| Page | URL | Status | Type | What it covers | +| ------------- | ------------------------ | ------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Overview | `/docs/` | Keep, rewrite | — | Three doors: send your first event, connect your AI agent, self-host. What's new in this version. | +| Quickstart | `/docs/getting-started/` | Keep, rewrite | Tutorial | Sign up, create a project, install a client (one tab per language), throw a test error, and see it. Includes an "Install with your coding agent" prompt. | +| Core concepts | `/docs/concepts/` | New | Explanation | Events, stacks, projects and organizations, environments, saved views, and stack statuses, in about five minutes. | +| What's new | `/docs/whats-new/` | New | Explanation | 9.0 for returning users: the new UI, saved views replacing dashboards, Exie, MCP, environments, source maps, and where things moved. | + +### 2. AI + +| Page | URL | Status | Type | What it covers | +| ----------------------- | ------------------------- | ------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| AI overview | `/docs/ai/` | Keep, rewrite | Explanation | What Exie and the MCP server each do, and when to use which. | +| Exie | `/docs/ai/exie/` | Keep, rewrite | How-to | Opening Exie (side panel, full page, the `a` shortcut, Fix with Exie), what it can answer, which actions it can take and when, plans and limits, and good prompts. | +| MCP server | `/docs/ai/mcp-server/` | Keep, rewrite | How-to + reference | Install steps for each client that passes [verification](#mcp-client-verification). Also covers consent and scopes (read vs `stacks:write`), managing connected apps, the tool reference, and example prompts. | +| Coding agents | `/docs/ai/coding-agents/` | New | How-to | Set up Exceptionless with an agent; the AGENTS.md snippet; the agent skills in the SDK repos; recipes such as "fix my top new error", "triage regressions after a deploy", and "verify a fix in production". | +| AI privacy and security | `/docs/ai/privacy/` | New | Explanation | What Exie and MCP can see and do, how tool results are cached, chat sharing, the model provider, prompt-injection risk and how tools treat untrusted data, read-only grants, and revoking access. | +| Docs for AI | `/docs/ai/docs-for-ai/` | New | Reference | `llms.txt`, `llms-full.txt`, the Markdown copy of every page, and the page actions. | + +### 3. Send data (clients) + +More clients are coming, so the section is built around languages as peers: + +- **One list of clients.** `_data/clients.json` holds each client's language, packages, install command, minimal setup + snippet, frameworks, minimum runtime, support level, repo, and docs URL. The client chooser, the quickstart tabs, the + feature matrix, the `llms.txt` client section, and the marketing home page's code tabs and FAQ answer all read from + it. +- **The same pages for every language.** Each language folder has an overview, app-type or framework guides, + configuration, sending events, client configuration values, plugins, private information, troubleshooting, and + upgrading, each from a shared template. A language that lacks a feature says so on that page instead of dropping it. +- **Shared behavior is explained once.** What a session is, how configuration values sync, and what data exclusions do + live in Use Exceptionless and How it works. Language pages cover only setup and API. +- **A client specification.** One reference page defines what every Exceptionless client does. It is the contract for + new official clients and for community ones. +- **Support levels.** Official, Community, and Preview. Only clients that work with 9.0 are listed, so the Java, Go, and + Python clients stay off until they are updated. + +| Page | URL | Status | Type | What it covers | +| --------------------- | ------------------------- | ------------- | --------- | ---------------------------------------------------------------------------------------------------- | +| Choose a client | `/docs/clients/` | Keep, rewrite | — | Language chooser with support levels, from `clients.json`. | +| Client feature matrix | `/docs/clients/features/` | New | Reference | Which features each client supports: sessions, logs, feature usage, configuration values, and so on. | + +**.NET** (`/docs/clients/dotnet/`) + +| Page | URL | Status | Type | What it covers | +| -------------------------------- | ------------------------------------- | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| .NET overview | `dotnet/` | Keep, rewrite | — | Packages, requirements (.NET 8+ for the ASP.NET Core, Hosting, and Logging packages; core on netstandard2.0), and a link to each app type. | +| ASP.NET Core | `dotnet/aspnet-core/` | New | How-to | `builder.AddExceptionless()`, `app.UseExceptionless()`, `IExceptionHandler`, problem details, and `appsettings.json`. | +| Worker services and generic host | `dotnet/worker-services/` | New | How-to | `Host.CreateApplicationBuilder` and flushing on shutdown. | +| Console apps | `dotnet/console/` | New | How-to | `Startup()` and `ProcessQueueAsync`. | +| Desktop apps | `dotnet/desktop/` | New | How-to | WPF, WinForms, and MAUI. | +| Blazor WebAssembly | `dotnet/blazor/` | New | How-to | Using the core package. | +| Serverless | `dotnet/serverless/` | New | How-to | AWS Lambda and Azure Functions, and processing the queue before returning. | +| Logging integrations | `dotnet/logging/` | New | How-to | Microsoft.Extensions.Logging, Serilog, NLog, and log4net. | +| Configuration | `dotnet/configuration/` | Keep, rewrite | Reference | `appsettings.json`, environment variables, and code. The `web.config` and attribute options move to the legacy page. | +| Sending events | `dotnet/sending-events/` | Keep, rewrite | How-to | Errors, logs, feature usage, 404s, custom events, the fluent builder, user identity, and sessions. | +| Client configuration values | `dotnet/client-configuration-values/` | Keep, merge `settings` | How-to | Reading server-synced settings and reacting to changes. | +| Plugins | `dotnet/plugins/` | Keep, rewrite | How-to | Enriching and excluding events, with a cross-platform example instead of `PerformanceCounter`. | +| Private information | `dotnet/private-information/` | Keep, rewrite | Reference | The `Include*` flags and data exclusions. | +| Legacy ASP.NET | `dotnet/legacy-aspnet/` | New | How-to | MVC, Web API, and WebForms on .NET Framework with `web.config`. | +| Troubleshooting | `dotnet/troubleshooting/` | Keep, rewrite | How-to | Client logging, the queue, storage, proxies, and certificates. Drops PCL and isolated storage paths. | +| Upgrading | `dotnet/upgrading/` | Keep, rewrite | How-to | 6.2 breaking changes first, older majors condensed. | + +**JavaScript** (`/docs/clients/javascript/`) + +| Page | URL | Status | Type | What it covers | +| --------------------------- | ----------------------------------------- | ------------------- | --------- | ------------------------------------------------------------------------ | +| JavaScript overview | `javascript/` | Keep, rewrite | — | Packages, ESM and ES2022, the CDN, and a link to each framework. | +| Framework guides | `javascript/guides/` | Keep, rewrite | — | Index of the guides below. | +| Browser | `javascript/guides/browser/` | New | How-to | npm and CDN setup. | +| Node.js and serverless | `javascript/guides/node/` | New | How-to | `processQueue` for short-lived processes. | +| Express | `javascript/guides/express/` | Keep, merge example | How-to | — | +| React | `javascript/guides/react/` | Keep, merge example | How-to | `ExceptionlessErrorBoundary` with `fallback` (React 18+). | +| React Native and Expo | `javascript/guides/react-native/` | New | How-to | The 3.2 package, the Expo config plugin, and native iOS crash reporting. | +| Next.js | `javascript/guides/nextjs/` | New | How-to | From the SDK's App Router example. | +| SvelteKit | `javascript/guides/sveltekit/` | New | How-to | From the SDK example. | +| Vue | `javascript/guides/vue/` | Keep, merge example | How-to | — | +| Angular | `javascript/guides/angular/` | Keep, rewrite | How-to | Standalone components and an `ErrorHandler` provider. | +| Configuration | `javascript/client-configuration/` | Keep, rewrite | Reference | — | +| Sending events | `javascript/sending-events/` | Keep, rewrite | How-to | — | +| Client configuration values | `javascript/client-configuration-values/` | Keep | How-to | — | +| Source maps | `javascript/source-maps/` | Moved | How-to | From `/docs/source-maps/`. | +| Troubleshooting | `javascript/troubleshooting/` | Keep, rewrite | How-to | — | + +**Other languages** + +| Page | URL | Status | Type | What it covers | +| ---------------------------------- | ------------------------------- | ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Other languages and custom clients | `/docs/clients/custom-clients/` | Keep, rewrite | How-to | Send events from any language over HTTP, and from shell scripts (Bash and PowerShell, which the app's setup page already offers). The event format and the client contract move to Reference. | + +### 4. Use Exceptionless + +| Page | URL | Status | Type | What it covers | +| ------------------------- | -------------------------------- | -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Events | `/docs/events/` | New | How-to | Event lists, the detail panel and its tabs, live updates, and finding an event by reference ID. | +| Stacks | `/docs/managing-stacks/` | Keep, merge `bulk-actions` | How-to | Statuses, fix, snooze, ignore, discard, critical, reference links, promote to webhook, and bulk actions. | +| Filtering and searching | `/docs/filtering-and-searching/` | Keep, split | How-to | The filter bar, filters, raw filters, and the date range. The field table moves to Reference. | +| Saved views | `/docs/saved-views/` | New | How-to | Built-in views, creating and sharing views, columns, charts, default views, and ordering. | +| Environments | `/docs/environments/` | Keep, rewrite | How-to | Setting the environment in each client once the SDKs ship it. Remove the release-notes section. | +| Releases and regressions | `/docs/versioning/` | Keep, rewrite | How-to | Versions, mark fixed in a version, and regression rules. | +| Logs and log levels | `/docs/setting-log-levels/` | Keep, rewrite | How-to | Log views and project and per-stack levels. | +| Feature usage | `/docs/feature-usage/` | New | How-to | Sending usage events and the Most Used Features view. | +| Sessions | `/docs/user-sessions/` | Keep, rewrite | How-to | — | +| Reference IDs | `/docs/references-ids/` | Keep, rewrite | How-to | A support workflow with a modern ASP.NET Core sample. | +| Notifications | `/docs/notifications/` | Keep, rewrite | How-to | Email and Slack, plus rate and budget notifications if #2271 and #2270 ship. | +| Integrations | `/docs/integrations/` | Keep, rewrite | How-to | Slack, webhooks (with a current payload), and Zapier. | +| Navigating the app | `/docs/navigation/` | New | How-to | The command palette, keyboard shortcuts, and guided tours. | +| Projects | `/docs/project-settings/` | Keep, rewrite | How-to | API keys, client configuration, data exclusions, stacking settings, spam detection, source maps, reset, and delete. Keeps the `#client-configuration` anchor. | +| Organizations and billing | `/docs/organizations/` | New | How-to | Users and invites, plans, upgrading, usage, and invoices. | +| Your account | `/docs/account/` | New | How-to | Profile, appearance, email notifications, AI Tools, connected applications, external logins, and password. | + +### 5. How it works + +| Page | URL | Status | Type | What it covers | +| ------------------------ | -------------------------- | ----------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | +| Stacking | `/docs/concepts/stacking/` | New, merges `manual-stacking` | Explanation | Signatures, stacking settings, manual stacking keys, and the Stacking information dialog. | +| Limits and deduplication | `/docs/concepts/limits/` | New, merges `deduplication` | Explanation | Plan limits from `plans.json`, retention, throttling, overage, client-side deduplication, and bursts. | +| Security and privacy | `/docs/security/` | Keep, rewrite | Explanation | Data handling, encryption in transit, private information, data exclusions, and access control. Links to AI privacy. | + +### 6. Reference + +| Page | URL | Status | Type | What it covers | +| -------------------- | -------------------------------- | ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Search syntax | `/docs/reference/search-syntax/` | New, from filtering | Reference | Every field, operators, ranges, and examples. | +| Event format | `/docs/reference/event-format/` | New, from custom clients | Reference | Event JSON, known types, and reserved data keys. Includes `environment`, `count`, and the browser and OS keys. | +| Client specification | `/docs/reference/client-spec/` | New, from custom clients | Reference | What every client does: submission and batching, the offline queue, retries and `429`/`503` handling, configuration value sync, session heartbeats, deduplication, data exclusions, and environments. | +| FAQ | `/docs/FAQ/` | Keep, trim | Reference | Only questions not answered elsewhere. The URL keeps its uppercase path. | + +### 7. REST API + +| Page | URL | Status | Type | What it covers | +| -------------------------- | --------------------------- | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| API overview | `/docs/api/` | Keep, rewrite | Reference | Base URLs, the Scalar reference at `/docs` and the OpenAPI JSON, status codes (402, 413, 429, 503), and rate limits. The MCP OAuth details move to the AI section. | +| Authentication | `/docs/api/authentication/` | New, merges `api-getting-started` | How-to | API keys, user tokens, OAuth bearer tokens, scopes, and the ways to pass a token. | +| Client-scoped tokens | `/docs/api/project-tokens/` | Keep, rewrite | How-to | In the new UI, plus the correct endpoint. | +| Posting events | `/docs/api/posting-events/` | Keep, rewrite | How-to | — | +| Querying events and stacks | `/docs/api/getting-events/` | Keep, rewrite | How-to | snake_case responses and paging. | + +### 8. Self-hosting + +| Page | URL | Status | Type | What it covers | +| ------------------------- | ---------------------------------------------------- | ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Overview and requirements | `/docs/self-hosting/` | Keep, rewrite | Explanation | Architecture (api, job, app, and all-in-one images), Elasticsearch and Redis versions, and storage and email options. A short reverse proxy section keeps the `#reverse-proxies-and-https` anchor and links to the new page. | +| Docker | `/docs/self-hosting/docker/` | Keep, rewrite | Tutorial | Docker Compose as the recommended path, plus the all-in-one image for trying it out. Fixes the SSL port example. | +| Kubernetes | `/docs/self-hosting/kubernetes/` | Keep, rewrite | How-to | The Helm chart, values, and ingress. Removes internal hosted-ops details and the Angular-era base URL advice. | +| Configuration | `/docs/self-hosting/configuration/` | New | Reference | `EX_` settings, connection strings, email, storage, OAuth login providers, LDAP, and account creation. | +| Reverse proxies and HTTPS | `/docs/self-hosting/reverse-proxy/` | New, from overview | How-to | Trusted forwarded-header peers, written for operators. | +| AI features | `/docs/self-hosting/ai/` | New | How-to | Enabling Exie (`Assistant` settings and model choice), the MCP server (`OAuthServer`, `Mcp:AllowedOrigins`), and turning AI off. | +| Administration | `/docs/self-hosting/administration/` | New | How-to | System pages: migrations, runtime settings and the event submission kill switch, Exie usage, OAuth apps, and notifications. | +| Upgrading | `/docs/self-hosting/upgrading-self-hosted-instance/` | Keep, rewrite | How-to | The current path: automatic migrations and reruns, Elasticsearch 8.19 to 9, and trusted proxies. The v1 to v5 content is dropped. | + +That is about 75 pages, up from 63, with less total text: duplicate clusters and example-only pages are merged. + +## AI throughout the docs + +- **AI is the second section** in the sidebar, right after Get started. +- **Agent setup path.** The quickstart and every client overview get an "Install with your coding agent" block: a + copyable prompt that points the agent at the page's Markdown and the SDK's agent skill (both SDK repos already have + `.agents/skills/...`). The prompt is opt-in for the reader. `llms.txt` stays factual and never contains instructions + aimed at agents. +- **"Ask Exie" blocks.** Task pages end with two or three copyable Exie prompts. Where it applies, they also show the + MCP tool and prompt an agent would use. This needs a small `prompt` component with a copy button. +- **Plan badges.** Exie pages and blocks show "Medium plans and up". The limits table comes from `plans.json`. +- **Security next to capability.** The MCP and Exie pages link to AI privacy and security. The MCP page has its own + scopes and prompt-injection section. +- **Docs for agents.** + - Split `llms.txt` by the new sections. + - Keep `llms-full.txt`. + - Add a small `llms-small.txt` with the get started, AI, and client overview pages. + - Keep Markdown copies of every page, and add redirect stubs for the old `.md` URLs. +- **Product follow-ups** (outside this docs PR, worth doing for launch): + - A `search_docs` MCP tool so agents can look things up while working. + - A server test that fails when an MCP tool exists that the MCP docs page does not list. + +### MCP client verification + +The MCP page documents a client only after it works end to end against a real deployment: sign-in and consent, a +read-only tool call, and a `stacks:write` action after granting it. + +What the server supports today: OAuth with Client ID Metadata Documents and dynamic client registration for public +clients, HTTPS or loopback redirect URIs, and requests with no `Origin` header, which server-side clients send. + +| Client | Evidence in the code today | Check | +| --------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------- | +| Claude Code | Tests use Claude Code's client metadata document | End to end | +| Codex | Tests register a Codex-style loopback client | End to end | +| VS Code and Copilot | Tests register a Copilot-style loopback client | End to end | +| Cursor | None | End to end | +| OpenCode | None | End to end | +| Claude.ai custom connectors | None. It should work on paper (registration with an HTTPS callback, calls from Anthropic's servers) | End to end on a public deployment | +| ChatGPT connectors | None. Same shape as Claude.ai | Worth trying | + +Claude.ai and ChatGPT cannot reach a local AppHost, so they need a public test deployment. A client that fails stays off +the page and gets an issue. + +## Site changes + +These come first, before content. + +1. **Redirects.** + - Add `redirectFrom: [...]` frontmatter. `postbuild.ts` writes an HTML stub at each old path and a Markdown stub at + each old `.md` path. + - Stubs keep the URL fragment, so `/docs/bulk-actions/` goes to `/docs/managing-stacks/#bulk-actions` and app links + with anchors keep working. +2. **A URL check that never forgets.** + - Commit today's list of docs URLs (`scripts/docs-urls.txt`). + - `deno task verify` fails if any of them stops resolving to a page or a stub. +3. **Explicit navigation.** + - A `_data/docs_nav.yml` file (or `section` and `order` frontmatter) defines sections and order, instead of folders + plus alphabetical titles. + - Previous and next links are generated from the nav, so the hand-written "Next >" links go away. +4. **Frontmatter.** + - Required: `title` and `description`. + - Optional: `metaTitle`, `redirectFrom`, and `plan` (renders a badge). + - `sources`: code paths the page is checked against, used in review and not rendered. +5. **Components.** + - A copyable `prompt` block for Exie and agent prompts. + - A plan badge. + - Language tabs built from `clients.json` plus curl, so a new language shows up on shared pages automatically. +6. **llms output.** Section mapping follows the new nav, plus `llms-small.txt`. +7. **Templates.** Every client app-type page follows the same outline: install, configure, verify with a test error, + what is captured automatically, next steps, and Ask Exie. Each language folder starts from the same set of page + templates. +8. **Client data.** Add `_data/clients.json`, and switch the marketing home page's code tabs and FAQ answer to read from + it. +9. **One API hostname.** Docs use `https://api.exceptionless.io` for the hosted API. `be.exceptionless.io` stays only + where a page means the web app. A verify check fails on `collector.exceptionless.io` or API paths on + `be.exceptionless.io`, and holds the allowed hostname in one constant, so a move to `api.exceptionless.com` is one + find-and-replace and one constant. + +## Accuracy + +- **Check every page against the code** listed in its `sources`, not against the old docs. +- **Snippets come from the SDK samples.** + - Exceptionless.Net `samples/` and the JavaScript `example/` apps. + - JavaScript's `packages/core/test/DocumentationExamples.test.ts`, which already tests documented usage. + - Each snippet notes its source in a comment in the Markdown source. +- **No unreleased APIs** unless they ship by launch, such as the environment APIs in the SDKs. +- **Review pass per section.** A second agent or a person checks claims against the code and runs the steps against a + local AppHost. +- **Screenshots go last,** once the UI is frozen, using the existing light and dark capture process. +- **App links.** The 12 docs links in the app keep working through redirects. A follow-up app PR points them at the new + pages. The app's Configure page also still shows `web.config` instructions as a main path, which is worth fixing at + the same time. + +## Launch dependencies + +Several in-flight PRs land before writing starts. When writing starts, check each one against main: document what has +merged and leave out what has not. + +| Change | Affects | +| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| Environment support in Exceptionless.Net #371 and Exceptionless.JavaScript #193 (unreleased) | Environments, client configuration. The SDKs must ship before 9.0, or the SDK sections come out. | +| Exie rebuild #2684 | Exie, AI privacy, navigation (the `a` shortcut) | +| Date range fields #2683 | Filtering | +| Microsoft sign-in #2403 | Account, self-hosting configuration | +| .NET 11 #2665 and Elasticsearch 9 #2416 | Self-hosting requirements and upgrading | +| Event telemetry and charts #2623 (draft) | Saved views, event format, MCP tools | +| Rate and budget notifications #2271 and #2270 | Notifications, organizations | +| Retry-After on 503 #2646 | API status codes, client troubleshooting | +| SSE push #2265 (draft) | Self-hosting reverse proxy | +| Typed custom fields #1815 (draft) | Filtering, saved views, event format | +| Connection string names #2273 (draft) | Self-hosting configuration | + +## Style guide + +A short `docs/STYLE.md` that every writer and agent follows: + +- **Voice.** Second person and present tense, with plain words and short paragraphs. Write for a developer in a hurry + and for an agent reading the Markdown. +- **Titles and headings.** Titles describe the task ("Send your first event"). Headings use sentence case. +- **Page shape.** Start with what the page lets you do, then the steps or facts. No history and no release notes in + pages; those go in What's new or the changelog. +- **Code.** Complete and runnable, with imports. Use the `YOUR_API_KEY` placeholder and hosted URLs, with self-hosted + overrides in a note. +- **UI names.** Match the UI exactly and set them in bold. Keyboard keys use ``. +- **Exie's voice.** Friendly and direct inside Exie's speech bubbles and prompt examples. Docs prose stays neutral. +- **Links.** Use relative docs links; never `blob/master` links with line anchors. Link to a heading only if it is + stable. +- **Screenshots.** Use the existing `![alt](/assets/img/docs/name-light.webp)` light and dark pairs, only when the UI is + hard to describe. + +## Phases + +1. **Land the in-flight PRs** that are part of 9.0, then check the launch dependency table against main. +2. **Foundation.** Redirects and the URL check, explicit nav, frontmatter, components, llms sections, the style guide, + and page templates. The site still builds, and every current URL resolves. +3. **Skeleton.** + - Create every page in the IA with its outline and `sources`. + - Move and merge pages with redirects. + - Park old content that has not been rewritten yet behind its new URL, so nothing is lost mid-rewrite. +4. **Write, in priority order:** + 1. Get started and AI. + 2. Clients. + 3. Use Exceptionless. + 4. How it works and reference. + 5. REST API. + 6. Self-hosting. + + Sections are independent and can be written in parallel against the style guide and templates. +5. **Review.** Check accuracy against the code, run the steps, run the snippets, verify each MCP client, and do an + editorial pass. +6. **Screenshots** once the UI is frozen. +7. **Launch.** + - Ship the app PR with updated docs links and any SDK releases. + - Run `deno task verify`. + - Submit the sitemap. + - Tag the release, which deploys the site. + +## Decisions + +1. **Scope.** Several in-flight PRs land before writing starts. The docs cover what is on main when writing starts. +2. **Version.** The launch is Exceptionless 9.0.0. +3. **Legacy upgrades.** The v1 to v5 self-hosted upgrade steps are dropped. +4. **Comparison page.** It goes away and redirects to `/why/`. +5. **Clients.** The docs and the marketing site are built for many languages (see [Send data](#3-send-data-clients)). + Only clients that work with 9.0 are listed. +6. **API hostname.** `api.exceptionless.io`, kept in one place so it can move to `api.exceptionless.com`. +7. **MCP clients.** Document only the clients that pass [verification](#mcp-client-verification). + +## Redirect map + +Every current page and where it goes. Pages not listed keep their URL. + +| Old URL | New URL | +| -------------------------------------------------------- | --------------------------------------------------- | +| `/docs/bulk-actions/` | `/docs/managing-stacks/#bulk-actions` | +| `/docs/manual-stacking/` | `/docs/concepts/stacking/#manual-stacking` | +| `/docs/deduplication/` | `/docs/concepts/limits/#deduplication` | +| `/docs/comparison/` | `/why/` | +| `/docs/source-maps/` | `/docs/clients/javascript/source-maps/` | +| `/docs/api/api-getting-started/` | `/docs/api/authentication/` | +| `/docs/clients/dotnet/settings/` | `/docs/clients/dotnet/client-configuration-values/` | +| `/docs/clients/dotnet/supported-platforms/` | `/docs/clients/dotnet/` | +| `/docs/clients/dotnet/guides/` | `/docs/clients/dotnet/` | +| `/docs/clients/dotnet/guides/web-server-example/` | `/docs/clients/dotnet/aspnet-core/` | +| `/docs/clients/dotnet/guides/console-apps-example/` | `/docs/clients/dotnet/console/` | +| `/docs/clients/dotnet/guides/logging-with-generic-host/` | `/docs/clients/dotnet/logging/` | +| `/docs/clients/javascript/javascript-example/` | `/docs/clients/javascript/guides/browser/` | +| `/docs/clients/javascript/node-example/` | `/docs/clients/javascript/guides/node/` | +| `/docs/clients/javascript/react-example/` | `/docs/clients/javascript/guides/react/` | +| `/docs/clients/javascript/vue-example/` | `/docs/clients/javascript/guides/vue/` | +| `/docs/clients/javascript/express-example/` | `/docs/clients/javascript/guides/express/` | +| `/docs/clients/javascript/guides/more-guides/` | `/docs/clients/javascript/guides/` | + +Anchors that the app or other pages link to stay on their new pages: + +- `/docs/project-settings/#client-configuration` +- `#data-exclusions` on project settings and security +- `/docs/self-hosting/#reverse-proxies-and-https` +- `/docs/api/project-tokens/#get-projects` +- `/docs/self-hosting/docker/#simple-setup-wssl-support-and-smtp` +- the Kubernetes `#configuration` and `#active-directory-authentication` anchors From e4fa8a1288cf542b29f653642d0038ae80837abd Mon Sep 17 00:00:00 2001 From: "Eric J. Smith" Date: Tue, 27 Oct 2026 23:36:47 -0500 Subject: [PATCH 2/3] Rewrite the docs for Exceptionless 9.0 Co-Authored-By: Claude Opus 5.5 --- docs/STYLE.md | 161 +++ docs/_config.ts | 75 +- docs/_data/client_features.json | 72 + docs/_data/clients.json | 319 +++++ docs/_data/docs_nav.yml | 120 ++ docs/_data/icons.json | 5 + docs/_data/site.json | 1 + docs/_includes/layouts/docs.vto | 5 +- docs/deno.json | 7 +- docs/docs/FAQ.md | 94 +- docs/docs/account.md | 124 ++ docs/docs/ai/coding-agents.md | 155 +++ docs/docs/ai/docs-for-ai.md | 53 + docs/docs/ai/exie.md | 216 ++- docs/docs/ai/index.md | 69 +- docs/docs/ai/mcp-server.md | 298 +++-- docs/docs/ai/privacy.md | 141 ++ docs/docs/api/api-getting-started.md | 57 - docs/docs/api/authentication.md | 141 ++ docs/docs/api/getting-events.md | 292 +++-- docs/docs/api/index.md | 134 +- docs/docs/api/posting-events.md | 212 ++- docs/docs/api/project-tokens.md | 152 ++- docs/docs/bulk-actions.md | 18 - docs/docs/clients/custom-clients/index.md | 309 +++-- docs/docs/clients/dotnet/aspnet-core.md | 238 ++++ docs/docs/clients/dotnet/blazor.md | 146 +++ .../dotnet/client-configuration-values.md | 195 ++- docs/docs/clients/dotnet/configuration.md | 412 +++--- docs/docs/clients/dotnet/console.md | 167 +++ docs/docs/clients/dotnet/desktop.md | 220 ++++ .../dotnet/guides/console-apps-example.md | 57 - docs/docs/clients/dotnet/guides/index.md | 20 - .../guides/logging-with-generic-host.md | 98 -- .../dotnet/guides/web-server-example.md | 72 - docs/docs/clients/dotnet/index.md | 148 ++- docs/docs/clients/dotnet/legacy-aspnet.md | 258 ++++ docs/docs/clients/dotnet/logging.md | 256 ++++ docs/docs/clients/dotnet/plugins.md | 188 +-- .../clients/dotnet/private-information.md | 127 +- docs/docs/clients/dotnet/sending-events.md | 287 ++-- docs/docs/clients/dotnet/serverless.md | 206 +++ docs/docs/clients/dotnet/settings.md | 179 --- .../clients/dotnet/supported-platforms.md | 56 - docs/docs/clients/dotnet/troubleshooting.md | 193 ++- docs/docs/clients/dotnet/upgrading.md | 227 ++-- docs/docs/clients/dotnet/worker-services.md | 177 +++ docs/docs/clients/features.md | 103 ++ docs/docs/clients/index.md | 45 +- .../javascript/client-configuration-values.md | 167 ++- .../javascript/client-configuration.md | 305 +++-- .../clients/javascript/express-example.md | 57 - .../docs/clients/javascript/guides/angular.md | 165 ++- .../docs/clients/javascript/guides/browser.md | 151 +++ .../docs/clients/javascript/guides/express.md | 175 ++- docs/docs/clients/javascript/guides/index.md | 49 +- .../clients/javascript/guides/more-guides.md | 14 - docs/docs/clients/javascript/guides/nextjs.md | 305 +++++ docs/docs/clients/javascript/guides/node.md | 180 +++ .../clients/javascript/guides/react-native.md | 203 +++ docs/docs/clients/javascript/guides/react.md | 197 ++- .../clients/javascript/guides/sveltekit.md | 142 ++ docs/docs/clients/javascript/guides/vue.md | 144 +- docs/docs/clients/javascript/index.md | 153 ++- .../clients/javascript/javascript-example.md | 15 - docs/docs/clients/javascript/node-example.md | 27 - docs/docs/clients/javascript/react-example.md | 60 - .../docs/clients/javascript/sending-events.md | 228 +++- docs/docs/clients/javascript/source-maps.md | 216 +++ .../clients/javascript/troubleshooting.md | 148 ++- docs/docs/clients/javascript/vue-example.md | 13 - docs/docs/comparison.md | 46 - docs/docs/concepts/index.md | 124 ++ docs/docs/concepts/limits.md | 192 +++ docs/docs/concepts/stacking.md | 176 +++ docs/docs/deduplication.md | 16 - docs/docs/demo-formatting.md | 90 +- docs/docs/environments.md | 166 ++- docs/docs/events.md | 165 +++ docs/docs/feature-usage.md | 98 ++ docs/docs/filtering-and-searching.md | 238 ++-- docs/docs/getting-started.md | 183 ++- docs/docs/index.md | 50 +- docs/docs/integrations.md | 197 ++- docs/docs/managing-stacks.md | 202 ++- docs/docs/manual-stacking.md | 75 -- docs/docs/navigation.md | 114 ++ docs/docs/notifications.md | 120 +- docs/docs/organizations.md | 167 +++ docs/docs/project-settings.md | 275 ++-- docs/docs/reference/client-spec.md | 301 +++++ docs/docs/reference/event-format.md | 341 +++++ docs/docs/reference/search-syntax.md | 217 +++ docs/docs/references-ids.md | 243 ++-- docs/docs/saved-views.md | 139 ++ docs/docs/security.md | 164 ++- docs/docs/self-hosting/administration.md | 162 +++ docs/docs/self-hosting/ai.md | 137 ++ docs/docs/self-hosting/configuration.md | 281 ++++ docs/docs/self-hosting/docker.md | 261 +++- docs/docs/self-hosting/index.md | 111 +- docs/docs/self-hosting/kubernetes.md | 316 +++-- docs/docs/self-hosting/reverse-proxy.md | 230 ++++ .../upgrading-self-hosted-instance.md | 1167 ++--------------- docs/docs/setting-log-levels.md | 99 +- docs/docs/source-maps.md | 155 --- docs/docs/user-sessions.md | 178 ++- docs/docs/versioning.md | 126 +- docs/docs/whats-new.md | 205 +++ docs/index.vto | 78 +- docs/public/assets/css/site.css | 343 ++++- docs/public/assets/img/logo-dark.svg | 38 +- docs/public/assets/img/logo.svg | 38 +- docs/public/assets/js/site.js | 93 +- docs/public/favicon.svg | 27 +- docs/scripts/clients.ts | 249 ++++ docs/scripts/docs-components.ts | 101 ++ docs/scripts/docs-markdown.test.ts | 295 +++++ docs/scripts/docs-markdown.ts | 305 +++++ docs/scripts/docs-nav.test.ts | 97 ++ docs/scripts/docs-nav.ts | 197 +++ docs/scripts/docs-urls.txt | 127 ++ docs/scripts/postbuild.ts | 195 ++- docs/scripts/redirects.test.ts | 95 ++ docs/scripts/redirects.ts | 159 +++ docs/scripts/site-collections.ts | 225 ++-- docs/scripts/structured-data.ts | 3 +- docs/scripts/test-helpers.ts | 37 + docs/scripts/verify-docs.ts | 227 ++++ docs/why.vto | 3 +- 130 files changed, 15979 insertions(+), 4899 deletions(-) create mode 100644 docs/STYLE.md create mode 100644 docs/_data/client_features.json create mode 100644 docs/_data/clients.json create mode 100644 docs/_data/docs_nav.yml create mode 100644 docs/docs/account.md create mode 100644 docs/docs/ai/coding-agents.md create mode 100644 docs/docs/ai/docs-for-ai.md create mode 100644 docs/docs/ai/privacy.md delete mode 100644 docs/docs/api/api-getting-started.md create mode 100644 docs/docs/api/authentication.md delete mode 100644 docs/docs/bulk-actions.md create mode 100644 docs/docs/clients/dotnet/aspnet-core.md create mode 100644 docs/docs/clients/dotnet/blazor.md create mode 100644 docs/docs/clients/dotnet/console.md create mode 100644 docs/docs/clients/dotnet/desktop.md delete mode 100644 docs/docs/clients/dotnet/guides/console-apps-example.md delete mode 100644 docs/docs/clients/dotnet/guides/index.md delete mode 100644 docs/docs/clients/dotnet/guides/logging-with-generic-host.md delete mode 100644 docs/docs/clients/dotnet/guides/web-server-example.md create mode 100644 docs/docs/clients/dotnet/legacy-aspnet.md create mode 100644 docs/docs/clients/dotnet/logging.md create mode 100644 docs/docs/clients/dotnet/serverless.md delete mode 100644 docs/docs/clients/dotnet/settings.md delete mode 100644 docs/docs/clients/dotnet/supported-platforms.md create mode 100644 docs/docs/clients/dotnet/worker-services.md create mode 100644 docs/docs/clients/features.md delete mode 100644 docs/docs/clients/javascript/express-example.md create mode 100644 docs/docs/clients/javascript/guides/browser.md delete mode 100644 docs/docs/clients/javascript/guides/more-guides.md create mode 100644 docs/docs/clients/javascript/guides/nextjs.md create mode 100644 docs/docs/clients/javascript/guides/node.md create mode 100644 docs/docs/clients/javascript/guides/react-native.md create mode 100644 docs/docs/clients/javascript/guides/sveltekit.md delete mode 100644 docs/docs/clients/javascript/javascript-example.md delete mode 100644 docs/docs/clients/javascript/node-example.md delete mode 100644 docs/docs/clients/javascript/react-example.md create mode 100644 docs/docs/clients/javascript/source-maps.md delete mode 100644 docs/docs/clients/javascript/vue-example.md delete mode 100644 docs/docs/comparison.md create mode 100644 docs/docs/concepts/index.md create mode 100644 docs/docs/concepts/limits.md create mode 100644 docs/docs/concepts/stacking.md delete mode 100644 docs/docs/deduplication.md create mode 100644 docs/docs/events.md create mode 100644 docs/docs/feature-usage.md delete mode 100644 docs/docs/manual-stacking.md create mode 100644 docs/docs/navigation.md create mode 100644 docs/docs/organizations.md create mode 100644 docs/docs/reference/client-spec.md create mode 100644 docs/docs/reference/event-format.md create mode 100644 docs/docs/reference/search-syntax.md create mode 100644 docs/docs/saved-views.md create mode 100644 docs/docs/self-hosting/administration.md create mode 100644 docs/docs/self-hosting/ai.md create mode 100644 docs/docs/self-hosting/configuration.md create mode 100644 docs/docs/self-hosting/reverse-proxy.md delete mode 100644 docs/docs/source-maps.md create mode 100644 docs/docs/whats-new.md create mode 100644 docs/scripts/clients.ts create mode 100644 docs/scripts/docs-components.ts create mode 100644 docs/scripts/docs-markdown.test.ts create mode 100644 docs/scripts/docs-markdown.ts create mode 100644 docs/scripts/docs-nav.test.ts create mode 100644 docs/scripts/docs-nav.ts create mode 100644 docs/scripts/docs-urls.txt create mode 100644 docs/scripts/redirects.test.ts create mode 100644 docs/scripts/redirects.ts create mode 100644 docs/scripts/test-helpers.ts create mode 100644 docs/scripts/verify-docs.ts diff --git a/docs/STYLE.md b/docs/STYLE.md new file mode 100644 index 0000000000..70d0b74c5d --- /dev/null +++ b/docs/STYLE.md @@ -0,0 +1,161 @@ +# Docs style guide + +How the Exceptionless docs are written. Every writer, person or agent, follows it. + +## Voice + +- Second person, present tense, plain words, short paragraphs. Write for a developer in a hurry and for an agent reading + the Markdown copy of the page. +- Neutral and direct. No marketing language ("powerful", "seamless", "simply"), no jokes, no emoji. +- Exie's friendly voice belongs only inside Exie's speech bubbles and prompt examples. + +## Page shape + +- One page, one type: a tutorial, a how-to guide, reference, or an explanation. +- Start with one or two sentences on what the page lets you do. Then the steps or the facts. +- No history and no release notes. "What changed in 9.0" goes on What's new, version history on the upgrading pages. +- Task pages end with an `## Ask Exie` section (see [Prompts](#prompts)). +- Don't write "Next" or "Previous" links. The layout generates them from the nav. + +## Titles and headings + +- The `title` frontmatter describes the page in a few words ("Send your first event", "ASP.NET Core"). The page body + starts with a matching `# Heading`. +- Headings use sentence case: "Mark a stack fixed", not "Mark A Stack Fixed". +- To keep an anchor that other pages or the app link to, give the heading an explicit id: + `## Client configuration + {#client-configuration}`. + +## Frontmatter + +```yaml +--- +title: "Saved views" +description: "One or two sentences, at most 160 characters, used for search results and social cards." +navTitle: "Saved views" # optional shorter sidebar label +plan: "Medium" # optional; renders a "Medium plan and up" badge. Use a plan name from _data/plans.json. +redirectFrom: # optional; old URLs that now point at this page + - /docs/manual-stacking/ + - from: /docs/bulk-actions/ + anchor: bulk-actions # optional; the redirect lands on this heading +sources: # code the page is checked against; not rendered + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs + - Exceptionless.Net:src/Platforms/Exceptionless.AspNetCore/ExceptionlessExtensions.cs + - Exceptionless.JavaScript:packages/core/src/configuration/Configuration.ts +--- +``` + +`sources` paths are relative to this repository unless prefixed with `Exceptionless.Net:` or +`Exceptionless.JavaScript:`. + +## Code + +- Complete and runnable, with imports and package installs. +- Use the `YOUR_API_KEY` placeholder for API keys. +- Hosted URLs: the API is `https://api.exceptionless.io`, and the web app is `https://be.exceptionless.io`. Never + `collector.exceptionless.io`. Self-hosted overrides go in a note. +- Modern setup first: ASP.NET Core minimal hosting with `appsettings.json`, ES modules. .NET Framework and `web.config` + belong on the legacy ASP.NET page. +- Only document released APIs: Exceptionless.Net 6.2.0 and Exceptionless.JavaScript 3.2.1. +- Show the same thing in several languages with tabs: adjacent fenced code blocks that each have a `tab` label. + + ````markdown + ```csharp tab=".NET" + ExceptionlessClient.Default.SubmitLog("Order placed"); + ``` + + ```ts tab="JavaScript" + await Exceptionless.submitLog("Order placed") + ``` + + ```bash tab="curl" + curl -X POST https://api.exceptionless.io/api/v2/events ... + ``` + ```` + +- To show the install and setup snippet for every client from `_data/clients.json`, use an empty `clients` block: + + ````markdown + ```clients + ``` + ```` + +## Callouts + +Use GitHub alert syntax, and use it sparingly: + +```markdown +> [!NOTE] +> Self-hosted instances use your own API URL instead. +``` + +`[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, and `[!WARNING]` are supported. + +## Prompts + +Copyable prompts use a `prompt` fenced block. The second word says who the prompt is for: + +- `prompt exie`: something to ask Exie in the app. +- `prompt agent`: something to paste into a coding agent, such as Claude Code, Codex, or Copilot. + +````markdown +## Ask Exie + +```prompt exie +Which new stacks appeared in production since yesterday's deploy? +``` + +```prompt exie +Snooze the stacks from the payments worker for a day. +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can do the same: + +```prompt agent +Find the most frequent new error in my Exceptionless project, fix it, and mark the stack fixed in the next version. +``` +```` + +Prompts must be things Exie and the MCP tools can actually do today. Check the tool list in the code before writing one. + +## UI names and keys + +- UI names match the app exactly and are bold: **Stacks**, **Mark Fixed**, **Project Settings**. +- Keyboard keys use ``: Ctrl+K. + +## Links + +- Link to docs pages with site paths and a trailing slash: `/docs/saved-views/`. +- Link to a heading only if it has a stable id. +- Link to code on GitHub at the default branch and a file path, never a line number. + +## Screenshots + +- Use the existing light and dark pairs: `![Alt text](/assets/img/docs/name-light.webp)`. The dark image is picked up + automatically. +- Only add a screenshot when the UI is hard to describe. Never leave a screenshot that shows the old UI. + +## Page templates + +**Client app-type page** (for example `/docs/clients/dotnet/aspnet-core/`): + +1. What it captures, in one or two sentences, and the requirements. +2. Install. +3. Configure. +4. Verify: throw a test error and find it in the app. +5. What is captured automatically. +6. Next steps. +7. Ask Exie. + +**Feature how-to** (for example `/docs/saved-views/`): + +1. What the feature does and when to use it. +2. One section per task, named for the task. +3. Self-hosting notes, if behavior differs. +4. Ask Exie. + +**Reference** (for example `/docs/reference/search-syntax/`): a short introduction, then tables or definition lists. No +"Ask Exie" section. + +**Explanation** (for example `/docs/concepts/stacking/`): the idea, how it works, what you can change, and links to the +how-to pages. diff --git a/docs/_config.ts b/docs/_config.ts index c35954778e..ec60769e0b 100644 --- a/docs/_config.ts +++ b/docs/_config.ts @@ -1,6 +1,14 @@ import lume from "lume/mod.ts" import codeHighlight from "lume/plugins/code_highlight.ts" -import { docsBreadcrumbs, docsNavHtml, siteDataJson } from "./scripts/site-collections.ts" +import { + type Client, + clientsSentence, + type FeatureDefinition, + renderHomeClientTabs, + validateClients, +} from "./scripts/clients.ts" +import { docsMarkdown } from "./scripts/docs-markdown.ts" +import { docsBreadcrumbs, docsNavHtml, docsPagerHtml, siteDataJson } from "./scripts/site-collections.ts" import { defaultSocialImage, structuredData } from "./scripts/structured-data.ts" const site = lume({ @@ -23,6 +31,7 @@ site.ignore( "package.json", "public", "README.md", + "STYLE.md", "scripts", "serialization-architecture.md", "site-migration-plan.md", @@ -31,27 +40,18 @@ site.ignore( site.use(codeHighlight()) -site.hooks.markdownIt((markdownIt: any) => { - const defaultHeadingOpen = markdownIt.renderer.rules.heading_open ?? - ((tokens: any[], index: number, options: unknown, env: Record, self: any) => { - return self.renderToken(tokens, index, options) - }) - - markdownIt.renderer.rules.heading_open = ( - tokens: any[], - index: number, - options: unknown, - env: Record, - self: any, - ) => { - const token = tokens[index] - if (!token.attrGet("id")) { - const content = tokens[index + 1]?.content ?? "" - token.attrSet("id", uniqueHeadingSlug(content, env)) - } +const icons = readJson>("_data/icons.json") +const clients = readJson("_data/clients.json") +const clientFeatures = readJson("_data/client_features.json") +validateClients(clients, clientFeatures) - return defaultHeadingOpen(tokens, index, options, env, self) - } +site.hooks.markdownIt((markdownIt: any) => { + docsMarkdown(markdownIt, { + icons, + clients, + features: clientFeatures, + plans: readJson<{ name: string }[]>("_data/plans.json").map((plan) => plan.name), + }) const defaultImage = markdownIt.renderer.rules.image markdownIt.renderer.rules.image = ( @@ -76,6 +76,9 @@ site.preprocess([".md"], (pages) => { }) site.data("docsNavHtml", docsNavHtml) +site.data("docsPagerHtml", docsPagerHtml) +site.data("homeClientTabs", () => renderHomeClientTabs(clients, icons)) +site.data("clientsSentence", () => clientsSentence(clients)) site.data("docsBreadcrumbs", docsBreadcrumbs) site.data("structuredData", structuredData) site.data("defaultSocialImage", defaultSocialImage) @@ -228,32 +231,6 @@ function exceptionlessClientScriptSrc(): string { return `/assets/js/exceptionless-client.js?${params}` } -function uniqueHeadingSlug(value: string, env: Record): string { - const counts = getHeadingSlugCounts(env) - const baseSlug = slugifyHeading(value) || "section" - const count = counts.get(baseSlug) ?? 0 - counts.set(baseSlug, count + 1) - return count ? `${baseSlug}-${count}` : baseSlug -} - -function getHeadingSlugCounts(env: Record): Map { - const key = "__headingSlugCounts" - const existing = env[key] - if (existing instanceof Map) { - return existing as Map - } - - const counts = new Map() - env[key] = counts - return counts -} - -function slugifyHeading(value: string): string { - return value - .trim() - .toLowerCase() - .replace(/\s+/g, "-") - .replace(/\./g, "") - .replace(/[^a-z0-9_-]/g, "") - .replace(/^-+|-+$/g, "") +function readJson(path: string): T { + return JSON.parse(Deno.readTextFileSync(path)) as T } diff --git a/docs/_data/client_features.json b/docs/_data/client_features.json new file mode 100644 index 0000000000..2db34607e0 --- /dev/null +++ b/docs/_data/client_features.json @@ -0,0 +1,72 @@ +[ + { + "id": "unhandledErrors", + "label": "Unhandled error capture", + "description": "Reports errors your code does not catch, without any extra calls." + }, + { + "id": "manualErrors", + "label": "Manual error submission", + "description": "Sends an error you caught and handled." + }, + { + "id": "logs", + "label": "Log messages", + "description": "Sends log events with a source and a level." + }, + { + "id": "featureUsage", + "label": "Feature usage", + "description": "Sends an event each time a feature is used." + }, + { + "id": "notFound", + "label": "404 tracking", + "description": "Reports requests for resources that do not exist." + }, + { + "id": "userIdentity", + "label": "User identity", + "description": "Attaches a user ID and name to events." + }, + { + "id": "sessions", + "label": "Sessions and heartbeats", + "description": "Sends session start, heartbeat, and end events." + }, + { + "id": "referenceIds", + "label": "Reference IDs", + "description": "Gives each error a short ID that a user can quote to support." + }, + { + "id": "configValues", + "label": "Server-synced configuration values", + "description": "Reads project settings from the server and reacts when they change." + }, + { + "id": "plugins", + "label": "Plugins", + "description": "Adds data to events or cancels them before they are sent." + }, + { + "id": "dataExclusions", + "label": "Data exclusions", + "description": "Removes sensitive fields from events on the client." + }, + { + "id": "offlineQueue", + "label": "Offline queue persistence", + "description": "Keeps queued events across restarts and sends them when the network returns." + }, + { + "id": "deduplication", + "label": "Deduplication", + "description": "Merges identical errors that occur in a short window into one event with a count." + }, + { + "id": "sourceMaps", + "label": "Source maps", + "description": "Readable stack traces for minified JavaScript." + } +] diff --git a/docs/_data/clients.json b/docs/_data/clients.json new file mode 100644 index 0000000000..dcc0734210 --- /dev/null +++ b/docs/_data/clients.json @@ -0,0 +1,319 @@ +[ + { + "id": "dotnet", + "language": ".NET", + "name": "Exceptionless.Net", + "support": "Official", + "repo": "https://github.com/exceptionless/Exceptionless.Net", + "docsUrl": "/docs/clients/dotnet/", + "version": "6.2.0", + "minimumRuntime": ".NET 8 for ASP.NET Core, hosting, and Microsoft.Extensions.Logging. .NET Standard 2.0 or .NET Framework 4.6.2 for the core package.", + "summary": "ASP.NET Core, worker services, console, WPF, WinForms, and Blazor apps, with Microsoft.Extensions.Logging, NLog, and log4net integrations", + "packages": [ + { + "name": "Exceptionless", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless", + "description": "Core client for console apps, services, and libraries.", + "minimumRuntime": ".NET Standard 2.0, .NET Framework 4.6.2" + }, + { + "name": "Exceptionless.AspNetCore", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless.AspNetCore", + "description": "ASP.NET Core integration: exception handler, 404 tracking, and request details.", + "minimumRuntime": ".NET 8" + }, + { + "name": "Exceptionless.Extensions.Hosting", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless.Extensions.Hosting", + "description": "Generic host and worker service integration, with queue flushing on shutdown.", + "minimumRuntime": ".NET 8" + }, + { + "name": "Exceptionless.Extensions.Logging", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless.Extensions.Logging", + "description": "Microsoft.Extensions.Logging provider.", + "minimumRuntime": ".NET 8" + }, + { + "name": "Exceptionless.NLog", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless.NLog", + "description": "NLog target.", + "minimumRuntime": ".NET Standard 2.0, .NET Framework 4.6.2" + }, + { + "name": "Exceptionless.Log4net", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless.Log4net", + "description": "log4net appender.", + "minimumRuntime": ".NET Standard 2.0, .NET Framework 4.6.2" + }, + { + "name": "Exceptionless.Wpf", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless.Wpf", + "description": "WPF integration.", + "minimumRuntime": ".NET 8 (Windows), .NET Framework 4.6.2" + }, + { + "name": "Exceptionless.Windows", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless.Windows", + "description": "Windows Forms integration.", + "minimumRuntime": ".NET 8 (Windows), .NET Framework 4.6.2" + }, + { + "name": "Exceptionless.Mvc", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless.Mvc", + "description": "ASP.NET MVC on .NET Framework.", + "minimumRuntime": ".NET Framework 4.6.2" + }, + { + "name": "Exceptionless.WebApi", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless.WebApi", + "description": "ASP.NET Web API on .NET Framework.", + "minimumRuntime": ".NET Framework 4.6.2" + }, + { + "name": "Exceptionless.Web", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless.Web", + "description": "ASP.NET WebForms on .NET Framework.", + "minimumRuntime": ".NET Framework 4.6.2" + } + ], + "snippets": [ + { + "label": "ASP.NET Core", + "package": "Exceptionless.AspNetCore", + "install": "dotnet add package Exceptionless.AspNetCore", + "language": "csharp", + "code": "using Exceptionless;\n\nvar builder = WebApplication.CreateBuilder(args);\nbuilder.AddExceptionless(\"YOUR_API_KEY\");\nbuilder.Services.AddProblemDetails();\n\nvar app = builder.Build();\napp.UseExceptionHandler();\napp.UseExceptionless();\n\napp.Run();", + "caption": "Reads your API key from the Exceptionless section of appsettings.json when you call AddExceptionless() with no arguments.", + "docsUrl": "/docs/clients/dotnet/aspnet-core/" + }, + { + "label": ".NET", + "package": "Exceptionless", + "install": "dotnet add package Exceptionless", + "language": "csharp", + "code": "using Exceptionless;\n\nExceptionlessClient.Default.Startup(\"YOUR_API_KEY\");\n\ntry\n{\n throw new InvalidOperationException(\"Order 1234 could not be submitted\");\n}\ncatch (Exception ex)\n{\n ex.ToExceptionless()\n .SetProperty(\"OrderId\", 1234)\n .AddTags(\"checkout\")\n .MarkAsCritical()\n .Submit();\n}", + "caption": "Works in console apps, services, desktop apps, and anything else on .NET. Unhandled exceptions are captured after Startup.", + "docsUrl": "/docs/clients/dotnet/console/" + } + ], + "features": { + "unhandledErrors": { + "status": "yes", + "note": "Startup hooks AppDomain and unobserved task exceptions. ASP.NET Core uses an IExceptionHandler." + }, + "manualErrors": { + "status": "yes", + "note": "ToExceptionless().Submit()" + }, + "logs": { + "status": "yes", + "note": "SubmitLog, plus Microsoft.Extensions.Logging, NLog, and log4net integrations." + }, + "featureUsage": { + "status": "yes", + "note": "SubmitFeatureUsage" + }, + "notFound": { + "status": "yes", + "note": "Automatic in ASP.NET Core with UseExceptionless(). Call SubmitNotFound elsewhere." + }, + "userIdentity": { + "status": "yes", + "note": "SetUserIdentity. ASP.NET Core uses the authenticated user's name when none is set." + }, + "sessions": { + "status": "opt-in", + "note": "Call UseSessions() on the configuration." + }, + "referenceIds": { + "status": "opt-in", + "note": "Call UseReferenceIds() on the configuration." + }, + "configValues": { + "status": "yes", + "note": "Settings, with a Changed event. Checked every 2 minutes while idle." + }, + "plugins": { + "status": "yes", + "note": "AddPlugin with a class or an action." + }, + "dataExclusions": { + "status": "yes", + "note": "AddDataExclusions, or a project-level exclusion list." + }, + "offlineQueue": { + "status": "opt-in", + "note": "The queue is in memory by default. Call UseFolderStorage or UseIsolatedStorage to persist it." + }, + "deduplication": { + "status": "yes", + "note": "Identical events within 60 seconds are merged into one with a count." + }, + "sourceMaps": { + "status": "n/a", + "note": "Source maps apply to JavaScript." + } + } + }, + { + "id": "javascript", + "language": "JavaScript", + "name": "Exceptionless.JavaScript", + "support": "Official", + "repo": "https://github.com/exceptionless/Exceptionless.JavaScript", + "docsUrl": "/docs/clients/javascript/", + "version": "3.2.1", + "minimumRuntime": "ES2022 browsers, Node.js 18, and React Native 0.71 with React 18.", + "summary": "Browser, Node.js, React, Vue, Angular, Express, and React Native with Expo", + "packages": [ + { + "name": "@exceptionless/browser", + "registry": "npm", + "url": "https://www.npmjs.com/package/@exceptionless/browser", + "description": "Browser client. Also available from a CDN as an ES module.", + "minimumRuntime": "ES2022 browsers" + }, + { + "name": "@exceptionless/node", + "registry": "npm", + "url": "https://www.npmjs.com/package/@exceptionless/node", + "description": "Node.js client, including Express apps and serverless functions.", + "minimumRuntime": "Node.js 18" + }, + { + "name": "@exceptionless/react", + "registry": "npm", + "url": "https://www.npmjs.com/package/@exceptionless/react", + "description": "React error boundary on top of the browser client.", + "minimumRuntime": "React 18" + }, + { + "name": "@exceptionless/vue", + "registry": "npm", + "url": "https://www.npmjs.com/package/@exceptionless/vue", + "description": "Vue error handler on top of the browser client.", + "minimumRuntime": "ES2022 browsers" + }, + { + "name": "@exceptionless/angularjs", + "registry": "npm", + "url": "https://www.npmjs.com/package/@exceptionless/angularjs", + "description": "AngularJS module on top of the browser client.", + "minimumRuntime": "ES2022 browsers" + }, + { + "name": "@exceptionless/react-native", + "registry": "npm", + "url": "https://www.npmjs.com/package/@exceptionless/react-native", + "description": "React Native and Expo client with native iOS crash reporting and a persistent queue.", + "minimumRuntime": "React Native 0.71, React 18" + }, + { + "name": "@exceptionless/core", + "registry": "npm", + "url": "https://www.npmjs.com/package/@exceptionless/core", + "description": "Shared core that the other packages build on. Install a platform package instead.", + "minimumRuntime": "ES2022" + } + ], + "snippets": [ + { + "label": "Browser", + "package": "@exceptionless/browser", + "install": "npm install @exceptionless/browser", + "language": "js", + "code": "import { Exceptionless } from \"@exceptionless/browser\";\n\nawait Exceptionless.startup(\"YOUR_API_KEY\");\n\n// Unhandled errors are captured automatically.\n// Track the things you care about, too:\nawait Exceptionless.submitFeatureUsage(\"Checkout\");", + "caption": "Upload source maps to get readable stack traces from minified bundles.", + "docsUrl": "/docs/clients/javascript/guides/browser/" + }, + { + "label": "Node.js", + "package": "@exceptionless/node", + "install": "npm install @exceptionless/node", + "language": "js", + "code": "import { Exceptionless } from \"@exceptionless/node\";\n\nawait Exceptionless.startup(\"YOUR_API_KEY\");\n\ntry {\n throw new Error(\"Orders import failed\");\n} catch (error) {\n await Exceptionless.submitException(error);\n}", + "caption": "Also available for Express, React, Vue, and Angular apps.", + "docsUrl": "/docs/clients/javascript/guides/node/" + }, + { + "label": "React Native", + "package": "@exceptionless/react-native", + "install": "npx expo install @exceptionless/react-native @react-native-async-storage/async-storage", + "language": "js", + "code": "import { Exceptionless } from \"@exceptionless/react-native\";\n\nawait Exceptionless.startup((c) => {\n c.apiKey = \"YOUR_API_KEY\";\n});\n\n// JavaScript errors and promise rejections are captured automatically.\nawait Exceptionless.submitFeatureUsage(\"Checkout\");", + "caption": "Works with Expo and bare React Native. Add the Expo config plugin for native iOS crash reporting.", + "docsUrl": "/docs/clients/javascript/guides/react-native/" + } + ], + "features": { + "unhandledErrors": { + "status": "yes", + "note": "Browser error and unhandledrejection events, Node.js uncaught exceptions and rejections, and React Native JavaScript errors plus native iOS crashes." + }, + "manualErrors": { + "status": "yes", + "note": "submitException" + }, + "logs": { + "status": "yes", + "note": "submitLog" + }, + "featureUsage": { + "status": "yes", + "note": "submitFeatureUsage" + }, + "notFound": { + "status": "partial", + "note": "Call submitNotFound. The browser client reports 404s from jQuery ajax calls automatically." + }, + "userIdentity": { + "status": "yes", + "note": "setUserIdentity" + }, + "sessions": { + "status": "opt-in", + "note": "Call useSessions() on the configuration." + }, + "referenceIds": { + "status": "yes", + "note": "Error events get a reference ID automatically. Read it with getLastReferenceId()." + }, + "configValues": { + "status": "yes", + "note": "settings, with subscribeServerSettingsChange. Checked every 2 minutes while idle." + }, + "plugins": { + "status": "yes", + "note": "addPlugin with an object or a function." + }, + "dataExclusions": { + "status": "yes", + "note": "addDataExclusions, or a project-level exclusion list." + }, + "offlineQueue": { + "status": "opt-in", + "note": "Set usePersistedQueueStorage = true in the browser and Node.js. React Native persists the queue by default." + }, + "deduplication": { + "status": "yes", + "note": "Identical errors are merged into one event with a count." + }, + "sourceMaps": { + "status": "yes", + "note": "The server applies public or uploaded source maps to stack frames with absolute script URLs." + } + } + } +] diff --git a/docs/_data/docs_nav.yml b/docs/_data/docs_nav.yml new file mode 100644 index 0000000000..b08bbd4b84 --- /dev/null +++ b/docs/_data/docs_nav.yml @@ -0,0 +1,120 @@ +# The docs sidebar, previous and next links, breadcrumbs, and llms.txt sections all come from this file. +# +# - section: a top-level sidebar section. +# - A plain URL is a page. The page's navTitle (or title) is its label. +# - group: a collapsible sub-group. Give it a url to link the group heading to its overview page; that page then comes +# first in the reading order, before the group's items. +# +# deno task verify fails if a URL here has no page, or if a published docs page is missing from this file. +- section: Get started + items: + - /docs/ + - /docs/getting-started/ + - /docs/concepts/ + - /docs/whats-new/ + +- section: AI + items: + - /docs/ai/ + - /docs/ai/exie/ + - /docs/ai/mcp-server/ + - /docs/ai/coding-agents/ + - /docs/ai/privacy/ + - /docs/ai/docs-for-ai/ + +- section: Send data + items: + - /docs/clients/ + - /docs/clients/features/ + - group: .NET + url: /docs/clients/dotnet/ + items: + - /docs/clients/dotnet/aspnet-core/ + - /docs/clients/dotnet/worker-services/ + - /docs/clients/dotnet/console/ + - /docs/clients/dotnet/desktop/ + - /docs/clients/dotnet/blazor/ + - /docs/clients/dotnet/serverless/ + - /docs/clients/dotnet/logging/ + - /docs/clients/dotnet/configuration/ + - /docs/clients/dotnet/sending-events/ + - /docs/clients/dotnet/client-configuration-values/ + - /docs/clients/dotnet/plugins/ + - /docs/clients/dotnet/private-information/ + - /docs/clients/dotnet/legacy-aspnet/ + - /docs/clients/dotnet/troubleshooting/ + - /docs/clients/dotnet/upgrading/ + - group: JavaScript + url: /docs/clients/javascript/ + items: + - group: Framework guides + url: /docs/clients/javascript/guides/ + items: + - /docs/clients/javascript/guides/browser/ + - /docs/clients/javascript/guides/node/ + - /docs/clients/javascript/guides/express/ + - /docs/clients/javascript/guides/react/ + - /docs/clients/javascript/guides/react-native/ + - /docs/clients/javascript/guides/nextjs/ + - /docs/clients/javascript/guides/sveltekit/ + - /docs/clients/javascript/guides/vue/ + - /docs/clients/javascript/guides/angular/ + - /docs/clients/javascript/client-configuration/ + - /docs/clients/javascript/sending-events/ + - /docs/clients/javascript/client-configuration-values/ + - /docs/clients/javascript/source-maps/ + - /docs/clients/javascript/troubleshooting/ + - group: Other languages + items: + - /docs/clients/custom-clients/ + +- section: Use Exceptionless + items: + - /docs/events/ + - /docs/managing-stacks/ + - /docs/filtering-and-searching/ + - /docs/saved-views/ + - /docs/environments/ + - /docs/versioning/ + - /docs/setting-log-levels/ + - /docs/feature-usage/ + - /docs/user-sessions/ + - /docs/references-ids/ + - /docs/notifications/ + - /docs/integrations/ + - /docs/navigation/ + - /docs/project-settings/ + - /docs/organizations/ + - /docs/account/ + +- section: How it works + items: + - /docs/concepts/stacking/ + - /docs/concepts/limits/ + - /docs/security/ + +- section: Reference + items: + - /docs/reference/search-syntax/ + - /docs/reference/event-format/ + - /docs/reference/client-spec/ + - /docs/FAQ/ + +- section: REST API + items: + - /docs/api/ + - /docs/api/authentication/ + - /docs/api/project-tokens/ + - /docs/api/posting-events/ + - /docs/api/getting-events/ + +- section: Self-hosting + items: + - /docs/self-hosting/ + - /docs/self-hosting/docker/ + - /docs/self-hosting/kubernetes/ + - /docs/self-hosting/configuration/ + - /docs/self-hosting/reverse-proxy/ + - /docs/self-hosting/ai/ + - /docs/self-hosting/administration/ + - /docs/self-hosting/upgrading-self-hosted-instance/ diff --git a/docs/_data/icons.json b/docs/_data/icons.json index 05687207b1..730314cc46 100644 --- a/docs/_data/icons.json +++ b/docs/_data/icons.json @@ -12,6 +12,7 @@ "check": "", "chevron-down": "", "chevron-right": "", + "circle-alert": "", "circle-check": "", "circle-x": "", "clock": "", @@ -37,9 +38,11 @@ "heart-handshake": "", "history": "", "infinity": "", + "info": "", "keyboard": "", "layers": "", "layout-dashboard": "", + "lightbulb": "", "link": "", "list-filter": "", "lock": "", @@ -52,6 +55,7 @@ "moon": "", "mouse-pointer-click": "", "newspaper": "", + "octagon-alert": "", "package": "", "plug": "", "quote": "", @@ -73,6 +77,7 @@ "tag": "", "terminal": "", "timer": "", + "triangle-alert": "", "users": "", "users-round": "", "webhook": "", diff --git a/docs/_data/site.json b/docs/_data/site.json index ac77250356..46ffff950a 100644 --- a/docs/_data/site.json +++ b/docs/_data/site.json @@ -6,6 +6,7 @@ "twitter": "@Exceptionless", "signupUrl": "https://be.exceptionless.io/signup?domain=exceptionless.com&type=organic", "appUrl": "https://be.exceptionless.io", + "apiUrl": "https://api.exceptionless.io", "githubUrl": "https://github.com/exceptionless/Exceptionless", "githubStars": "2.5k" } diff --git a/docs/_includes/layouts/docs.vto b/docs/_includes/layouts/docs.vto index 6d252c8479..7d616587dd 100644 --- a/docs/_includes/layouts/docs.vto +++ b/docs/_includes/layouts/docs.vto @@ -5,7 +5,7 @@ bodyClass: layout-docs
+``` + +The CDN URL serves the package's minified ES2022 bundle. `https://cdn.jsdelivr.net/npm/@exceptionless/browser@3` also +works. Pin the version you tested with, for example `@exceptionless/browser@3.2.1`, if you want no updates at all. + +Once `startup` has run, import `Exceptionless` from the same package anywhere in your app to send events: + +```js +import { Exceptionless } from "@exceptionless/browser" + +await Exceptionless.submitFeatureUsage("Export to CSV") +``` + +The API key is visible to anyone who loads your page. That's expected: client API keys are made to ship in apps, and +they can submit events but can't read them. See the +[configuration reference](/docs/clients/javascript/client-configuration/) for every setting, including privacy options. + +> [!NOTE] +> Self-hosted instances use your own URL: add `c.serverUrl = "https://exceptionless.example.com"`. + +## Verify + +Add a button that throws an error nobody catches: + +```html + + + +``` + +Click it, then open **Events** in Exceptionless. The client sends its queue every 10 seconds, so the error appears +shortly after. The stack trace is on the event's **Exception** tab, and the browser and page URL are on its **Request** +tab. + +If nothing arrives, turn on `c.useDebugLogger()` and read the browser console. See +[Troubleshooting](/docs/clients/javascript/troubleshooting/). + +## What is captured automatically {#what-is-captured-automatically} + +- **Unhandled errors** from the window `error` event and **unhandled promise rejections** from `unhandledrejection`. + Rejections with a value that isn't an `Error` are converted to one. +- **jQuery AJAX failures**, when jQuery is on the page: a 404 is sent as a not-found event and other failures except 401 + as errors. +- **Request details** on every event: the user agent, host, port, path, whether the page uses HTTPS, the referrer, and + the page's cookies and query string. [Data exclusions](/docs/security/) remove matching cookie and query string keys, + and `includeCookies` and `includeQueryString` turn them off. +- **Scripts on the page.** The `src` of each script tag is attached to errors as a module list. +- **Repeated errors.** When the same error repeats within 30 seconds, the client holds the repeats and sends them as one + event with a count. + +The client also: + +- ignores errors whose stack trace comes from a browser extension (`chrome-extension://`, `moz-extension://`, and so + on); +- drops events from user agents that match your project's **Spam Detection** list; +- sends the queue and pauses its timers when the page is hidden, and resumes when the page is visible again; +- keeps synced project settings in `localStorage`. + +Events wait in memory until they are sent. To keep unsent events across page reloads, set +`c.usePersistedQueueStorage = true` to store the queue in `localStorage` as well. + +## Next steps + +- [Send logs, feature usage, and handled errors](/docs/clients/javascript/sending-events/). +- [Identify users and track sessions](/docs/user-sessions/) with `c.setUserIdentity(...)` and `c.useSessions()`. +- [Make minified stack traces readable](/docs/clients/javascript/source-maps/) with source maps. +- [Turn off logs or errors without redeploying](/docs/clients/javascript/client-configuration-values/). + +## Ask Exie + +```prompt exie +Which browsers reported the most errors in the last 7 days? +``` + +```prompt exie +What new error stacks showed up since yesterday's deploy? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can do the same: + +```prompt agent +Find the most frequent JavaScript error in my Exceptionless project this week, open the latest event's stack trace, and fix the cause in this codebase. +``` diff --git a/docs/docs/clients/javascript/guides/express.md b/docs/docs/clients/javascript/guides/express.md index d5a5e2ece5..2004611ed3 100644 --- a/docs/docs/clients/javascript/guides/express.md +++ b/docs/docs/clients/javascript/guides/express.md @@ -1,81 +1,152 @@ --- title: "Express" metaTitle: "Exceptionless error tracking for Express" -description: "Set up Exceptionless in an Express app on Node.js: install @exceptionless/node, submit logs, and report unhandled errors and 404s with request details." -order: 4 +description: "Report Express route errors and 404s to Exceptionless with request details, using error-handling middleware and @exceptionless/node." +order: 3 +redirectFrom: + - /docs/clients/javascript/express-example/ +sources: + - Exceptionless.JavaScript:example/express/app.js + - Exceptionless.JavaScript:example/express/package.json + - Exceptionless.JavaScript:packages/node/src/plugins/NodeRequestInfoPlugin.ts + - Exceptionless.JavaScript:packages/node/src/plugins/NodeGlobalHandlerPlugin.ts + - Exceptionless.JavaScript:packages/core/src/ExceptionlessClient.ts + - Exceptionless.JavaScript:packages/core/src/EventBuilder.ts --- # Express -Perhaps the most popular NodeJS server-side framework, Express is used in thousands of projects. Exceptionless provides dedicated NodeJS support, and configuring your Exceptionless client in Express is easy. +Two middleware functions report every error that reaches Express's error handler and every request that matches no +route, with the request's method, path, headers, and body attached. Errors outside a request are reported by the +[Node.js client](/docs/clients/javascript/guides/node/) on its own. -### Install +This guide uses Express 5, Node.js 18 or later, and ES modules. -To install exceptionless, you can use npm or yarn: +## Install -npm - `npm install @exceptionless/node` - -yarn - `yarn add @exceptionless/node` - -### Initializing the Client - -Exceptionless provides a default singleton client instance. While we recommend -using the default client instance for most use cases, you can also create -custom instances (though that's beyond the scope of this guide). - -```javascript -import { Exceptionless } from "@exceptionless/node"; - -await Exceptionless.startup((c) => { - c.apiKey = "YOUR API KEY"; -}); +```bash +npm install @exceptionless/node express ``` -You can see an additional parameter passed into the configuration object as an -example. To see all the available options, take a look at our -[configuration values here](/docs/clients/javascript/client-configuration-values). - -### Using Exceptionless in a Express App +## Configure -In this example, we're just making use of the Exceptionless client in a file -that handles one of our API routes. We will also show off how to handle errors -and 404s in Express. +Start the client before you create the app, then add the two middleware functions after all your routes. Save this as +`app.js` in a project whose `package.json` has `"type": "module"`: ```js -import { Exceptionless, KnownEventDataKeys } from "@exceptionless/node"; -import express from "express"; +import express from "express" +import { Exceptionless, KnownEventDataKeys, toError } from "@exceptionless/node" await Exceptionless.startup((c) => { - c.apiKey = "YOUR API KEY"; -}); + c.apiKey = process.env.EXCEPTIONLESS_API_KEY + c.addDataExclusions("authorization", "cookie", "password", "token") +}) + +const app = express() +app.use(express.json()) + +app.get("/", (req, res) => { + res.send("Hello World!") +}) -const app = express(); -app.get("/", async (req, res) => { - await Exceptionless.submitLog("Hello World!"); - res.send("Hello World!"); -}); +app.get("/boom", () => { + throw new Error("Exceptionless test error") +}) +// Report errors. Express treats middleware with four arguments as an error handler. app.use(async (err, req, res, next) => { if (res.headersSent) { - return next(err); + return next(err) } - await Exceptionless.createUnhandledException(err, "express").setContextProperty(KnownEventDataKeys.RequestInfo, req).submit(); - res.status(500).send("Something broke!"); -}); + await Exceptionless.createUnhandledException(toError(err), "express") + .setContextProperty(KnownEventDataKeys.RequestInfo, req) + .submit() + res.status(500).send("Something broke!") +}) + +// Report requests that matched no route. app.use(async (req, res) => { - await Exceptionless.createNotFound(req.originalUrl).setContextProperty(KnownEventDataKeys.RequestInfo, req).submit(); - res.status(404).send("Sorry cant find that!"); -}); + await Exceptionless.createNotFound(req.originalUrl).setContextProperty(KnownEventDataKeys.RequestInfo, req).submit() + + res.status(404).send("Sorry, can't find that!") +}) + +app.listen(3000, () => { + console.log("Listening on http://localhost:3000") +}) +``` + +`setContextProperty(KnownEventDataKeys.RequestInfo, req)` hands the Express request to the client, which turns it into +the event's request details. Use the same call when you report a handled error inside a route: + +```js +app.get("/orders/:id", async (req, res) => { + try { + // loadOrder is your own data access function. + res.json(await loadOrder(req.params.id)) + } catch (error) { + await Exceptionless.createException(toError(error)).setContextProperty(KnownEventDataKeys.RequestInfo, req).submit() + + res.status(500).send("Unable to load the order") + } +}) +``` + +Express 5 sends errors thrown or rejected in `async` route handlers to the error middleware. In Express 4, pass errors +from async code to `next(error)` so they reach it. + +> [!NOTE] +> Self-hosted instances use your own URL: add `c.serverUrl = "https://exceptionless.example.com"`. + +## Verify + +Start the app with `EXCEPTIONLESS_API_KEY=YOUR_API_KEY node app.js` and open `http://localhost:3000/boom`. Within about +10 seconds, the error appears on the **Events** page in Exceptionless with the request on its **Request** tab. Open +`http://localhost:3000/missing` to send a 404. + +If nothing arrives, add `c.useDebugLogger()` to `startup` and watch the console. See +[Troubleshooting](/docs/clients/javascript/troubleshooting/). + +## What is captured automatically + +For events that carry an Express request: + +- the HTTP method, host, port, path, whether the request used HTTPS, the user agent, and the referrer; +- the client IP address, unless `includeIpAddress` is off; +- cookies, unless `includeCookies` is off; +- request headers, unless `includeHeaders` is off. `Authorization`, `Cookie`, `Host`, `Proxy-Authorization`, `Referer`, + and `User-Agent` are never copied into the headers; +- route parameters (`req.params`), unless `includeQueryString` is off; +- the parsed body (`req.body`), unless `includePostData` is off. It's only there if a body parser such as + `express.json()` ran. -const server = app.listen(3000, async () => { - var host = server.address().address; - var port = server.address().port; +[Data exclusions](/docs/security/), from `c.addDataExclusions(...)` and from your project settings, remove matching +cookie, header, parameter, and body keys. Requests whose user agent matches your project's **Spam Detection** list are +not reported. - var message = "Example app listening at http://" + host + port; - await Exceptionless.submitLog("app", message, "Info"); -}); +Everything the [Node.js client](/docs/clients/javascript/guides/node/#what-is-captured-automatically) captures is also +included, such as uncaught exceptions outside requests and machine details. + +## Next steps + +- [Turn off request data you don't need](/docs/clients/javascript/client-configuration/#general-data-protection-regulation). +- [Send logs and feature usage from routes](/docs/clients/javascript/sending-events/). +- [Ignore 404s from known paths](/docs/clients/javascript/client-configuration-values/) without redeploying. + +## Ask Exie + +```prompt exie +Which paths returned the most 404s this week? ``` -With that set up, you can use the Exceptionless client anywhere in your app. +```prompt exie +Show me the request details for the latest event in this stack. +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can do the same: + +```prompt agent +Find the Express route errors in my Exceptionless project from the last 24 hours, read the request details on the latest events, and fix the failing route handler in this app. +``` diff --git a/docs/docs/clients/javascript/guides/index.md b/docs/docs/clients/javascript/guides/index.md index e8f9b597a0..6f6c1e82ad 100644 --- a/docs/docs/clients/javascript/guides/index.md +++ b/docs/docs/clients/javascript/guides/index.md @@ -1,20 +1,45 @@ --- -title: "JavaScript Framework Guides" -description: "Guides for adding Exceptionless error and event tracking to JavaScript frameworks, including React, Angular, and Vue in the browser and Express on Node.js." -order: 3 +title: "JavaScript framework guides" +navTitle: "Framework guides" +description: "Set up Exceptionless in a browser app, Node.js, Express, React, React Native and Expo, Next.js, SvelteKit, Vue, or Angular." +order: 1 +redirectFrom: + - /docs/clients/javascript/guides/more-guides/ +sources: + - Exceptionless.JavaScript:example/ + - Exceptionless.JavaScript:packages/ --- -# JavaScript Framework Guides +# JavaScript framework guides -Exceptionless works with all popular JavaScript frameworks on both the front end and the backend including React, Angular, Typescript, Express, and Svelte. Below, you will find our guides for those frameworks. +Each guide installs the right package, starts the client, wires it into the framework's error hooks, and checks that a +test error arrives. -* [React](/docs/clients/javascript/guides/react) -* [Angular](/docs/clients/javascript/guides/angular) -* [Vue](/docs/clients/javascript/guides/vue) -* [Express](/docs/clients/javascript/guides/express) +| Guide | Package | Covers | +| ---------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------- | +| [Browser](/docs/clients/javascript/guides/browser/) | `@exceptionless/browser` | npm and CDN setup for any web page. | +| [Node.js and serverless](/docs/clients/javascript/guides/node/) | `@exceptionless/node` | Servers, scripts, workers, and functions that must flush before exit. | +| [Express](/docs/clients/javascript/guides/express/) | `@exceptionless/node` | Error and 404 middleware with request details. | +| [React](/docs/clients/javascript/guides/react/) | `@exceptionless/react` | `ExceptionlessErrorBoundary` with a fallback UI. | +| [React Native and Expo](/docs/clients/javascript/guides/react-native/) | `@exceptionless/react-native` | JavaScript errors, the Expo config plugin, and native iOS crashes. | +| [Next.js](/docs/clients/javascript/guides/nextjs/) | `@exceptionless/browser` and `@exceptionless/node` | App Router client and server errors. | +| [SvelteKit](/docs/clients/javascript/guides/sveltekit/) | `@exceptionless/browser` and `@exceptionless/node` | Client and server `handleError` hooks. | +| [Vue](/docs/clients/javascript/guides/vue/) | `@exceptionless/vue` | The global Vue error handler. | +| [Angular](/docs/clients/javascript/guides/angular/) | `@exceptionless/browser` | An `ErrorHandler` provider for standalone apps. | -Exceptionless should work anywhere JavaScript runs, but if you have specific frameworks you'd like to see covered, let us know or submit a pull request. Our documentation is [open-source and editable](https://github.com/exceptionless/Website/tree/master/content/docs). +For AngularJS 1.x, see the +[`@exceptionless/angularjs` README](https://github.com/exceptionless/Exceptionless.JavaScript/tree/main/packages/angularjs). ---- +## Example apps + +The [Exceptionless.JavaScript repository](https://github.com/exceptionless/Exceptionless.JavaScript/tree/main/example) +has a runnable app for the browser, Express, React, Vue, Next.js, SvelteKit, and Expo. To run one: -[Next > React Guide](/docs/clients/javascript/guides/react) +1. Install [Node.js](https://nodejs.org/). +2. Clone the repository and run `npm install` and then `npm run build` from its root. The examples use the packages + built from the repository. +3. Point the example at your project. The examples send to a local development server, so replace the `apiKey` value + with your project's API key and remove or change the `serverUrl`. The Next.js example reads both from environment + variables instead (see its README). +4. Start the example from its folder, for example `cd example/react` and then `npm start`. Each example's `package.json` + lists its scripts. diff --git a/docs/docs/clients/javascript/guides/more-guides.md b/docs/docs/clients/javascript/guides/more-guides.md deleted file mode 100644 index da60cf1ee7..0000000000 --- a/docs/docs/clients/javascript/guides/more-guides.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "More Guides" -metaTitle: "More JavaScript guides and sample apps" -description: "Find complete Exceptionless JavaScript sample apps on GitHub that go beyond the React, Vue, Angular, and Express quick-start guides in these docs." -order: 5 ---- - -# More Guides - -In addition to the quick start guides we've provided here, there are full app examples located in our Github repository. Take a look and feel free to let us know if you'd like to see other tutorials and guides included. - -[JavaScript Example Repository](https://github.com/exceptionless/Exceptionless.JavaScript/blob/master/example) - -[Next > Sending Events](/docs/clients/javascript/sending-events) diff --git a/docs/docs/clients/javascript/guides/nextjs.md b/docs/docs/clients/javascript/guides/nextjs.md new file mode 100644 index 0000000000..b4fae7f9ed --- /dev/null +++ b/docs/docs/clients/javascript/guides/nextjs.md @@ -0,0 +1,305 @@ +--- +title: "Next.js" +metaTitle: "Exceptionless error tracking for Next.js" +description: "Report Next.js App Router errors from the browser and the server to Exceptionless with instrumentation files, onRequestError, and error boundaries." +order: 6 +sources: + - Exceptionless.JavaScript:example/nextjs/README.md + - Exceptionless.JavaScript:example/nextjs/package.json + - Exceptionless.JavaScript:example/nextjs/instrumentation.js + - Exceptionless.JavaScript:example/nextjs/instrumentation-client.js + - Exceptionless.JavaScript:example/nextjs/lib/exceptionless-browser.js + - Exceptionless.JavaScript:example/nextjs/lib/exceptionless-server.js + - Exceptionless.JavaScript:example/nextjs/lib/next-request.js + - Exceptionless.JavaScript:example/nextjs/app/error.jsx + - Exceptionless.JavaScript:example/nextjs/app/global-error.jsx + - Exceptionless.JavaScript:example/nextjs/app/api/demo/route.js + - Exceptionless.JavaScript:packages/node/src/plugins/NodeRequestInfoPlugin.ts +--- + +# Next.js + +A Next.js App Router app runs code in two places, so it uses two packages: `@exceptionless/browser` in the browser and +`@exceptionless/node` on the server. With the files in this guide, Exceptionless receives: + +- unhandled errors and promise rejections in the browser; +- client render errors caught by `app/error.jsx` and `app/global-error.jsx`; +- server render, route handler, and server action errors from Next.js's `onRequestError` hook, with the request + attached. + +This guide follows the +[Next.js example app](https://github.com/exceptionless/Exceptionless.JavaScript/tree/main/example/nextjs) in the SDK +repository, which uses Next.js 16 and the App Router. The server side runs in the Node.js runtime only. Errors in the +Edge runtime are not reported. + +## Install + +```bash +npm install @exceptionless/browser @exceptionless/node +``` + +Add your API key to `.env.local`. The browser needs the `NEXT_PUBLIC_` variable, and the server reads the other: + +```bash +NEXT_PUBLIC_EXCEPTIONLESS_API_KEY=YOUR_API_KEY +EXCEPTIONLESS_API_KEY=YOUR_API_KEY +``` + +## Configure + +### 1. Start each client once + +Create a small module for each side. Each one keeps the `startup` promise, so every caller shares one started client and +later calls wait for the same startup. + +`lib/exceptionless-browser.js`: + +```js +import { Exceptionless } from "@exceptionless/browser" + +export { Exceptionless } + +let startupPromise + +export function startup() { + startupPromise ??= Exceptionless.startup((c) => { + c.apiKey = process.env.NEXT_PUBLIC_EXCEPTIONLESS_API_KEY + c.defaultTags.push("client") + }) + + return startupPromise +} +``` + +`lib/exceptionless-server.js`: + +```js +import { Exceptionless, KnownEventDataKeys, toError } from "@exceptionless/node" + +export { Exceptionless, KnownEventDataKeys, toError } + +let startupPromise + +export function startup() { + startupPromise ??= Exceptionless.startup((c) => { + c.apiKey = process.env.EXCEPTIONLESS_API_KEY + c.addDataExclusions("authorization", "cookie", "password", "set-cookie", "token") + c.defaultTags.push("server") + }) + + return startupPromise +} +``` + +### 2. Start the browser client + +Next.js runs `instrumentation-client.js`, in the project root or `src/`, before your app becomes interactive: + +```js +import { startup } from "./lib/exceptionless-browser.js" + +void startup() +``` + +### 3. Report server errors + +`instrumentation.js` starts the server client and reports every error that Next.js passes to `onRequestError`. It +imports the server module dynamically and checks `NEXT_RUNTIME`, so the Node.js package never loads in the Edge runtime: + +```js +export async function register() { + if (process.env.NEXT_RUNTIME !== "nodejs") { + return + } + + const { startup } = await import("./lib/exceptionless-server.js") + await startup() +} + +export async function onRequestError(error, request, context) { + if (process.env.NEXT_RUNTIME !== "nodejs") { + return + } + + const { Exceptionless, KnownEventDataKeys, startup, toError } = await import("./lib/exceptionless-server.js") + await startup() + + await Exceptionless.createUnhandledException(toError(error), `nextjs.${context.routeType}`) + .setContextProperty(KnownEventDataKeys.RequestInfo, toRequestInfo(request)) + .setProperty("digest", error?.digest) + .setProperty("routePath", context.routePath) + .setProperty("routeType", context.routeType) + .submit() + + // Send now: a serverless function can be frozen right after the response. + await Exceptionless.processQueue() +} + +// Converts the request Next.js passes to onRequestError into the shape the Node.js client reads. +function toRequestInfo(request) { + const headers = Object.fromEntries( + Object.entries(request.headers).map(( + [key, value], + ) => [key.toLowerCase(), Array.isArray(value) ? value.join(", ") : String(value)]), + ) + const protocol = headers["x-forwarded-proto"] ?? "http" + const host = headers["x-forwarded-host"] ?? headers.host ?? "localhost" + const url = new URL(request.path, `${protocol}://${host}`) + + return { + method: request.method, + secure: url.protocol === "https:", + ip: headers["x-forwarded-for"]?.split(",")[0]?.trim() ?? "", + hostname: url.hostname, + path: url.pathname, + headers, + params: Object.fromEntries(url.searchParams.entries()), + } +} +``` + +The `digest` property matches the digest Next.js shows in the browser for a server error, so you can connect what a user +saw with the server event. + +### 4. Report client render errors + +Errors during client rendering go to the nearest `error.jsx`. Errors with a `digest` came from the server and were +already reported by `onRequestError`, so report only the others. + +`app/error.jsx`: + +```jsx +"use client" + +import { useEffect } from "react" + +import { Exceptionless, startup } from "../lib/exceptionless-browser.js" + +export default function ErrorPage({ error, reset }) { + useEffect(() => { + if (error.digest) { + return + } + + void startup().then(() => Exceptionless.createException(error).addTags("error-boundary").submit()) + }, [error]) + + return ( +
+

Something went wrong.

+ +
+ ) +} +``` + +`app/global-error.jsx` catches errors in the root layout. It uses the same effect and renders its own `` and +``: + +```jsx +"use client" + +import { useEffect } from "react" + +import { Exceptionless, startup } from "../lib/exceptionless-browser.js" + +export default function GlobalError({ error, reset }) { + useEffect(() => { + if (error.digest) { + return + } + + void startup().then(() => Exceptionless.createException(error).addTags("global-error").submit()) + }, [error]) + + return ( + + +

Something went wrong.

+ + + + ) +} +``` + +### 5. Send events from route handlers + +Start the server client and send events as usual. Use `after()` to send the queue once the response is on its way: + +```js +import { after } from "next/server" + +import { Exceptionless, startup } from "../../../lib/exceptionless-server.js" + +export async function POST() { + await startup() + await Exceptionless.submitFeatureUsage("Checkout") + + after(() => Exceptionless.processQueue()) + + return Response.json({ ok: true }) +} +``` + +In client components, import `Exceptionless` and `startup` from `lib/exceptionless-browser.js` and call +`await startup()` before you submit. + +> [!NOTE] +> Self-hosted instances use your own URL: set `c.serverUrl` in both modules, for example from +> `NEXT_PUBLIC_EXCEPTIONLESS_SERVER_URL` and `EXCEPTIONLESS_SERVER_URL`. + +## Verify + +Add a route handler that throws, at `app/api/boom/route.js`: + +```js +export async function GET() { + throw new Error("Exceptionless test error") +} +``` + +Run `npm run dev` and open `http://localhost:3000/api/boom`. The error appears on the **Events** page in Exceptionless, +tagged `server`, with the request on its **Request** tab and the route path and type in its extended data. Delete the +route when you're done. + +To check the browser side, throw from a button's click handler in a client component. That error arrives tagged +`client`. + +## What is captured automatically + +- **In the browser**: everything the + [browser client captures](/docs/clients/javascript/guides/browser/#what-is-captured-automatically), including + unhandled errors, promise rejections, and the page URL. +- **On the server**: errors from server rendering, route handlers, and server actions through `onRequestError`, with the + request method, path, headers, query string, and client IP, the route path and type, and the digest. Data exclusions + remove matching header and query keys. +- **In the Node.js process**: uncaught exceptions and machine details, as described in the + [Node.js guide](/docs/clients/javascript/guides/node/#what-is-captured-automatically). + +## Next steps + +- [Make minified browser stack traces readable](/docs/clients/javascript/source-maps/) with source maps. +- [Identify users](/docs/user-sessions/) in the browser with `c.setUserIdentity(...)`. +- [Send logs and feature usage](/docs/clients/javascript/sending-events/). +- [Flush events in other serverless code](/docs/clients/javascript/guides/node/#short-lived-processes-and-serverless). + +## Ask Exie + +```prompt exie +Which error stacks tagged server happened most in the last 24 hours? +``` + +```prompt exie +Compare error counts for events tagged client and server this week. +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can do the same: + +```prompt agent +Find the newest error stack tagged server in my Exceptionless project, read the routePath and request on its latest event, and fix the failing route or server component in this Next.js app. +``` diff --git a/docs/docs/clients/javascript/guides/node.md b/docs/docs/clients/javascript/guides/node.md new file mode 100644 index 0000000000..373421009b --- /dev/null +++ b/docs/docs/clients/javascript/guides/node.md @@ -0,0 +1,180 @@ +--- +title: "Node.js and serverless" +metaTitle: "Node.js and serverless error tracking" +description: "Report Node.js errors to Exceptionless from servers, scripts, workers, and serverless functions, and flush the queue before a short-lived process ends." +order: 2 +redirectFrom: + - /docs/clients/javascript/node-example/ +sources: + - Exceptionless.JavaScript:packages/node/README.md + - Exceptionless.JavaScript:packages/node/package.json + - Exceptionless.JavaScript:packages/node/src/NodeExceptionlessClient.ts + - Exceptionless.JavaScript:packages/node/src/plugins/NodeGlobalHandlerPlugin.ts + - Exceptionless.JavaScript:packages/node/src/plugins/NodeLifeCyclePlugin.ts + - Exceptionless.JavaScript:packages/node/src/plugins/NodeEnvironmentInfoPlugin.ts + - Exceptionless.JavaScript:packages/core/src/ExceptionlessClient.ts + - Exceptionless.JavaScript:packages/core/src/queue/DefaultEventQueue.ts + - Exceptionless.JavaScript:example/nextjs/lib/exceptionless-server.js +--- + +# Node.js and serverless + +`@exceptionless/node` reports uncaught exceptions and unhandled promise rejections from Node.js, with details about the +machine and process. It works in long-running servers, scripts, CLIs, queue workers, and serverless functions. +Short-lived processes need one extra call, covered [below](#short-lived-processes-and-serverless). + +It requires Node.js 18 or later and ES modules. + +## Install + +```bash +npm install @exceptionless/node +``` + +## Configure + +Call `startup` once when the process starts, before the rest of your app runs: + +```js +import { Exceptionless } from "@exceptionless/node" + +await Exceptionless.startup((c) => { + c.apiKey = process.env.EXCEPTIONLESS_API_KEY + c.version = "1.2.3" // optional: your app's version, used for regressions +}) +``` + +Then import `Exceptionless` anywhere in your app to send events: + +```js +import { Exceptionless } from "@exceptionless/node" + +await Exceptionless.submitLog("worker", "Nightly import finished", "info") +``` + +The package is ES modules only. From a CommonJS file, load it with a dynamic `import("@exceptionless/node")`. + +> [!NOTE] +> Self-hosted instances use your own URL: add `c.serverUrl = "https://exceptionless.example.com"`. + +> [!IMPORTANT] +> The client listens for `uncaughtException` and `unhandledRejection`. Node.js does not exit on its own when a listener +> handles these, so after `startup` an uncaught exception no longer stops the process. If your process should stop, exit +> it yourself from your own handler, and send queued events first. + +## Short-lived processes and serverless {#short-lived-processes-and-serverless} + +The client sends its queue every 10 seconds, and those timers don't keep the process alive. In a long-running server +that's all you need. In a script that ends on its own, the client sends what's left when Node.js emits `beforeExit`. + +Call `await Exceptionless.processQueue()` yourself when the process can end before that: + +- before calling `process.exit()`, which skips `beforeExit`; +- at the end of a serverless function, because the platform freezes or stops the process after the response and the + timers never fire; +- after a critical event in a CLI or job that a scheduler may kill. + +Each call sends up to 50 events, the `submissionBatchSize` setting. + +For a serverless function, start the client once outside the handler, and flush in a `finally` block: + +```js +import { Exceptionless } from "@exceptionless/node" + +const exceptionlessReady = Exceptionless.startup((c) => { + c.apiKey = process.env.EXCEPTIONLESS_API_KEY +}) + +export async function handler(event) { + await exceptionlessReady + + try { + return await handleOrder(event) + } catch (error) { + await Exceptionless.submitException(error) + throw error + } finally { + await Exceptionless.processQueue() + } +} + +async function handleOrder(event) { + // your function's work + return { statusCode: 200 } +} +``` + +Keeping the `startup` promise in a module-level variable means warm invocations reuse the started client. The same shape +works on AWS Lambda, Vercel and Netlify functions, and Google Cloud Functions. On Next.js, see the +[Next.js guide](/docs/clients/javascript/guides/nextjs/), which flushes with `after()`. + +The client stores synced settings in a `.exceptionless` folder in the current working directory. On a read-only file +system it can't create the folder, so it keeps them in memory instead. + +## Verify + +Save this as `exceptionless-test.mjs` and run `node exceptionless-test.mjs`: + +```js +import { Exceptionless } from "@exceptionless/node" + +await Exceptionless.startup((c) => { + c.apiKey = "YOUR_API_KEY" +}) + +await Exceptionless.submitException(new Error("Exceptionless test error")) +await Exceptionless.processQueue() +``` + +Open **Events** in Exceptionless. The error is there, with the machine name, Node.js version, and command line on the +event's **Environment** tab. If it isn't, add `c.useDebugLogger()` to `startup` and run the script again. See +[Troubleshooting](/docs/clients/javascript/troubleshooting/). + +## What is captured automatically {#what-is-captured-automatically} + +- **Uncaught exceptions** and **unhandled promise rejections**. Rejections with a value that isn't an `Error` are + converted to one. The client also raises `Error.stackTraceLimit` to 50 frames. +- **Environment details** on every event: OS name and version, architecture, processor count, memory, Node.js version, + process name, ID, and command line, load average, and uptime, plus the machine name and IP addresses unless + `includeMachineName` or `includeIpAddress` is off. +- **Request details** when you attach an Express-style request to an event. The + [Express guide](/docs/clients/javascript/guides/express/) shows how. +- **Repeated errors.** When the same error repeats within 30 seconds, the client holds the repeats and sends them as one + event with a count. + +On `beforeExit`, the client also ends the current session if you turned on [sessions](/docs/user-sessions/). + +### Readable stack traces for TypeScript and bundled code + +Exceptionless applies source maps only to stack frames whose file is an HTTP or HTTPS URL. Node.js stack frames are file +paths, so let Node.js apply your source maps before the error is reported: + +```bash +node --enable-source-maps dist/server.js +``` + +Or set `NODE_OPTIONS=--enable-source-maps` in the environment. + +## Next steps + +- [Add error and 404 middleware to Express](/docs/clients/javascript/guides/express/). +- [Send logs, feature usage, and handled errors](/docs/clients/javascript/sending-events/). +- [Remove private data](/docs/clients/javascript/client-configuration/#general-data-protection-regulation) such as + headers, cookies, and request bodies. +- [Change log levels without redeploying](/docs/clients/javascript/client-configuration-values/). + +## Ask Exie + +```prompt exie +Which error types happened most often in the last 24 hours? +``` + +```prompt exie +How many errors did version 1.2.3 produce compared with the version before it? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can do the same: + +```prompt agent +List the open error stacks in my Exceptionless project from the last 7 days, find the one with the most occurrences, read its latest event, and fix the cause in this service. +``` diff --git a/docs/docs/clients/javascript/guides/react-native.md b/docs/docs/clients/javascript/guides/react-native.md new file mode 100644 index 0000000000..5061714178 --- /dev/null +++ b/docs/docs/clients/javascript/guides/react-native.md @@ -0,0 +1,203 @@ +--- +title: "React Native and Expo" +metaTitle: "Exceptionless error tracking for React Native and Expo" +description: "Report JavaScript errors and native iOS crashes from React Native and Expo apps with @exceptionless/react-native and its Expo config plugin." +order: 5 +sources: + - Exceptionless.JavaScript:packages/react-native/README.md + - Exceptionless.JavaScript:packages/react-native/package.json + - Exceptionless.JavaScript:packages/react-native/exceptionless-react-native.podspec + - Exceptionless.JavaScript:packages/react-native/react-native.config.cjs + - Exceptionless.JavaScript:packages/react-native/expo-plugin/withExceptionless.cjs + - Exceptionless.JavaScript:packages/react-native/src/ReactNativeExceptionlessClient.ts + - Exceptionless.JavaScript:packages/react-native/src/ExceptionlessErrorBoundary.tsx + - Exceptionless.JavaScript:packages/react-native/src/plugins/ReactNativeGlobalHandlerPlugin.ts + - Exceptionless.JavaScript:packages/react-native/src/plugins/ReactNativeLifeCyclePlugin.ts + - Exceptionless.JavaScript:packages/react-native/src/plugins/ReactNativeEnvironmentInfoPlugin.ts + - Exceptionless.JavaScript:packages/react-native/src/plugins/NativeCrashPlugin.ts + - Exceptionless.JavaScript:packages/react-native/ios/ExceptionlessCrashReporter.mm + - Exceptionless.JavaScript:example/expo/README.md + - Exceptionless.JavaScript:example/expo/App.tsx + - Exceptionless.JavaScript:example/expo/app.json + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs +--- + +# React Native and Expo + +`@exceptionless/react-native` reports unhandled JavaScript errors and promise rejections from React Native and Expo +apps, and on iOS it also reports native crashes: Objective-C and Swift exceptions, signals such as `SIGSEGV` and +`SIGABRT`, and Mach exceptions. Events wait in a queue stored with AsyncStorage, so they survive an app restart. + +Requirements: + +- React 18 or later and React Native 0.71 or later. +- `@react-native-async-storage/async-storage` 1.19 or later. +- For native crash reporting: iOS 14 or later, and a development build, standalone build, or React Native CLI app. Expo + Go reports JavaScript errors only. + +Android reports JavaScript errors and promise rejections. Native crash reporting on Android is not available yet. + +Use this package instead of `@exceptionless/browser` or `@exceptionless/react` in React Native apps. + +## Install + +### Expo + +```bash +npx expo install @exceptionless/react-native @react-native-async-storage/async-storage +``` + +Add the config plugin to `app.json` so development and standalone builds include the native crash reporter: + +```json +{ + "expo": { + "plugins": ["@exceptionless/react-native/expo-plugin"] + } +} +``` + +Then rebuild the native app, for example with `npx expo run:ios` after installing `expo-dev-client`, or with an EAS +build. Expo Go can't load the native module, so it reports JavaScript errors but not native crashes. + +### React Native CLI + +```bash +npm install @exceptionless/react-native @react-native-async-storage/async-storage +cd ios && pod install +``` + +CocoaPods links [PLCrashReporter](https://github.com/microsoft/plcrashreporter), which the package uses for native crash +reporting. + +## Configure + +Start the client once, when the app's JavaScript loads, and wrap your app in `ExceptionlessErrorBoundary`: + +```tsx +import { Text } from "react-native" +import { Exceptionless, ExceptionlessErrorBoundary } from "@exceptionless/react-native" + +import HomeScreen from "./HomeScreen" + +Exceptionless.startup((c) => { + c.apiKey = "YOUR_API_KEY" + c.version = "1.2.3" // optional: your app's version, used for regressions +}) + +export default function App() { + return ( + Something went wrong.}> + + + ) +} +``` + +`startup` returns a promise. It sets the API key right away, so you don't need to wait for it before rendering. On iOS +it also installs the native crash reporter and sends any crash reports saved by the previous launch. + +The error boundary reports render errors with React's component stack and shows `fallback` in place of its children. +Errors in event handlers and async code are reported by the global handlers instead. Submit errors you catch yourself: + +```tsx +import { Exceptionless, toError } from "@exceptionless/react-native" + +export async function saveProfile(profile: unknown) { + try { + await fetch("https://example.com/api/profile", { method: "PUT", body: JSON.stringify(profile) }) + } catch (error) { + await Exceptionless.submitException(toError(error)) + } +} +``` + +To group events into user sessions, identify the user and turn on sessions. Apps usually let the client create session +IDs: + +```tsx +Exceptionless.startup((c) => { + c.apiKey = "YOUR_API_KEY" + c.setUserIdentity("user-123", "Jane Doe") + c.useSessions(true, 60000, true) +}) +``` + +See [Sessions](/docs/user-sessions/) for what the three arguments do. + +> [!NOTE] +> Self-hosted instances use your own URL: add `c.serverUrl = "https://exceptionless.example.com"`. To reach a server on +> your development machine, use `http://localhost:` from the iOS Simulator and `http://10.0.2.2:` from the +> Android Emulator. Physical devices need your machine's LAN address. + +## Verify + +Add a temporary button that sends a handled error and flushes the queue: + +```tsx +import { Button } from "react-native" +import { Exceptionless } from "@exceptionless/react-native" + +export function SendTestError() { + return ( + } + > + + + ) +} +``` -### Using Exceptionless in a React App +React error boundaries don't catch errors in event handlers, effects that run later, or async code. Those reach the +browser's global handlers, which the client already listens to. Errors you catch yourself are not reported unless you +submit them: -```javascript -import { Exceptionless, ExceptionlessErrorBoundary } from "@exceptionless/react"; +```jsx +import { Exceptionless, toError } from "@exceptionless/react" -class App extends Component { - async componentDidMount() { - await Exceptionless.startup((c) => { - c.apiKey = "YOUR API KEY"; - }); +export function SaveButton({ profile }) { + async function save() { + try { + await fetch("/api/profile", { method: "PUT", body: JSON.stringify(profile) }) + } catch (error) { + await Exceptionless.submitException(toError(error)) + } } - render() { - return ( - - -// YOUR APP COMPONENTS HERE + return +} +``` + +`toError` turns any caught value into an `Error`, since JavaScript lets code throw strings and other values. + +## Verify + +Render this component somewhere inside the boundary: - - ); +```jsx +import { useState } from "react" + +export function ThrowTestError() { + const [shouldThrow, setShouldThrow] = useState(false) + + if (shouldThrow) { + throw new Error("Exceptionless test error") } + + return } +``` + +Click the button. The boundary shows its fallback, and within about 10 seconds the error appears on the **Events** page +in Exceptionless. Remove the component when you're done. -export default App; +If nothing arrives, add `c.useDebugLogger()` to `startup` and check the browser console. See +[Troubleshooting](/docs/clients/javascript/troubleshooting/). + +## What is captured automatically + +- **Render errors** inside `ExceptionlessErrorBoundary`, with React's component stack stored on the error. +- **Unhandled errors and promise rejections** anywhere on the page, from event handlers, timers, effects, and async + code. +- **Request details**: the browser, page URL, referrer, cookies, and query string. +- Everything else the + [browser client captures](/docs/clients/javascript/guides/browser/#what-is-captured-automatically), such as ignoring + errors from browser extensions and combining repeated errors. + +## Next steps + +- [Identify users and track sessions](/docs/user-sessions/) with `c.setUserIdentity(...)` and `c.useSessions()`. +- [Make minified stack traces readable](/docs/clients/javascript/source-maps/) for your production build. +- [Send feature usage and logs](/docs/clients/javascript/sending-events/) from components. +- [Remove private data](/docs/clients/javascript/client-configuration/#general-data-protection-regulation) such as + cookies and query strings. + +## Ask Exie + +```prompt exie +What are the most frequent React errors this week, and which browsers do they happen in? ``` -With that set up, you can use the Exceptionless client anywhere in your app. +```prompt exie +Show me the stack trace of the latest event in this stack. +``` ---- +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can do the same: -[Next > Vue](/docs/clients/javascript/guides/vue) +```prompt agent +Find the newest error stack in my Exceptionless project from the last 24 hours, read its latest event, fix the React component that throws, and mark the stack fixed in the next version. +``` diff --git a/docs/docs/clients/javascript/guides/sveltekit.md b/docs/docs/clients/javascript/guides/sveltekit.md new file mode 100644 index 0000000000..daa7c8aa1d --- /dev/null +++ b/docs/docs/clients/javascript/guides/sveltekit.md @@ -0,0 +1,142 @@ +--- +title: "SvelteKit" +metaTitle: "Exceptionless error tracking for SvelteKit" +description: "Report SvelteKit errors from the browser and the server to Exceptionless with handleError hooks in hooks.client.js and hooks.server.js." +order: 7 +sources: + - Exceptionless.JavaScript:example/svelte-kit/README.md + - Exceptionless.JavaScript:example/svelte-kit/package.json + - Exceptionless.JavaScript:example/svelte-kit/src/hooks.client.js + - Exceptionless.JavaScript:example/svelte-kit/src/hooks.server.js + - Exceptionless.JavaScript:packages/browser/src/plugins/BrowserGlobalHandlerPlugin.ts + - Exceptionless.JavaScript:packages/node/src/plugins/NodeGlobalHandlerPlugin.ts +--- + +# SvelteKit + +SvelteKit runs your code in the browser and on the server, so it uses `@exceptionless/browser` in `src/hooks.client.js` +and `@exceptionless/node` in `src/hooks.server.js`. Each hook file starts a client and reports the unexpected errors +that SvelteKit passes to `handleError`. Both clients also report unhandled errors and promise rejections on their side. + +This guide follows the +[SvelteKit example app](https://github.com/exceptionless/Exceptionless.JavaScript/tree/main/example/svelte-kit) in the +SDK repository, which uses SvelteKit 2 and Svelte 5. The server hook needs a Node.js-based adapter, such as +`adapter-node` or a Node.js serverless runtime. + +## Install + +```bash +npm install @exceptionless/browser @exceptionless/node +``` + +Add your API key to `.env`. SvelteKit exposes only `PUBLIC_` variables to the browser: + +```bash +PUBLIC_EXCEPTIONLESS_API_KEY=YOUR_API_KEY +EXCEPTIONLESS_API_KEY=YOUR_API_KEY +``` + +## Configure + +`src/hooks.client.js`: + +```js +import { PUBLIC_EXCEPTIONLESS_API_KEY } from "$env/static/public" +import { Exceptionless, toError } from "@exceptionless/browser" + +Exceptionless.startup((c) => { + c.apiKey = PUBLIC_EXCEPTIONLESS_API_KEY + c.defaultTags.push("client") +}) + +/** @type {import("@sveltejs/kit").HandleClientError} */ +export async function handleError({ error, message, status }) { + await Exceptionless.createException(toError(error ?? message)) + .setProperty("status", status) + .submit() +} +``` + +`src/hooks.server.js`: + +```js +import { env } from "$env/dynamic/private" +import { Exceptionless, toError } from "@exceptionless/node" + +Exceptionless.startup((c) => { + c.apiKey = env.EXCEPTIONLESS_API_KEY + c.defaultTags.push("server") +}) + +/** @type {import("@sveltejs/kit").HandleServerError} */ +export async function handleError({ error, status }) { + await Exceptionless.createException(toError(error)) + .setProperty("status", status) + .submit() + + // Send now in case the platform stops the function after the response. + await Exceptionless.processQueue() +} +``` + +`toError` turns any thrown value into an `Error`. `startup` sets the API key right away, so the hooks don't need to wait +for it. + +Errors you raise with SvelteKit's `error()` helper are expected errors and don't go through `handleError`. To report a +caught error elsewhere, import `Exceptionless` from the package for that side and call +`Exceptionless.submitException(toError(error))`. + +> [!NOTE] +> Self-hosted instances use your own URL: set `c.serverUrl` in both hooks. + +## Verify + +Add a page that throws during server-side load, at `src/routes/exceptionless-test/+page.server.js`: + +```js +export function load() { + throw new Error("Exceptionless test error") +} +``` + +Run `npm run dev` and open `http://localhost:5173/exceptionless-test`. SvelteKit shows its error page, and the error +appears on the **Events** page in Exceptionless, tagged `server`, with a `status` of 500. Delete the route when you're +done. + +To check the browser side, throw from a button's click handler in a component. That error arrives tagged `client`. + +## What is captured automatically + +- **In the browser**: unexpected errors from navigation and client-side `load` functions through `handleError`, plus + everything the [browser client captures](/docs/clients/javascript/guides/browser/#what-is-captured-automatically), + such as unhandled errors, promise rejections, and the page URL. +- **On the server**: unexpected errors from server `load` functions, form actions, and endpoints through `handleError`, + plus uncaught exceptions, unhandled rejections, and machine details from the + [Node.js client](/docs/clients/javascript/guides/node/#what-is-captured-automatically). + +Server events don't include request details, because the Node.js client reads Express-style requests and SvelteKit +passes a standard `Request`. Add what you need with `setProperty`, for example +`.setProperty("path", event.url.pathname)` using the `event` argument of `handleError`. + +## Next steps + +- [Make minified browser stack traces readable](/docs/clients/javascript/source-maps/) with source maps. +- [Identify users](/docs/user-sessions/) in the browser with `c.setUserIdentity(...)`. +- [Send logs and feature usage](/docs/clients/javascript/sending-events/). +- [Flush events in serverless deployments](/docs/clients/javascript/guides/node/#short-lived-processes-and-serverless). + +## Ask Exie + +```prompt exie +Which error stacks tagged server happened most in the last 24 hours? +``` + +```prompt exie +Show me the latest event in this stack and explain what caused it. +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can do the same: + +```prompt agent +Find the most frequent new error in my Exceptionless project this week, read its latest event, and fix the SvelteKit load function or component that throws it. +``` diff --git a/docs/docs/clients/javascript/guides/vue.md b/docs/docs/clients/javascript/guides/vue.md index 1b52c687a7..09ac6b7b12 100644 --- a/docs/docs/clients/javascript/guides/vue.md +++ b/docs/docs/clients/javascript/guides/vue.md @@ -1,59 +1,135 @@ --- title: "Vue" metaTitle: "Exceptionless error tracking for Vue" -description: "Install @exceptionless/vue, start the Exceptionless client with your API key, and set ExceptionlessErrorHandler as the global Vue error handler." -order: 2 +description: "Install @exceptionless/vue, start the Exceptionless client, and set ExceptionlessErrorHandler as Vue's global error handler to report component errors." +order: 8 +redirectFrom: + - /docs/clients/javascript/vue-example/ +sources: + - Exceptionless.JavaScript:packages/vue/README.md + - Exceptionless.JavaScript:packages/vue/src/index.ts + - Exceptionless.JavaScript:example/vue/src/main.js + - Exceptionless.JavaScript:example/vue/src/components/HelloWorld.vue + - Exceptionless.JavaScript:packages/browser/src/BrowserExceptionlessClient.ts --- # Vue -Vue is one of the more popular JavaScript frameworks out there, and Exceptionless has your back if you're working with it. Getting started is simple. +`@exceptionless/vue` reports errors from Vue components, and everything the +[browser client](/docs/clients/javascript/guides/browser/) reports: unhandled errors and promise rejections anywhere on +the page. `ExceptionlessErrorHandler` plugs into Vue's global `app.config.errorHandler`. -### Install +The example app uses Vue 3. -To install exceptionless, you can use npm or yarn: +## Install -npm - `npm install @exceptionless/vue` +```bash +npm install @exceptionless/vue +``` + +## Configure -yarn - `yarn add @exceptionless/vue` +Start the client and set the error handler in your entry file, usually `src/main.js`: -### Initializing the Client +```js +import { createApp } from "vue" +import { Exceptionless, ExceptionlessErrorHandler } from "@exceptionless/vue" -Exceptionless provides a default singleton client instance. While we recommend -using the default client instance for most use cases, you can also create -custom instances (though that's beyond the scope of this guide). +import App from "./App.vue" -```javascript -import { Exceptionless } from "@exceptionless/vue"; +Exceptionless.startup((c) => { + c.apiKey = "YOUR_API_KEY" + c.version = "1.2.3" // optional: your app's version, used for regressions +}) -await Exceptionless.startup((c) => { - c.apiKey = "YOUR API KEY"; -}); +const app = createApp(App) +app.config.errorHandler = ExceptionlessErrorHandler +app.mount("#app") ``` -You can see an additional parameter passed into the configuration object as an -example. To see all the available options, take a look at our -[configuration values here](/docs/clients/javascript/client-configuration-values). +`startup` returns a promise, but you don't need to wait for it before mounting. It sets the API key right away, so early +errors are queued and sent once the client finishes starting. -### Using Exceptionless in a Vue App +Vue calls `errorHandler` for errors in component rendering, lifecycle hooks, watchers, and event handlers bound in +templates. `ExceptionlessErrorHandler` submits the error with two extra properties: `vm`, the component instance, and +`info`, Vue's description of where the error happened. -```javascript -import { createApp } from "vue"; -import App from "./App.vue"; -import { Exceptionless, ExceptionlessErrorHandler } from "@exceptionless/vue"; +Setting `app.config.errorHandler` replaces Vue's default handling, so Vue stops logging those errors to the console. To +keep the console output, wrap the handler: -Exceptionless.startup((c) => { - c.apiKey = "YOUR API KEY"; -}); +```js +app.config.errorHandler = (err, instance, info) => { + console.error(err) + return ExceptionlessErrorHandler(err, instance, info) +} +``` + +Errors you catch yourself are not reported unless you submit them. Import `Exceptionless` from `@exceptionless/vue` +anywhere in your app: + +```js +import { Exceptionless, toError } from "@exceptionless/vue" -const app = createApp(App); -// Set the global vue error handler. -app.config.errorHandler = ExceptionlessErrorHandler; -app.mount("#app"); +export async function saveSettings(settings) { + try { + await fetch("/api/settings", { method: "PUT", body: JSON.stringify(settings) }) + } catch (error) { + await Exceptionless.submitException(toError(error)) + } +} ``` -With that set up, you can use the Exceptionless client anywhere in your app. +> [!NOTE] +> Self-hosted instances use your own URL: add `c.serverUrl = "https://exceptionless.example.com"`. ---- +## Verify + +Add a button to a component that throws when clicked: + +```html + + + +``` + +Click it. Within about 10 seconds, the error appears on the **Events** page in Exceptionless, with Vue's `info` string +on its **Extended Data** tab. Remove the button when you're done. -[Next > Angular](/docs/clients/javascript/guides/angular) +If nothing arrives, add `c.useDebugLogger()` to `startup` and check the browser console. See +[Troubleshooting](/docs/clients/javascript/troubleshooting/). + +## What is captured automatically + +- **Component errors** passed to Vue's `errorHandler`, with the component instance and Vue's `info` string. +- **Unhandled errors and promise rejections** that don't go through Vue, such as errors in timers and async code. +- Everything else the + [browser client captures](/docs/clients/javascript/guides/browser/#what-is-captured-automatically), such as request + details and ignoring errors from browser extensions. + +## Next steps + +- [Identify users and track sessions](/docs/user-sessions/) with `c.setUserIdentity(...)` and `c.useSessions()`. +- [Make minified stack traces readable](/docs/clients/javascript/source-maps/) for your production build. +- [Send feature usage and logs](/docs/clients/javascript/sending-events/) from components. + +## Ask Exie + +```prompt exie +What are the most frequent errors in the last 7 days, and are any of them new? +``` + +```prompt exie +Snooze this stack for a week. +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can do the same: + +```prompt agent +Find the most frequent new error in my Exceptionless project this week, read its latest event, fix the Vue component that throws it, and mark the stack fixed in the next version. +``` diff --git a/docs/docs/clients/javascript/index.md b/docs/docs/clients/javascript/index.md index 0c35df51cf..cfba32769a 100644 --- a/docs/docs/clients/javascript/index.md +++ b/docs/docs/clients/javascript/index.md @@ -1,65 +1,150 @@ --- -title: "JavaScript Client" -description: "Install the Exceptionless JavaScript client with npm or a CDN script tag, capture unhandled browser errors, submit exceptions, and fix minified stack traces." +title: "JavaScript client" +metaTitle: "JavaScript client for browsers and Node.js" +description: "Install the Exceptionless JavaScript client for browsers, Node.js, React, Vue, React Native, and Expo, from npm or a CDN, and capture unhandled errors." +sources: + - Exceptionless.JavaScript:README.md + - Exceptionless.JavaScript:packages/core/package.json + - Exceptionless.JavaScript:packages/core/src/ExceptionlessClient.ts + - Exceptionless.JavaScript:packages/browser/package.json + - Exceptionless.JavaScript:packages/browser/src/BrowserExceptionlessClient.ts + - Exceptionless.JavaScript:packages/node/package.json + - Exceptionless.JavaScript:packages/react/package.json + - Exceptionless.JavaScript:packages/react-native/package.json + - Exceptionless.JavaScript:packages/vue/src/index.ts + - Exceptionless.JavaScript:packages/angularjs/README.md + - Exceptionless.JavaScript:.agents/skills/exceptionless-javascript/SKILL.md --- -# JavaScript Client +# JavaScript client -The Exceptionless JavaScript client SDK makes it easy to report errors, log details, track feature usage and more. Be sure you have an Exceptionless account ([you can sign up here](/)) or that you are self-hosting a running instance of Exceptionless. +The Exceptionless JavaScript client sends errors, logs, feature usage, and 404s from browsers, Node.js, and React Native +apps. After you call `startup`, it reports unhandled errors and unhandled promise rejections automatically. ---- +## Install with your coding agent -Full guides can be found below: +Paste this into Claude Code, Codex, Copilot, or another coding agent from the root of your app: -* [React](/docs/clients/javascript/guides/react) -* [Vue](/docs/clients/javascript/guides/vue) -* [Angular](/docs/clients/javascript/guides/angular) -* [Node](/docs/clients/javascript/node-example) -* [Express](/docs/clients/javascript/guides/express) +```prompt agent +Add Exceptionless error monitoring to this JavaScript app. Read https://exceptionless.com/docs/clients/javascript.md, pick the framework guide that matches this app, and follow it. The agent skill at https://github.com/exceptionless/Exceptionless.JavaScript/tree/main/.agents/skills/exceptionless-javascript has source-checked setup notes for every package. Read the API key from configuration or an environment variable instead of hard-coding it, and add a way for me to throw a test error so I can confirm it shows up in Exceptionless. +``` ---- +The agent skill lives in the +[Exceptionless.JavaScript repository](https://github.com/exceptionless/Exceptionless.JavaScript/tree/main/.agents/skills/exceptionless-javascript). +See [Coding agents](/docs/ai/coding-agents/) for adding it to your agent. + +## Packages + +Install the package for your platform. Each one includes everything in `@exceptionless/core` and exports a ready-to-use +`Exceptionless` client. + +| Package | Use it for | What it adds | +| ----------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| `@exceptionless/browser` | Browser apps, the CDN, Angular, and the SvelteKit client side | Global `error` and `unhandledrejection` handlers, page request details, and stored settings in `localStorage`. | +| `@exceptionless/node` | Node.js 18 and later: servers, scripts, Express, serverless | `uncaughtException` and `unhandledRejection` handlers, machine details, request details, and a flush on exit. | +| `@exceptionless/react` | React 18 and later in the browser | Everything in `@exceptionless/browser`, plus `ExceptionlessErrorBoundary`. | +| `@exceptionless/vue` | Vue apps | Everything in `@exceptionless/browser`, plus `ExceptionlessErrorHandler`. | +| `@exceptionless/react-native` | React Native 0.71 and later, and Expo | Global JavaScript error capture, an error boundary, an AsyncStorage queue, and native iOS crash reporting. | +| `@exceptionless/angularjs` | AngularJS 1.x apps | An `exceptionless` module with `$ExceptionlessClient`, an `$exceptionHandler` decorator, and an HTTP interceptor. | +| `@exceptionless/core` | Other JavaScript runtimes and custom clients | The client, event builder, plugins, queue, and configuration that the other packages build on. | -This quickstart focuses on the vanilla JavaScript implementation of Exceptionless. +For AngularJS, see the +[package README](https://github.com/exceptionless/Exceptionless.JavaScript/tree/main/packages/angularjs). For modern +Angular, use `@exceptionless/browser` as shown in the [Angular guide](/docs/clients/javascript/guides/angular/). -## npm +## Requirements -To install with npm, run: `npm install @exceptionless/browser` +- **ES modules only.** Every package is an ES module (`"type": "module"`) with no CommonJS build. Load it with `import`. + In a CommonJS file, use a dynamic `import("@exceptionless/node")`. +- **ES2022.** The packages and CDN bundles are compiled for ES2022, so they need a browser or runtime that supports + ES2022. +- **Node.js 18 or later** for `@exceptionless/node`. +- **React 18 or later** for `@exceptionless/react` and `@exceptionless/react-native`. +- **React Native 0.71 or later** and **iOS 14 or later** for native iOS crash reporting. -Next, you just need to call startup during your apps startup to automatically capture unhandled errors. +## Quick start + +Install the browser package: + +```bash +npm install @exceptionless/browser +``` + +Start the client once when your app loads. `startup` takes your project's API key, which you can copy from the project's +**API Keys** page in Exceptionless: ```js -import { Exceptionless } from "@exceptionless/browser"; +import { Exceptionless } from "@exceptionless/browser" -await Exceptionless.startup("API KEY HERE"); +await Exceptionless.startup("YOUR_API_KEY") try { - throw new Error("test"); + throw new Error("Exceptionless test error") } catch (error) { - await Exceptionless.submitException(error); + await Exceptionless.submitException(error) } ``` -## CDN +The client sends queued events every 10 seconds, so the error shows up on the **Events** page shortly after. Unhandled +errors are reported without a `try`/`catch`. + +To set more than the API key, pass a callback: -To install via a script tag referencing Exceptionless over a CDN, add the following before your closing `` tag and call startup like so: +```js +import { Exceptionless } from "@exceptionless/browser" + +await Exceptionless.startup((c) => { + c.apiKey = "YOUR_API_KEY" + c.version = "1.2.3" + c.defaultTags.push("web") +}) +``` + +Every setting is listed on the [configuration reference](/docs/clients/javascript/client-configuration/). + +> [!NOTE] +> If you self-host Exceptionless, also set `c.serverUrl` to your instance's URL, for example +> `c.serverUrl = "https://exceptionless.example.com"`. + +## Load it from a CDN + +Without a bundler, import the browser package from a CDN in a module script. Both unpkg and jsDelivr serve the minified +ES2022 bundle: ```html ``` -## Production stack traces +`https://cdn.jsdelivr.net/npm/@exceptionless/browser@3` works the same way. Pin at least the major version so a future +release can't change your app without notice. The [browser guide](/docs/clients/javascript/guides/browser/) has the full +setup. -Production bundles are often minified, which makes their stack traces difficult to read and group. Exceptionless can automatically discover public source maps or accept private source maps from your CI/CD pipeline. See [JavaScript Source Maps](/docs/source-maps) for setup and upload instructions. +## Framework guides ---- +- [Browser](/docs/clients/javascript/guides/browser/): npm or CDN in any web page. +- [Node.js and serverless](/docs/clients/javascript/guides/node/): servers, scripts, workers, and functions. +- [Express](/docs/clients/javascript/guides/express/): error and 404 middleware with request details. +- [React](/docs/clients/javascript/guides/react/): `ExceptionlessErrorBoundary` with a fallback UI. +- [React Native and Expo](/docs/clients/javascript/guides/react-native/): JavaScript errors and native iOS crashes. +- [Next.js](/docs/clients/javascript/guides/nextjs/): App Router, `instrumentation.js`, and `onRequestError`. +- [SvelteKit](/docs/clients/javascript/guides/sveltekit/): `handleError` hooks on the client and server. +- [Vue](/docs/clients/javascript/guides/vue/): the global Vue error handler. +- [Angular](/docs/clients/javascript/guides/angular/): an `ErrorHandler` provider for standalone apps. + +## Readable production stack traces + +Minified bundles produce stack traces with short names and one-line files. Exceptionless finds public source maps +automatically and accepts private ones from your CI/CD pipeline. See +[Source maps](/docs/clients/javascript/source-maps/). + +## Next steps -[Next > Configuration](/docs/clients/javascript/client-configuration) +- [Send logs, feature usage, and custom events](/docs/clients/javascript/sending-events/). +- [Change client behavior from Exceptionless](/docs/clients/javascript/client-configuration-values/) without + redeploying. +- [Track user sessions](/docs/user-sessions/). +- [Fix events that don't arrive](/docs/clients/javascript/troubleshooting/). diff --git a/docs/docs/clients/javascript/javascript-example.md b/docs/docs/clients/javascript/javascript-example.md deleted file mode 100644 index b1f50f94a6..0000000000 --- a/docs/docs/clients/javascript/javascript-example.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "JavaScript Example" -metaTitle: "Exceptionless JavaScript example apps" -description: "Clone the Exceptionless.JavaScript GitHub repository to run example apps for the browser and JavaScript frameworks, or use them as a starting point." ---- - -# JavaScript Example - -We have put together an example for a few JavaScript-based frameworks and the browser to help you get started. You can find those [here in the GitHub Repo](https://github.com/exceptionless/Exceptionless.JavaScript/tree/master/example). You can clone the repository and run the code as is or you can use the repository example as a starting point. - -For framework specific details, continue on to the next page or select a specific framework on the left. - ---- - -[Next > React Example](/docs/clients/javascript/react-example) diff --git a/docs/docs/clients/javascript/node-example.md b/docs/docs/clients/javascript/node-example.md deleted file mode 100644 index d509725625..0000000000 --- a/docs/docs/clients/javascript/node-example.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "Node.js Example" -metaTitle: "Exceptionless Node.js example" -description: "A minimal Node.js script that imports @exceptionless/node, starts the Exceptionless client with your API key, and submits a caught exception." ---- - -# Node.js Example - -Here is a very simple example using a Node.js script. - -```js -import { Exceptionless } from "@exceptionless/node"; - -await Exceptionless.startup("YOUR API KEY"); - -const forceError = async () => { - try { - throw new Error("Whoops, I did it again.") - } catch(e) { - await Exceptionless.submitException(e); - } -} -``` - ---- - -[Next > Express Example](/docs/clients/javascript/express-example) {.text-right } diff --git a/docs/docs/clients/javascript/react-example.md b/docs/docs/clients/javascript/react-example.md deleted file mode 100644 index 3aed661a5d..0000000000 --- a/docs/docs/clients/javascript/react-example.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "React Example" -metaTitle: "React error boundary example for Exceptionless" -description: "Report React rendering errors to Exceptionless by wrapping your root component in ExceptionlessErrorBoundary, with an optional custom fallback UI." ---- - -# React Example - -The React Client from Exceptionless includes all of the functionality from the browser client, but with some extra React-specific helpers. - -The one thing you'll specifically notice in the React client is the addition of an `ExceptionlessErrorBoundary` class component. This is a wrapper component that can be used to ensure all errors in the presentational layer of your app are reported. - -It works exactly as Error Boundaries in React work, but it's pre-wired to report to Exceptionless. Here's a very simple example: - -```js -import React from 'react'; -import ReactDOM from 'react-dom'; -import './index.css'; -import App from './App'; -import reportWebVitals from './reportWebVitals'; -import { - Exceptionless, - ExceptionlessErrorBoundary -} from "@exceptionless/react"; -import ErrorBoundary from './ErrorBoundary'; - -const startExceptionless = async () => { - await Exceptionless.startup((c) => { - c.apiKey = "YOUR API KEY"; - c.useDebugLogger(); - - c.defaultTags.push("Example", "React"); - }); -}; - -startExceptionless(); - -ReactDOM.render( - - - - - - - , - document.getElementById('root') -); - -reportWebVitals(); -``` - -As you can see, we wrap the root `App` component first in the `ExceptionlessErrorBoundary` and then if you want to present your own fallback UI, you can create a custom `ErrorBoundary` component that will make sure that UI is served. - -We have a detailed [blog post about this here](https://exceptionless.com/news/2021/2021-08-16-how-to-use-error-boundaries-in-react/). - -[The full example / sample can be found here](https://github.com/exceptionless/Exceptionless.JavaScript/tree/master/example/react). - ---- - -[Next > Node.js Example](/docs/clients/javascript/node-example) {.text-right } diff --git a/docs/docs/clients/javascript/sending-events.md b/docs/docs/clients/javascript/sending-events.md index 194a57960c..68462ae5d6 100644 --- a/docs/docs/clients/javascript/sending-events.md +++ b/docs/docs/clients/javascript/sending-events.md @@ -1,83 +1,209 @@ --- -title: "Sending Events" -metaTitle: "Sending events from JavaScript" -description: "Send logs, feature usage, 404s, custom events, and caught errors from the Exceptionless JavaScript client, and attach tags, properties, and user identity." -order: 4 +title: "Send events from JavaScript" +navTitle: "Sending events" +metaTitle: "Send events from the JavaScript client" +description: "Send handled errors, logs, feature usage, 404s, and custom events from JavaScript, and add tags, extended data, user identity, and references." +order: 3 +sources: + - Exceptionless.JavaScript:packages/core/src/ExceptionlessClient.ts + - Exceptionless.JavaScript:packages/core/src/EventBuilder.ts + - Exceptionless.JavaScript:packages/core/src/models/Event.ts + - Exceptionless.JavaScript:packages/core/src/Utils.ts + - Exceptionless.JavaScript:packages/core/src/plugins/default/ReferenceIdPlugin.ts + - Exceptionless.JavaScript:packages/core/src/plugins/default/EventExclusionPlugin.ts + - Exceptionless.JavaScript:packages/core/test/DocumentationExamples.test.ts + - Exceptionless.JavaScript:.agents/skills/exceptionless-javascript/references/sending-events.md + - src/Exceptionless.Core/Pipeline/035_CopySimpleDataToIdxAction.cs --- -# Sending Events +# Send events from JavaScript -Once configured, Exceptionless automatically sends unhandled exceptions that happen in your application. To send different event types, as well as customize the data that is sent, continue reading. +Once the client is started, it reports unhandled errors on its own. Use the methods on this page to send errors you +catch, logs, feature usage, 404s, and your own event types, and to attach more information to any of them. -You can send us log messages, feature usages, or other kinds of events easily with our fluent api. +The examples import from `@exceptionless/browser`. The methods are the same in every package; import `Exceptionless` +from the package you installed. + +## Send an error you caught ```js -import { Exceptionless } from "@exceptionless/browser"; +import { Exceptionless, toError } from "@exceptionless/browser" -await Exceptionless.submitLog('Logging made easy'); +try { + await placeOrder() // your own code +} catch (error) { + await Exceptionless.submitException(toError(error)) +} +``` -// You can also specify the log source and log level. -// We recommend specifying one of the following log levels: Trace, Debug, Info, Warn, Error -await Exceptionless.submitLog('app.logger', 'This is so easy', 'Info'); -await Exceptionless.createLog('app.logger', 'This is so easy', 'Info').addTags('Exceptionless').submit(); +`submitException` takes an `Error`. JavaScript lets code throw any value, so `toError` converts strings and other values +to an `Error` and passes real errors through unchanged. -// Submit feature usages -await Exceptionless.submitFeatureUsage('MyFeature'); -await Exceptionless.createFeatureUsage('MyFeature').addTags('Exceptionless').submit(); +## Send a log message -// Submit a 404 -await Exceptionless.submitNotFound('/somepage'); -await Exceptionless.createNotFound('/somepage').addTags('Exceptionless').submit(); +```js +import { Exceptionless } from "@exceptionless/browser" -// Submit a custom event type -await Exceptionless.submitEvent({ message: 'Low Fuel', type: 'racecar', source: 'Fuel System' }); +await Exceptionless.submitLog("Order placed") +await Exceptionless.submitLog("checkout", "Order placed") +await Exceptionless.submitLog("checkout", "Payment provider timed out", "warn") ``` -### Manually Sending Errors +The forms are message only, source and message, and source, message, and level. Use the levels `trace`, `debug`, `info`, +`warn`, `error`, and `fatal`. The source is usually the area of your app, such as a logger or module name. -In addition to automatically sending all unhandled exceptions, you may want to manually send exceptions to the service. You can do so by using code like this: +You can turn log sources up or down from Exceptionless without redeploying. The client drops logs below the minimum +level for their source. See [Log levels](/docs/setting-log-levels/). -```javascript -import { Exceptionless } from "@exceptionless/browser"; +## Send feature usage -try { - throw new Error('test'); -} catch (error) { - await Exceptionless.submitException(error); -} +```js +import { Exceptionless } from "@exceptionless/browser" + +await Exceptionless.submitFeatureUsage("Export to CSV") ``` -### Sending Additional Information +The feature name is the event's source. See [Feature usage](/docs/feature-usage/) for the views that use these events. + +## Send a 404 -You can easily include additional information in your error reports using our fluent [event builder API](https://github.com/exceptionless/Exceptionless.JavaScript/blob/master/packages/core/src/EventBuilder.ts). +```js +import { Exceptionless } from "@exceptionless/browser" + +await Exceptionless.submitNotFound("/products/old-sku") +``` -```javascript -import { Exceptionless } from "@exceptionless/node"; +The path is the event's source. The [Express guide](/docs/clients/javascript/guides/express/) reports 404s from +middleware. + +## Send a custom event + +```js +import { Exceptionless } from "@exceptionless/browser" + +await Exceptionless.submitEvent({ type: "racecar", message: "Low fuel", source: "Fuel System" }) +``` + +An event with no type is sent as a log. + +## Add more information + +Every `submit*` method has a `create*` method that returns an event builder. Chain what you need and end with +`submit()`: + +```js +import { Exceptionless } from "@exceptionless/browser" + +const order = { + id: "order-123", + quoteId: 123, + creditCardNumber: "4111111111111111", +} try { - throw new Error('Unable to create order from quote.'); + throw new Error("Unable to create order from quote") } catch (error) { await Exceptionless.createException(error) - // Set the reference id of the event so we can search for it later (reference:id). - // This will automatically be populated by default with a unique id; - .setReferenceId('random guid') - // Add the order object (the ability to exclude specific fields will be coming in a future version). - .setProperty("Order", order) - // Set the quote number. + // Set your own reference ID so you can find this event later. + .setReferenceId("order-12345678") + // Add the order without its card number, up to 4 levels deep. + .setProperty("Order", order, 4, ["creditCardNumber"]) .setProperty("Quote", 123) - // Add an order tag. - .addTags("Order") - // Mark critical. + .addTags("orders") + // Adds the Critical tag. .markAsCritical() - // Set the coordinates of the end user. .setGeo(43.595089, -88.444602) - // Set the user id that is in our system and provide a friendly name. - .setUserIdentity(user.Id, user.FullName) - // Submit the event. - .submit(); + .setUserIdentity("user-123", "Jane Doe") + .submit() } ``` ---- +The builder methods are `createException`, `createUnhandledException`, `createLog`, `createFeatureUsage`, +`createNotFound`, `createSessionStart`, and `createEvent`. + +| Method | What it does | +| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `addTags(...tags)` | Adds tags. | +| `setProperty(name, value, maxDepth?, excluded?)` | Adds a value to the event's extended data. Objects are copied up to `maxDepth` levels (10 by default), without the property names in `excluded` or your [data exclusions](/docs/clients/javascript/client-configuration/#data-exclusions). | +| `markAsCritical(critical = true)` | Adds the `Critical` tag. `markAsCritical(false)` does nothing. | +| `setUserIdentity(identity, name?)` | Sets the user for this event. Also accepts `{ identity, name, data }`. | +| `setUserDescription(email, description)` | Adds the user's email address and their description of what happened. | +| `setReferenceId(id)` | Sets the event's reference ID. It must be 8 to 100 letters, digits, or hyphens, or the method throws. See [Reference IDs](/docs/references-ids/). | +| `setEventReference(name, id)` | Links this event to another event by that event's reference ID. | +| `setManualStackingKey(key, title?)` | Groups events with the same key into one stack, instead of the default grouping. See [Stacking](/docs/concepts/stacking/). | +| `setManualStackingInfo(signatureData, title?)` | Groups events by your own set of signature values. | +| `setGeo(latitude, longitude)` | Sets where the event happened. Throws if a value is out of range. | +| `setValue(value)` | Sets a numeric value on the event. | +| `setSource(source)`, `setMessage(message)`, `setType(type)` | Override the event's source, message, or type. | +| `setContextProperty(name, value)` | Passes a value to plugins without sending it, such as an Express request. | +| `submit()` | Sends the event to the queue and returns the plugin context. `context.cancelled` is `true` if a plugin or a setting stopped it. | + +To add the same tags or data to every event, use `defaultTags` and `defaultData` in the +[configuration](/docs/clients/javascript/client-configuration/). + +### Make custom data searchable + +On paid plans, Exceptionless indexes simple extended data values, such as strings, numbers, booleans, and dates, so you +can filter on them: -[Next > Troubleshooting](/docs/clients/javascript/troubleshooting) +```js +import { Exceptionless } from "@exceptionless/browser" + +await Exceptionless.createFeatureUsage("Checkout") + .setProperty("plan", "enterprise") + .setProperty("retryCount", 2) + .submit() +``` + +These events match the filters `data.plan:enterprise` and `data.retrycount:2`. Field names are lowercased. Keep names +short and stable, and keep objects for detail you only read. See +[Filtering and searching](/docs/filtering-and-searching/). + +## Let users describe an error + +Errors get a reference ID automatically. Show it to the user, then attach what they tell you to the event: + +```js +import { Exceptionless } from "@exceptionless/browser" + +const referenceId = Exceptionless.getLastReferenceId() + +// Later, when the user fills in your feedback form: +await Exceptionless.updateUserEmailAndDescription(referenceId, "jane@example.com", "The checkout page went blank.") +``` + +`getLastReferenceId()` returns the reference ID of the last queued event that had one. See +[Reference IDs](/docs/references-ids/). + +## Send right away + +`submit` puts the event in a queue that the client sends every 10 seconds. Before a short-lived process exits, or before +a hard page navigation, send the queue yourself: + +```js +import { Exceptionless } from "@exceptionless/browser" + +await Exceptionless.processQueue() +``` + +See [Node.js and serverless](/docs/clients/javascript/guides/node/#short-lived-processes-and-serverless). + +## Ask Exie + +```prompt exie +How many times was Export to CSV used each day this week? +``` + +```prompt exie +Count log events by level for the last 24 hours. +``` + +```prompt exie +Which stacks had events tagged Critical today? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can search the data you send: + +```prompt agent +Search my Exceptionless project for Checkout feature usage events from the last 7 days where data.plan is enterprise, and summarize how often they retried. +``` diff --git a/docs/docs/clients/javascript/source-maps.md b/docs/docs/clients/javascript/source-maps.md new file mode 100644 index 0000000000..35dd358da4 --- /dev/null +++ b/docs/docs/clients/javascript/source-maps.md @@ -0,0 +1,216 @@ +--- +title: "JavaScript source maps" +navTitle: "Source maps" +metaTitle: "JavaScript source maps for stack traces" +description: "Get readable stack traces for minified JavaScript: let Exceptionless discover public source maps, or upload private ones from CI/CD with a scoped token." +order: 5 +redirectFrom: + - /docs/source-maps/ +sources: + - src/Exceptionless.Core/Services/SourceMaps/SourceMapService.cs + - src/Exceptionless.Core/Services/SourceMaps/SourceMapDownloader.cs + - src/Exceptionless.Core/Services/SourceMaps/SourceMapDocument.cs + - src/Exceptionless.Core/Services/SourceMaps/SourceMapRequestThrottle.cs + - src/Exceptionless.Core/Configuration/SourceMapOptions.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/15_SourceMapPlugin.cs + - src/Exceptionless.Core/Bootstrapper.cs + - src/Exceptionless.Web/Api/Endpoints/SourceMapEndpoints.cs + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/source-maps/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/api-keys/+page.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/stack-trace/source-map-status.svelte + - Exceptionless.JavaScript:packages/browser/src/plugins/BrowserErrorPlugin.ts + - Exceptionless.JavaScript:packages/node/README.md +--- + +# JavaScript source maps + +Production JavaScript is bundled and minified, so a stack frame such as `loadCurrentUser` in `src/user.ts` becomes `a` +in `app.a1b2c3.js` at line 1. Exceptionless uses your source maps to restore the original function names, files, lines, +and columns before it groups a new error into a stack. You get readable stack traces, and errors group by the code that +actually failed. + +There are two ways to give Exceptionless your source maps: + +| Your source maps are... | Do this | +| ----------------------------------------- | --------------------------------------------------------------------------------------------------- | +| Deployed publicly next to your JavaScript | [Nothing](#use-public-source-maps). Exceptionless finds them automatically. | +| Private, or kept only as build artifacts | [Upload them](#upload-private-source-maps), by hand or [from CI/CD](#upload-source-maps-from-cicd). | + +Source maps apply to new events only. Adding a map doesn't change events that were already processed. + +They apply to stack frames whose file is an absolute HTTP or HTTPS URL and that have a line and column, which is what +the browser client reports. Node.js stack frames are file paths, so for Node.js run your app with +`node --enable-source-maps`, and Node.js maps the stack trace before the client sends it. + +## Generate source maps + +Have your bundler write a `.map` file for each production bundle: + +- **Vite**: set `build.sourcemap` to `true`, or to `"hidden"` to leave out the `sourceMappingURL` comment. +- **webpack**: set `devtool` to `"source-map"`, or to `"hidden-source-map"` to leave out the comment. +- **esbuild**: pass `--sourcemap`. + +Generate the maps in the same build that produces the JavaScript you deploy. A map from a different build points at the +wrong code. + +## Use public source maps {#use-public-source-maps} + +If your `.map` files are deployed with your JavaScript, there's nothing to configure. When a new error has a frame from +a file Exceptionless hasn't seen, it: + +1. uses a map already stored for that exact file URL, if there is one; +2. otherwise downloads the generated JavaScript file over HTTPS; +3. looks for a `SourceMap` or `X-SourceMap` response header, then a `sourceMappingURL` comment in the file; +4. if neither is there, tries the file's URL with `.map` added; +5. validates and stores the map for the project, then maps the frame. + +For example, these two files work with no setup: + +```text +https://cdn.example.com/assets/app.a1b2c3.js +https://cdn.example.com/assets/app.a1b2c3.js.map +``` + +The `sourceMappingURL` comment can be relative, as bundlers usually write it, or absolute, or an inline `data:` URL. + +Discovered maps appear on the project's **Source Maps** page as **Automatic**. When a discovered map is used and is more +than an hour old, Exceptionless downloads it again, so it follows a file that changed at the same URL. Content-hashed +file names such as `app.a1b2c3.js` avoid that problem entirely, because each URL always means one build. + +### Requirements for discovery + +- The JavaScript URL in the stack frame is an absolute `https://` URL on the default port (443). +- The JavaScript file and map are reachable from the internet without cookies, authentication, or an IP allowlist. + Exceptionless doesn't connect to private network addresses, and follows at most 3 redirects. +- The map is a version 3 source map. Indexed maps, which have a `sections` property, aren't supported. +- The map is at most 20 MiB, and each download finishes within 3 seconds. + +Exceptionless discovers a limited number of new maps for each project in a 15-minute period: 10 for organizations on the +Free plan and 50 on paid plans, with lower limits for each client API key. An event processed while the limit is reached +keeps its minified frames, and later events use the map once it's stored. When a download fails, Exceptionless doesn't +try that file again for 15 minutes. + +Check that a deployed map is public before you rely on it: + +```bash +curl --fail --silent --show-error --output /dev/null "https://cdn.example.com/assets/app.a1b2c3.js.map" +``` + +Public maps often include your original source code in `sourcesContent`. If that code shouldn't be public, don't deploy +the maps. Upload them instead. + +## Upload private source maps {#upload-private-source-maps} + +An uploaded map doesn't need to be public. Exceptionless stores it for the exact JavaScript URL you give it, and uses it +without downloading anything. + +To upload a map by hand: + +1. Open your project's settings and select **Source Maps**. +2. Under **Upload Source Map**, enter the **Generated JavaScript URL**: the full URL of the JavaScript file, exactly as + it appears in the stack trace. +3. Choose the matching `.map` file under **Source map**, and select **Upload**. + +The URL can be HTTP or HTTPS, on any host or port, but can't contain a user name, password, or `#` fragment. Keep the +path and query string exactly as they appear in the stack frame. A map can be up to 20 MiB. + +Uploading another map for the same URL replaces the old one. The **Available Source Maps** table lists uploaded and +discovered maps with their size, when they were added, and when they were last used. Delete a map there with its trash +button. + +## Upload source maps from CI/CD {#upload-source-maps-from-cicd} + +Upload maps from the same build you deploy: build once, upload the maps, then deploy those exact files. + +### 1. Create a source map upload token + +1. Open your project's settings and select **API Keys**. +2. Select **Add token**, then **Source map upload token**. +3. Copy the new token and save it in your CI/CD system as a secret, for example `EXCEPTIONLESS_SOURCE_MAP_TOKEN`. + +This token can only upload source maps, and only to this project. It can't read events, change settings, or send events. +Don't use the client API key from your app; it can't upload maps. + +Your pipeline also needs your project's ID. It's in the address bar when you open the project in Exceptionless: +`/project//...`. + +### 2. Upload each map + +Send each map as `multipart/form-data` with two fields: `generated_file_url`, the public URL of its JavaScript file, and +`file`, the map: + +```bash +curl --fail-with-body --request POST \ + "https://api.exceptionless.io/api/v2/projects/${EXCEPTIONLESS_PROJECT_ID}/source-maps" \ + --header "Authorization: Bearer ${EXCEPTIONLESS_SOURCE_MAP_TOKEN}" \ + --form-string "generated_file_url=https://cdn.example.com/assets/app.a1b2c3.js" \ + --form "file=@dist/assets/app.a1b2c3.js.map;type=application/json" +``` + +A successful upload returns `201 Created` with the stored map's details. An invalid URL or map returns +`422 Unprocessable Entity` with the reason, and so does an upload past your project's storage limits. + +Run the request after the production build and before the release step, once for each `.map` file the build produced. +How you list the files and build their public URLs depends on your bundler and where you deploy. + +> [!NOTE] +> Self-hosted instances use your own server URL in place of `https://api.exceptionless.io`. + +## Verify + +1. Trigger a new error in the deployed app. +2. Open the event. Its stack trace shows the original file and function names. +3. Open your project's settings and select **Source Maps**. The JavaScript URL is listed as **Automatic** or + **Uploaded**. Usage is saved in the background, so **Last used** can take a while to show a date. + +## Troubleshooting + +When Exceptionless can't map a stack trace, the event's stack trace shows a **Source map unavailable** or **Stack trace +partially symbolicated** button. Select it to see each file that failed and why: + +| Reason shown | What to check | +| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| No usable source map could be downloaded. | The map isn't public, isn't at a URL Exceptionless looks for, or the file isn't on HTTPS. Upload it instead. | +| The downloaded source map is invalid or unsupported. | The file isn't a version 3 source map, or it's an indexed map with `sections`. | +| The source map does not contain this generated location. | The map came from a different build than the deployed JavaScript. | +| The source map download timed out. | The map took longer than 3 seconds to download. Upload it instead. | +| The source map could not be downloaded. | The server returned an error, a limit was reached, or the download was too large. | + +If an uploaded map isn't used: + +- Compare its **Generated file** URL with the file URL in the event's stack frame. They must match, including the query + string. +- Send a new error. Existing events are not reprocessed. +- Confirm that the frame has a line and a column. + +## Storage and retention + +| Limit | Free plan | Paid plans | +| --------------------------------------------- | --------- | ---------- | +| Source maps per project | 100 | 1,000 | +| Storage per project | 100 MiB | 1 GiB | +| Unused maps are deleted after | 14 days | 90 days | +| New maps discovered per project in 15 minutes | 10 | 50 | + +A map counts as used when it maps a frame. A map that's never used is deleted that long after it was added. Automatic +discovery never rejects an event: if a map is unavailable or a limit is reached, the event keeps its original frames. + +Self-hosted administrators can change these limits in the `SourceMaps` configuration section, and turn off discovery +with `EX_SourceMaps__EnableAutoDownload=false`. See [Self-hosting configuration](/docs/self-hosting/configuration/). + +## Ask Exie + +```prompt exie +Show me the stack trace of the latest event in this stack. +``` + +```prompt exie +Which error stacks are new this week? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can read the mapped stack trace and go straight +to the code: + +```prompt agent +Get the latest event for the top JavaScript error stack in my Exceptionless project, use its source-mapped stack trace to find the failing code in this repository, and fix it. +``` diff --git a/docs/docs/clients/javascript/troubleshooting.md b/docs/docs/clients/javascript/troubleshooting.md index e1bf591c96..f33a6f4c9f 100644 --- a/docs/docs/clients/javascript/troubleshooting.md +++ b/docs/docs/clients/javascript/troubleshooting.md @@ -1,51 +1,147 @@ --- -title: "Troubleshooting" -metaTitle: "Troubleshooting the JavaScript client" -description: "Fix Exceptionless JavaScript client events that are not sent: update the client, process the queue before exit, enable debug logging, and check your API key." +title: "Troubleshoot the JavaScript client" +navTitle: "Troubleshooting" +metaTitle: "Troubleshooting the Exceptionless JavaScript client" +description: "Find out why JavaScript events don't reach Exceptionless: turn on debug logging, read server responses, flush the queue, and check filters and privacy settings." order: 6 +sources: + - Exceptionless.JavaScript:packages/core/src/ExceptionlessClient.ts + - Exceptionless.JavaScript:packages/core/src/configuration/Configuration.ts + - Exceptionless.JavaScript:packages/core/src/queue/DefaultEventQueue.ts + - Exceptionless.JavaScript:packages/core/src/submission/DefaultSubmissionClient.ts + - Exceptionless.JavaScript:packages/core/src/plugins/default/EventExclusionPlugin.ts + - Exceptionless.JavaScript:packages/core/src/plugins/default/DuplicateCheckerPlugin.ts + - Exceptionless.JavaScript:packages/core/src/logging/ILog.ts + - Exceptionless.JavaScript:packages/browser/src/plugins/BrowserIgnoreExtensionErrorsPlugin.ts + - Exceptionless.JavaScript:packages/browser/package.json + - Exceptionless.JavaScript:.agents/skills/exceptionless-javascript/references/troubleshooting.md --- -# Troubleshooting +# Troubleshoot the JavaScript client -If your events aren't being sent to the server there are a few things that you can try to diagnose the issue. +The client doesn't throw when it can't send events, so a bad API key or an unreachable server fails quietly. Start with +debug logging, which shows every step from queuing an event to the server's response. -## Update Your Client +## Turn on debug logging -Please make sure that you are using the latest version of the client. +```js +import { Exceptionless } from "@exceptionless/browser" + +await Exceptionless.startup((c) => { + c.apiKey = "YOUR_API_KEY" + c.useDebugLogger() +}) +``` + +The client writes to the console: the browser's developer tools, your Node.js output, or the Metro logs in React Native. +When events flow, you see lines such as `Enqueued event`, `Sending 1 events to ...`, and `Sent 1 events`. + +To send the client's messages somewhere else, set `c.services.log` to an object with `trace`, `info`, `warn`, and +`error` methods. Turn debug logging off again in production. + +## Nothing is sent + +Check these in order: + +1. **`startup` ran.** Events submitted before `startup`, or from a different copy of the package, aren't sent. Import + `Exceptionless` from the same package everywhere. +2. **The API key is right.** The client sends nothing while `apiKey` is shorter than 10 characters, and logs + `Exceptionless is not configured and will not process events.` Copy the key from your project's **API Keys** page, + and make sure it isn't disabled. +3. **The client is enabled.** `c.enabled = false` discards every event. +4. **The process lived long enough.** Events wait in a queue that's sent every 10 seconds. A script, serverless + function, or page that ends first loses them. Call `await Exceptionless.processQueue()` before it ends. See + [Node.js and serverless](/docs/clients/javascript/guides/node/#short-lived-processes-and-serverless). +5. **The request isn't blocked.** In the browser, look for a failed request in the network tab. If your site has a + Content Security Policy, its `connect-src` must allow your Exceptionless server. For the hosted service, set + `c.serverUrl = "https://api.exceptionless.io"` and allow that origin. Self-hosted servers must also allow your site's + origin for cross-origin requests. + +## The client stopped sending + +The client pauses when the server turns events away. The debug log shows which case you hit: + +| Server response | Log message | What the client does | +| -------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| `401` or `403` | `Unable to authenticate, please check your configuration.` | Discards the batch and pauses for 15 minutes. Check the API key. | +| `402` | `Too many events have been submitted, please upgrade your plan` | Your organization is over its plan's limit. Discards the queue and new events until the next quarter hour. | +| `429` or `503` | `Server returned service unavailable` | Keeps the queue and pauses until the next quarter hour. | +| `400` or `404` | `Error while trying to submit data: ...` | Discards the batch and pauses for 4 hours. A `404` usually means a wrong `serverUrl`. | +| `413` | `Event submission discarded for being too large.` | Retries with smaller batches, and discards an event that's too large on its own. | +| No response, such as a network or CORS error | `Error processing queue: ...` | Keeps the queue and pauses until the next quarter hour. | +| Any other error status | `Error submitting events: ...` | Keeps the queue and pauses until the next quarter hour. | + +Reloading the page or restarting the process clears a pause. + +## Some events are missing -## Ensure the Queue has Time to Process +The client drops events on purpose in these cases: -If you are using Exceptionless in a scenario where an event is submitted and the process is immediately terminated, then you will need to make sure that the queue is processed before the application ends. Please note that the client will try to do this automatically. +- **A configuration value turns them off**, such as a `@@log` minimum level or `@@error:` set to `false`. See + [built-in keys](/docs/clients/javascript/client-configuration-values/#built-in-keys). +- **A plugin cancelled them**, by setting `context.cancelled = true` or by throwing. +- **The user agent matches a bot pattern** from your project's **Spam Detection** list or `addUserAgentBotPatterns`. +- **The error came from a browser extension.** The browser client ignores errors whose stack trace has an + `-extension://` URL. +- **The error repeated within 30 seconds.** Repeats are held and sent later as one event with a count. -Events are queued and sent in the background, if the application isn't running then the events cannot be sent. You can manually force the queue to be processed by calling the following line of code before before the process ends: +`submit()` returns the plugin context, and `context.cancelled` is `true` when the client dropped the event: ```js -import { Exceptionless } from "@exceptionless/browser"; -await Exceptionless.processQueue(); +import { Exceptionless } from "@exceptionless/browser" + +const context = await Exceptionless.submitLog("checkout", "Order placed", "info") +console.log("Dropped:", context.cancelled) ``` -This will cause the event queue to be processed asynchronously and the events to be reported. If this doesn’t solve the issue then please enable client logging and send us the log file. You can also attempt to pass true to `process(true)` to try and process the queue synchronously. _Please note that sending synchronously depends on specific api's that may not be available, so it may not send synchronously._ +## Some data is missing -## Enable Client Logging +If cookies, headers, query strings, request bodies, IP addresses, or extended data values are missing, check the +`include*` settings and your data exclusions, both in code and in your project's **Data Exclusions** setting. See +[Private information](/docs/clients/javascript/client-configuration/#general-data-protection-regulation). -The Exceptionless client can be configured to write diagnostic messages to the console to help diagnose any issues with the client. +## Stack traces are minified -```js -import { Exceptionless } from "@exceptionless/browser"; +Production bundles need source maps for readable stack traces. See [Source maps](/docs/clients/javascript/source-maps/). +For Node.js, run with `--enable-source-maps`. + +## Update the client -await Exceptionless.startup(c => { - c.useDebugLogger(); -}); +Make sure you have the current release, and that every `@exceptionless/*` package you use is the same version: + +```bash +npm install @exceptionless/browser@latest ``` -## Check Your API Key +To step through the client's code in the browser, load the unminified bundle from the CDN, which ships with a source +map: -By design, an invalid API key provided to the Exceptionless client is not going to crash your application. Be sure to check the log outputs as this information will tell you if you have provided an invalid key. +```html + +``` -You can also debug the Exceptionless source code by using the unmagnified version and set breakpoints in your browsers developer tools. +If you're still stuck, [open an issue](https://github.com/exceptionless/Exceptionless.JavaScript/issues/new) with the +debug log. ---- +## Ask Exie -[Next > JavaScript Example](/docs/clients/javascript/javascript-example) +```prompt exie +Did this project receive any events in the last 15 minutes? +``` + +```prompt exie +When did each of my projects last receive an event? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can check while it works: + +```prompt agent +I just added Exceptionless to this app. Throw a test error, run the app, and then check my Exceptionless project for the event. If it doesn't arrive, turn on useDebugLogger, read the client's output, and fix the setup. +``` diff --git a/docs/docs/clients/javascript/vue-example.md b/docs/docs/clients/javascript/vue-example.md deleted file mode 100644 index 44911e2bde..0000000000 --- a/docs/docs/clients/javascript/vue-example.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Vue Example" -metaTitle: "Exceptionless Vue example app" -description: "Find the Exceptionless Vue sample app in the Exceptionless.JavaScript GitHub repository to see error reporting wired into a working Vue application." ---- - -# Vue Example - -[Example / Sample can be found here](https://github.com/exceptionless/Exceptionless.JavaScript/tree/master/example/vue). - ---- - -[Next > Self-Hosting](/docs/self-hosting/) diff --git a/docs/docs/comparison.md b/docs/docs/comparison.md deleted file mode 100644 index 0941527bf1..0000000000 --- a/docs/docs/comparison.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "Comparison" -metaTitle: "Exceptionless vs Application Insights, Elmah, Raygun" -description: "Compare Exceptionless with Application Insights, Elmah, and Raygun on open source, free self-hosting, stacking, search, sessions, webhooks, and REST API." ---- - -# Comparison - -| Feature | Exceptionless | Application Insights | Elmah | Raygun | -| :----------------------------- | :-----------: | :------------------: | :---: | :----: | -| Open Source | X | | X | | -| Free Self Hosting | X | | X | | -| Detailed error reports | X | X | | X | -| Email Notifications | X | X | X | X | -| Export Events | | X | X | | -| Filtering | X | X | | X | -| Send Custom Data [^1] | X | | | X | -| Real-time Client Configuration | X | | | | -| Real-time Dashboards | X | | | | -| Complete Rest API | X | | | | -| Search | X | X | | X | -| Search Custom Fields | X | | | | -| Intelligent Stacking | X | X | | X | -| Custom Stacking | X | | | X | -| Mark Fixed | X | | | X | -| Mark Hidden | X | | | X | -| Comment on Events | | | | X | -| Support Multiple Platforms | X | X | | X | -| User Sessions [^2] | X | | | X | -| User % [^3] | X | | | ? | -| Broken Links | X | X | X | X | -| Releases | | | | X | -| Feature Usages | X | | | | -| Log Messages | X | | | | -| Custom Event Types | X | X | | | -| Webhooks | X | X | | X | - -- **X** = has feature, **empty box** does not have feature, **?** = unknown - -[^1]: Send custom data on any event and promote it to a first class tab. -[^2]: Automatically tracks users sessions. Please note that this is a paid add on for Raygun Pulse (**$149/mo**). -[^3]: Ability to see how many users are affected by an error or are using a specific feature. - ---- - -[Next > Security](/docs/security) diff --git a/docs/docs/concepts/index.md b/docs/docs/concepts/index.md new file mode 100644 index 0000000000..32d5c0a357 --- /dev/null +++ b/docs/docs/concepts/index.md @@ -0,0 +1,124 @@ +--- +title: "Core concepts" +description: "How Exceptionless organizes your data: organizations, projects, events, stacks and their statuses, versions, environments, saved views, and AI." +sources: + - src/Exceptionless.Core/Models/Event.cs + - src/Exceptionless.Core/Models/Stack.cs + - src/Exceptionless.Core/Models/SavedView.cs + - src/Exceptionless.Core/Pipeline/010_AssignToStackAction.cs + - src/Exceptionless.Core/Pipeline/030_CheckForRegressionAction.cs + - src/Exceptionless.Core/Jobs/StackStatusJob.cs + - src/Exceptionless.Core/Seed/predefined-saved-views.json + - src/Exceptionless.Core/Serialization/EventEnvironmentConverter.cs + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/stack-status-dropdown-menu.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/components/save-view-dialog.svelte + - src/Exceptionless.Web/Assistant/AssistantToolDefinitions.cs + - src/Exceptionless.Web/Assistant/AssistantSystemPrompt.cs + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs +--- + +# Core concepts + +Exceptionless takes in events from your apps, groups the ones that describe the same problem into stacks, and lets you +triage stacks instead of individual occurrences. This page explains the pieces in about five minutes and links to the +pages that cover each one in depth. + +## Organizations and projects + +An **organization** is your team's account. It has the plan, the billing details, and the users who can see its data. +You invite teammates to an organization, and they see every project in it. One person can belong to several +organizations. + +A **project** is one app or service that sends events, such as a web API or a mobile app. Each project has its own API +keys, settings, and data. Clients use a project API key to send events, so the key decides which project an event lands +in. + +Plan limits, such as monthly events, retention, and the number of projects and users, apply to the whole organization. +See [Organizations and billing](/docs/organizations/), [Projects](/docs/project-settings/), and +[Limits and deduplication](/docs/concepts/limits/). + +## Events + +An **event** is one thing that happened in your app: an error, a log message, a feature being used. Each event has a +type, a date, and optional details such as a message, source, tags, user, version, environment, request, and custom +data. + +| Type | What it records | +| --------- | ---------------------------------------------------------------------------------------- | +| `error` | An exception, with its type, message, and stack trace. | +| `log` | A log message, with an optional source and level. | +| `usage` | Feature usage: someone used a feature you want to count. | +| `404` | A request for a page or resource that wasn't found. | +| `session` | The start of a user session. `heartbeat` events keep it open and `sessionend` closes it. | + +Clients send most of these automatically. Unhandled exceptions become errors as soon as the client is installed, and you +send logs, feature usage, and handled errors with one line of code. Any other type name is a custom event. + +See [Events](/docs/events/), [Logs and log levels](/docs/setting-log-levels/), [Feature usage](/docs/feature-usage/), +[Sessions](/docs/user-sessions/), and the [event format](/docs/reference/event-format/). + +## Stacks + +A **stack** groups every event that describes the same problem. Exceptionless computes a signature for each event: for +errors, the exception type and the stack trace; for other events, the type and source. Events with the same signature in +the same project join the same stack. A thousand occurrences of one bug are one stack with a count of 1,000, not a +thousand rows to read. + +You triage at the stack level. A stack's status, critical flag, reference links, and fixed version apply to all of its +events. See [Stacking](/docs/concepts/stacking/) for how signatures work and how to change them. + +### Stack statuses + +| Status | Meaning | +| ------------- | ----------------------------------------------------------------------------------------------------------- | +| **Open** | Needs attention. New stacks start here. | +| **Fixed** | You fixed it, optionally in a specific version. If it happens again, Exceptionless marks it regressed. | +| **Regressed** | It was fixed and has happened again. Regressed stacks show up next to open ones. | +| **Snoozed** | Hidden and silent for 6 hours, a day, a week, or a month. When the time is up, the stack goes back to open. | +| **Ignored** | Events are still recorded, but you get no notifications for the stack. | +| **Discarded** | Future events are dropped and don't count against your plan's event limit. | + +The built-in views show open and regressed stacks, so fixed, snoozed, ignored, and discarded stacks drop out of your +daily list. See [Stacks](/docs/managing-stacks/). + +## Versions and regressions + +When your client sends your app's version with each event, you can mark a stack **Fixed** in a version, such as `2.4.0`. +Exceptionless then treats an event from version `2.4.0` or later as a regression, and reopens the stack as +**Regressed**. Events from older versions that are still running don't reopen it. + +If you mark a stack fixed without a version, any new event after that moment is a regression. See +[Releases and regressions](/docs/versioning/). + +## Environments + +An event can name the **environment** it came from, such as `production`, `staging`, or `development`. You can filter +every list by environment, and saved views remember the filter. Environments don't split stacks: the same error in +staging and production is one stack with one status. See [Environments](/docs/environments/). + +## Saved views + +The **Stacks**, **Events**, and **Sessions** pages each show a **saved view**: a filter, a time range, a sort order, and +the columns and charts to show. Every organization starts with built-in views: + +- **Stacks**: All, Most Frequent Errors, Most Frequent 404s, and Most Used Features. +- **Events**: All, Errors, and Logs. +- **Sessions**: All. + +Each built-in view covers the last 7 days. Change the filter or time range, then save it as a new view. A view is shared +with everyone in the organization unless you mark it **Private**. Saved views appear in the sidebar under the page they +belong to. See [Saved views](/docs/saved-views/) and [Filtering and searching](/docs/filtering-and-searching/). + +## Where AI fits + +Exceptionless works with AI in two ways, and both use the same set of tools over your data: + +- **Exie** is the assistant in the app. Ask it which errors matter, what changed after a release, or why a stack keeps + happening. It searches stacks and events, counts events over time, and reads stack traces. When you ask it to, it also + changes a stack's status, snoozes it, marks it critical, or adds a reference link. Exie never changes data unless you + ask for that exact change. Exie is on Medium plans and up. See [Exie](/docs/ai/exie/). +- **The MCP server** connects your own coding agent, such as Claude Code or Codex, to Exceptionless on every plan. The + agent signs in with your account, you choose what it can access, and it can look up an error and fix the code in the + same session. Changing stacks needs a separate `stacks:write` permission. See [MCP server](/docs/ai/mcp-server/). + +For what these tools can see and how to limit them, see [AI privacy and security](/docs/ai/privacy/). diff --git a/docs/docs/concepts/limits.md b/docs/docs/concepts/limits.md new file mode 100644 index 0000000000..ad8b84dba3 --- /dev/null +++ b/docs/docs/concepts/limits.md @@ -0,0 +1,192 @@ +--- +title: "Limits and deduplication" +description: "Plan limits, data retention, throttling, what happens at the monthly limit, and how clients and the server keep bursts of events from using up your plan." +navTitle: "Limits" +redirectFrom: + - from: /docs/deduplication/ + anchor: deduplication +sources: + - docs/_data/plans.json + - src/Exceptionless.Core/Billing/BillingPlans.cs + - src/Exceptionless.Core/Billing/BillingManager.cs + - src/Exceptionless.Core/Services/UsageService.cs + - src/Exceptionless.Core/Jobs/EventPostsJob.cs + - src/Exceptionless.Core/Jobs/CleanupDataJob.cs + - src/Exceptionless.Core/Pipeline/001_CheckEventDateAction.cs + - src/Exceptionless.Core/Pipeline/010_AssignToStackAction.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/0_ThrottleBotsPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/05_CheckForDuplicateReferenceIdPlugin.cs + - src/Exceptionless.Core/Configuration/AppOptions.cs + - src/Exceptionless.Core/Repositories/Queries/AppFilterQuery.cs + - src/Exceptionless.Web/Utility/Handlers/OverageMiddleware.cs + - src/Exceptionless.Web/Utility/Handlers/ThrottlingMiddleware.cs + - src/Exceptionless.Web/Program.cs + - src/Exceptionless.Web/Api/Handlers/OrganizationHandler.cs + - src/Exceptionless.Web/ClientApp/src/routes/(app)/organization/[organizationId]/usage/+page.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/organizations/components/organization-notifications.svelte + - Exceptionless.Net:src/Exceptionless/Plugins/Default/910_DuplicateCheckerPlugin.cs + - Exceptionless.Net:src/Exceptionless/Queue/DefaultEventQueue.cs + - Exceptionless.JavaScript:packages/core/src/plugins/default/DuplicateCheckerPlugin.ts + - Exceptionless.JavaScript:packages/core/src/queue/DefaultEventQueue.ts +--- + +# Limits and deduplication + +Each organization's plan sets how many events it can store each month and how long they're kept. This page explains +those limits, how Exceptionless spreads your events across the month, what happens when you reach a limit, and how the +clients and the server keep a burst of identical errors from using up your plan. + +## Plan limits + +| Plan | Events per month | Retention | Projects | Users | +| ----------- | ---------------- | --------- | --------- | --------- | +| Free | 3,000 | 3 days | 1 | 1 | +| Small | 15,000 | 30 days | 5 | 10 | +| Medium | 75,000 | 90 days | 15 | 25 | +| Large | 250,000 | 180 days | Unlimited | Unlimited | +| Extra Large | 1,000,000 | 180 days | Unlimited | Unlimited | +| Enterprise | 3,000,000 | 180 days | Unlimited | Unlimited | + +Yearly plans have the same limits as their monthly versions. See [pricing](/pricing/) for prices and +[Organizations and billing](/docs/organizations/) to change plans. Exie's monthly AI allowance also depends on the plan; +see [Exie](/docs/ai/exie/). + +- Limits apply to the whole organization, across all of its projects. +- The event count resets at the start of each calendar month, in UTC. +- The user limit counts pending invites as well as members. +- You can't create another organization while you belong to one on the Free plan. + +### What counts as an event + +An event counts against the monthly limit when it's processed and stored. These don't count: + +- Events for stacks marked **Discarded**. +- Events that the server throws away: those removed by [bot protection](#bots-and-spam), events dated outside the + [submission window](#retention), and events that repeat a reference ID. +- Events that a client filters out before sending them, such as logs below the minimum log level or events excluded by a + plugin. + +An event that the client has [merged from duplicates](#deduplication) counts once, however many occurrences it stands +for. + +To see where your events went, open the organization's **Usage** page. The chart shows **Total**, **Blocked** (rejected +because of a limit), **Discarded**, **Too Big**, and **Deleted** events against the **Limit**. Each project has its own +**Usage** page too. + +## Throttling + +If an app sent its whole month's events in one afternoon, you'd have no events left for the rest of the month. To +prevent this, Exceptionless counts events in five-minute windows and caps each window at 10 times the even share of the +month: + +```text +events per five minutes = 10 × monthly event limit ÷ five-minute windows left in the month +``` + +For example, on the Medium plan at the start of a 30-day month, that's about 87 events per five minutes. The cap rises +as the month goes on. Plans with fewer than 5,000 events a month, such as Free, aren't throttled, and no plan is +throttled during the last day of the month. + +When a window's cap is reached, new events are rejected until the next window starts, and the app shows **Events are +currently being throttled** for the organization. Rejected events show up as **Blocked** on the **Usage** page. +Upgrading raises the cap right away. + +## Reaching the monthly limit + +When the organization reaches its monthly limit, the API rejects new events until the next month starts or you upgrade. +The app shows that the organization has reached its monthly plan limit, and Exceptionless emails the organization's +users once that month. Events you've already stored stay available, and nothing is billed for events over the limit. + +### How clients respond + +The API answers rejected event submissions with `402 Payment Required`, both while you're throttled and at the monthly +limit. The clients then stop sending for a while and drop the events they had queued, so that once sending resumes the +events you get are recent ones: + +- The .NET client pauses for five minutes and discards events submitted in that time. +- The JavaScript client pauses until the next quarter hour and discards events submitted in that time. + +Your app keeps running normally the whole time. + +### Other API limits + +- **Request rate:** each organization's API keys, and each signed-in user, can make 3,500 API requests per 15 minutes. + Requests over the limit get `429 Too Many Requests`. Responses include `X-RateLimit-Limit` and `X-RateLimit-Remaining` + headers. Client configuration and session heartbeat requests don't count. +- **Request size:** an event submission larger than 200,000 bytes gets a `413` response. The clients retry with smaller + batches, and drop a single event that is still too large. + +See the [API overview](/docs/api/) for status codes, and the [client specification](/docs/reference/client-spec/) for +how clients retry. + +## Retention {#retention} + +Events older than your plan's retention period are no longer shown in the app or returned by the API. Exceptionless +deletes them later, after the retention period of the next plan up, or after 180 days on the largest plans. If you +upgrade before then, the older events become visible again. + +Stacks are kept longer than their events. An open stack with no reference links is deleted 60 days after its last event +is deleted. Stacks with another status, such as fixed or discarded, and stacks with reference links are kept, so their +status still applies when the error comes back. + +Events must also arrive within three days of when they happened. The server discards events dated earlier than that, or +earlier than your retention period, and changes dates in the future to the current time. So events that wait in a +client's offline queue for more than three days are discarded when they arrive. + +Deleting stacks or resetting a project's data doesn't give back events already counted for the month. + +## Deduplication {#deduplication} + +When the same error happens many times in a few seconds, such as an exception thrown in a loop, the clients merge the +repeats into one event with a count: + +1. The first occurrence is sent right away. +2. Identical occurrences within the window are held and counted instead of being sent. +3. When the window ends, the client sends one event with the total in its `count` field and the date of the latest + occurrence. + +The merged event counts once against your plan, and the event counts in the app include its full `count`. + +| | .NET client | JavaScript client | +| ------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| Events deduplicated | All types | Errors only | +| Identical means | Same type, source, message, tags, value, and data, such as the error and request details | Same error messages and stack traces, including inner errors | +| Window | 60 seconds | 30 seconds | + +Each client remembers the last 50 events it sent. Deduplication is done by the `DuplicateCheckerPlugin` in both clients. +To turn it off, remove the plugin: `RemovePlugin()` on the .NET configuration, or +`removePlugin("DuplicateCheckerPlugin")` on the JavaScript configuration. + +The server also discards an event whose [reference ID](/docs/references-ids/) was already used in the same project in +the last day, so a client that retries a submission doesn't store the event twice. + +## Bursts + +Deduplication and throttling together handle most bursts. When an outage throws thousands of errors a minute: + +- Identical errors from one process are merged by the client. +- The same error from many processes or servers isn't merged, because each client deduplicates on its own, but it still + goes into one [stack](/docs/concepts/stacking/), so it's easy to review. +- Throttling stops the burst from using the rest of the month's events. +- The client pauses after a `402`, so your app doesn't keep sending events that will be rejected. + +To keep a known noisy error from counting at all, mark its stack **Discarded**. See [Stacks](/docs/managing-stacks/). + +### Bots and spam {#bots-and-spam} + +Two project settings deal with traffic from crawlers and attackers, such as a scanner that causes hundreds of 404s. Find +them on the project's **Settings** page under **Spam Detection**: + +- A list of user agents to ignore. The clients drop events from requests with a matching user agent before sending them. +- **Reduce noise by automatically hiding high volumes of events coming from a single client IP address.** When a single + public IP address causes 25 or more events within a five-minute window, the server discards them and removes the + events already stored from that address in that window. This needs IP addresses, so it has no effect when the project + removes user identifiable information. + +See [Projects](/docs/project-settings/) for both settings. + +## Self-hosted limits + +On a self-hosted instance without billing, new organizations get an unlimited plan: no event limit, unlimited projects +and users, and retention up to the instance's maximum (180 days by default). The request rate, request size, bot +threshold, and maximum retention are settings; see [Configuration](/docs/self-hosting/configuration/). diff --git a/docs/docs/concepts/stacking.md b/docs/docs/concepts/stacking.md new file mode 100644 index 0000000000..6851ce3129 --- /dev/null +++ b/docs/docs/concepts/stacking.md @@ -0,0 +1,176 @@ +--- +title: "Stacking" +description: "How Exceptionless groups events into stacks: the signature for each event type, the project's stacking settings, and manual stacking keys." +redirectFrom: + - from: /docs/manual-stacking/ + anchor: manual-stacking +sources: + - src/Exceptionless.Core/Pipeline/010_AssignToStackAction.cs + - src/Exceptionless.Core/Utility/ErrorSignature.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/03_ManualStackingPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/10_NotFoundPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/15_SourceMapPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/20_ErrorPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/30_SimpleErrorPlugin.cs + - src/Exceptionless.Core/Plugins/Formatting/Default/05_ManualStackingFormattingPlugin.cs + - src/Exceptionless.Core/Extensions/MethodExtensions.cs + - src/Exceptionless.Core/Models/Data/ManualStackingInfo.cs + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/settings/+page.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/stack-options-dropdown-menu.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/dialogs/stacking-information-dialog.svelte + - Exceptionless.Net:src/Exceptionless/Extensions/EventBuilderExtensions.cs + - Exceptionless.Net:src/Exceptionless/Extensions/EventExtensions.cs + - Exceptionless.JavaScript:packages/core/src/EventBuilder.ts +--- + +# Stacking + +Exceptionless groups events that have the same cause into a stack, so a thousand occurrences of one bug show up as one +item with a count. This page explains how events are grouped, what you can change, and how to group events yourself. + +## How a stack is chosen + +When an event arrives, Exceptionless builds a set of named values that describe its cause, called the signature. It +hashes those values and looks for a stack in the same project with the same hash. If there is one, the event joins it. +If not, a new stack is created, and the event is its first occurrence. + +A few things follow from this: + +- Stacks belong to a project. The same error in two projects makes two stacks. +- The environment, version, tags, and user are not part of the signature. The same error in staging and production lands + in one stack; filter by [environment](/docs/environments/) to tell them apart. +- The signature is set when the event is processed. Changing a stacking setting affects new events only; existing events + stay in the stacks they joined, and a change can start new stacks for errors you already have. +- The stack title comes from the event that created the stack. + +## Signatures by event type + +| Event type | Signature values | +| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Error with a stack trace | `ExceptionType` and `Method`: the exception type and the method where it was thrown in your code. Also `Number` or `ErrorCode` when the error carries one, such as a SQL error number. | +| Simple error | `ExceptionType`, and `StackTrace` (a hash of the stack trace text). Custom clients send these as `@simple_error`. | +| Log (`log`) | `Type` and `Source`. The message is not included, so every message from one source, such as a logger category, goes to the same stack. | +| Feature usage (`usage`) | `Type` and `Source`, where the source is the feature name. | +| Not found (`404`) | `Type` and `Source`, where the source is the resource or request path, such as `GET /missing-page`. | +| Any other type | `Type` and `Source`. | +| Any event with a stacking key | Only the [manual stacking](#manual-stacking) values. Nothing else is used, not even the type. | + +### How the method of an error is found + +For errors, Exceptionless looks for the method in your code that threw. It starts at the innermost exception and walks +out through the inner exceptions, reading each stack trace from the top. The first frame that counts as your code is the +stacking target: + +- If the project has **User Namespaces** set, a frame is your code when its namespace starts with one of them. +- Otherwise, any frame whose namespace doesn't start with `System` or `Microsoft` is your code. A frame with no + namespace, as in most JavaScript stack traces, also counts. +- Frames whose method signature contains one of the project's **Common Methods** are skipped. + +When no frame qualifies, Exceptionless uses the innermost exception's target method, then its top stack frame, and +finally the exception type alone. + +The method value is the full method signature: namespace, type, method name, generic arguments, and parameter types. It +has no line numbers, so editing the body of a method keeps its errors in the same stack. Renaming the method or changing +its parameters starts a new one. The error message isn't part of the signature, so one exception type thrown from one +method with different messages is a single stack. + +For JavaScript errors, [source maps](/docs/clients/javascript/source-maps/) are applied before the signature is built, +so stacks use your original function names or, for anonymous functions, the original file, line, and column. A new build +with different minified names doesn't start new stacks. + +## Stacking settings + +Each project has two settings that change how errors are stacked. Open the project's **Settings** page under **Project +Settings** and find **Error Stacking**: + +- **User Namespaces**: a comma-delimited list of the namespaces your code belongs to, such as `Contoso`. When set, only + methods in these namespaces can be stacking targets. Set it when library or framework frames, which would otherwise + count as your code, are becoming the stacking target. +- **Common Methods**: a comma-delimited list of method names that should never be stacking targets, such as `Assert` or + `ThrowIfInvalid`. Use it for shared helpers that throw on behalf of their callers, so errors stack by the code that + called the helper instead of all landing in one stack. When the setting is empty, `DataContext.SubmitChanges` and + `Entities.SaveChanges` are skipped; setting a value replaces those defaults. + +See [Projects](/docs/project-settings/) for the rest of the project settings. + +## See why events were grouped + +To see the values that grouped a stack, open the stack, click the **Stack options** gear button next to the status +button, and choose **View Stacking Information**. + +![The Stack Options menu with View Stacking Information](/assets/img/docs/managing-stacks-options-menu-light.webp) + +The **Stacking Information** dialog lists each signature value, such as `ExceptionType` and `Method` for an error, +`Type` and `Source` for a log, or your own key for a manually stacked event. + +## Manual stacking {#manual-stacking} + +Set a manual stacking key when you want to choose the grouping yourself. Every event in a project with the same key goes +to the same stack, regardless of its type, message, or stack trace. Some uses: + +- Keep all errors from a new or critical feature in one stack, so you can watch them and set + [notifications](/docs/notifications/) on it. +- Split log messages that share a source into separate stacks. +- Group events that Exceptionless would put in different stacks, such as the same failure thrown from several places. + +You can also give the stack a title. The title is used when the stack is created; otherwise the stack gets its usual +title. + +```csharp tab=".NET" +using Exceptionless; + +try { + throw new ApplicationException("Unable to create order from quote."); +} catch (Exception ex) { + ex.ToExceptionless() + .SetManualStackingKey("Order creation", "order-creation") + .Submit(); +} +``` + +```ts tab="JavaScript" +import { Exceptionless } from "@exceptionless/browser" // or "@exceptionless/node" + +try { + throw new Error("Unable to create order from quote.") +} catch (error) { + await Exceptionless.createException(error) + .setManualStackingKey("order-creation", "Order creation") + .submit() +} +``` + +```bash tab="curl" +curl -X POST https://api.exceptionless.io/api/v2/events \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "type": "error", + "message": "Unable to create order from quote.", + "@simple_error": { + "message": "Unable to create order from quote.", + "type": "System.ApplicationException", + "stack_trace": " at Orders.QuoteService.CreateOrder()" + }, + "@stack": { + "title": "Order creation", + "signature_data": { "ManualStackingKey": "order-creation" } + } + }' +``` + +The title is optional. Note the argument order: in .NET it's `SetManualStackingKey(title, key)` or +`SetManualStackingKey(key)`, and in JavaScript it's `setManualStackingKey(key, title?)`. + +To group by more than one value, pass a dictionary of values instead: `SetManualStackingInfo` in .NET and +`setManualStackingInfo` in JavaScript. Over HTTP, put any keys you like in `signature_data` under the `@stack` data key. +You can also set the key from a client plugin for every event that matches a condition; see +[.NET plugins](/docs/clients/dotnet/plugins/). + +Manual stacking replaces the automatic signature, so the stacking settings above don't apply to these events. + +## Related pages + +- [Stacks](/docs/managing-stacks/): fix, snooze, ignore, discard, and delete stacks. +- [Releases and regressions](/docs/versioning/): what happens when a fixed stack gets a new event. +- [Event format](/docs/reference/event-format/): the `@error`, `@simple_error`, and `@stack` data keys. diff --git a/docs/docs/deduplication.md b/docs/docs/deduplication.md deleted file mode 100644 index c1f999459e..0000000000 --- a/docs/docs/deduplication.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Event De-Duplication" -description: "Learn how Exceptionless de-duplicates identical events within a minute, holding repeats for 60 seconds and counting them so floods do not use up plan limits." ---- - -# Event De-Duplication - -Have you ever run into an error where the event that triggers the error happens rapidly in a short amount of time? Infinite loops combined with errors? Ugh. If that happens, we don't think you should have to worry about your event quotas and plan limits. - -That's why we built automatic de-duplication. - -If we get two events that are exactly the same within a minute, we send the first, cancel the second and hold onto it for 60 seconds. If that same exact event comes in again, we cancel it and increment the count on the one we were holding. Once 60 seconds is released we submit that event and now you get a sampling of events during that period with the exact account that occurred. We only do this if the event is an exactly the same minus date occurred. - ---- - -[Next > Integrations](/docs/integrations) diff --git a/docs/docs/demo-formatting.md b/docs/docs/demo-formatting.md index 7c551ab2a9..7afce48722 100644 --- a/docs/docs/demo-formatting.md +++ b/docs/docs/demo-formatting.md @@ -1,74 +1,66 @@ --- -title: "Markdown Formatting Demo" -description: "Internal demo of the Markdown formatting available in Exceptionless docs and blog posts: footnotes, anchors, attributes, spans, alerts, and tables." +title: "Markdown formatting demo" +description: "Source-only demo of the Markdown features available in Exceptionless docs: heading ids, callouts, prompts, tabs, and client blocks." hidden: true url: false --- -# Markdown Formatting Demo +# Markdown formatting demo -Shows all the different markdown formatting options available for writing docs and blog posts +This page is not published and is not in the docs nav. It shows the syntax the docs build supports; `docs/STYLE.md` has +the rules for using it. To see it rendered, temporarily remove `hidden` and `url: false`, add the page to +`_data/docs_nav.yml`, and run `deno task serve`. -General markdown-it formatting: +## Heading ids {#heading-ids} -- [Footnote](#footnote) -- [Anchor Links](#anchor-links) -- [Attrs {.text-center}](#attrs-text-center) -- [Bracketed Spans](#bracketed-spans) -- [Alerts](#alerts) -- [Abbreviations](#abbreviations) -- [Tables](#tables) +An explicit `{#id}` suffix sets the heading's id and is removed from the title. Other headings get an id from their +text. -## Footnote +## Callouts - +> [!NOTE] +> Self-hosted instances use your own API URL instead. -Here is a footnote reference,[^1] and another.[^longnote] +> [!TIP] +> Use sparingly. -[^1]: Here is the footnote. +> [!IMPORTANT] +> Something the reader must not miss. -[^longnote]: Here's one with multiple blocks. +> [!WARNING] +> Something that can lose data. - Subsequent paragraphs are indented to show that they belong to the previous footnote. +## Prompts -## Anchor Links +```prompt exie +Which new stacks appeared in production since yesterday's deploy? +``` - +```prompt agent +Find the most frequent new error in my Exceptionless project, fix it, and mark the stack fixed in the next version. +``` -[Link to footnote section](#footnote) +## Tabs -## Attrs {.text-center} +Adjacent code blocks with a `tab` label form one tab set. Choosing a label switches every tab set on the page that has +the same label. - +```csharp tab=".NET" +ExceptionlessClient.Default.SubmitLog("Order placed"); +``` -paragraph {.text-center} +```ts tab="JavaScript" +await Exceptionless.submitLog("Order placed") +``` -## Bracketed Spans +## Clients - +An empty `clients` block shows each client's install command and setup snippet from `_data/clients.json`. -paragraph with [a warning span]{.text-warning} +```clients +``` -## Alerts +A `clients features` block shows the feature matrix. - - -::: danger Danger danger danger! [Link](#). ::: - -::: info Information information information! [Link](#). ::: - -::: success Success success success! [Link](#). ::: - -## Abbreviations - - - -*[HTML]: Hyper Text Markup Language *[W3C]: World Wide Web Consortium The HTML specification is maintained by the W3C. - -## Tables - -| Feature | Exceptionless | Application Insights | Elmah | Raygun | -| :--------------------- | :-----------: | :------------------: | :---: | :----: | -| Open Source | X | | X | | -| Free Self Hosting | X | | X | | -| Detailed error reports | X | X | | X | +```clients features +``` diff --git a/docs/docs/environments.md b/docs/docs/environments.md index fc1e066a9a..5b65dd48d5 100644 --- a/docs/docs/environments.md +++ b/docs/docs/environments.md @@ -1,73 +1,151 @@ --- title: "Environments" +description: "Tag Exceptionless events with a deployment environment such as production or staging, then filter and compare every list by environment." +sources: + - src/Exceptionless.Core/Models/Event.cs + - src/Exceptionless.Core/Serialization/EventEnvironmentConverter.cs + - src/Exceptionless.Web/Api/Handlers/EventHandler.cs + - src/Exceptionless.Web/Api/Endpoints/EventEndpoints.cs + - src/Exceptionless.Core/Repositories/Configuration/Indexes/EventIndex.cs + - src/Exceptionless.Core/Repositories/Queries/Validation/PersistentEventQueryValidator.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/70_SessionPlugin.cs + - src/Exceptionless.Core/Migrations/010_AddEventEnvironment.cs + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/filters/environment-faceted-filter.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/filters/models.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/views/overview.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/table/options.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/sessions/components/session-table-columns.ts + - tests/http/events.http + - Exceptionless.Net:src/Exceptionless/Models/Client/Event.cs + - Exceptionless.JavaScript:packages/core/src/models/Event.ts --- # Environments -Use an environment to distinguish production, staging, development, or a custom deployment within one project. Each event can carry one optional top-level `environment` string. The same error still belongs to one stack, with one shared status and fixed version. +An environment names the deployment an event came from, such as `production`, `staging`, or `development`. With +environments, one project can hold every deployment of an app, and you can filter any list down to one of them. -## Configure your client +Each event has at most one environment. The same error in staging and production is still one stack, with one status and +one fixed version. -Set a default during application startup. In the .NET client: +## Set an event's environment -```csharp -client.Configuration.SetEnvironment("production"); -client.CreateLog("Deployment complete").SetEnvironment("staging").Submit(); +An event gets an environment from the `environment` property at the top level of the event: + +```bash tab="POST" +curl -X POST "https://api.exceptionless.io/api/v2/events" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "type": "log", + "message": "Deployment complete", + "environment": "production" + }' ``` -You can also set `Exceptionless:Environment` in .NET configuration, or the `Exceptionless__Environment` environment variable. The hosting integration uses `IHostEnvironment.EnvironmentName` when no explicit environment is configured. A per-event value overrides the default. +```bash tab="GET" +curl "https://api.exceptionless.io/api/v2/events/submit?access_token=YOUR_API_KEY&type=log&message=Deployment+complete&environment=production" +``` -In the JavaScript client: +The `POST` body can also be an array of events, each with its own environment. See +[Posting events](/docs/api/posting-events/) and the [event format](/docs/reference/event-format/). -```javascript -await Exceptionless.startup((config) => { - config.apiKey = "API_KEY_HERE"; - config.environment = "production"; -}); +> [!IMPORTANT] +> The current .NET (6.2.0) and JavaScript (3.2.1) clients don't set an environment yet, so their events show as +> **Unspecified**. Setting a custom data property named `environment`, for example with `SetProperty` or `setProperty`, +> adds custom data and doesn't set the event's environment. -await Exceptionless.createLog("Deployment complete") - .setEnvironment("staging") - .submit(); -``` +> [!NOTE] +> On a self-hosted instance, use your own API URL instead of `https://api.exceptionless.io`. -For direct API submissions: +### Naming rules -```json -{ - "type": "log", - "message": "Deployment complete", - "environment": "production" -} -``` +- Leading and trailing spaces are trimmed, and the name keeps its casing: `" Production "` is stored as `Production`. +- Names can be up to 64 characters. Custom names such as `qa-west` are fine. +- Filters ignore case, so `Production` and `production` are the same environment. +- A value that isn't a valid name, such as an empty string, a number, an object, or a name over 64 characters, leaves + the event unspecified. The value is kept in the event's custom data under `environment` instead, or `environment1` if + that key is already taken. + +### Environment isn't machine information + +The **Machine & runtime** tab of an event shows details the client collects about the machine and process, such as the +machine name, OS, and runtime version. Those aren't the deployment environment and don't set it. + +## Filter by environment + +On **Stacks**, **Events**, or **Sessions**, select **Manage filters** > **Environment** and pick one or more names. +**Unspecified** matches events without an environment. To filter by a name that hasn't sent events in the time range, +type it and select **Use** _name_. + +Save the filter in a [saved view](/docs/saved-views/), such as "Production errors", so you don't set it each time. In a +raw filter or the API, use these queries: + +| Query | Finds | +| ------------------------------------------------- | ----------------------------- | +| `environment:production` | Production events | +| `(environment:production OR environment:staging)` | Either environment | +| `_missing_:environment` | Events without an environment | +| `_exists_:environment` | Events with an environment | +| `environment:"qa west"` | A name with a space in it | -Names are trimmed, with a maximum of 64 characters. Events preserve the supplied casing: `" Production "` is stored and returned as `"Production"`. Filtering is case-insensitive, and aggregation keys are normalized to lowercase, so `Production` and `production` share one environment bucket. Custom names such as `qa-west` are supported. Empty, oversized, control-character, and non-string values are treated as unspecified. Historical events and older clients without this field remain unspecified; they are never assumed to be production. +Environment filters work on every plan. See the [search syntax](/docs/reference/search-syntax/). -## Filter your data +## Where environments appear -Choose **Manage filters → Environment** on Events, Stacks, Sessions, or Stream. Select one or more names, or **Unspecified** for events without an environment. Clear the selection to include all environments. The picker discovers names for the selected projects and time range; you can also enter a name that has no current events. +- **Event details**: the **Overview** tab shows **Environment** when the event has one. Select the filter icon next to + it to filter the list by that environment. +- **Columns**: the **Events** and **Sessions** lists have an **Environment** column, hidden by default. Add it with + **View** > **Manage Columns...**. Events without an environment show **Unspecified**. +- **Stack lists**: there's no environment column, because a stack can span environments. With an environment filter, the + event and user counts in the list include only that environment's events. -Environment selections persist in URLs and saved views. Events, sessions, and stream tables have an optional Environment column. Event details show Environment in the overview when the event has one; **Machine & runtime** contains the existing `data.@environment` diagnostics. +## Stacks and statuses across environments -Environment searches and aggregations are available on every plan: +Environments don't split stacks, so a stack's status is shared. Marking a stack fixed while you look at production also +marks it fixed in staging. -| Search | Meaning | -| --- | --- | -| `environment:production` | Production events | -| `(environment:production OR environment:staging)` | Either deployment | -| `_missing_:environment` | Historical or unspecified events | -| `_exists_:environment` | Events with an environment | -| `environment:"qa west"` | A custom name containing spaces | +When environments run different releases, mark stacks fixed in a version. If a stack is fixed in `2.4.0` and staging +already runs it, events from production on `2.3.0` don't reopen the stack. Continue sending your app's version with +every event so this works. See [Releases and regressions](/docs/versioning/). -Stack dashboard counts and charts use events matching the filter. Stack status remains shared, so changing status while viewing production also changes the same stack seen in staging. Automatic session detection separates the same user's activity by environment. Session heartbeats do not include an environment, so a heartbeat keeps the user's open sessions active in every environment. +Some features don't look at environments yet: -Notifications and the **New** view are not environment-aware yet. A stack is new once, when its first event arrives from any environment. An error first seen in development triggers the new error notification then, and is not reported as new again when it reaches production; the **New** view also dates it from that first occurrence. Critical error and regression notifications are sent for events from every environment. +- A stack is new once, when its first event arrives from any environment. An error first seen in development triggers + the new error notification then, and isn't new again when it reaches production. **New Stacks** counts work the same + way. +- Critical error and regression notifications are sent for events from every environment. -## Fixing stacks across deployments +## Sessions -Use [fixed in version](/docs/versioning/) when environments run different releases. For example, if a stack is fixed in `2.4.0`, occurrences from production running `2.3.0` do not represent a regression just because staging already has the fix. Continue sending the application version with events. Plain **Fixed**, without a version, retains its existing behavior across all environments. +When Exceptionless builds sessions from a user's events, it keeps each environment's sessions apart. Session heartbeats +don't carry an environment, so a heartbeat keeps the user's open sessions active in every environment. See +[Sessions](/docs/user-sessions/). -## Rollout +## Self-hosting -Deploy the server before adopting SDK versions that expose the new setting. The server adds mappings to existing event indices without rewriting historical events. Self-hosted installs should let the migration job finish before the new API and job instances process events: events written to an existing index before the mapping is added keep their environment but cannot be filtered or aggregated by it. Clients that do not send an environment continue to work. `data.@environment` and custom `data.environment` values retain their existing meanings. +The 9.0 upgrade adds the environment field to existing event indexes without reindexing. Let the migration job finish +before the new API and job instances process events. Events stored in an existing index before the migration ran keep +their environment, but you can't filter or count them by it. See +[Upgrading](/docs/self-hosting/upgrading-self-hosted-instance/). -Before this release, the server stored an unrecognized root `environment` property as custom data in `data.environment`. A valid root `environment` string is now stored only as the event's environment, trimmed, so read it from `environment` instead of `data.environment`. Any other root value, such as null, an object, a number, a blank string, or an oversized name, is still stored as `data.environment`. If `data.environment` already exists, that value uses the next available key (`environment1`, `environment2`, and so on). +## Ask Exie + +```prompt exie +Which environments had the most errors in the last 7 days? +``` + +```prompt exie +What are the top errors in production since yesterday? +``` + +```prompt exie +Is the checkout timeout happening in staging as well as production? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can compare environments while it works: + +```prompt agent +Using Exceptionless, list the errors that occur in staging but not in production over the last 7 days, and check +whether any of them come from code changed on this branch. +``` diff --git a/docs/docs/events.md b/docs/docs/events.md new file mode 100644 index 0000000000..514abab2fd --- /dev/null +++ b/docs/docs/events.md @@ -0,0 +1,165 @@ +--- +title: "Events" +metaTitle: "Viewing events in Exceptionless" +description: "Browse Exceptionless events, read every tab of the event details, watch lists update live, and find an event by its reference ID." +sources: + - src/Exceptionless.Web/ClientApp/src/routes/(app)/event/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/stream/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/event/by-ref/[referenceId]/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/+layout.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/api.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/events-overview.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/events-stats-dashboard.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/extended-data-item.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/views/overview.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/views/error.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/views/environment.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/views/request.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/views/session-events.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/table/options.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/events/persistent-event.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/shared/components/detail-sheet.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/shared/components/streaming-indicator-button.svelte + - src/Exceptionless.Core/Repositories/EventRepository.cs + - src/Exceptionless.Core/Seed/predefined-saved-views.json + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs +--- + +# Events + +An event is one thing that happened in your app: an error, a log message, a feature being used, a 404, or a session. +This page shows how to browse events, what each part of an event's details means, and how to find a specific event. + +## Browse events + +Open **Events** in the sidebar and pick a view: + +- **All**: every event in the last 7 days. +- **Errors**: error events from open and regressed stacks. +- **Logs**: log messages from open and regressed stacks. + +The view starts with stat boxes and a chart for the time range: + +- **Events**: total occurrences that match the filters. +- **Stacks**: how many stacks those events belong to. +- **New Stacks**: stacks whose first occurrence is in the time range. +- **Events/hr**: average occurrences per hour. + +Drag across the chart to zoom into a time range. Turn the stat boxes and chart off under **View** > **Display**. + +The list shows **Summary**, **User**, and **Date** by default. Add **Project**, **Tags**, **Message**, **Type**, +**Environment**, **Version**, **Exception Type**, **Source**, **Name**, or **Level** with **View** > **Manage +Columns...**. See [Saved views](/docs/saved-views/) to keep your columns, and +[Filtering and searching](/docs/filtering-and-searching/) to narrow the list. + +The **Stacks** lists work the same way, with one row per stack instead of one per event. See +[Stacks](/docs/managing-stacks/). + +## Live updates + +Lists update on their own. When new events arrive or a stack changes, the open list, stat boxes, and chart refresh +within a few seconds, without reloading the page. Select **Refresh results** to refresh right away. + +To watch events arrive as they happen, open the **Event Stream** page at `/stream` in the app, for example +`https://be.exceptionless.io/stream`. It loads new events as they arrive. Select **Pause streaming updates** to stop the +list from changing while you read it, and **Resume streaming updates** to continue. + +## Open an event + +Select an event to open its details in a side panel. The panel header has a copy icon (**Copy event link**) and **Open +in new window**, which opens the event's own page. + +The panel has two parts. + +### Stack + +The stack card at the top shows the stack the event belongs to: its status, totals, users affected, first and last +occurrence, and a 7-day chart. You can change the stack's status and options right there. See +[Stacks](/docs/managing-stacks/). + +When Exie is available, **Fix** on the card asks [Exie](/docs/ai/exie/) for the likely root cause and next steps. + +### Event + +Above the tabs, **Occurred On** shows when the event happened. The buttons next to the **Event** heading are: + +- **View Event JSON**: the raw event, with **Copy to Clipboard**. +- **Show all events**: filters the list behind the panel to this stack's events. +- **Older event** and **Newer event**: step through the other occurrences in the same stack. + +## Event tabs + +An event shows only the tabs it has data for. + +| Tab | What it shows | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Overview** | The key facts: environment, reference ID, level, type, error type, source, value, message, version, location, tags, URL, user, and the stack trace. | +| **Exception** | Error type, message, code, and submission method; the full stack trace, including inner exceptions; additional error data; and loaded modules. | +| **Machine & runtime** | Machine name, IP address, OS name and version, architecture, processor count, memory, process name and ID, command line, and runtime version. | +| **Request** | HTTP method, URL, referrer, client IP address, user agent, device, browser, browser OS, post data, headers, cookie values, and additional request data. | +| **Trace Log** | The log messages the client recorded before the event. | +| **Session Events** | The other events in the same user session, with the session's duration. Sessions need a paid plan. | +| **Extended Data** | Your custom data, one section per key. | + +On the **Overview** tab: + +- Select the filter icon next to a value, such as the type, source, version, environment, or user, to filter the list by + it. Select a tag to filter by that tag. +- Select the reference ID to open the events that share it. +- **User Info** shows the user's email, identity, name, and any description they submitted. +- For errors, the stack trace has **Copy Stack Trace to Clipboard**. For JavaScript errors, it can also show whether a + [source map](/docs/clients/javascript/source-maps/) was applied. + +### Custom data tabs + +Each key in the **Extended Data** tab has an options menu with: + +- **Toggle View**: switch between a structured view and the raw value. +- **Copy to Clipboard**. +- **Promote to Tab**: show this key as its own tab on every event in the project that has it. + +On a promoted tab, the options menu has **Demote Tab**, which moves the key back to **Extended Data**. Drag promoted +tabs to reorder them. Promoted tabs are saved for the project, so everyone sees the same tabs. + +To send custom data, see the sending events page for [.NET](/docs/clients/dotnet/sending-events/) or +[JavaScript](/docs/clients/javascript/sending-events/). + +## Find an event by reference ID + +A reference ID is an ID your app assigns to an event, so a user or support agent can quote it later. See +[Reference IDs](/docs/references-ids/) to set one up. To find the event: + +- Go to `https://be.exceptionless.io/event/by-ref/YOUR_REFERENCE_ID`. If one event has that reference ID, it opens. If + several do, the **Event Reference** page lists them, with **View In Events** to see them in a list. +- Or add a **Reference** filter to any event list and enter the ID. In a raw filter, use `reference:YOUR_REFERENCE_ID`. + +> [!NOTE] +> On a self-hosted instance, use your own app URL instead of `https://be.exceptionless.io`. + +## Delete events + +Select events in a list, then open **Actions** and select **Delete**. To delete every event in a stack, delete the stack +instead. See [Bulk actions](/docs/managing-stacks/#bulk-actions). + +## Ask Exie + +Open an event and ask about it. Exie uses the event you're viewing as context: + +```prompt exie +Explain this error and suggest a fix. +``` + +```prompt exie +Which errors did jane@example.com run into in the last 7 days? +``` + +```prompt exie +How many events came in per hour today, and which stack caused the spike? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can read an event's stack trace and request +details and work on the fix in your code: + +```prompt agent +Get Exceptionless event 54dbc16ca0f5c61398427b00, find the code in this repository that threw it, and propose a fix. +``` diff --git a/docs/docs/feature-usage.md b/docs/docs/feature-usage.md new file mode 100644 index 0000000000..61bcc3038a --- /dev/null +++ b/docs/docs/feature-usage.md @@ -0,0 +1,98 @@ +--- +title: "Feature usage" +description: "Count how often each feature of your app is used, and by how many users, with Exceptionless feature usage events and the Most Used Features view." +sources: + - src/Exceptionless.Core/Pipeline/010_AssignToStackAction.cs + - src/Exceptionless.Core/Plugins/Formatting/Default/40_UsageFormattingPlugin.cs + - src/Exceptionless.Core/Seed/predefined-saved-views.json + - src/Exceptionless.Web/ClientApp/src/lib/features/events/options.ts + - Exceptionless.Net:src/Exceptionless/Extensions/ExceptionlessClientExtensions.cs + - Exceptionless.Net:src/Exceptionless/Models/Collections/SettingsDictionary.cs + - Exceptionless.Net:samples/Exceptionless.SampleConsole/Program.cs + - Exceptionless.JavaScript:packages/core/src/ExceptionlessClient.ts + - Exceptionless.JavaScript:packages/core/src/plugins/default/EventExclusionPlugin.ts +--- + +# Feature usage + +Feature usage events count how often the features of your app are used and by how many users. Send one each time someone +uses a feature you care about, such as exporting a report or starting a checkout, and Exceptionless ranks your features +by use. + +## Send feature usage + +A feature usage event has the type `usage`, and its source is the feature's name: + +```csharp tab=".NET" +using Exceptionless; + +ExceptionlessClient.Default.SubmitFeatureUsage("Export Report"); +``` + +```ts tab="JavaScript" +import { Exceptionless } from "@exceptionless/browser" + +await Exceptionless.submitFeatureUsage("Export Report") +``` + +```bash tab="curl" +curl -X POST "https://api.exceptionless.io/api/v2/events" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ "type": "usage", "source": "Export Report" }' +``` + +To attach the user, tags, or custom data, build the event with `CreateFeatureUsage` (.NET) or `createFeatureUsage` +(JavaScript) and submit it. See the sending events page for [.NET](/docs/clients/dotnet/sending-events/) or +[JavaScript](/docs/clients/javascript/sending-events/). + +Use the same name every time for the same feature. Each feature name becomes one stack, so `Export Report` and +`export-report` are counted as two features. + +## See which features are used most + +Open **Stacks** > **Most Used Features**. It lists one stack per feature for the last 7 days, with the most used first. +The **Events** column is how many times the feature was used, and **Users** is the share of users who used it. Change +the **Date** filter to look at another period. + +Select a feature's stack to see its usage over the last 7 days, and step through the individual events to see who used +it and when. + +To list the individual events instead, add a **Type** filter set to **Feature Usage** on an **Events** view, or use +`type:usage` in a raw filter. Save either as a [saved view](/docs/saved-views/) to keep it. + +> [!TIP] +> **Most Used Features**, like the other built-in views, shows only open and regressed stacks. Don't mark feature usage +> stacks fixed, ignored, or snoozed if you want to keep counting them there. + +## Stop counting a feature + +To stop collecting a feature's events, open its stack and choose **Discarded**. New events for it are dropped and don't +count against your plan. + +The .NET and JavaScript clients can also skip a feature before sending it. Add the client configuration value `@@usage:` +followed by the feature name, such as `@@usage:Export Report`, with the value `false`, on the project's +**Configuration** tab. A `*` wildcard works too, as in `@@usage:Admin*`. See +[Projects](/docs/project-settings/#client-configuration). + +## Ask Exie + +```prompt exie +Which features were used most in the last 30 days? +``` + +```prompt exie +How many times was Export Report used each day this month? +``` + +```prompt exie +Which users used Export Report most this week? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can use feature usage while it works on a +feature: + +```prompt agent +Look up the Exceptionless feature usage for "Export Report" over the last 30 days, then add feature usage tracking for +the other export options in this repository using the same naming style. +``` diff --git a/docs/docs/filtering-and-searching.md b/docs/docs/filtering-and-searching.md index 8fbfe50a52..9b698e87b2 100644 --- a/docs/docs/filtering-and-searching.md +++ b/docs/docs/filtering-and-searching.md @@ -1,167 +1,175 @@ --- -title: "Filtering & Searching" +title: "Filtering and searching" metaTitle: "Filtering and searching events in Exceptionless" -description: "Search and filter Exceptionless events by fields like tag, type, level, version, or user, with AND/OR queries, wildcards, exclusions, and date ranges." +description: "Narrow any Exceptionless list with the filter bar: field filters, environments, raw filter queries, and the date range." +sources: + - src/Exceptionless.Web/ClientApp/src/lib/features/shared/components/faceted-filter/faceted-filter-builder.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/shared/components/faceted-filter/faceted-filter-keyword.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/shared/components/faceted-filter/faceted-filter-actions.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/filters/organization-defaults-faceted-filter-builder.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/filters/models.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/filters/environment-faceted-filter.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/filters/date-faceted-filter.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/shared/components/date-range-picker/date-range-picker.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/events-dashboard-chart.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/views/overview.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/premium-filter.ts + - src/Exceptionless.Core/Seed/predefined-saved-views.json --- -# Filtering & Searching +# Filtering and searching -- [Views](#views) -- [Filter by Time Frame](#filter-by-time-frame) -- [Filter by Environment](#filter-by-environment) -- [Add Filters](#add-filters) -- [Search with a Raw Filter](#search-with-a-raw-filter) -- [Save a View](#save-a-view) -- [Searchable Fields & Requirements](#searchable-fields--requirements) -- [Multiple Queries](#multiple-queries) -- [Wild Cards](#wild-cards) -- [Exclusions](#exclusions) -- [Set and Unset Fields](#set-and-unset-fields) -- [Ranges](#ranges) -- [Custom Extended Data](#custom-extended-data) +Every list in Exceptionless, such as **Stacks**, **Events**, and **Sessions**, has a filter bar. Use it to narrow the +list by project, status, type, environment, tag, or any other field, and to set the time range. The filters belong to +the [saved view](/docs/saved-views/) you're looking at; there's no global filter that follows you between pages. -## Views +![Stacks list filtered by project, tag, and date range](/assets/img/docs/filtering-and-searching-filtered-view-light.webp) -Every list in Exceptionless is a view, and each view owns its filters. There is no global project or time filter. Pick a view from the sidebar under **Stacks**, **Events**, or **Sessions**, for example **Stacks > All**, **Stacks > Most Frequent Errors**, or **Events > Errors**. +The filter bar sits next to the view's name. Each filter is a button that shows its field and value. Changes apply right +away, and the address bar updates so you can share a link to exactly what you see. -The filter bar at the top of the view shows the view name, the date range, and any filters that are applied. Changing a filter only changes the view you are looking at. +## Add a filter -![Stacks view filtered by project, tag, and date range](/assets/img/docs/filtering-and-searching-filtered-view-light.webp) +1. Select **Manage filters** (the **Filter** button when the view has no filters yet). +2. Type to find a field, then select it. +3. Pick or enter a value. Text filters apply when you press Enter; Escape cancels. -## Filter by Time Frame +![Add filter menu listing the fields you can filter by](/assets/img/docs/filtering-and-searching-add-filter-light.webp) -Click the **Date** filter to change the time frame. Pick a preset, such as **Last 24 hours** or **Last 7 days**, or expand **Custom range** and enter a start and end. Custom values accept a year (`2024`), month (`2024-01`), day (`2024-01-01`), a timestamp, or a relative time such as `now-1h`. Click **Apply** to use the custom range. +The most common filters are **Project**, **Status**, **Type**, **Environment**, **Tag**, **Log Level**, **Message**, +**User**, and **Version**. You can also filter by **Source**, **Error Type**, **Error Code**, **Browser**, **OS**, +**Device**, **Machine Name**, **Ip Address**, **Http Path**, **Country**, **Reference**, **Session**, **First +Occurrence**, **Is Bot**, **Value**, **Count**, and more. -You can also drag across the chart to zoom into a time range. +Selecting more than one value in a filter, such as two statuses, matches either value. Different filters all have to +match. -![Date range picker with presets and a custom range](/assets/img/docs/filtering-and-searching-date-range-light.webp) +A text, number, date, or version filter with **No Value** matches items where that field isn't set. A **Project** filter +with no value includes every project. -## Filter by Environment +To change a filter, select its button. At the bottom of each filter: -Choose **Manage filters → Environment** to select production, staging, development, or a custom name. Select **Unspecified** for events without this property, or clear the selection to include all environments. See [Environments](/docs/environments/) for client configuration and shared stack behavior. +- **Clear value** empties it. +- **Hide filter** keeps it in effect but hides its button. **Show filter** brings it back. +- **Remove filter** removes it. -## Add Filters +## Filter from an event or stack -Click the **+** button next to the filters (it reads **Filter** when the view has none) to add a filter. Type in the search box to find a field, then pick it. Common choices are **Project**, **Status**, **Tag**, **Type**, **Log Level**, **Message**, **User**, and **Version**, and you can filter on many more fields, such as browser, OS, machine name, IP address, location, and error type. +You don't have to start from the filter bar. In an event's or stack's details, select the filter icon next to a value, +such as its type, source, version, environment, or user, to filter the list by it. Select a tag to filter by that tag, +and select **Open events for this stack** on a stack to list its events. See [Events](/docs/events/). -Each filter shows up as a button in the filter bar. Click it to change its value. The buttons at the bottom of a filter let you clear the value, hide the filter, or remove it. +## Hidden filters -![Add filter menu listing the fields you can filter by](/assets/img/docs/filtering-and-searching-add-filter-light.webp) +Views can include filters you don't see. The built-in views use them to keep the list focused: **Stacks** > **All** has +a hidden **Status** filter for open and regressed stacks, and **Events** > **Errors** hides its **Type** and **Status** +filters. -Some views include hidden filters. For example, **Stacks > All** has a hidden **Status** filter that only shows open and regressed stacks. The number on the **+** button is the count of hidden filters. Open the menu and click the eye icon to show them, or the eraser icon to clear all filters. +The number on **Manage filters** is the count of hidden filters. Open it and select the eye icon to show them, or the +eraser icon (**Clear all filters**) to remove every filter except the date range. -You can also add filters from an event or stack. Click the filter icon next to a value, such as the type, source, or version, or click a tag, to filter the view by it. +Selecting a field in **Manage filters** that the view already filters on, such as **Status**, opens that filter instead +of adding a second one, even when it's hidden. -## Search with a Raw Filter +## Filter by environment -To search with the query syntax described below, add a **Raw Filter**. Open the **+** menu and pick **Raw Filter**, or type your query in the menu's search box and choose **Create Raw Filter**. Press Enter to apply it, or Escape to cancel. The **?** button opens this page. +Select **Manage filters** > **Environment** and pick one or more names, such as `production` or `staging`. The list +shows the environments seen in the selected projects and time range. To filter by a name that hasn't sent events yet, +type it and select **Use** _name_. -![Raw filter with a query using OR and an exclusion](/assets/img/docs/filtering-and-searching-raw-filter-light.webp) +- **Unspecified** matches events that have no environment. +- With nothing selected, the filter reads **All environments**. -Raw filters are combined with the date range and the other filters in the view. +Environment names are matched without regard to case. See [Environments](/docs/environments/) for how events get an +environment. -You can also press `/` to open the command menu and search events and stacks from anywhere in the app. +## Search with a raw filter -## Save a View +A **Raw Filter** takes a query in the [search syntax](/docs/reference/search-syntax/), so you can use `OR`, exclusions, +ranges, wildcards, and custom data fields: -When you change a view's filters, a dot appears on the **View** button to show you have unsaved changes. Open the **View** menu to: +```text +(tag:Billing OR tag:Checkout) -bot:true +``` -- **Save** your changes to the current view. -- **Save As...** to create a new view. Give it a name and choose whether it is **Private** (only visible to you). The new view shows up in the sidebar. -- **Reset to Saved** to discard your changes. -- **Set as my home view** to open this view when you open Exceptionless. +Open **Manage filters** and select **Raw Filter**, or type your query in the menu's search box and select **Create Raw +Filter**. Press Enter to apply it or Escape to cancel. The help icon in the filter opens this +page. -![View menu with options to save, reset, and set a home view](/assets/img/docs/filtering-and-searching-save-view-light.webp) +![Raw filter with a query using OR and an exclusion](/assets/img/docs/filtering-and-searching-raw-filter-light.webp) -## Searchable Fields & Requirements +A raw filter is combined with the view's other filters, including hidden ones, and with the date range. -| TERM | EXAMPLE | FIELD REQUIRED? (field:term) | DESCRIPTION | -| ------------------ | -------------------------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------- | -| `*` | `*` | false | Matches everything. Status filters still apply | -| id | `id:54d8315ce6bb2d0500bcc7b4` | true | Documents id | -| organization | `organization:54d8315ce6bb2d0500bcc7b4` | true | Organization id | -| project | `project:54d8315ce6bb2d0500bcc7b4` | true | Project id | -| stack | `stack:54d8315ce6bb2d0500bcc7b4` | true | Stack id | -| reference | `reference:12345678` | true | Reference id | -| ref.session | `ref.session:12345678` | true | Session id | -| environment | `environment:production` or `_missing_:environment` | true | Deployment environment | -| type | `type:error` | true | Event type | -| source | `source:"my log source"` or `"my log source"` | false | Event source | -| level | `level:Error` | true | Log level | -| date | `date:"2020-10-16T12:00:00.000"` | true | Occurrence date | -| first | `first:true` | true | True if first occurrence of event | -| message | `message:"My error message"` or `"My error message"` | false | Event message | -| tag | `tag:"Blake Niemyjski"` or `tag:Blake` or `blake` | false | Tags | -| value | `value:1` | true | Value of event (used in charts) | -| geo | `geo:75044~75mi` or `geo:[geohash1..geohash2]` | true | Geo Location | -| status | `status:open` or `status:discarded` or `status:fixed` or `status:regressed` or `status:snoozed` or `status:ignored` | true | Stack status | -| version | `version:1` or `version:1.0` or `version:1.0.0` | true | Application version | -| machine | `machine:Server` | true | Machine name | -| ip | `ip:127.0.0.1` | true | IP address | -| architecture | `architecture:x64` | true | Machine architecture | -| useragent | `useragent:IE` or `useragent:"Mozilla/5.0"` | true | User Agent | -| path | `path:"/cart"` or `"/cart"` | false | URL path | -| browser | `browser:Chrome` | true | Browser | -| browser.version | `browser.version:50.0` | true | Browser version | -| browser.major | `browser.major:50` | true | Browser major version | -| device | `device:iPhone` | true | Device | -| os | `os:iOS` | true | Operating System | -| os.version | `os.version:8.0` | true | Operating System version | -| os.major | `os.major:8` | true | Operating System major version | -| count | `count:>5` | true | Number of occurrences the event represents | -| client.version | `client.version:4.0.0` | true | Exceptionless client version | -| cmd | `cmd:"MyApp.exe --run"` | true | Command line | -| country | `country:US` | true | Country | -| level1 | `level1:TX` | true | Region | -| level2 | `level2:Dallas` | true | City | -| bot | `bot:true` | true | bot | -| error.code | `error.code:500` or `500` | false | Error code | -| error.message | `error.message:"A NullReferenceException occurred"` | true | Error message | -| error.type | `error.type:"System.NullReferenceException"` or `"System.NullReferenceException"` | false | Error type | -| error.targettype | `error.targettype:"System.NullReferenceException"` or `"System.NullReferenceException"` | false | Error target type | -| error.targetmethod | `error.targetmethod:AssociateWithCurrentThread` or `AssociateWithCurrentThread` | false | Error target method | -| user | `user:"random user identifier"` or `"random user identifier"` | false | Uniquely identifies user | -| user.name | `user.name:"Exceptionless User"` or `"Exceptionless User"` | false | Friendly name of user | -| user.description | `user.description:"I clicked the button"` or `"I clicked the button"` | false | User Description | -| user.email | `user.email:"support@exceptionless.io"` or `"support@exceptionless.io"` | false | User email address (the user identity) | +Some examples: -## Multiple Queries +| Query | Finds | +| --------------------------------------- | ------------------------------------------------ | +| `error.type:NullReferenceException` | Errors of one exception type | +| `type:log (level:error OR level:fatal)` | Error and fatal log messages | +| `user:jane@example.com` | Events from one user | +| `version:2.4 environment:production` | Events from any `2.4.x` version in production | +| `_missing_:environment` | Events with no environment | +| `data.orderid:12345` | Events whose custom data has that order ID | +| `count:>5` | Events that represent more than five occurrences | -All queries separated by a space will be an `AND` operation. If you wish to `OR` queries you’ll need to use an `OR` statement. We recommend wrapping conditional statements with parentheses. +See the [search syntax reference](/docs/reference/search-syntax/) for every field and operator. -**Example:** Let's assume we want to return all events that have a `blue` or `red` tag. To search for these events our query would be `(tag:blue OR tag:red)`. +> [!NOTE] +> On the Free plan, filters can use only a few fields, such as type, environment, status, and project. Other fields, +> search terms without a field, and custom data need a paid plan. See +> [Free plan searches](/docs/reference/search-syntax/#free-plan-searches). -## Wild Cards +## Set the date range -Suffix your query with `*` for wild card searches. +The **Date** filter sets the time range of the list. Select it, then pick a range: -## Exclusions +- **Last 15 minutes**, **Last 1 hour**, **Last 4 hours**, **Last 24 hours**, **Last 7 days**, **Last 30 days**, or + **Last 90 days**. +- **Custom range** for anything else. -Prefix the field name with `-` for exclusions. +A custom range has two tabs: -**Example:** Let's assume that we want to return all events that are not marked as a bot. To search for these events our query would be `-bot:true`. -*NOTE: In some cases searching with `-bot:true` is more accurate than searching with `bot:false`. This happens because the first query returns all records where `bot` field is `not set` or `not equal to true`. The second query returns results only where the `bot` field is set to `false`. +- **Absolute**: Set **From** and **To** with the date and time fields, or select days on the calendar. The first click + selects a whole day and a second click extends the range. Times are in your browser's local time zone. +- **Relative**: Type expressions such as `now-1h`, `now-7d`, or `now/d` (the start of today). A year or month, such as + `2024` or `2024-01`, covers all of it. Each field shows the date it resolves to. -## Set and Unset Fields +Select **Apply** or press Enter to use the custom range. -Prefix the field name with `_missing_` or `_exists_`. +On lists with a chart, drag across the chart to zoom into that time range. -**Example:** Let's assume that we want to return all events that do not contain any tags. To search for these events our query would be `_missing_:tag`. +The built-in views start at **Last 7 days**. Removing the **Date** filter shows all time, back to your plan's retention +limit. -## Ranges +## Save your filters -Specify a `date` or `numeric` range as part of the term. +Changing a filter changes only the view you're on, and a dot on the **View** button shows the view has unsaved changes. +Open **View** to save them to the view, save them as a new view, or reset. See [Saved views](/docs/saved-views/). -**Date Range Example:** Let's assume that we want to return all events that occurred in 2020. To search for these events our query would be `date:[2020-01-01 TO 2020-12-31]`. +## Search from anywhere -**Numeric Range Example:** Let's assume that we want to return all events that contain a `value` between 1 and 10. To search for these events our query would be `value:(>0 AND <=10)`. +Press / to open the command palette and type at least two characters to search recent events and stacks. See +[Navigating the app](/docs/navigation/). -## Custom Extended Data +## Ask Exie -All simple data types (`string`, `boolean`, `date`, `number`) that are stored in extended data will be indexed. _NOTE_: Field names are lowercased. Any field name that contains characters other than letters, digits, and hyphens, or is longer than 25 characters, is not indexed. +Exie filters with the same fields, so you can ask in plain words instead of building a query: -**Example:** Let's assume that our events extended data contains a property called `Age` with a value of `18`. To search for this value our query would be `data.age:18`. +```prompt exie +Which errors did users on Chrome hit in production over the last 24 hours? +``` ---- +```prompt exie +Count the events for version 2.4.0 by environment for the last 7 days. +``` + +```prompt exie +Which stacks tagged Billing are still open? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can run the same searches: -[Next > Bulk Actions](/docs/bulk-actions) +```prompt agent +Use Exceptionless to find the errors with error.type NullReferenceException in production over the last 7 days, +then find where they're thrown in this repository and explain the likely cause. +``` diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md index 99f68ce0da..b5de338e0b 100644 --- a/docs/docs/getting-started.md +++ b/docs/docs/getting-started.md @@ -1,43 +1,174 @@ --- -title: "Getting Started" -metaTitle: "Getting started with Exceptionless" -description: "Get started with Exceptionless: create a hosted account and project or self-host, configure a client for your app, and send a first error event with curl." +title: "Send your first event" +navTitle: "Quickstart" +metaTitle: "Exceptionless quickstart: send your first event" +description: "Create an Exceptionless account and project, install a client or let your coding agent do it, send a test error, and find it in the app." +sources: + - src/Exceptionless.Web/ClientApp/src/routes/(auth)/signup/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/organization/add/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/add/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/configure/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/routes.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/projects/components/table/project-actions-cell.svelte + - src/Exceptionless.Web/Api/Endpoints/EventEndpoints.cs + - src/Exceptionless.Web/Api/Handlers/OrganizationHandler.cs + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs + - src/Exceptionless.Web/Assistant/AssistantToolDefinitions.cs + - Exceptionless.Net:.agents/skills/exceptionless-dotnet/SKILL.md + - Exceptionless.Net:src/Exceptionless/Extensions/ExceptionExtensions.cs + - Exceptionless.JavaScript:.agents/skills/exceptionless-javascript/SKILL.md + - Exceptionless.JavaScript:packages/core/src/ExceptionlessClient.ts --- -# Getting Started +# Send your first event -Exceptionless provides you the tools to track errors, logs, and events while guiding you toward actionable solutions. To get started, you'll want to decide if you are self-hosting Exceptionless or using our hosted version. If you choose to use our hosted version, you can get started for free. +In a few minutes you create an Exceptionless account, connect an app, send a test error, and find it in the app. You can +install the client yourself or hand that step to your coding agent. -## Hosted Option +> [!NOTE] +> Running your own Exceptionless server? Set it up with the [self-hosting guide](/docs/self-hosting/), then follow these +> steps on your own URL instead of `be.exceptionless.io`. -1. [Create an account](https://be.exceptionless.io/signup) -2. When you sign-up, you will be prompted to create your first project. -3. [Configure your application](https://be.exceptionless.io/project/list) by clicking the Download & Configure Client action button on the project list page. -4. Select your project type and follow the instructions. -5. Your application will now automatically send all unhandled errors to the Exceptionless service. -6. You can also send handled errors, feature usage or log messages along with additional information ([see documentation for your specific client](/docs/clients/)). +## 1. Create an account -## Self-Hosted Option +Go to [be.exceptionless.io/signup](https://be.exceptionless.io/signup). Sign up with **Microsoft**, **Google**, or +**GitHub**, or enter your **Name**, **Email**, and **Password** and select **Create My Account**. -We have put together comprehensive documentation to help you get started with a self-hosted Exceptionless instance. You can [find that documentation here](/docs/self-hosting/). +New organizations start on the Free plan. See [pricing](/pricing/) for what each plan includes. -## Sending Your First Event +## 2. Create an organization and a project -Once you've singed up for an account and created a project, you can start receiving events. Let's take a look at sending a simple event to Exceptionless. +After you sign up, the **Set Up Exceptionless** page asks for two names: -POST `api/v2/events` +- **Organization Name**: your team or company. An organization holds your projects, users, and plan. +- **Project Name**: the app you're connecting, such as `Storefront API`. Each project has its own API key and events. -```shell -curl --location --request POST "https://api.exceptionless.com/api/v2/events" \ ---header 'Authorization: Bearer YOUR_PROJECT_TOKEN' \ ---header 'Content-Type: application/json' \ ---data-raw '{ "type": "error", "date":"2030-01-01T12:00:00.0000000-05:00", "@simple_error": { "message": "Simple Exception", "type": "System.Exception", "stack_trace": " at Client.Tests.ExceptionlessClientTests.CanSubmitSimpleException() in ExceptionlessClientTests.cs:line 77" } }' +Select **Continue**. Exceptionless creates both and opens **Client Setup** for the new project. + +To add another project later, go to **Settings** > **Projects** in the sidebar and select **Add Project** (the plus +button). + +## 3. Install a client + +The **Client Setup** page, titled **Send Events to** your project name, shows **Waiting for your first event** while it +listens for data. Choose your app type from the list, and the page shows the install command and startup code with your +project's API key already filled in. Copy them into your app. + +The same setup for each client, with `YOUR_API_KEY` in place of your key: + +```clients ``` ---- +You can come back to this page any time: open **Settings** > **Projects** in the sidebar, open the project's actions +menu, and choose **Client Setup**. The project's keys are on its **API Keys** settings page. -You've got your account created, now what? Let's get a better understanding of how you manage events in Exceptionless and then we can dive into some best practice and ways to enhance your use. +For framework-specific setup, such as ASP.NET Core, React, or Express, see [Send data](/docs/clients/). ---- +### Or install with your coding agent + +Paste this prompt into Claude Code, Codex, Copilot, or another coding agent, and replace `YOUR_API_KEY` with the key +from **Client Setup**: + +```prompt agent +Add Exceptionless error reporting to this app. My Exceptionless API key is YOUR_API_KEY. + +1. Work out the app's language and framework. Then read the matching Exceptionless setup guide as Markdown. The client list is at https://exceptionless.com/docs/clients.md, and each guide has a .md URL, for example https://exceptionless.com/docs/clients/dotnet/aspnet-core.md for ASP.NET Core. +2. If you can use agent skills, follow the official Exceptionless skill for the language: https://github.com/exceptionless/Exceptionless.Net/tree/main/.agents/skills/exceptionless-dotnet for .NET, or https://github.com/exceptionless/Exceptionless.JavaScript/tree/main/.agents/skills/exceptionless-javascript for JavaScript. +3. Install the right package for the app type and configure it at startup. Put the API key in the app's configuration, not inline in code, where the framework supports it. +4. Send one test error so I can check that it arrives in Exceptionless, then tell me how to remove the test code. +``` + +The agent skills are part of the [Exceptionless.Net](https://github.com/exceptionless/Exceptionless.Net) and +[Exceptionless.JavaScript](https://github.com/exceptionless/Exceptionless.JavaScript) repositories. For more agent +workflows, see [Coding agents](/docs/ai/coding-agents/). + +## 4. Send a test error + +Once the client is installed, unhandled errors are sent automatically. To check the setup right away, submit a handled +error from your app: + +```csharp tab=".NET" +using Exceptionless; + +try { + throw new InvalidOperationException("Exceptionless test error"); +} catch (Exception ex) { + ex.ToExceptionless().Submit(); +} +``` + +```ts tab="JavaScript" +// Use the package you installed: @exceptionless/browser, @exceptionless/node, and so on. +import { Exceptionless } from "@exceptionless/node" + +try { + throw new Error("Exceptionless test error") +} catch (error) { + await Exceptionless.submitException(error as Error) +} +``` -[Next > Managing Stacks](/docs/managing-stacks) +```bash tab="curl" +curl "https://api.exceptionless.io/api/v2/events" \ + --request POST \ + --header "Authorization: Bearer YOUR_API_KEY" \ + --header "Content-Type: application/json" \ + --data-binary '{"type":"error","@simple_error":{"message":"Exceptionless test error","type":"System.Exception","stack_trace":" at Quickstart.Main() in Program.cs:line 1"}}' +``` + +Clients queue events and send them in the background, so a test error can take a few seconds to arrive. In a console +app, script, or serverless function that exits right away, flush the queue before it exits: call +`await ExceptionlessClient.Default.ProcessQueueAsync()` in .NET or `await Exceptionless.processQueue()` in JavaScript. + +> [!NOTE] +> On a self-hosted server, use your own API URL instead of `https://api.exceptionless.io`, and set the client's server +> URL as shown on your **Client Setup** page. + +## 5. Find it in Exceptionless + +If **Client Setup** is still open from step 2, it opens **Events** for your project as soon as the first event arrives. +Otherwise, select **Events** or **Stacks** in the sidebar. + +- **Events** lists each occurrence. Select the test error to open its details; the **Exception** tab shows the stack + trace. +- **Stacks** groups repeats of the same error into one stack, with its event count, first and last occurrence, and + status. + +Once you've seen the test error, set its stack's status to **Fixed** or **Discarded** so it doesn't stay in your open +errors. [Manage stacks](/docs/managing-stacks/) explains each status. + +Nothing showing up? Check that the API key matches the project and is enabled on the project's **API Keys** page, then +see troubleshooting for [.NET](/docs/clients/dotnet/troubleshooting/) or +[JavaScript](/docs/clients/javascript/troubleshooting/). + +## Next steps + +- **Connect your coding agent.** The [MCP server](/docs/ai/mcp-server/), available on every plan, lets an agent such as + Claude Code or Codex look up your stacks and events and update them while it works in your code. Choose **AI Tools** + in your user menu for the setup commands for your agent. +- **Ask Exie.** [Exie](/docs/ai/exie/) is the assistant built into the app. Open it with **Ask Exie** in the top bar or + press A. Exie is on Medium plans and up. +- **Learn the model.** [Core concepts](/docs/concepts/) explains events, stacks, environments, and saved views. +- **Get alerted.** Set up [notifications](/docs/notifications/) for new errors and regressions. +- **Send more.** Logs, feature usage, and user context are covered in your client's [sending events](/docs/clients/) + guide. + +## Ask Exie + +```prompt exie +Did my new project receive any errors today? +``` + +```prompt exie +Explain the "Exceptionless test error" stack and show me its latest event. +``` + +```prompt exie +Mark the "Exceptionless test error" stack as fixed. +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can check the setup for you: + +```prompt agent +Check that my Exceptionless project received the "Exceptionless test error" event. If it did, mark that stack fixed. +``` diff --git a/docs/docs/index.md b/docs/docs/index.md index c0cb7899e0..e869b2ea0a 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -1,31 +1,49 @@ --- title: "Overview" metaTitle: "Exceptionless documentation" -description: "Exceptionless documentation for real-time error reporting in JavaScript, Node.js, ASP.NET Core, and .NET apps, configurable without redeploying." +description: "Exceptionless docs: send your first event, connect your AI agent to Exceptionless, or self-host it. Guides for .NET, JavaScript, the REST API, and more." +sources: + - src/Exceptionless.Web/ClientApp/src/routes/(auth)/signup/+page.svelte + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs + - src/Exceptionless.Web/Assistant/AssistantAccessService.cs --- # Exceptionless documentation -The definition of the word exceptionless is: to be without exception. Exceptionless provides real-time error reporting for your JavaScript, Node, .NET Core, ASP.NET, Web API, WebForms, WPF, Console, and MVC apps. It organizes the gathered information into simple actionable data that will help your app become exceptionless! +Exceptionless collects errors, logs, feature usage, and 404s from your apps, groups repeats of the same problem into +stacks, and shows you what to fix first. These docs cover the hosted service at +[be.exceptionless.io](https://be.exceptionless.io) and self-hosted installs. -Exceptionless focuses on real-time configurability which sets it apart from other error monitoring services. Where others might require a configuration change in your code and a re-deployment of your app, Exceptionless allows you to make changes without ever changing your deployed code. +## Start here ---- - -## Who is using us? - -Companies from around the world trust Exceptionless to help them deliver an improved experience for their customers. +**Send your first event.** Create a free account, add a client to your app, and see a test error in a few minutes. +[Quickstart](/docs/getting-started/) -![Customers](/assets/img/codesmith-client-logo-bar-left.png) {.text-center} +**Connect your AI agent.** Ask Exie, the assistant in the app, about your errors, or connect Claude Code, Codex, +Copilot, or another coding agent through the Exceptionless MCP server so it can find and fix them in your code. +[AI overview](/docs/ai/) -## Want to Learn More? +**Self-host.** Run Exceptionless on your own infrastructure with Docker or Kubernetes. +[Self-hosting](/docs/self-hosting/) -Browse the [news archive](/news/) for release notes, engineering updates, and articles about error monitoring, .NET, JavaScript, and development. - ---- +Coming back after a while? [What's new in 9.0](/docs/whats-new/) covers the new app, saved views, Exie, the MCP server, +and where things moved. -## Ready to Dive in? +## Explore the docs -Let's jump right into the documentation and get you up and running. Navigate at your leisure on the left, or click through each section and read the entirety of our docs (if you're an over-achiever). +- [Core concepts](/docs/concepts/): events, stacks, projects, environments, and saved views in five minutes. +- [AI](/docs/ai/): [Exie](/docs/ai/exie/), the [MCP server](/docs/ai/mcp-server/), and + [coding agents](/docs/ai/coding-agents/). +- [Send data](/docs/clients/): the [.NET](/docs/clients/dotnet/) and [JavaScript](/docs/clients/javascript/) clients, + and [other languages](/docs/clients/custom-clients/). +- Use Exceptionless: [events](/docs/events/), [stacks](/docs/managing-stacks/), + [filtering and searching](/docs/filtering-and-searching/), [saved views](/docs/saved-views/), and + [notifications](/docs/notifications/). +- How it works: [stacking](/docs/concepts/stacking/), [limits and deduplication](/docs/concepts/limits/), and + [security and privacy](/docs/security/). +- Reference: [search syntax](/docs/reference/search-syntax/), [event format](/docs/reference/event-format/), and the + [FAQ](/docs/FAQ/). +- [REST API](/docs/api/): authentication, posting events, and querying events and stacks. +- [Self-hosting](/docs/self-hosting/): Docker, Kubernetes, configuration, and upgrading. -[Getting Started](/docs/getting-started) +Every page is also available as Markdown for AI tools. See [Docs for AI](/docs/ai/docs-for-ai/). diff --git a/docs/docs/integrations.md b/docs/docs/integrations.md index f6f3806ff8..8f4c787bed 100644 --- a/docs/docs/integrations.md +++ b/docs/docs/integrations.md @@ -1,74 +1,195 @@ --- title: "Integrations" -metaTitle: "Exceptionless integrations: Slack, Zapier, webhooks" -description: "Connect Exceptionless to Slack, Zapier, and webhooks from project settings, pick which notifications to send, and see the webhook JSON payload." +metaTitle: "Integrations: Slack, webhooks, and Zapier" +description: "Send Exceptionless notifications to Slack, call your own endpoint with a webhook when errors happen, and connect other apps with Zapier." +sources: + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/integrations/+page.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/webhooks/options.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/webhooks/components/dialogs/add-webhook-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/webhooks/components/table/options.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/webhooks/components/table/webhook-actions-cell.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/stack-options-dropdown-menu.svelte + - src/Exceptionless.Core/Models/WebHook.cs + - src/Exceptionless.Core/Models/WebHookEvent.cs + - src/Exceptionless.Core/Models/WebHookStack.cs + - src/Exceptionless.Core/Plugins/WebHook/Default/020_VersionTwoPlugin.cs + - src/Exceptionless.Core/Pipeline/070_QueueNotificationAction.cs + - src/Exceptionless.Core/Jobs/WebHooksJob.cs + - src/Exceptionless.Core/Services/WebHookDelivery.cs + - src/Exceptionless.Core/Serialization/JsonSerializerOptionsExtensions.cs + - src/Exceptionless.Web/Api/Handlers/WebHookHandler.cs + - src/Exceptionless.Web/Api/Handlers/StackHandler.cs + - tests/Exceptionless.Tests/Plugins/WebHookData/v2.event.expected.json + - tests/Exceptionless.Tests/Plugins/WebHookData/v2.stack.expected.json --- # Integrations -To make managing events from your application easier, Exceptionless provides some useful integrations. To find them, go to **Settings** > **Projects** in the sidebar, click your project, then click the **Integrations** tab. +Integrations send what happens in a project to other tools: Slack messages, webhook calls to your own endpoint, and +Zapier zaps. They're set up per project. Open the project's settings and click the **Integrations** tab. ![Integrations tab in project settings](/assets/img/docs/integrations-overview-light.webp) -We provide three integrations: +Slack and webhooks need a paid plan. On the Free plan, adding one asks you to upgrade. -1. Zapier -2. Slack -3. Webhooks +## Slack -## Zapier +Connect a Slack channel to get new errors, critical errors, and regressions as Slack messages: -Exceptionless has built a [first-class Zapier application](https://zapier.com/apps/exceptionless/integrations) that allows you to connect your Exceptionless account to over 3,000 other apps. Click **Connect Zapier** on the Integrations tab to open the Exceptionless app on Zapier, or sign into your Zapier account and search for Exceptionless. +1. On the **Integrations** tab, click **Connect Slack**. +2. Sign in to your Slack workspace and choose the channel. +3. Choose which notifications to send with the switches: **New Errors**, **Critical Errors**, **Error Regressions**, + **New Events**, and **Critical Events**. -## Slack - -Connecting to Slack is as simple as clicking the **Connect Slack** button. You'll be prompted to sign into your Slack workspace. Once signed in, you can choose the channel for your notifications to be sent to. Then, back on the Integrations tab, use the switches to choose which notifications are sent: **New Errors**, **Critical Errors**, **Error Regressions**, **New Events**, and **Critical Events**. To disconnect, click **Remove Slack**. +To disconnect, click **Remove Slack**. See [Notifications](/docs/notifications/) for what each notification means and +how often they're sent. ## Webhooks -By configuring a webhook, you are telling Exceptionless to post data to the specified endpoint whenever specific events happen. This is useful in creating custom, bespoke integrations for your Exceptionless account. Configuring a webhook is simple. Click the **+** (Add Webhook) button in the **Webhooks** section of the Integrations tab, enter the **URL** to call, choose the **Event Types** that should trigger it, and click **Add Webhook**. +A webhook calls a URL of yours whenever certain things happen in the project. Use it to create tickets, page someone, or +feed your own tools. + +### Add a webhook + +1. On the **Integrations** tab, click **+** (**Add Webhook**) in the **Webhooks** section. +2. Enter the **URL** to call. +3. Choose the **Event Types** that call it. +4. Click **Add Webhook**. ![Add New Webhook dialog with a URL and event types selected](/assets/img/docs/integrations-add-webhook-light.webp) -You can choose from these event types: +To remove a webhook, open its menu (**...**) in the list and click **Delete**. + +### Event types + +| Event type | Value in the API | Called when | Payload | +| ------------------ | ----------------- | -------------------------------------------------- | ------- | +| **New Error** | `NewError` | An error happens that starts a new stack. | Event | +| **Critical Error** | `CriticalError` | An error marked critical happens. | Event | +| **Regression** | `StackRegression` | An event happens in a stack marked fixed. | Event | +| **New Event** | `NewEvent` | An event of any type starts a new stack. | Event | +| **Critical Event** | `CriticalEvent` | An event of any type marked critical happens. | Event | +| **Promoted** | `StackPromoted` | Someone clicks **Promote To External** on a stack. | Stack | + +An event is critical when its stack has **Future Occurrences Are Critical** turned on, or when your code marks it +critical. Events in stacks that are fixed, snoozed, ignored, or discarded don't call webhooks. Unlike email and Slack, +webhooks aren't rate limited: every matching event calls them. + +**Promote To External** is in a stack's options menu. It sends the stack to every **Promoted** webhook in the project, +for example to open an issue in your tracker. If the project has no **Promoted** webhook, the app offers to take you to +the **Integrations** tab. See [Stacks](/docs/managing-stacks/). -- **New Error**: a new error that has never been seen before is reported to your project. -- **Critical Error**: an error that has been marked as critical is reported to your project. -- **Regression**: an event that has been marked as fixed has reoccurred in your project. -- **New Event**: a new event that has never been seen before is reported to your project. -- **Critical Event**: an event that has been marked as critical is reported to your project. -- **Promoted**: a stack is promoted to external systems. +### Delivery -Here's an example of the event payload (this applies to v2 of the Exceptionless API): +- Exceptionless sends a `POST` request with a JSON body (`Content-Type: application/json`). +- Your endpoint has 5 seconds to respond with a `2xx` status code. +- Requests aren't signed. Use an HTTPS URL that's hard to guess, such as one with a secret token in the path, and check + the IDs in the payload against the [API](/docs/api/) if you need to be sure. +- A `401`, `403`, or `410` response disables the webhook right away. +- After more than 10 failed deliveries in a row, Exceptionless tries at most once every 15 minutes and skips the calls + in between. If deliveries keep failing for more than two days, it disables the webhook. + +A disabled webhook stays in the list but isn't called. To turn it back on, delete it and add it again. + +### Event payload + +The five event types send the event that triggered the webhook, with its stack: + + ```json { - "id": "22cd0826e447a44e78877a22", - "url": "http://localhost:5200/event/22cd0826e447a44e78877a22", - "occurrence_date": "2014-01-17T14:37:02.739-06:00", + "id": "6720f3c4e1b2a3c4d5e6f708", + "url": "https://be.exceptionless.io/event/6720f3c4e1b2a3c4d5e6f708", + "occurrence_date": "2026-10-27T14:37:02.739-05:00", "type": "error", - "message": "A potentially dangerous Request.Path value was detected from the client (&).", + "environment": "production", + "message": "Object reference not set to an instance of an object.", "project_id": "537650f3b77efe23a47914f4", - "project_name": "Disintegrating Pistol", + "project_name": "Store API", "organization_id": "537650f3b77efe23a47914f3", "organization_name": "Acme", "stack_id": "1ecd0826e447a44e78877ab1", - "stack_url": "http://localhost:5200/stack/1ecd0826e447a44e78877ab1", - "stack_title": "A potentially dangerous Request.Path value was detected from the client (&).", - "stack_tags": [ - "Test" - ], - "total_occurrences": 0, - "first_occurrence": "2014-01-17T20:37:02.739Z", - "last_occurrence": "2014-01-17T20:37:02.739Z", + "stack_url": "https://be.exceptionless.io/stack/1ecd0826e447a44e78877ab1", + "stack_title": "Object reference not set to an instance of an object.", + "stack_tags": ["checkout"], + "total_occurrences": 42, + "first_occurrence": "2026-10-02T16:11:45.102Z", + "last_occurrence": "2026-10-27T19:37:02.739Z", "is_new": false, - "is_regression": false, + "is_regression": true, "is_critical": false } ``` -To see both v1 and v2 models for events and stacks, [see this link](https://github.com/exceptionless/Exceptionless/tree/master/tests/Exceptionless.Tests/Plugins/WebHookData). +| Field | Description | +| ---------------------------------------------------------- | -------------------------------------------------------------------------------- | +| `id`, `url` | The event ID and its page in the app. | +| `occurrence_date` | When the event happened, with the offset the client sent. | +| `type`, `source`, `message`, `environment`, `tags` | The event's type, source, message, [environment](/docs/environments/), and tags. | +| `project_id`, `project_name` | The project. | +| `organization_id`, `organization_name` | The organization. | +| `stack_id`, `stack_url`, `stack_title` | The stack the event belongs to and its page in the app. | +| `stack_description`, `stack_tags` | The stack's description and tags. | +| `total_occurrences`, `first_occurrence`, `last_occurrence` | The stack's occurrence count and first and last occurrence, in UTC. | +| `date_fixed` | When the stack was marked fixed, if it is. | +| `is_new` | `true` when this event started the stack. | +| `is_regression` | `true` when this event regressed a fixed stack. | +| `is_critical` | `true` when the event is marked critical. | ---- +Fields without a value, and empty lists, are left out of the payload. For example, `source` is usually missing on +errors, and `tags` is missing when the event has none. -[Next > FAQ](/docs/FAQ) +### Stack payload + +**Promoted** webhooks send the stack: + + + +```json +{ + "id": "1ecd0826e447a44e78877ab1", + "url": "https://be.exceptionless.io/stack/1ecd0826e447a44e78877ab1", + "title": "Object reference not set to an instance of an object.", + "tags": ["checkout"], + "type": "System.NullReferenceException", + "project_id": "537650f3b77efe23a47914f4", + "project_name": "Store API", + "organization_id": "537650f3b77efe23a47914f3", + "organization_name": "Acme", + "total_occurrences": 42, + "first_occurrence": "2026-10-02T16:11:45.102Z", + "last_occurrence": "2026-10-27T19:37:02.739Z", + "is_regression": true, + "is_critical": false +} +``` + +The stack payload can also include `description`, `request_path` (for 404 stacks), `target_method` (the method an error +stack is grouped on), `date_fixed`, and `fixed_in_version`. + +## Zapier + +Exceptionless has a [Zapier app](https://zapier.com/apps/exceptionless/integrations) that connects your projects to +thousands of other apps without code. Click **Connect Zapier** on the **Integrations** tab to open it, or search for +Exceptionless in Zapier. The Zapier app connects with a project's client API key, so each connection works with one +project. Create a key on the project's **API Keys** tab (see [Projects](/docs/project-settings/#api-keys)). + +## Ask Exie + +[Exie](/docs/ai/exie/) can attach links to a stack, such as the issue a webhook created. Exie is on Medium plans and up. + +```prompt exie +Add https://github.com/acme/store/issues/412 as a reference link on this stack. +``` + +```prompt exie +Which new errors appeared in this project since yesterday? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can connect Exceptionless to your issue +tracker: + +```prompt agent +Find the top new error in my Exceptionless project from the last 24 hours, open a GitHub issue for it with the stack trace and a link to the stack, and add the issue URL to the stack as a reference link. +``` diff --git a/docs/docs/managing-stacks.md b/docs/docs/managing-stacks.md index 9ad51d0086..6578f4e66b 100644 --- a/docs/docs/managing-stacks.md +++ b/docs/docs/managing-stacks.md @@ -1,70 +1,204 @@ --- -title: "Managing Stacks" -description: "Manage Exceptionless stacks: view stack details, mark them Open, Fixed, Snoozed, Ignored, or Discarded, flag future occurrences critical, and add links." +title: "Stacks" +metaTitle: "Managing stacks in Exceptionless" +description: "Triage Exceptionless stacks: open, fix, snooze, ignore, or discard them, mark them critical, add reference links, promote them, and act in bulk." +redirectFrom: + - from: /docs/bulk-actions/ + anchor: bulk-actions +sources: + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/stack-card.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/stack-details.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/stack-status-dropdown-menu.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/stack-options-dropdown-menu.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/stacks-bulk-actions-dropdown-menu.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/dialogs/mark-stack-fixed-in-version-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/dialogs/mark-stack-discarded-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/dialogs/add-stack-reference-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/dialogs/requires-promoted-web-hook-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/dialogs/stacking-information-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/table/events-bulk-actions-dropdown-menu.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/stacks/+page.svelte + - src/Exceptionless.Web/Api/Handlers/StackHandler.cs + - src/Exceptionless.Core/Models/Stack.cs + - src/Exceptionless.Core/Extensions/StackExtensions.cs + - src/Exceptionless.Core/Pipeline/010_AssignToStackAction.cs + - src/Exceptionless.Core/Pipeline/020_MarkAsCriticalAction.cs + - src/Exceptionless.Core/Pipeline/030_CheckForRegressionAction.cs + - src/Exceptionless.Core/Pipeline/070_QueueNotificationAction.cs + - src/Exceptionless.Core/Jobs/StackStatusJob.cs + - src/Exceptionless.Core/Seed/predefined-saved-views.json + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs --- -# Managing Stacks +# Stacks -Perhaps the most important thing you'll do in Exceptionless is manage your stacks. Think of stacks as your todo list for error management. And like any good todo list, you can drill into a task for more details, mark the task complete, or set the task aside for a later date. +A stack groups every event that describes the same problem, so you triage one stack instead of a thousand occurrences. +This page covers how to review a stack and change its status, and the other actions you can take on one or many stacks. +To learn how events are grouped, see [Stacking](/docs/concepts/stacking/). -But what is a stack, exactly? It's pretty simple, actually. A stack is an automatically ([or manually](/docs/manual-stacking)) grouped list of events. Events can be errors, messages, or logs. Exceptionless will try to automatically group the same events together while gathering as much information about them as possible (i.e. number of users affected, frequency of the event, last occurrence). +## Review a stack -### Viewing Stacks - -Now, let's take a look at how you manage these stacks. When you sign in, you land on the Stacks list. The **Stacks** menu in the sidebar has saved views for common lists: **All**, **Most Frequent 404s**, **Most Frequent Errors**, and **Most Used Features**. The Most Frequent views sort stacks by how many events they received. +Open **Stacks** in the sidebar and pick a view: **All**, **Most Frequent Errors**, **Most Frequent 404s**, or **Most +Used Features**. Each lists stacks that are open or regressed and had events in the last 7 days. ![Most Frequent Errors view of the Stacks list](/assets/img/docs/managing-stacks-list-light.webp) -Click on a stack you'd like to manage (We recommend you start with the most frequent event because that's probably pretty annoying for your customers 😉). Clicking on a stack opens its details in a side panel, and the panel's **Open in new window** button opens the full stack page. The details include important information such as how many times the event occurred, the percentage of users affected, and the first and last occurrences of the event. Below the stack summary, you can page through the individual events in the stack. +Select a stack to open it in a side panel. **Open in new window** in the panel header opens the full stack page, and the +copy icon copies a link to it. The stack card at the top shows: + +- **Total Events**: how many times the stack has occurred. Select the calendar icon (**Open events for this stack**) to + list its events. +- **Users Affected**: the share of the project's users in the last 7 days who hit this stack. Hover over the info icon + for the counts. +- **First** and **Last**: the stack's first and last occurrence in the last 7 days. +- A chart of the stack's events over the last 7 days. +- The **Project**, **Tags**, when it was **Fixed** or how long it's **Snoozed Until**, and any **Reference** links. ![Stack details showing total events, users affected, and first and last occurrence](/assets/img/docs/managing-stacks-details-light.webp) -### Applying Statuses +Below the card is the stack's most recent event. Use **Older event** and **Newer event** to step through its +occurrences. See [Events](/docs/events/) for the event tabs. -To apply a status on a stack, click the status button in the top-right corner of the stack details (it shows the current status, such as **Open**) and pick a new status. The options are: +## Stack statuses -* Open -* Fixed -* Snoozed (choose 6 Hours, 1 Day, 1 Week, or 1 Month) -* Ignored -* Discarded +The status button in the stack card shows the current status. Select it to change it. ![Stack status menu with Open, Fixed, Snoozed, Ignored, and Discarded](/assets/img/docs/managing-stacks-status-menu-light.webp) -Marking the status of a stack will control your [filtering](/docs/filtering-and-searching) options, but it can also drive your workflow. Ignored stacks may be stacks you have no plans of addressing. Discarded stacks (which do not count against your plan quota) may be stacks that you can't easily prevent from coming through but you don't want to see and don't care about. Snoozing stacks allows you to be reminded at a future point to address the stack in question. +| Status | New events | Notifications | In the built-in stack views | +| ------------- | ----------------------------- | ------------- | --------------------------- | +| **Open** | Stored | Yes | Yes | +| **Fixed** | Stored; may regress the stack | No | No | +| **Regressed** | Stored | Yes | Yes | +| **Snoozed** | Stored | No | No | +| **Ignored** | Stored | No | No | +| **Discarded** | Dropped | No | No | + +Notifications here means the emails, Slack messages, and webhooks sent when an event is new, critical, or a regression. +See [Notifications](/docs/notifications/). + +**Regressed** isn't in the menu. Exceptionless sets it when a fixed stack happens again. + +### Open + +New stacks start open. Choose **Open** to reopen a stack that's fixed, snoozed, ignored, or discarded. Reopening clears +its fixed version and snooze time. + +### Mark a stack fixed + +Choose **Fixed** when you've shipped a fix. In the **Mark Stack As Fixed** dialog, optionally enter the **Version** that +contains the fix, then select **Mark Stack Fixed**. -Let's take a look at each status in detail: +- **With a version**, only events from that version or later reopen the stack as regressed. Events from older versions + that are still running don't, and on paid plans they're dropped instead of stored. +- **Without a version**, any event that occurs after you marked it fixed reopens it. -**Open** - This status indicates that the error is new or actively occurring. You will receive email notifications for these issues. +See [Releases and regressions](/docs/versioning/) for how versions are compared. -**Fixed** - Well, this one means you fixed it. If you look at Exceptionless as your todo list for errors, marking a stack as "Fixed" is like checking an item off your todo list. To be more specific, you won't get notifications if you have marked events as fixed. When you choose Fixed, you can optionally enter the [version](/docs/versioning) of your software in which the fix was introduced. If another error comes through of the same kind and it matches the version number that was supposed to fix the issue, your stacks will be marked as "Regressed" instead of "Fixed". Additionally, if you mark a stack as Fixed but do not supply a version number in which it was fixed, should the event happen again, the stack will be marked as "Regressed". +### Snooze a stack -**Snoozed** - Marking a stack as snoozed hides it from your stack lists and means you will not get email notifications for whatever period of time you indicate. This is like your alarm clock in the morning. You know you need to take action (like wake up or fix the bug), but you really don't want to yet. Snooze has your back. After the specified period of time, the stacks will once again start alerting you. +Hover over **Snoozed** and pick **6 Hours**, **1 Day**, **1 Week**, or **1 Month**. Selecting **Snoozed** itself snoozes +for a month. A snoozed stack leaves the built-in views and sends no notifications. When the time is up, it goes back to +**Open**. The stack card shows when, under **Snoozed Until**. -**Ignored** - When you ignore a stack, you will no longer receive email notifications unless you change the status. You may choose to do this when you have no intentions of resolving the issue but still want to collect information from the stacks. +### Ignore a stack -**Discarded** - You should use this status when you do not care about the event at all. If "Ignored" is turning your back on an event and trying not to see it, "Discarded" is putting its feet in cement and dropping it into the middle of a lake. And since these events are sleeping with the fishes, they don't count against your plan quota. You'll be asked to confirm before a stack is discarded. +Choose **Ignored** for a stack you've decided not to fix but still want to record, such as noise from a third-party +script. Events keep arriving and counting against your plan, but the stack sends no notifications and leaves the +built-in views. -Beyond statuses, you have options to further control your stacks. +### Discard a stack -### Additional Options +Choose **Discarded** when you don't want the stack's events at all. After you confirm in the **Discard Stack** dialog, +new events for the stack are dropped when they arrive and don't count against your plan's event limit. Events already +stored stay until you delete the stack or they age out. -Click the gear button next to the status button to open the **Stack Options** menu. +### Find fixed, ignored, and discarded stacks + +The built-in views show only open and regressed stacks. To see the others: + +- On a stack list, select **Manage filters** > **Status** and pick the statuses you want. This opens the view's hidden + **Status** filter if it has one. See [Filtering and searching](/docs/filtering-and-searching/). +- Open the project's settings (**Settings** > **Projects**, then the project) and select **Stack Management**. It lists + the project's ignored and discarded stacks, so you can restore them. + +## Mark future occurrences critical + +Open **Stack options** (the gear next to the status button) and check **Future Occurrences Are Critical**. Every new +event in the stack gets the `Critical` tag, which you can filter on and be [notified](/docs/notifications/) about. +Uncheck it to stop. Existing events don't change. ![Stack Options menu with Future Occurrences Are Critical, Promote To External, Add Reference Link, View Stacking Information, and Delete](/assets/img/docs/managing-stacks-options-menu-light.webp) -Marking a stack with "Future Occurrences Are Critical" will automatically tag all subsequent events that come into that stack with the critical tag and will make them more prominent for you to review. +## Add reference links -The "Promote To External" option allows you to send the stack details to an external source that you've configured as a promoted webhook in the [Integrations](/docs/integrations) section. If the project has no promoted webhook yet, Exceptionless offers to take you to the project's integrations. This can help you automate issue tracking and project management. For example, you can use this functionality to connect to [Zapier](https://zapier.com), a no-code automation tool. By doing so, you can automatically funnel events from Exceptionless to issues on Github or Jira. You can send text alerts to your devops team (just be smart about this one because those folks need sleep too!), or you can use the data from Exceptionless to build custom dashboards for your entire organization. +Link a stack to an issue, pull request, incident, or chat thread: -"Add Reference Link" allows you to attach a link to an external source. This is helpful when a customer files a GitHub issue, for example. You can link to GitHub or to a Slack conversation, or anywhere, really. Reference links are listed in the stack details. +1. Open **Stack options** and select **Add Reference Link**. +2. Enter a URL and select **Save Reference Link**. -"View Stacking Information" shows the values Exceptionless used to group events into the stack. This is handy when you want to understand why two events did or didn't land in the same stack. +The link appears in the stack card under **Reference**. Select the trash icon next to it to remove it. -"Delete" removes the stack and its events. You'll be asked to confirm first. +## Promote a stack to an external system -Managing your stacks is the core focus within Exceptionless, and we try to automate as much as possible for you. However, it is possible to manually stack events, allowing you some of the same management tools outlined here. +**Promote To External** sends the stack to every enabled webhook in the project that subscribes to promoted stacks, for +example to create an issue in your tracker. Set up the webhook first in the project's **Integrations**; if there isn't +one, Exceptionless offers to take you there. See [Integrations](/docs/integrations/). ---- +Promoting a stack needs a paid plan. + +## View stacking information + +**View Stacking Information** shows the values Exceptionless used to group events into the stack, such as the exception +type and the method that threw. Use it to understand why two events did or didn't land in the same stack. See +[Stacking](/docs/concepts/stacking/). + +## Delete a stack + +**Delete** in **Stack options** removes the stack and all of its events after you confirm. Deleting runs in the +background. If the same error happens again, it starts a new stack. + +To stop collecting a stack's events, discard it instead. + +## Bulk actions {#bulk-actions} + +To act on many stacks at once, select the check box on each row, or the check box in the header to select every row on +the page. Then open **Actions** above the list. + +![Stacks list with three stacks selected and the Actions menu open](/assets/img/docs/bulk-actions-menu-light.webp) + +In a stack list, **Actions** has **Mark Open**, **Mark Fixed**, **Mark Snoozed**, **Mark Ignored**, **Mark Discarded**, +and **Delete**. They work like the single-stack actions above. **Mark Fixed** asks for one version for all the selected +stacks. + +In an event list, **Actions** has **Delete**, which deletes the selected events. + +**Actions** stays disabled until you select at least one row. + +## Ask Exie + +Exie can find stacks and change them when you ask for that exact change: + +```prompt exie +Which stacks regressed in the last 7 days? +``` + +```prompt exie +Mark the NullReferenceException stack in the Checkout project fixed in version 2.4.1. +``` + +```prompt exie +Snooze the "Connection reset by peer" stack for a day. +``` + +```prompt exie +Add https://github.com/acme/api/issues/42 as a reference link on the top error stack this week. +``` + +Exie can't promote or delete stacks. With the [MCP server](/docs/ai/mcp-server/) connected and the `stacks:write` +permission granted, your coding agent can change stacks too: -[Next > Manual Stacking](/docs/manual-stacking) +```prompt agent +Find the most frequent open error in my Exceptionless project this week and fix it in this repository. Then mark its +stack fixed in the version this fix will ship in, and add a link to the commit as a reference link on the stack. +``` diff --git a/docs/docs/manual-stacking.md b/docs/docs/manual-stacking.md deleted file mode 100644 index 24f8147998..0000000000 --- a/docs/docs/manual-stacking.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "Manual Stacking" -description: "Group related Exceptionless events into a custom stack with a manual stacking key, with examples for the REST API, the .NET client, and JavaScript." ---- - -# Manual Stacking - -We try to group events into intuitive stacks, but sometimes you might want to create your own for organization, reporting, troubleshooting, etc. A good example use case might be when you are introducing a new feature. The errors or events you send to Exceptionless may ultimately look like or be the same as events linked to other features in your applications. However, you might want to see the events triggered by use of this new feature stacked together. - -How might we do this? You can use the `SetManualStackingKey` method to facilitate this need. - -## Creating Custom Stacks - -In the examples below, the cURL request sets a stacking key named "mystackingkey" to the value "ANOTHER FEATURE" and titles the stack "My stack title". The .NET and JavaScript examples call `SetManualStackingKey("MyCustomStackingKey")`, which stores "MyCustomStackingKey" as the event's `ManualStackingKey` value. Any events that share the same key are grouped into the same stack, regardless of the type or reason for the event. - -To check which values grouped a stack, open the stack, click the gear button next to the status button, and choose **View Stacking Information**. For a manually stacked event, it lists your stacking key and value. Let's see how you would do this in practice. - -## cURL Example - -```shell -curl --location --request POST 'https://api.exceptionless.com/api/v2/events' \ ---header 'Authorization: Bearer YOUR_PROJECT_TOKEN' \ ---header 'Content-Type: application/json' \ ---data-raw '{ "type": "error", - "date":"2030-01-01T12:00:00.0000000-05:00", - "title": "NEW FEATURE WORK", - "@simple_error": { - "message": "Weird Exception", - "type": "System.Exception", - "stack_trace": " at Client.Tests.ExceptionlessClientTests.CanSubmitSimpleException() in ExceptionlessClientTests cs:line 99" - }, - "@stack": { "title": "My stack title", "signature_data": { "mystackingkey": "ANOTHER FEATURE" } } -}' -``` - -## C# Example - -```csharp -try { - throw new ApplicationException("Unable to create order from quote."); -} catch (Exception ex) { - ex.ToExceptionless().SetManualStackingKey("MyCustomStackingKey").Submit(); -} -``` - -Or, you can set the stacking directly on an event (e.g., inside a plugin). - -```csharp -event.SetManualStackingKey("MyCustomStackingKey"); -``` - -## JavaScript Example - -```javascript -import { Exceptionless } from "@exceptionless/browser"; -// For Node.js, import from "@exceptionless/node" instead. - -try { - throw new Error("Unable to create order from quote."); -} catch (error) { - await Exceptionless.createException(error).setManualStackingKey("MyCustomStackingKey").submit(); -} -``` - -## When Should You Use This - -Custom, manual stacking is certainly an advanced feature. We have tried to make your experience fantastic without needing this functionality, but sometimes, there's no avoiding it. So, let's think about some times when you might want to use manual stacking: - -* Critical Functionality - if you have a piece of your app that you need see all errors for quickly, manual stacking would be perfect. -* Logs - we tend to think of stacks as errors, but they don't have to be, and you can easily use manual stacking to group logs for other purposes. -* Notifications - manual stacking makes it easy to set up [notifications](/docs/notifications) for errors or events that happen from a specific source that you define. - ---- - -[Next > Filtering & Searching](/docs/filtering-and-searching) diff --git a/docs/docs/navigation.md b/docs/docs/navigation.md new file mode 100644 index 0000000000..b0a5d27e9e --- /dev/null +++ b/docs/docs/navigation.md @@ -0,0 +1,114 @@ +--- +title: "Navigating the app" +description: "Find anything in Exceptionless with the command palette, move around with keyboard shortcuts, and learn the app with guided tours." +navTitle: "Navigation" +sources: + - src/Exceptionless.Web/ClientApp/src/lib/features/shared/keyboard-shortcuts.ts + - src/Exceptionless.Web/ClientApp/src/routes/(app)/+layout.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/(components)/keyboard-shortcuts-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/(components)/navigation-command.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/(components)/layouts/navbar.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/(components)/layouts/sidebar-user.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/(components)/layouts/sidebar-organization-switcher.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/routes.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/projects/components/project-command-actions.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/shared/components/data-table/data-table-body.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/product-tours/catalog.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/product-tours/components/dialogs/product-tour-catalog-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/product-tours/components/alerts/product-tour-welcome.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/product-tours/components/alerts/product-tour-feature-announcement.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/product-tours/components/product-tour-shell-spotlight.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/product-tours/components/product-tour-spotlight.svelte +--- + +# Navigating the app + +The Exceptionless app has a command palette for finding things and running actions, single-key shortcuts for the places +you go most, and guided tours that show you around. + +## Command palette + +Press /, or click **Type / to search** in the top bar, to open the command palette. Type to filter it, use +the arrow keys to pick an item, press Enter to open it, and press Esc to close the palette. + +Type at least two characters to also search the current organization's events and stacks from the last 7 days. The +palette shows up to three of each, with **View all matching events** and **View all matching stacks** to open the full +results. It searches the same fields as the filter bar's text search, so you can paste an event ID, a +[reference ID](/docs/references-ids/), an error message, or a URL path. + +The palette also lists: + +- **Pages:** **All Stacks**, **All Events**, and **All Sessions**, each followed by your + [saved views](/docs/saved-views/) for it; the Exie page; settings pages for your account, the current organization, + and the current project when you're in one; and help links such as **Documentation** and **API**. +- **Project Actions:** **Open Project**, **Project Stacks**, **Project Events**, **Project API Keys**, **Project + Webhooks & Integrations**, **Project Source Maps**, **Project Notifications**, **Client Setup**, **Generate Sample + Data**, and **Reset Project Data**. Pick an action, then pick the project. +- **Guided Tours:** opens the tour list. +- **Exie:** **Ask Exie**, **Triage Recent Errors**, and **Analyze Error Trends**, when [Exie](/docs/ai/exie/) is + available. +- **Organizations:** **Switch to** another organization, **Switch Organization**, **View Organization Users**, **Invite + User**, and **Add Organization**. +- **Actions:** **Toggle Theme**, **Refresh Current View**, **Open User Menu**, **Keyboard Shortcuts**, **Log Out**, and + **Chat with Support** where support chat is available. + +Many items match related words too. For example, typing `members` finds **Users**, and `MCP` finds **AI Tools**. + +## Keyboard shortcuts + +Press ? to see this list in the app. + +| Key | Action | +| ---------------- | ------------------------------------------------------------ | +| I | Go to **Stacks** | +| E | Go to **Events** (all events) | +| / | Open the command palette | +| A | Open or close [Exie](/docs/ai/exie/), when Exie is available | +| O | Open the organization switcher | +| U | Open the user menu | +| ? | Show the keyboard shortcuts | +| Enter | Open the selected command, or the focused row in a list | +| Space | Toggle the focused checkbox in a list | +| Esc | Close the command palette, menus, and popovers | + +The single-key shortcuts don't fire while you're typing in a field, while you hold Ctrl, Cmd, or +Alt, or while a menu or dialog is open. + +Other places where the keyboard helps: + +- In Exie, Enter sends your message and Shift+Enter adds a new line. +- During a guided tour, Esc ends the tour, and ← and → move between steps while a tour + button has focus. + +## Guided tours + +Guided tours highlight parts of the app and explain them, one step at a time. To open the list, choose **Guided Tours** +in the command palette, or open the user menu and choose **Help** > **Guided Tours**. + +| Tour | What it shows | Available when | +| ------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------- | +| **Explore Exceptionless** | Stacks, events, the filter bar, saved views, Exie, and the command palette, in about a minute. | You have an organization. | +| **Configure a project** | Creating an organization and project, and connecting your app on the **Client Setup** page. | Always. | +| **Create a saved view** | Saving a set of filters as a view you can come back to. | You have an organization. | +| **Investigate an error** | Opening an error, seeing its impact, and reading what happened. | Your projects have at least one error. | +| **Meet Exie** | Opening Exie and asking your first question. | Exie is available to you. | + +Each tour shows **Start**, **Continue** if you left it partway through, or **Restart** if you've finished it. Finished +tours are marked **Completed**. If a tour isn't available yet, the list says why, such as **Send an error report before +starting this guide.** + +When you first sign in, a **Welcome to Exceptionless** card suggests a tour until you start one or close the card: +**Continue setup** if you haven't connected an app yet, or **Explore Exceptionless** if you have. **Browse guides** +opens the full list. + +## Ask Exie + +[Exie](/docs/ai/exie/) is on Medium plans and up. These are the prompts behind the command palette's Exie commands: + +```prompt exie +Triage the most important recent errors in the current context. Summarize their impact, likely causes, and the next investigation steps. +``` + +```prompt exie +Analyze error trends in the current context over the last 7 days. Highlight spikes, regressions, and the issues that deserve attention first. +``` diff --git a/docs/docs/notifications.md b/docs/docs/notifications.md index f3b3beabc5..061fccdfd3 100644 --- a/docs/docs/notifications.md +++ b/docs/docs/notifications.md @@ -1,19 +1,125 @@ --- title: "Notifications" -metaTitle: "Exceptionless email notification settings" -description: "Turn on Exceptionless email notifications from the Notifications tab in your account settings, then choose which notifications you get for each project." +metaTitle: "Exceptionless email and Slack notifications" +description: "Get an email or Slack message when a new error, critical error, or regression happens, and a daily summary of each project's errors." +sources: + - src/Exceptionless.Web/ClientApp/src/routes/(app)/account/notifications/+page.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/projects/components/user-notification-settings-form.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/projects/components/integration-notification-settings-form.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/integrations/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/manage/+page.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/stack-options-dropdown-menu.svelte + - src/Exceptionless.Core/Pipeline/070_QueueNotificationAction.cs + - src/Exceptionless.Core/Jobs/EventNotificationsJob.cs + - src/Exceptionless.Core/Jobs/DailySummaryJob.cs + - src/Exceptionless.Core/Jobs/WebHooksJob.cs + - src/Exceptionless.Core/Models/Stack.cs + - src/Exceptionless.Core/Models/User.cs + - src/Exceptionless.Core/Extensions/ProjectExtensions.cs + - src/Exceptionless.Core/Services/SlackService.cs + - src/Exceptionless.Web/Api/Handlers/ProjectHandler.cs + - Exceptionless.Net:src/Exceptionless/EventBuilder.cs + - Exceptionless.JavaScript:packages/core/src/EventBuilder.ts --- # Notifications -To turn on email notifications, click your name at the bottom of the sidebar and choose **Notifications**. You can also open **Account** from the same menu and click the **Notifications** tab. +Exceptionless can email you, or post to a Slack channel, when something happens in a project that needs attention: a new +error, a critical error, or a regression. It can also email you a summary of each project's errors once a day. -Make sure **Enable Email Notifications** is turned on. You must verify your email address before Exceptionless sends you email notifications. +Notification settings are per user and per project. Each person in the organization chooses what they get. -Under **Project Notifications**, select the project you want to edit notifications for, and then turn on the notifications you want to receive for that project: **Daily Project Summary**, **New Errors**, **Critical Errors**, **Error Regressions**, **New Events**, and **Critical Events**. The event notifications require a paid plan. Changes save automatically. +## Which events notify + +| Notification | Sent when | Plan | +| ------------------------- | ------------------------------------------------------------------------------------------ | ---------- | +| **New Errors** | An error happens that starts a new stack. | Paid plans | +| **Critical Errors** | An error marked critical happens. | Paid plans | +| **Error Regressions** | An event happens in a stack marked fixed, so the stack [regresses](/docs/versioning/). | Paid plans | +| **New Events** | An event of any type starts a new stack, such as a new log message, 404, or feature usage. | Paid plans | +| **Critical Events** | An event of any type marked critical happens. | Paid plans | +| **Daily Project Summary** | Once a day, by email only. | All plans | + +An event is critical when its stack has **Future Occurrences Are Critical** turned on (see +[Stacks](/docs/managing-stacks/)), or when your code marks it with `MarkAsCritical()` in .NET or `markAsCritical()` in +JavaScript. + +To keep notifications useful when something breaks badly, Exceptionless limits them: + +- After a stack's first two occurrences, that stack sends at most one notification every 15 minutes. +- A project sends notifications for at most 10 events every 30 minutes. +- Regressions are always sent. +- Events from stacks that are fixed, snoozed, ignored, or discarded don't notify. +- Events from bots don't notify. Bots are user agents that look like crawlers or match the project's + [spam detection](/docs/project-settings/#spam-detection) list. + +## Turn on email notifications + +1. Open the user menu at the bottom of the sidebar (or press U) and click **Notifications**. +2. Make sure **Enable Email Notifications** is on. This switch turns all of your notification emails on or off. +3. Under **Project Notifications**, choose the project. +4. Turn on **Daily Project Summary** and the **Event Notifications** you want. Changes save right away. ![Project Notifications settings with the daily summary and event notification switches](/assets/img/docs/notifications-project-settings-light.webp) ---- +You can also click **Notifications** on a project's **General** settings tab to open this page with that project +selected. + +Some things to know: + +- You must verify your email address first. Until you do, the page shows **Email notifications are currently disabled** + with a link to resend the verification email. +- When you create a project, your **Daily Project Summary**, **New Errors**, **Critical Errors**, and **Error + Regressions** notifications start on. Other members of the organization start with nothing turned on for it. +- On the Free plan, the **Event Notifications** switches are turned off, with an **Upgrade now** link. + +## Daily project summary + +The daily summary is an email for one project that covers the previous day, in UTC: + +- the number of errors, how many unique stacks they came from, and how many were new, +- the most frequent error stacks and the newest ones, +- errors in stacks you've marked fixed, +- events that were blocked by a plan limit or rejected for being too big. + +It's sent once a day, after the day it covers ends, to everyone who turned on **Daily Project Summary** for the project. +Projects with no errors that day still get a summary. + +## Send notifications to Slack + +Slack notifications post to one Slack channel per project: + +1. Open the project's settings and click the **Integrations** tab. +2. Click **Connect Slack**, sign in to your Slack workspace, and choose the channel. +3. Back on the **Integrations** tab, use the switches to choose which notifications go to Slack: **New Errors**, + **Critical Errors**, **Error Regressions**, **New Events**, and **Critical Events**. + +New connections start with **New Errors**, **Critical Errors**, and **Error Regressions** on. Slack notifications follow +the same rules and limits as email, need a paid plan, and there's no daily summary in Slack. To stop them, click +**Remove Slack**. + +If Slack keeps rejecting messages, for example because the Exceptionless app was removed from the workspace, +Exceptionless disconnects Slack from the project. Connect it again to resume. + +For webhooks and Zapier, see [Integrations](/docs/integrations/). + +## Self-hosting + +A self-hosted instance needs email settings to send notifications and daily summaries, and a Slack app to show **Connect +Slack**. See [Self-hosting configuration](/docs/self-hosting/configuration/). + +## Ask Exie + +[Exie](/docs/ai/exie/) is on Medium plans and up. + +```prompt exie +Which new errors appeared in this project in the last 24 hours? +``` + +```prompt exie +Mark this stack critical so its future occurrences send critical notifications. +``` -[Next > Log Levels](/docs/setting-log-levels) +```prompt exie +Which stacks regressed this week? +``` diff --git a/docs/docs/organizations.md b/docs/docs/organizations.md new file mode 100644 index 0000000000..059a11cd49 --- /dev/null +++ b/docs/docs/organizations.md @@ -0,0 +1,167 @@ +--- +title: "Organizations and billing" +description: "Create organizations, invite users, change plans, check usage, and view invoices for your Exceptionless organization." +navTitle: "Organizations" +sources: + - docs/_data/plans.json + - src/Exceptionless.Core/Billing/BillingPlans.cs + - src/Exceptionless.Core/Billing/BillingManager.cs + - src/Exceptionless.Core/Authorization/AuthorizationRoles.cs + - src/Exceptionless.Core/Services/OrganizationService.cs + - src/Exceptionless.Web/Api/Handlers/OrganizationHandler.cs + - src/Exceptionless.Web/Api/Handlers/AuthHandler.cs + - src/Exceptionless.Web/ClientApp/src/routes/(app)/organization/routes.svelte.ts + - src/Exceptionless.Web/ClientApp/src/routes/(app)/organization/[organizationId]/routes.svelte.ts + - src/Exceptionless.Web/ClientApp/src/routes/(app)/organization/[organizationId]/manage/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/organization/[organizationId]/users/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/organization/[organizationId]/billing/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/organization/[organizationId]/usage/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/organization/add/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/organization/list/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/payment/[id]/+page@.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/(components)/layouts/sidebar-user.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/(components)/layouts/sidebar-organization-switcher.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/billing/components/change-plan-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/billing/invoice.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/users/components/invite-user-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/users/components/table/options.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/users/components/table/user-actions-cell.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/organizations/components/table/organization-actions-cell.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/organizations/components/notifications/free-plan-notification.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/organizations/components/notifications/monthly-overage-notification.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/organizations/components/notifications/hourly-overage-notification.svelte +--- + +# Organizations and billing + +An organization holds your projects, the users who can see them, and the plan you pay for. Plan limits, such as events +per month and the number of users, apply to the whole organization. This page covers organization settings, users, +plans, usage, and invoices. + +## Open organization settings + +Any of these opens the current organization's settings: + +- the user menu at the bottom of the sidebar (U) > **Manage Organization** or **Billing**, +- the organization switcher at the top of the sidebar (O) > **Manage Organization**, +- **Settings** > **Organizations** in the sidebar, then click the organization. + +The settings have these tabs: **General**, **Users**, **Billing**, and **Usage**. + +To switch to another organization, use the organization switcher, or press / and type its name. See +[Navigating the app](/docs/navigation/). + +## Create an organization + +1. Open the organization switcher and click **Add Organization**, or click **+** (**Add Organization**) on **Settings** + > **Organizations**. +2. Enter an **Organization Name** and a **Project Name**, then click **Continue**. +3. Connect your app on the **Client Setup** page that opens. See [Quickstart](/docs/getting-started/). + +New organizations start on the Free plan. You can belong to only one organization on the Free plan, so to create another +organization, upgrade the Free one first. + +## Change organization settings + +On the **General** tab: + +- Click the icon to upload an organization icon (PNG, JPEG, GIF, or WebP). The **X** button next to it removes it. +- Edit the **Organization name**. It saves as you type. +- **View Events** and **View Projects** open the organization's events and projects. + +## Users and invites {#users-and-invites} + +Everyone in an organization has the same access: they can see all of its projects and events, change settings, invite +and remove users, and manage billing. There are no per-user roles, so invite only people you trust with all of that. To +give a tool limited access instead, use a [client API key](/docs/project-settings/#api-keys) or a +[connected application](/docs/account/#connected-applications). + +To invite someone: + +1. Open the **Users** tab and click **+** (**Invite User**). You can also choose **Invite User** in the command palette. +2. Enter their **Email Address** and click **Invite User**. + +If the email address already has an Exceptionless account, that user joins the organization right away and gets an email +about it. Otherwise, Exceptionless emails them an invitation, and they join when they sign up from it. Pending +invitations show in the list with the date in the **Invited** column. + +From a user's menu (**...**) in the list: + +- **Resend Invite Email** sends a pending invitation again. +- **Revoke Invite** cancels a pending invitation. +- **Remove User** takes a member out of the organization. Their private [saved views](/docs/saved-views/) and their + [notification settings](/docs/notifications/) for the organization's projects are deleted. + +Pending invitations count toward your plan's user limit. An organization always keeps at least one user. + +To leave an organization yourself, open **Settings** > **Organizations**, open the organization's menu (**...**), and +click **Leave Organization**. + +## Plans + +| Plan | Includes | +| ------------ | ---------------------------------------------------------------------------------------------------------------------- | +| Free | Error and log monitoring, the daily project summary, and the MCP server. | +| Small | Everything in Free, plus event notifications by email and Slack, webhooks, sessions, and filtering on any event field. | +| Medium | Everything in Small, plus [Exie](/docs/ai/exie/). | +| Large and up | Everything in Medium, with unlimited projects and users. | + +Plans differ in events per month, data retention, and the number of projects and users. See +[Limits](/docs/concepts/limits/) for the numbers and what happens when you reach them, and [pricing](/pricing/) for +prices. Yearly billing is available for every paid plan and costs the same as 11 months. + +When the organization reaches a limit, the app shows a banner, such as **has reached its monthly plan limit** or +**Events are currently being throttled**, with an **Upgrade now** link. + +## Change your plan + +1. Open the **Billing** tab and click **Change your plan or billing information**. The **Manage subscription** dialog + opens. **Upgrade now** links in the app open the same dialog. +2. Choose **Monthly** or **Yearly**, then choose a plan. Choose **Free** to cancel your paid plan. +3. For a paid plan, enter a card under **Payment method**, or keep the card on file. +4. To use a coupon, click **Have a coupon code?**, enter it, and click **Apply**. +5. Click the button at the bottom, such as **Start Small monthly**, **Switch to Large**, or **Downgrade to Free**. + +Plan changes take effect right away and are prorated: you pay the difference when you upgrade, and get a prorated credit +when you downgrade. To update only your card, choose **Use a different payment method**, enter it, and click **Update +payment method**. + +You can't move to a plan that allows fewer users or projects than you have. The dialog tells you how many to remove +first, and pending invitations count as users. + +## Usage + +The **Usage** tab shows how many events the organization has left this billing period and when the count resets. The +chart shows **Total** events against the **Limit**, along with **Blocked**, **Discarded**, **Too Big**, and **Deleted** +events. Each project's settings have a **Usage** tab too. See [Limits](/docs/concepts/limits/) for what each line means. + +## Invoices + +The **Billing** tab lists your payments with their **Payment Number**, **Date**, **Amount**, and **Status**, such as +**Paid**, **Payment due**, or **Credit issued**. Click a payment, or choose **View Payment** from its menu, to open a +receipt that you can print or save. + +## Delete an organization + +1. Delete the organization's projects first. See [Projects](/docs/project-settings/#delete-a-project). +2. On the **General** tab, click **Delete** > **Delete Organization**, and confirm. + +You can't delete an organization that still has projects. You also can't delete one that has had a paid subscription: +the app shows **An organization cannot be deleted if it has a subscription.** Contact support to close it. + +## Self-hosting + +Self-hosted instances usually run without billing. New organizations then get an unlimited plan, the **Billing** tab has +no plan to change, and the **Usage** tab says monthly usage isn't available. See [Self-hosting](/docs/self-hosting/). + +## Ask Exie + +[Exie](/docs/ai/exie/) is on Medium plans and up. + +```prompt exie +List the projects in this organization and when each one last received an event. +``` + +```prompt exie +How many events did this project receive each day this week? +``` diff --git a/docs/docs/project-settings.md b/docs/docs/project-settings.md index 36ecd7ee26..acdf0cf2c3 100644 --- a/docs/docs/project-settings.md +++ b/docs/docs/project-settings.md @@ -1,163 +1,240 @@ --- -title: "Project Settings" -description: "Configure Exceptionless project settings: API keys, data exclusions, error stacking, spam detection, client configuration values, and event exclusions." +title: "Projects" +metaTitle: "Exceptionless project settings" +description: "Manage a project's API keys, client configuration values, data exclusions, stacking and spam settings, source maps, and reset or delete the project." +sources: + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/routes.svelte.ts + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/+layout.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/manage/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/api-keys/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/settings/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/configuration-values/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/source-maps/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/stacks/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/usage/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/list/+page.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/tokens/project-token.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/tokens/components/table/token-actions-cell.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/projects/components/table/config-options.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/projects/components/dialogs/add-project-config-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/projects/components/dialogs/reset-project-data-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/projects/components/dialogs/remove-project-dialog.svelte + - src/Exceptionless.Core/Models/Collections/SettingsDictionary.cs + - src/Exceptionless.Core/Extensions/ProjectExtensions.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/0_ThrottleBotsPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/40_RequestInfoPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/45_EnvironmentInfoPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/90_RemovePrivateInformationPlugin.cs + - src/Exceptionless.Core/Configuration/AppOptions.cs + - src/Exceptionless.Web/Api/Endpoints/ProjectEndpoints.cs + - src/Exceptionless.Web/Utility/Headers.cs + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs + - Exceptionless.Net:src/Exceptionless/ExceptionlessClient.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/010_EventExclusionPlugin.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/110_IgnoreUserAgentPlugin.cs + - Exceptionless.Net:src/Exceptionless/Extensions/StringExtensions.cs + - Exceptionless.JavaScript:packages/core/src/ExceptionlessClient.ts + - Exceptionless.JavaScript:packages/core/src/configuration/Configuration.ts + - Exceptionless.JavaScript:packages/core/src/plugins/default/EventExclusionPlugin.ts --- -# Project Settings +# Projects -Exceptionless is different from most error monitoring services in that it provides you with real-time updates. That includes updates from your Exceptionless project settings to your client. What does that mean? +A project is one app or service that sends events to Exceptionless. Each project has its own API keys and settings. This +page covers every project setting: API keys, client configuration values, data exclusions, stacking, spam detection, +source maps, and resetting or deleting a project. -All project settings are synced to the client in almost real time, so when an event is submitted to Exceptionless we send down a response header with the current configuration version. If a newer version is available we will immediately retrieve and apply the latest configuration. We will also periodically check for newer configuration when the client is idle. +## Open a project's settings -By default the client will check after `5 seconds` on client startup (*if no events are submitted on startup*) and then every `2 minutes` after the last event submission for updated configuration settings. +In the sidebar, open **Settings** > **Projects** and click the project. The settings page has these tabs: -- Checking for updated settings doesn't count towards plan limits. -- Only the current configuration version is sent when checking for updated settings (no user information will ever be sent). -- If the settings haven't changed, then no settings will be retrieved. +- **General**: the project name, shortcuts, and the reset and delete buttons. +- **API Keys**: client API keys and source map upload tokens. +- **Settings**: the default log level, data exclusions, error stacking, source maps, and spam detection. +- **Configuration**: client configuration values. +- **Integrations**: Slack, webhooks, and Zapier. See [Integrations](/docs/integrations/). +- **Stack Management**: every stack in the project, including ignored and discarded ones you want to restore. See + [Stacks](/docs/managing-stacks/). +- **Usage**: the project's event history against the organization's plan limit, including blocked, discarded, too big, + and deleted events. -You can also **turn off the automatic updating of configuration settings when idle** in each client respectively. Please see the [client specific documentation](#client-configuration). +The **General** tab also has **Go To Stacks**, **Client Setup** (install a client and send your first event), +**Notifications** (your own email notifications for this project, see [Notifications](/docs/notifications/)), and +**Generate Sample Data**, which queues sample events so you can try the app. -Now, let's take a look at the available settings for your projects. There are quite a few, so feel free to jump to the section that interests you below: +You can also reach most of these from the command palette: press / and type **Project**. See +[Navigating the app](/docs/navigation/). - -- [API Keys](#api-keys) -- [Data Exclusions](#data-exclusions) - - [Example usage](#example-usage) -- [Error Stacking](#error-stacking) - - [User Namespaces](#user-namespaces) - - [Common Methods](#common-methods) -- [Spam Detection](#spam-detection) - - [Automatic Spam Detection](#automatic-spam-detection) -- [Client Configuration](#client-configuration) -- [Event Exclusions](#event-exclusions) - - [Example](#example) -- [Using Client Configuration Settings](#using-client-configuration-settings) +## API keys {#api-keys} ---- - - +![API Keys tab with the Add token menu open](/assets/img/docs/project-settings-api-keys-light.webp) -## API Keys +The same menu has **Edit Notes**, **Disable Token** (or **Enable Token**), and **Delete**. A disabled key is struck +through in the list and stops working until you enable it again. To rotate a key, add a new one, deploy it, then disable +or delete the old one. -Before doing anything, you want to create an API Key for your project. This protects you and your team by ensuring you are using a revokable key. Instead of using a user-scoped key that would provide access to everything, a project-scoped key is limited to—you guessed it—a single project. +To install a client with the key, open **Client Setup** on the **General** tab or see [Choose a client](/docs/clients/). -To open your project settings, go to **Settings** > **Projects** in the sidebar and click your project. The settings page has tabs for **General**, **API Keys**, **Settings**, **Configuration**, **Integrations**, **Stack Management**, and **Usage**. +## Client configuration values {#client-configuration} -To generate an API Key, click the **API Keys** tab, click **Add token**, and choose **Client API key**. The same menu also creates a **Source map upload token** for uploading source maps from CI/CD. +Client configuration values are key-value pairs that you set on the project and that the Exceptionless clients download +while your app runs. Use them to change your app's behavior without a redeploy, for example to turn a feature on or off +or to drop a noisy kind of event. -![API Keys tab with the Add token menu open](/assets/img/docs/project-settings-api-keys-light.webp) +To add one: -## Data Exclusions +1. Open the **Configuration** tab. +2. Click **+** (**Add Configuration Value**). +3. Enter a **Key** and a **Value**, then click **Add Configuration Value**. -Data can be excluded from your error reports by specifying the information you'd like excluded. This is especially important when you are dealing with sensitive information. For example, an error on log in might, by default, send a user's password to our server. You probably don't want that, so you can exclude that type of data from being sent. For more on how we handle security issues, check out our [security page](/docs/security). +![Configuration tab listing a project's client configuration values](/assets/img/docs/project-settings-configuration-light.webp) -To get started, go to your project settings page and click the **Settings** tab. The **Data Exclusions** section is near the top. +To change or remove a value, open its menu (**...**) and click **Edit** or **Delete**. -![Data Exclusions section on the project Settings tab](/assets/img/docs/project-settings-data-exclusions-light.webp) +The table doesn't list the values that the **Settings** tab manages: `@@DataExclusions`, `@@IncludePrivateInformation`, +`@@UserAgentBotPatterns`, `@@log:*`, `UserNamespaces`, and `CommonMethods`. -Enter a comma delimited list of field names that should be removed from any error report data (e.g., extended data properties, form fields, cookies and query parameters). You can also specify a field name with wildcards `*` to specify starts with, ends with, or contains just to be extra safe. Changes save automatically when you leave the field. +### How values reach your app -Turn on the switch below the field to automatically remove user identifiable information from events, such as the machine name, user information, and IP addresses. +The .NET and JavaScript clients keep their copy up to date: -### Example usage +- Every response to an event submission includes the project's current configuration version in the + `X-Exceptionless-ConfigVersion` header. If it's newer than the client's copy, the client downloads the new values. +- When the app is idle, the client also checks for changes: 5 seconds after startup, then every 2 minutes. +- A check sends only the client's current version, and downloads values only when they've changed. Checks don't count + toward your plan's event limit. -- Entering `Password` will remove any field **named** `Password` from the report. -- Entering `Password*` will remove any field that **starts with** `Password` from the report. -- Entering `*Password` will remove any field that **ends with** `Password` from the report. -- Entering `*Password*` will remove any field that **contains** `Password` from the report. +You can change the idle interval, or turn idle checks off, in each client's configuration. A custom client can download +the values itself with `GET /api/v2/projects/config` and its client API key. ---- +To read values and react to changes in your code, see the client pages: -## Error Stacking +- [.NET client configuration values](/docs/clients/dotnet/client-configuration-values/) +- [JavaScript client configuration values](/docs/clients/javascript/client-configuration-values/) -You can also control how errors are stacked by specifying user namespaces (if you application code utilizes namespaces) or common methods (in all apps) to ignore. Let's take a look at how each works. +### Discard events with configuration values -### User Namespaces +The clients discard events whose type and source match a key in the form `@@EVENT_TYPE:SOURCE` with the value `false`. +The source can contain `*` as a wildcard. For errors, the source is the exception type, and the clients check inner +exceptions too. -If your app runs on .NET or other languages that support namespaces, you can define what namespaces your code runs in. This allows Exceptionless to pick a stacking target within your code. +| Key | Value | What it discards | +| -------------------------------------- | ------- | ------------------------------------------------ | +| `@@error:System.ArgumentNullException` | `false` | Errors with an `ArgumentNullException` | +| `@@error:*` | `false` | All errors | +| `@@404:*` | `false` | All 404 events | +| `@@404:/favicon.ico` | `false` | 404 events for one path | +| `@@usage:*` | `false` | All [feature usage](/docs/feature-usage/) events | -You can set this up on the project settings page in the **Settings** tab, under **Error Stacking** > **User Namespaces**. You simply need to provide a comma delimited list of the namespace names that your applications code belongs to. If this value is set, only methods inside of these namespaces will be considered as stacking targets. +Log events work the same way, except the value is a minimum log level: `Trace`, `Debug`, `Info`, `Warn`, `Error`, +`Fatal`, or `Off`. The **Default Log Level** on the **Settings** tab sets `@@log:*`, and a key such as +`@@log:*AuthController` overrides it for matching log sources. See [Logs and log levels](/docs/setting-log-levels/). -### Common Methods +## Data exclusions {#data-exclusions} -Slightly different from your namespace definitions above, defining common methods here will *exclude* stacks from building up for specified methods. This is important as you may have catch-all methods in your code or specific methods that you expect to have frequent errors you'd rather not pass to Exceptionless. +Data exclusions remove fields you don't want stored, such as passwords or card numbers, from your events. They're on the +**Settings** tab, under **Data Exclusions**. -You can set this up on the project settings page in the **Settings** tab, under **Error Stacking** > **Common Methods**. Simply supply a comma delimited list of common method names that should not be used as stacking targets. +![Data Exclusions section on the project Settings tab](/assets/img/docs/project-settings-data-exclusions-light.webp) ---- +Enter a comma-separated list of field names. Matching is case-insensitive, and `*` is a wildcard: -## Spam Detection +| Entry | Removes fields that | +| ------------ | --------------------- | +| `Password` | are named `Password` | +| `Password*` | start with `Password` | +| `*Password` | end with `Password` | +| `*Password*` | contain `Password` | -Spam detection allows you to prevent noise from being tracked. Bots crawling your site or app can contribute to stacks that you simply do not want to see or track. We make it easy to filter these out. +The clients remove matching fields from the data they collect, such as extended data properties, form fields, cookies, +and query string parameters, before an event leaves your app. The server also removes matching cookies, query string +parameters, and POST data fields from every event it receives, so those exclusions apply even to clients that don't +support them. Changes save when you leave the field. -On your project settings page, click the **Settings** tab and scroll down to the **Spam Detection** section. There, you can specify a comma delimited list of user agents that should be ignored client side. This list supports wildcards and by default covers a vast majority of bots. +Turn on **Automatically remove user identifiable information from events** to have the server strip personal data from +every event in the project: the user identity, the email address on user descriptions, IP addresses, the machine name, +cookies, query string parameters, and POST data. -![Spam Detection section on the project Settings tab](/assets/img/docs/project-settings-spam-detection-light.webp) +For what each client collects and the settings that control it in code, see [Security and privacy](/docs/security/) and +the [.NET private information](/docs/clients/dotnet/private-information/) page. -### Automatic Spam Detection +## Error stacking -We also provide you with a simple tool to automatically detect spam from a single IP address sending in a high volume of activity. Turn on the switch below the user agent list, and we will automatically hide high volumes of events coming from a single client IP address. +The **Error Stacking** section of the **Settings** tab controls which stack frame Exceptionless uses to group errors +into stacks: ---- +- **User Namespaces**: a comma-separated list of the namespaces your code is in, such as `Contoso`. When set, only + methods in these namespaces are used as stacking targets. +- **Common Methods**: a comma-separated list of method names, such as `Assert`, that should never be used as stacking + targets. Use it for shared helpers that throw for many unrelated reasons. -## Client Configuration +Changes apply to new errors. See [Stacking](/docs/concepts/stacking/) for how Exceptionless picks a stack. -Custom client configuration values allow you to control the behavior of your app in real time. They are a dictionary of key value pairs (string key, string value). Usage examples include controlling data exclusions to protecting sensitive data and or enabling/disabling features. +## Source maps -To set up custom client configurations, go to **Settings** > **Projects** in the sidebar and click your project. On the project settings page, click the **Configuration** tab. Click the **+** (Add Configuration Value) button, enter a **Key** and **Value**, and click **Add Configuration Value**. +Exceptionless downloads public source maps for minified JavaScript automatically. To upload private maps, click **Manage +source maps** under **JavaScript Source Maps** on the **Settings** tab, or create a **Source map upload token** on the +**API Keys** tab for your build pipeline. See [Source maps](/docs/clients/javascript/source-maps/). -![Configuration tab listing a project's client configuration values](/assets/img/docs/project-settings-configuration-light.webp) +## Spam detection {#spam-detection} -Once you have made changes to your Project Settings, the configuration values will only be read by your client if your client is aware of the configuration. This happens out of the box with the [Exceptionless .NET Client](/docs/clients/dotnet/) and the [Exceptionless JS Client](/docs/clients/javascript/). If you are building your own client or simply wrapping our API, you can still make use of these configuration values by reading them in periodically via a `GET` request to `/api/v2/projects/{id}/config`. +The **Spam Detection** section of the **Settings** tab filters out bots and crawlers. -## Event Exclusions +![Spam Detection section on the project Settings tab](/assets/img/docs/project-settings-spam-detection-light.webp) -The Exceptionless clients have the ability to automatically discard events based on client configuration settings. We have a plugin that looks at the client configuration settings using a simple key name convention. +- **User agents**: a comma-separated list of user agent patterns, with `*` wildcards. New projects start with + `*bot*,*crawler*,*spider*,*aolbuild*,*teoma*,*yahoo*`. The .NET and JavaScript clients don't send events from requests + whose user agent matches. The server marks matching events as bots and doesn't send notifications for them. +- **Reduce noise by automatically hiding high volumes of events coming from a single client IP address**: when more than + 25 events arrive from one public IP address within five minutes, the server discards them and deletes the events from + that window. This needs IP addresses, so it doesn't apply while the project removes user identifiable information. -To help us understand this consider that every event has a `Type` and `Source` property. The `Type` can be anything but we have a few first class types like [`error`, `usage`, `log`, `404`, `session`](https://github.com/exceptionless/Exceptionless/blob/master/src/Exceptionless.Core/Models/Event.cs#L92-L100). `Source` is usually set to the exception type when dealing with `error` events or the `log` source. +## Reset project data -With that said, you can exclude any event type and source by adding a new client configuration key `@@EVENT_TYPE:SOURCE` by replacing the `EVENT_TYPE` and `SOURCE` respectively and specify a configuration value of `false`. *You can also specify a wild card `*` as part of the `SOURCE`.* +Resetting deletes every event and stack in the project and keeps its settings, API keys, and integrations. Use it to +start fresh after testing. -### Example +1. On the **General** tab, click the warning button (**Reset project data**). +2. Click **Reset Project Data** to confirm. -- To discard all errors of type `System.ArgumentNullException`: - - **KEY:** `@@error:System.ArgumentNullException` - - **VALUE:** `false` +The reset runs in the background and can't be undone. -- To discard all errors in general you would use a wildcard `*`: - - **KEY:** `@@error:*` - - **VALUE:** `false` +## Delete a project {#delete-a-project} -- To discard all 404s in general you would use a wildcard `*`: - - **KEY:** `@@404:*` - - **VALUE:** `false` +1. On the **General** tab, click the **X** button (**Delete project**). +2. Click **Delete Project** to confirm. -- To discard all 404s for a specific resource, use the resource's event source as the key. - - **KEY:** `@@404:/invalid-file-path.jpg` - - **VALUE:** `false` +The project and its data are queued for deletion. You can also delete a project from its menu (**...**) on the +**Projects** list. -We have also added some additional known values to support **minimum log levels**. The known values are: `Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`, `Off`. +## Ask Exie -- Sets a minimum log level of `Info` for my application: - - **KEY:** `@@log:*` - - **VALUE:** `Info` +[Exie](/docs/ai/exie/) is on Medium plans and up. -- You can also set a log level on a per log source basis. This will override any general minimum log level (e.g., `@@log:*` you have defined! - - **KEY:** `@@log:*AuthController` - - **VALUE:** `Trace` +```prompt exie +List my projects and when each one last received an event. +``` -## Using Client Configuration Settings +```prompt exie +How do I send events from my ASP.NET Core app to this project? +``` -- [.NET](/docs/clients/dotnet/client-configuration-values) -- [JavaScript / Node.js](/docs/clients/javascript/client-configuration-values) +```prompt exie +Which error types happened most in this project over the last 7 days? +``` ---- +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can set up a client for you: -[Next > Versioning](/docs/versioning) +```prompt agent +Get the Exceptionless client setup for my project and add Exceptionless to this app. Read the API key from configuration instead of hard-coding it. +``` diff --git a/docs/docs/reference/client-spec.md b/docs/docs/reference/client-spec.md new file mode 100644 index 0000000000..3cf6099210 --- /dev/null +++ b/docs/docs/reference/client-spec.md @@ -0,0 +1,301 @@ +--- +title: "Client specification" +description: "What every Exceptionless client does: authentication, batching, the offline queue, retries and status codes, configuration sync, sessions, and data exclusions." +navTitle: "Client specification" +sources: + - src/Exceptionless.Web/Api/Endpoints/EventEndpoints.cs + - src/Exceptionless.Web/Api/Endpoints/ProjectEndpoints.cs + - src/Exceptionless.Web/Api/Handlers/EventHandler.cs + - src/Exceptionless.Web/Api/Filters/ConfigurationResponseEndpointFilter.cs + - src/Exceptionless.Web/Utility/Headers.cs + - src/Exceptionless.Web/Utility/Handlers/OverageMiddleware.cs + - src/Exceptionless.Web/Utility/Handlers/ThrottlingMiddleware.cs + - src/Exceptionless.Web/Utility/Handlers/ProjectConfigMiddleware.cs + - src/Exceptionless.Web/Utility/Handlers/RecordSessionHeartbeatMiddleware.cs + - src/Exceptionless.Web/Extensions/HttpExtensions.cs + - src/Exceptionless.Web/Security/ApiKeyAuthenticationHandler.cs + - src/Exceptionless.Core/Configuration/AppOptions.cs + - src/Exceptionless.Core/Models/ClientConfiguration.cs + - src/Exceptionless.Core/Models/Collections/SettingsDictionary.cs + - src/Exceptionless.Core/Jobs/EventPostsJob.cs + - src/Exceptionless.Core/Jobs/CloseInactiveSessionsJob.cs + - src/Exceptionless.Core/Pipeline/001_CheckEventDateAction.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/05_CheckForDuplicateReferenceIdPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/07_SubmissionClientPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/70_SessionPlugin.cs + - Exceptionless.Net:src/Exceptionless/Submission/DefaultSubmissionClient.cs + - Exceptionless.Net:src/Exceptionless/Queue/DefaultEventQueue.cs + - Exceptionless.Net:src/Exceptionless/Configuration/ExceptionlessConfiguration.cs + - Exceptionless.Net:src/Exceptionless/Configuration/SettingsManager.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/010_EventExclusionPlugin.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/025_SessionIdManagementPlugin.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/100_HeartbeatPlugin.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/910_DuplicateCheckerPlugin.cs + - Exceptionless.JavaScript:packages/core/src/submission/DefaultSubmissionClient.ts + - Exceptionless.JavaScript:packages/core/src/queue/DefaultEventQueue.ts + - Exceptionless.JavaScript:packages/core/src/configuration/Configuration.ts + - Exceptionless.JavaScript:packages/core/src/configuration/SettingsManager.ts + - Exceptionless.JavaScript:packages/core/src/plugins/default/EventExclusionPlugin.ts + - Exceptionless.JavaScript:packages/core/src/plugins/default/SessionIdManagementPlugin.ts + - Exceptionless.JavaScript:packages/core/src/plugins/default/HeartbeatPlugin.ts + - Exceptionless.JavaScript:packages/core/src/plugins/default/DuplicateCheckerPlugin.ts +--- + +# Client specification + +This page defines what an Exceptionless client does. It is the contract for new official clients and for community +clients, and it describes how the .NET and JavaScript clients behave today. "Must" marks behavior the server depends on; +"should" marks behavior users expect from every client. + +The events themselves are described in [Event format](/docs/reference/event-format/). To send a few events from a script +without writing a client, see [Other languages and custom clients](/docs/clients/custom-clients/). + +## Endpoints {#endpoints} + +All paths are relative to the server URL, `https://api.exceptionless.io` for the hosted service. + +| Method and path | Purpose | +| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| `POST /api/v2/events` | Submit a batch of events. | +| `GET /api/v2/projects/config?v={version}` | Get the project's [configuration values](#configuration-values). | +| `GET /api/v2/events/session/heartbeat?id={id}&close={bool}` | Keep a [session](#sessions) open, or close it. | +| `POST /api/v2/events/by-ref/{referenceId}/user-description` | Attach a user's email address and description to an event. | +| `GET /api/v2/events/submit?type={type}&...` | Submit one event with query string parameters, for platforms that can only make a GET request. | + +## Configuration {#configuration} + +A client must let the app set: + +- **API key.** A client-scoped key from the project's **API Keys** settings (see + [Client-scoped tokens](/docs/api/project-tokens/)). Both official clients treat a key shorter than 10 characters as + invalid and send nothing. +- **Server URL.** Defaults to `https://api.exceptionless.io`. Self-hosted users set it to their own URL. +- **Enabled.** A switch that turns off all submission. + +A client should also let the app set default tags and data added to every event, the app version (`@version`), local +data exclusions, and whether to include private information. + +## Authentication {#authentication} + +Send the API key in the `Authorization` header on every request: + +```http +Authorization: Bearer YOUR_API_KEY +``` + +The server also accepts the key in an `access_token` query parameter. Use that only for `GET /api/v2/events/submit` on +platforms that cannot set headers, because URLs end up in logs. + +## User agent {#user-agent} + +Identify the client with a `name/version` value: + +```http +User-Agent: exceptionless-ruby/1.0.0 +``` + +The server stores the name and version in each event's `@submission_client`. If the platform doesn't let you set +`User-Agent`, as in browsers, send the same value in `X-Exceptionless-Client`; the server prefers it when present. + +Pick a name of your own. The official clients use `exceptionless` (.NET) and `exceptionless-js` (JavaScript), and the +server treats those two names differently when it picks which IP address belongs to the user. + +## Submission and batching {#submission} + +A client must not block the app while it sends events. Both official clients work the same way: + +1. Run plugins on the event (defaults, exclusions, deduplication), then add it to an in-memory queue. +2. Every 10 seconds, take up to 50 events (the default batch size) from the queue. +3. `POST` them to `/api/v2/events` as a JSON array with `Content-Type: application/json`. +4. Remove the batch from the queue when the server responds `202 Accepted`. + +```http +POST /api/v2/events HTTP/1.1 +Host: api.exceptionless.io +Authorization: Bearer YOUR_API_KEY +User-Agent: exceptionless-ruby/1.0.0 +Content-Type: application/json + +[{"type":"log","message":"Order placed","date":"2026-10-27T14:03:12-05:00","data":{"@level":"info"}}] +``` + +Rules for the request body: + +- Send `application/json`. The server also accepts `text/plain`, where each line becomes a log event. Other content + types get `415 Unsupported Media Type`. +- Compress with `Content-Encoding: gzip` or `deflate` if you like. The .NET client compresses bodies over 4 KB. +- Don't send an empty body. A `POST` with `Content-Length: 0` gets `411 Length Required`. +- Keep the body under the server's size limit, 200,000 bytes by default (`MaximumEventPostSize` on self-hosted servers). + A compressed body may expand to ten times the limit; larger payloads are dropped when processed. + +`202 Accepted` means the server stored the payload for processing. Events are parsed and processed in the background, so +an accepted event can still be discarded later, for example when the organization is over its plan limit or the date is +too old. + +## Offline queue {#offline-queue} + +Events stay in the queue until the server accepts them, so a client keeps working while the network or the server is +down. + +- **Cap the queue.** The JavaScript client keeps at most 250 events and drops the oldest. The .NET client deletes queued + events after 7 days or 3 failed attempts. +- **Persist it where you can.** Both clients keep the queue in memory by default. The JavaScript client can store it in + `localStorage` (`usePersistedQueueStorage`), and the .NET client can store it in a folder. +- **Don't hold events too long.** The server discards events dated more than three days in the past. +- **Flush on shutdown.** Process the queue once more when the app exits or the page is hidden. + +## Responses and retries {#responses} + +After each batch, the client decides whether to keep the events and how long to pause. The official clients do this: + +| Status | Meaning | What the client does | +| ------------------------------ | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `202` | Accepted. | Remove the batch. | +| `400` | The request was rejected, for example no project could be found for the key. | Drop the batch and pause for 4 hours. | +| `401`, `403` | The key is missing, wrong, disabled, or its organization is suspended. | Drop the batch and pause for 15 minutes. | +| `402` | The organization has used its plan's events for the month. | Drop the batch, clear the queue, and discard new events until the pause ends. | +| `404` | The project wasn't found, or the server URL is wrong. | Drop the batch and pause for 4 hours. | +| `413` | The body is too large. | Retry with a smaller batch (both clients divide the batch size by 1.5). If a single event is too large, drop it. | +| `429` | Too many requests. See [rate limits](/docs/api/#rate-limits). | Keep the batch and pause. | +| `503` | The server isn't accepting events right now. | Keep the batch and pause. | +| Other errors, network failures | Anything else. | Keep the batch and pause. | + +A pause stops queue processing for a while; events submitted during a pause still go into the queue, except after a +`402`. The .NET client pauses for 5 minutes by default, and the JavaScript client pauses until the next quarter hour. A +client should also slow down when `X-RateLimit-Remaining` reaches `0`. Never retry in a tight loop. + +## Configuration values {#configuration-values} + +Each project has a set of key-value settings, edited in the project's **Configuration** settings, that the server sends +to clients. Clients use them for data exclusions and event filtering, and apps can read their own values. See +[Projects](/docs/project-settings/#client-configuration). + +```http +GET /api/v2/projects/config?v=3 HTTP/1.1 +Authorization: Bearer YOUR_API_KEY +``` + +- If `v` matches the project's current version, the server responds `304 Not Modified`. +- Otherwise it responds `200` with the version and the settings: + +```json +{ + "version": 4, + "settings": { + "@@DataExclusions": "*Password*,CreditCard", + "@@log:*": "info", + "FeatureFlagCheckout": "true" + } +} +``` + +A client must keep settings current: + +1. On startup, load the last saved settings and version, then fetch settings shortly after startup (the official clients + wait 5 to 15 seconds). +2. Read `X-Exceptionless-ConfigVersion` from every `200` or `202` response to an event or user-description submission. + When it's higher than the saved version, fetch settings. +3. While the app is idle, fetch settings on an interval: every 2 minutes by default, and never more often. +4. Save the settings and version so they apply on the next start. Replace the previous server settings; remove keys the + server no longer sends. + +The configuration endpoint and the heartbeat endpoint don't count toward the API rate limit. + +### Reserved settings {#reserved-settings} + +| Key | Value | Used by | +| ----------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| `@@DataExclusions` | Comma-separated patterns. | Clients and the server. See [data exclusions](#data-exclusions). | +| `@@UserAgentBotPatterns` | Comma-separated user agent patterns. | Clients drop events whose request user agent matches. The server marks matching requests as bots. | +| `@@log:{source}` | Minimum log level: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, or `off`, in any case. | Clients drop log events below the level for that source. | +| `@@{type}:{source}` | `false` to drop events of that type and source. | Clients, for types other than `log`. For errors, the source is the exception type, checked for every inner error. | +| `@@IncludePrivateInformation` | `false` to strip private information. | The server only. Clients don't need to read it. | + +`{source}` can be a wildcard pattern. When several keys match, the official clients use the longest key. A log event +with no `@level` is never dropped by level. + +## Data exclusions {#data-exclusions} + +Data exclusions remove sensitive values before an event leaves the app. A client must combine its local exclusions with +the `@@DataExclusions` setting and remove every matching key from: + +- custom data and the `data` of errors and other reserved objects, +- request headers, cookies, query string parameters, and form data. + +Patterns match keys without regard to case. `*` at the start, end, or both matches any text, so `*password*` matches +`UserPassword`. The server also applies the project's exclusions to request data it receives, but the client should not +rely on that. + +## Private information {#private-information} + +A client should let the app turn off sending private information: the user name, machine name, IP address, request +headers, cookies, post data, and query string. Both official clients have one `includePrivateInformation` switch for all +of these. When the project turns off private information in its settings, the server removes the IP address, machine +name, cookies, post data, and query string from events it receives. + +## Deduplication {#deduplication} + +A client should merge repeated events instead of sending each one, so a loop that throws the same error doesn't use up +the plan. Both official clients: + +1. Compute a hash for each event. The .NET client hashes the whole event; the JavaScript client hashes error messages + and stack traces and only deduplicates errors. +2. Remember the last 50 hashes and when they were seen. +3. When an event matches a hash seen within the window (60 seconds in .NET, 30 seconds in JavaScript), hold it instead + of sending it, and add later matches to its `count`. +4. Send held events on a timer that runs once per window, with the total `count` and the latest `date`. + +See [Limits and deduplication](/docs/concepts/limits/#deduplication) for how this looks in the app. + +## Sessions {#sessions} + +Sessions show what a user did between starting and leaving the app. See [Sessions](/docs/user-sessions/). + +**Starting a session.** Submit an event with `type` `session`. There are two ways to tie events to it: + +- **By user.** Set `@user.identity` on every event. The server groups each user's events into sessions automatically. + The .NET client drops a session start event that has no user identity. +- **By session ID.** Generate a session ID (8 to 100 letters, digits, or hyphens; both clients use a GUID without + hyphens). Put it in the session start event's `reference_id`, and add `"@ref:session": ""` to the `data` + of every other event in the session. + +**Heartbeats.** While the session is active, send a heartbeat every minute: + +```http +GET /api/v2/events/session/heartbeat?id=SESSION_ID_OR_USER_IDENTITY HTTP/1.1 +Authorization: Bearer YOUR_API_KEY +``` + +`id` is the session ID, or the user identity when sessions are tied to the user. The official clients send a heartbeat +one minute after the last event and every minute after that, and fall back to one minute if the app asks for an interval +under 30 seconds. The endpoint returns `200`. + +**Ending a session.** Send the heartbeat with `close=true` when the app exits or the user signs out, or submit an event +with `type` `sessionend`. The server also closes a session after 5 minutes with no events or heartbeats. + +## User descriptions {#user-descriptions} + +To let users describe what they were doing when an error happened, show them the event's reference ID and send their +answer to the event later: + +```http +POST /api/v2/events/by-ref/a1b2c3d4e5/user-description HTTP/1.1 +Authorization: Bearer YOUR_API_KEY +Content-Type: application/json + +{"email_address":"ana@example.com","description":"I clicked Pay twice."} +``` + +The server responds `202`. At least one of `email_address` and `description` is required. Clients that support this +should set a `reference_id` on every error event; both official clients can generate a 10-character ID. + +## Environment {#environment} + +A client should let the app set a default deployment environment and override it per event, and send it in the top-level +`environment` field. See [Event format](/docs/reference/event-format/#environment) for the rules and +[Environments](/docs/environments/) for how the app uses it. + +## Errors in the client {#client-errors} + +A client must never throw into the app. Catch errors in plugins, serialization, and network calls, log them to the +client's own log, and keep going. diff --git a/docs/docs/reference/event-format.md b/docs/docs/reference/event-format.md new file mode 100644 index 0000000000..8a92bc77b5 --- /dev/null +++ b/docs/docs/reference/event-format.md @@ -0,0 +1,341 @@ +--- +title: "Event format" +description: "The JSON format of an Exceptionless event: top-level fields, known event types, and the reserved @ data keys for errors, requests, users, and more." +sources: + - src/Exceptionless.Core/Models/Event.cs + - src/Exceptionless.Core/Models/PersistentEvent.cs + - src/Exceptionless.Core/Models/Data/Error.cs + - src/Exceptionless.Core/Models/Data/InnerError.cs + - src/Exceptionless.Core/Models/Data/StackFrame.cs + - src/Exceptionless.Core/Models/Data/Method.cs + - src/Exceptionless.Core/Models/Data/Module.cs + - src/Exceptionless.Core/Models/Data/SimpleError.cs + - src/Exceptionless.Core/Models/Data/RequestInfo.cs + - src/Exceptionless.Core/Models/Data/EnvironmentInfo.cs + - src/Exceptionless.Core/Models/Data/UserInfo.cs + - src/Exceptionless.Core/Models/Data/UserDescription.cs + - src/Exceptionless.Core/Models/Data/ManualStackingInfo.cs + - src/Exceptionless.Core/Models/Data/SubmissionClient.cs + - src/Exceptionless.Core/Models/Data/Location.cs + - src/Exceptionless.Core/Serialization/EventDataNormalizer.cs + - src/Exceptionless.Core/Serialization/EventEnvironmentConverter.cs + - src/Exceptionless.Core/Serialization/JsonSerializerOptionsExtensions.cs + - src/Exceptionless.Core/Plugins/EventParser/EventParserPluginManager.cs + - src/Exceptionless.Core/Plugins/EventParser/Default/JsonEventParserPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/40_RequestInfoPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/07_SubmissionClientPlugin.cs + - src/Exceptionless.Core/Pipeline/001_CheckEventDateAction.cs + - src/Exceptionless.Core/Pipeline/006_TruncateFieldsAction.cs + - src/Exceptionless.Core/Extensions/PersistentEventExtensions.cs + - Exceptionless.JavaScript:packages/core/src/models/Event.ts + - Exceptionless.Net:src/Exceptionless/Models/Client/Event.cs +--- + +# Event format + +Every Exceptionless event is a JSON object. Clients send one object or an array of them to `POST /api/v2/events`, and +the API returns stored events in the same shape with a few extra fields. This page describes each field and the reserved +data keys the server understands. + +Property names are `snake_case`. Dates are ISO 8601 strings with a UTC offset. + +```json +{ + "type": "error", + "source": "CheckoutController.PlaceOrder", + "date": "2026-10-27T14:03:12.512-05:00", + "message": "Payment provider timed out", + "tags": ["checkout", "payments"], + "reference_id": "a1b2c3d4e5", + "environment": "production", + "count": 1, + "data": { + "@simple_error": { + "message": "Payment provider timed out", + "type": "System.TimeoutException", + "stack_trace": " at Payments.Client.ChargeAsync() in Client.cs:line 42" + }, + "@user": { "identity": "user-1042", "name": "Ana Lopez" }, + "@version": "2.4.1", + "order_id": "ORD-55812" + } +} +``` + +## Event fields {#event-fields} + +| Field | Type | Description | +| -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `type` | string | The [event type](#event-types), 1 to 100 characters. When it's missing, the server uses `error` if `data` has `@error` or `@simple_error`, and `log` otherwise. | +| `source` | string | Where the event came from: a logger name, a feature name, a request path, or a machine name. Values longer than 2,000 characters are truncated. | +| `date` | string | When the event happened. When it's missing, the server uses the time it parsed the event. A date in the future is moved to the current time. Events dated more than three days in the past, or older than the organization's retention, are discarded. | +| `message` | string | A short description. Values longer than 2,000 characters are truncated. For errors without a message, the server copies the error's message. | +| `tags` | array of strings | Labels for the event. The server keeps up to 50 tags and drops empty tags and tags longer than 100 characters. The `Critical` tag marks an occurrence as critical. | +| `geo` | string | Coordinates as `"latitude,longitude"`, for example `"32.85,-96.96"`. When it's missing or invalid, the server looks up a location from the IP addresses on the event. | +| `value` | number | A number to attach to the event, such as a duration. Session start events store the session length in seconds here. | +| `count` | integer | How many times this event happened. See [count](#count). | +| `reference_id` | string | An identifier you choose, 8 to 100 letters, digits, or hyphens. See [reference IDs](#reference-ids). | +| `environment` | string | The deployment environment, such as `production` or `staging`. See [environment](#environment). | +| `data` | object | Custom data and the [reserved data keys](#reserved-data-keys). | + +Unknown top-level properties are moved into `data`, so `{"message": "Hi", "@user": {"identity": "42"}}` is the same as +nesting `@user` under `data`. + +### Count {#count} + +`count` is the number of occurrences one event stands for. Clients set it when they merge duplicate events before +sending (see [client-side deduplication](/docs/reference/client-spec/#deduplication)). A missing `count` means one +occurrence. The occurrence counts in stack lists add up `count` across events. + +### Reference IDs {#reference-ids} + +A reference ID lets you find an event later, for example from an error page shown to a user. It must be 8 to 100 +characters long and contain only letters, digits, and hyphens. The server replaces an invalid value with +`invalid-reference-id` and keeps the original in `data.InvalidReferenceId`. + +Within a project, the server discards a second event with the same reference ID that arrives within a day. Clients use +this to make retries safe. See [Reference IDs](/docs/references-ids/) for the support workflow. + +### Environment {#environment} + +`environment` names the deployment the event came from. The server trims it and keeps the casing you send. A value that +is empty, longer than 64 characters, or contains control characters is not used as the environment. It is kept as custom +data instead. See [Environments](/docs/environments/). + +Don't confuse it with the `@environment` data key, which describes the machine and runtime. + +## Event types {#event-types} + +`type` can be any string, but these types have built-in behavior. + +| Type | Meaning | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `error` | An error or exception. Put the details in `@error` or `@simple_error`; errors are stacked by their stack trace. | +| `log` | A log message. Put the level in `@level` and the logger name in `source`. | +| `usage` | Feature usage. Put the feature name in `source`. See [Feature usage](/docs/feature-usage/). | +| `404` | A resource that wasn't found. Include `@request`; when `source` is empty the server sets it to the request method and path. | +| `session` | The start of a session. Its `reference_id` is the session ID. See [Sessions](/docs/user-sessions/). | +| `sessionend` | The end of a session. | +| `heartbeat` | Keeps a session open. The server applies it to the session and discards the event. Clients normally use the [heartbeat endpoint](/docs/reference/client-spec/#sessions) instead. | + +## Reserved data keys {#reserved-data-keys} + +Keys in `data` that start with `@` are reserved for Exceptionless. Everything else in `data` is custom data that appears +on the event's **Extended Data** tab and can be searched (see [Search syntax](/docs/reference/search-syntax/)). + +If a reserved key that expects an object holds something else, such as a plain string in `@user`, the server keeps the +value as custom data under the same key prefixed with `_`, for example `_@user`. + +| Key | Shape | Set by | +| -------------------- | --------------------------------------- | --------------------------------------------------------------------------------- | +| `@error` | [Error](#error) | Clients that can read the full exception. | +| `@simple_error` | [Simple error](#simple-error) | Clients and scripts that only have a message and a trace. | +| `@request` | [Request](#request) | Clients running in a web request or a browser. | +| `@environment` | [Environment info](#environment-info) | Clients that can read the machine and process. | +| `@user` | [User](#user) | The app, to identify the user an event happened to. | +| `@user_description` | [User description](#user-description) | The app, with feedback from the user. | +| `@version` | string | The app version, such as `2.4.1`. Used for regressions. | +| `@level` | string | Log events: `trace`, `debug`, `info`, `warn`, `error`, or `fatal`. | +| `@submission_method` | string | Clients, to record how an event was captured, such as an unhandled error handler. | +| `@stack` | [Manual stacking](#manual-stacking) | The app, to choose which stack an event joins. | +| `@trace` | array of strings | Clients that attach recent log lines to an event. | +| `@ref:` | string | A reference to another event's `reference_id`, such as `@ref:session`. | +| `@submission_client` | [Submission client](#submission-client) | The server. Anything a client sends here is replaced. | +| `@location` | [Location](#location) | The server, from `geo` or the IP address. | +| `sessionend` | string (date) | The server, on a session start event once the session has ended. | + +### Error {#error} + +`@error` holds a structured exception. Inner exceptions nest in `inner`. + +| Field | Type | Description | +| --------------- | ------------------------------- | ------------------------------------------------------------------------- | +| `message` | string | The exception message. | +| `type` | string | The full exception type name, such as `System.InvalidOperationException`. | +| `code` | string | An error code, if the platform has one. | +| `data` | object | Extra values. `@ext` holds additional exception properties. | +| `inner` | object | The inner error, with the same fields except `modules`. | +| `stack_trace` | array of [frames](#stack-frame) | The stack frames. | +| `target_method` | [method](#stack-frame) | The method that threw. | +| `modules` | array of [modules](#module) | Loaded assemblies or scripts. Only on the outermost error. | + +#### Stack frame {#stack-frame} + +A frame is a method plus a location. Methods (`target_method`) have the same fields without `file_name`, `line_number`, +and `column`. + +| Field | Type | Description | +| --------------------- | ---------------- | ------------------------------------------------------------------------------- | +| `name` | string | The method or function name. | +| `declaring_namespace` | string | The namespace or module. | +| `declaring_type` | string | The class or type. | +| `parameters` | array | Objects with `name`, `type`, `type_namespace`, `generic_arguments`, and `data`. | +| `generic_arguments` | array of strings | Generic type arguments. | +| `is_signature_target` | boolean | Marks the frame used to build the stack signature. | +| `module_id` | integer | The `module_id` of the module the frame belongs to. | +| `file_name` | string | The source file or script URL. | +| `line_number` | integer | The line number. | +| `column` | integer | The column number. | +| `data` | object | Extra values. | + +#### Module {#module} + +| Field | Type | Description | +| --------------- | ------- | --------------------------------------- | +| `module_id` | integer | An ID that stack frames refer to. | +| `name` | string | The assembly, package, or script name. | +| `version` | string | The module version. | +| `is_entry` | boolean | Whether this is the app's entry module. | +| `created_date` | string | When the module file was created. | +| `modified_date` | string | When the module file was last modified. | +| `data` | object | Extra values, such as `PublicKeyToken`. | + +### Simple error {#simple-error} + +`@simple_error` is for errors where you only have text. The server stacks simple errors by `type` and a hash of +`stack_trace`. + +| Field | Type | Description | +| ------------- | ------ | ------------------------------------------------- | +| `message` | string | The error message. | +| `type` | string | The error type or class name. | +| `stack_trace` | string | The stack trace as one string. | +| `data` | object | Extra values. `@ext` holds additional properties. | +| `inner` | object | The inner error, with the same fields. | + +### Request {#request} + +`@request` describes the HTTP request or browser page the event happened in. + +| Field | Type | Description | +| ------------------- | ------- | ------------------------------------------------------------------- | +| `user_agent` | string | The request's user agent. | +| `http_method` | string | `GET`, `POST`, and so on. | +| `is_secure` | boolean | Whether the request used HTTPS. | +| `host` | string | The host name. | +| `port` | integer | The port. | +| `path` | string | The path, without the query string. | +| `referrer` | string | The referring URL. | +| `client_ip_address` | string | The client's IP address. Several addresses are separated by commas. | +| `headers` | object | Header names mapped to arrays of values. | +| `cookies` | object | Cookie names mapped to values. | +| `post_data` | any | The form or body data. | +| `query_string` | object | Query parameters mapped to values. | +| `data` | object | Extra values, including the browser and OS keys below. | + +The server applies the project's [data exclusions](/docs/project-settings/#data-exclusions) to headers, cookies, query +parameters, and post data, and truncates long values. When the project excludes private information, it removes the +client IP address, cookies, post data, and query string. + +#### Browser and OS keys {#browser-and-os-keys} + +The server parses `user_agent` and adds these keys to `@request.data`. They are what the browser, OS, and device filters +search. + +| Key | Example | +| ------------------------ | ------------ | +| `@browser` | `Chrome` | +| `@browser_version` | `130.0.6723` | +| `@browser_major_version` | `130` | +| `@device` | `iPhone` | +| `@os` | `Windows` | +| `@os_version` | `10` | +| `@os_major_version` | `10` | +| `@is_bot` | `false` | + +`@is_bot` is `true` when the user agent is a known crawler or matches the project's bot patterns. + +### Environment info {#environment-info} + +`@environment` describes the machine and process. Every field is optional. + +| Field | Type | Description | +| --------------------------- | ------- | ------------------------------------------------------- | +| `processor_count` | integer | Logical processors. | +| `total_physical_memory` | integer | Total memory in bytes. | +| `available_physical_memory` | integer | Free memory in bytes. | +| `command_line` | string | The process command line. | +| `process_name` | string | The process name. | +| `process_id` | string | The process ID. | +| `process_memory_size` | integer | Memory used by the process, in bytes. | +| `thread_name` | string | The current thread name. | +| `thread_id` | string | The current thread ID. | +| `architecture` | string | The CPU architecture, such as `x64`. | +| `o_s_name` | string | The operating system name. | +| `o_s_version` | string | The operating system version. | +| `ip_address` | string | The machine's IP addresses, separated by commas. | +| `machine_name` | string | The host name. | +| `install_id` | string | An ID for this installation of the app. | +| `runtime_version` | string | The runtime version, such as a .NET or Node.js version. | +| `data` | object | Extra values. | + +The OS fields are spelled `o_s_name` and `o_s_version`. When the project excludes private information, the server +removes `ip_address` and `machine_name`. + +### User {#user} + +`@user` identifies the user an event happened to. Events with a user identity are grouped into +[sessions](/docs/user-sessions/) automatically. + +| Field | Type | Description | +| ---------- | ------ | ----------------------------------------------------------------- | +| `identity` | string | A stable ID for the user, such as an account ID or email address. | +| `name` | string | A display name. | +| `data` | object | Extra values. | + +### User description {#user-description} + +`@user_description` holds feedback from the user. You can also add it after the fact with +`POST /api/v2/events/by-ref/{referenceId}/user-description`. + +| Field | Type | Description | +| --------------- | ------ | ------------------------- | +| `email_address` | string | The user's email address. | +| `description` | string | What the user was doing. | +| `data` | object | Extra values. | + +### Manual stacking {#manual-stacking} + +`@stack` overrides how the server groups the event into a stack. See +[Stacking](/docs/concepts/stacking/#manual-stacking). + +| Field | Type | Description | +| ---------------- | ------ | ------------------------------------------------------------------------------------------------ | +| `title` | string | The title for the stack. | +| `signature_data` | object | String keys and values that identify the stack. Events with the same values join the same stack. | + +### Submission client {#submission-client} + +The server sets `@submission_client` from the request that delivered the event. + +| Field | Type | Description | +| ------------ | ------ | -------------------------------------------------------------------------------------- | +| `user_agent` | string | The client name, lowercased, from the `X-Exceptionless-Client` or `User-Agent` header. | +| `version` | string | The client version, when the header has the form `name/version`. | +| `ip_address` | string | The IP address the request came from, unless the project excludes private information. | + +### Location {#location} + +The server sets `@location` from `geo` or from the event's IP addresses. + +| Field | Type | Description | +| ---------- | ------ | -------------------------------------------------- | +| `country` | string | The country. | +| `level1` | string | The first administrative level, such as a state. | +| `level2` | string | The second administrative level, such as a county. | +| `locality` | string | The city. | + +## Stored events {#stored-events} + +Events returned by the API have these extra fields, set by the server. Clients don't send them; an `id` sent with a new +event is ignored, and is used as the `reference_id` if that's empty. + +| Field | Type | Description | +| --------------------- | ------- | ----------------------------------------- | +| `id` | string | The event ID. | +| `organization_id` | string | The organization the event belongs to. | +| `project_id` | string | The project the event belongs to. | +| `stack_id` | string | The stack the event was grouped into. | +| `is_first_occurrence` | boolean | Whether this event created its stack. | +| `created_utc` | string | When the server stored the event, in UTC. | +| `idx` | object | Search index values copied from `data`. | diff --git a/docs/docs/reference/search-syntax.md b/docs/docs/reference/search-syntax.md new file mode 100644 index 0000000000..09521aa453 --- /dev/null +++ b/docs/docs/reference/search-syntax.md @@ -0,0 +1,217 @@ +--- +title: "Search syntax" +description: "Every field you can search in Exceptionless, with operators, ranges, wildcards, custom data, and examples for raw filters and the API." +sources: + - src/Exceptionless.Core/Repositories/Configuration/Indexes/EventIndex.cs + - src/Exceptionless.Core/Repositories/Configuration/Indexes/StackIndex.cs + - src/Exceptionless.Core/Repositories/Queries/Visitors/EventFieldsQueryVisitor.cs + - src/Exceptionless.Core/Repositories/Queries/Visitors/EventStackFilterQueryVisitor.cs + - src/Exceptionless.Core/Repositories/Queries/Validation/PersistentEventQueryValidator.cs + - src/Exceptionless.Core/Repositories/Queries/Validation/StackQueryValidator.cs + - src/Exceptionless.Core/Repositories/Queries/Validation/EventStackQueryValidator.cs + - src/Exceptionless.Core/Extensions/PersistentEventExtensions.cs + - src/Exceptionless.Core/Extensions/StringExtensions.cs + - src/Exceptionless.Core/Pipeline/035_CopySimpleDataToIdxAction.cs + - src/Exceptionless.Web/Api/Infrastructure/ApiFilterPolicy.cs + - src/Exceptionless.Web/Api/Infrastructure/TimeRangeParser.cs + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs + - src/Exceptionless.Web/ClientApp/src/lib/features/events/premium-filter.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/shared/components/date-range-picker/date-range-picker.svelte + - tests/Exceptionless.Tests/Search/EventIndexTests.cs + - tests/Exceptionless.Tests/Search/EventStackFilterTests.cs +--- + +# Search syntax + +Exceptionless filters use a Lucene-style query syntax. You type it into a **Raw Filter** in the app (see +[Filtering and searching](/docs/filtering-and-searching/)), pass it as the `filter` parameter to the +[REST API](/docs/api/getting-events/), and Exie and the [MCP server](/docs/ai/mcp-server/) use it in their tools. + +```text +type:error environment:production (tag:Billing OR tag:Checkout) -bot:true +``` + +The time range is separate from the filter. The app sets it with the date range picker and the API with the `time` +parameter. See [Date ranges](#date-ranges). + +## Operators + +| Syntax | Meaning | Example | +| --------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------- | +| `field:value` | The field matches the value. | `type:error` | +| `field:"two words"` | Quote values that contain spaces or special characters. | `message:"Invalid hash. Parameter name: hash"` | +| `a b` or `a AND b` | Both terms must match. A space means AND. | `type:log level:error` | +| `a OR b` | Either term matches. Wrap OR groups in parentheses. | `(tag:blue OR tag:red)` | +| `field:(a OR b)` | Either value in one field. | `level:(error OR fatal)` | +| `-field:value` | Excludes matches. `NOT` and `!` work too. | `-bot:true` | +| `_exists_:field` | The field has a value. | `_exists_:environment` | +| `_missing_:field` | The field has no value. | `_missing_:tag` | +| `value*` | Starts with. Only a trailing wildcard is supported. | `reference:order-*` | +| `field:>n`, `>=`, `<`, `<=` | Comparisons on numbers and dates. | `count:>5` | +| `field:[a TO b]` | An inclusive range. Use `{a TO b}` to exclude the ends and `*` for an open end. | `value:[1 TO 10]` | + +`-bot:true` and `bot:false` aren't the same: `-bot:true` also matches events that don't have the field at all. + +Write field names in lowercase, as shown here; some of them are case-sensitive. Whether a value is case-sensitive +depends on the field, as noted in the tables below. + +## Event fields + +These fields work in the **Stacks**, **Events**, and **Sessions** lists in the app and with the `/api/v2/events` +endpoints. "Words" means the field matches any word in the value; quote the value to match a phrase. "Exact" means the +whole value must match, including case. "Whole value" means the whole value must match, ignoring case. + +| Field | What it matches | Match | Example | +| -------------------- | -------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------- | +| `id` | Event ID | Exact | `id:54dbc16ca0f5c61398427b00` | +| `reference` | The event's [reference ID](/docs/references-ids/) | Exact | `reference:876554321` | +| `stack` | Stack ID | Exact | `stack:1ecd0826e447a44e78877ab1` | +| `project` | Project ID | Exact | `project:537650f3b77efe23a47914f4` | +| `organization` | Organization ID | Exact | `organization:537650f3b77efe23a47914f3` | +| `type` | Event type: `error`, `log`, `usage`, `404`, `session`, `heartbeat`, `sessionend`, or a custom type | Whole value | `type:usage` | +| `environment` | The deployment [environment](/docs/environments/) | Whole value | `environment:production` | +| `source` | Log source, feature name, or other event source | Words | `source:"GET /Print"` | +| `message` | Event message | Words | `message:timeout` | +| `tag` | A tag | Exact | `tag:"Blake Niemyjski"` | +| `date` | When the event occurred | Date | `date:>now-1h` | +| `first` | `true` for the first event in its stack | Boolean | `first:true` | +| `value` | The event's numeric value | Number | `value:[1 TO 10]` | +| `count` | How many occurrences the event stands for, after client-side deduplication | Number | `count:>5` | +| `level` | Log level: `trace`, `debug`, `info`, `warn`, `error`, or `fatal` | Whole value | `level:error` | +| `version` | Your app's version. See [Versions](#versions). | Version | `version:2.4` | +| `submission` | How the client captured the event, such as `UnobservedTaskException` | Exact | `submission:UnobservedTaskException` | +| `client.version` | Exceptionless client version | Exact | `client.version:6.2.0` | +| `client.useragent` | Exceptionless client user agent | Whole value | `client.useragent:"exceptionless/6.2.0"` | +| `ip` | Client, request, or machine IP address | Words | `ip:192.168.0.243` | +| `useragent` | Request user agent | Words | `useragent:"Mozilla/5.0"` | +| `path` | Request path | Words | `path:"/cart"` | +| `browser` | Browser name | Words | `browser:"Chrome Mobile"` | +| `browser.version` | Browser version | Exact | `browser.version:39.0.2171` | +| `browser.major` | Browser major version | Exact | `browser.major:39` | +| `device` | Device name | Words | `device:"Huawei U8686"` | +| `bot` | `true` when the request came from a bot | Boolean | `bot:true` | +| `os` | Operating system name | Words | `os:"Mac OS X"` | +| `os.version` | Operating system version | Exact | `os.version:10.10.1` | +| `os.major` | Operating system major version | Exact | `os.major:10` | +| `machine` | Machine name | Whole value | `machine:SERVER-01` | +| `architecture` | Machine architecture | Exact | `architecture:x64` | +| `cmd` | Process command line | Exact | `cmd:"MyApp.exe --run"` | +| `country` | Country | Whole value | `country:US` | +| `level1` | Region, such as a state | Exact | `level1:TX` | +| `level2` | City | Exact | `level2:Dallas` | +| `locality` | Locality | Exact | `locality:Downtown` | +| `user` | The user's identity | Words | `user:jane@example.com` | +| `user.email` | The user's email address (matches the user identity) | Words | `user.email:jane@example.com` | +| `user.name` | The user's name | Whole value | `user.name:"Jane Doe"` | +| `user.description` | The description a user submitted with an error | Words | `user.description:"I clicked save"` | +| `error.code` | Error code | Exact | `error.code:502` | +| `error.message` | Error message | Words | `error.message:"A task was canceled"` | +| `error.type` | Exception type, with or without its namespace | Type name | `error.type:NullReferenceException` | +| `error.targettype` | Type of the method that threw | Type name | `error.targettype:System.Exception` | +| `error.targetmethod` | Method that threw | Type name | `error.targetmethod:AssociateWithCurrentThread` | +| `data.` | A custom data value. See [Custom data](#custom-data). | Depends | `data.orderid:12345` | +| `ref.` | A named event reference, such as a session | Exact | `ref.session:abc123` | + +The `error.*` fields match any exception in the chain, including inner exceptions. "Type name" fields match the full +name or any trailing part of it: `error.type:NullReferenceException` and `error.type:System.NullReferenceException` both +match a `System.NullReferenceException`. + +### Search without a field + +A term without a field name searches several fields at once: `id`, `reference`, `source`, `message`, `tag`, `path`, +`error.code`, `error.type`, `error.targettype`, `error.targetmethod`, `user`, `user.name`, and the email address and +description a user submitted with an error. + +```text +NullReferenceException +"Invalid hash. Parameter name: hash" +``` + +## Stack fields + +Event lists can also filter by fields of the stack an event belongs to. Exceptionless finds the matching stacks and +returns their events. + +| Field | What it matches | Example | +| ------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------- | +| `status` | Stack status: `open`, `fixed`, `regressed`, `snoozed`, `ignored`, or `discarded` | `(status:open OR status:regressed)` | +| `fixed` | `true` for fixed stacks. The same as `status:fixed`. | `fixed:true` | +| `regressed` | `true` for regressed stacks. The same as `status:regressed`. | `regressed:true` | +| `hidden` | `true` for stacks that aren't open or regressed | `hidden:false` | +| `critical` | `true` when future occurrences are marked critical | `critical:true` | +| `title` | Stack title | `title:"GET /Print"` | +| `description` | Stack description | `description:"checkout"` | +| `links` | A stack's reference link | `links:"https://github.com/acme/api/issues/42"` | +| `version_fixed` | The version the stack was marked fixed in | `version_fixed:1.2.3` | +| `fixedon` | When the stack was marked fixed | `fixedon:>now-7d` | +| `first_occurrence` | When the stack first occurred | `first_occurrence:>now-1d` | +| `last` | When the stack last occurred | `last:100` | +| `signature` | Stack signature hash | `signature:abc123` | + +`type`, `tag`, `project`, `stack`, and `organization` apply to both the event and its stack. + +Most of the app's built-in views include `(status:open OR status:regressed)` as a hidden filter, so fixed, snoozed, +ignored, and discarded stacks stay out of them. A raw filter in a view is combined with the view's hidden **Status** +filter. A filter sent to the API has no default status, so add one yourself. + +## Versions {#versions} + +`version` compares the parts of a version, so `version:1` matches `1.0`, `1.2.3`, and `1.9`, and `version:1.2` matches +`1.2.0` and `1.2.3`, but not `1.20`. Four-part versions such as `1.2.3.0` match `version:1.2.3`. Prerelease versions +match exactly, as in `version:3.2.1-beta1`. + +Version ranges such as `version:>1.2` aren't supported. `browser.version`, `os.version`, `client.version`, and +`version_fixed` are plain values and only match exactly. + +## Custom data {#custom-data} + +Exceptionless indexes simple values in an event's custom data, so you can search them with `data.`: + +```text +data.orderid:12345 +data.total:>100 +data.isbeta:true +data.signupdate:>2025-01-01 +data.customer:"Acme Corp" +``` + +- Only organizations on a paid plan get custom data indexed, and only for events received while they're on one. +- Only top-level keys are indexed. A key is indexed when it's 25 characters or fewer and has only letters, digits, and + hyphens. Keys with underscores, dots, or spaces aren't indexed. +- Field names are lowercase in searches: a value sent as `OrderId` is searched as `data.orderid`. +- Strings, numbers, booleans, and dates are indexed. Objects, arrays, JSON strings, and strings of 1,000 characters or + more aren't. A string that looks like `true`, `false`, a date, or a number is indexed as that type. +- String values are exact and case-sensitive. + +Event references set with the client's `SetEventReference(name, id)` or `setEventReference(name, id)` are searchable as +`ref.`, with the same key rules. + +## Date ranges {#date-ranges} + +Search a date field with a range or a comparison: + +```text +date:[2025-01-01 TO 2025-01-31] +date:>=now-24h +fixedon:[now-7d TO now] +``` + +Date values can be dates and times, such as `2025-01-15` or `2025-01-15T09:30:00Z`, or date math from `now`: `now-1h`, +`now-7d`, `now-1M`, and `now/d` for the start of today. Units are `s`, `m`, `h`, `d`, `w`, `M`, and `y`. + +The time range of a view, set with the app's date range picker or the API's `time` parameter, takes the same kind of +range, such as `[now-7d TO now]`, or `[now-1d/d TO now-1d/d]` for yesterday. There, a year or a month on its own, such +as `2025` or `2025-01`, covers the whole year or month. + +## Free plan searches {#free-plan-searches} + +On the Free plan, filters can use only these fields: `type`, `environment`, `status`, `date`, `reference`, `project`, +`stack`, and `organization`. Stack lists also allow `critical`, `first_occurrence`, `last`, and `last_occurrence`. Any +other field, a term without a field, or a `data.*` field needs a paid plan, and the app offers to upgrade when you use +one. + +## Exie and the MCP server + +Exie and the MCP tools accept the same syntax, but only for a fixed set of fields. A coding agent can call the MCP +server's `get_filter_fields` tool to list them. See [MCP server](/docs/ai/mcp-server/). diff --git a/docs/docs/references-ids.md b/docs/docs/references-ids.md index 53a5669a4b..a94c572748 100644 --- a/docs/docs/references-ids.md +++ b/docs/docs/references-ids.md @@ -1,118 +1,205 @@ --- -title: "Reference Ids" -description: "Use Exceptionless reference IDs to look up submitted events: enable UseReferenceIds in .NET, show the last reference ID to users, and search by it." +title: "Reference IDs" +metaTitle: "Look up errors by reference ID" +description: "Show users a short reference ID when something fails, then find that exact event in Exceptionless. Includes an ASP.NET Core problem details example." +sources: + - src/Exceptionless.Web/ClientApp/src/routes/(app)/event/by-ref/[referenceId]/+page.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/views/overview.svelte + - src/Exceptionless.Web/Api/Endpoints/EventEndpoints.cs + - src/Exceptionless.Web/Utility/Constraints/IdentifierRouteConstraint.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/05_CheckForDuplicateReferenceIdPlugin.cs + - src/Exceptionless.Core/Pipeline/006_TruncateFieldsAction.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/90_RemovePrivateInformationPlugin.cs + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs + - Exceptionless.Net:src/Exceptionless/Extensions/ExceptionlessConfigurationExtensions.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/040_ReferenceIdPlugin.cs + - Exceptionless.Net:src/Exceptionless/ExceptionlessClient.cs + - Exceptionless.Net:src/Exceptionless/EventBuilder.cs + - Exceptionless.Net:src/Platforms/Exceptionless.AspNetCore/ExceptionlessExceptionHandler.cs + - Exceptionless.Net:src/Platforms/Exceptionless.AspNetCore/ExceptionlessExtensions.cs + - Exceptionless.Net:samples/Exceptionless.SampleAspNetCore/Program.cs + - Exceptionless.JavaScript:packages/core/src/plugins/default/ReferenceIdPlugin.ts + - Exceptionless.JavaScript:packages/core/src/plugins/EventPluginManager.ts + - Exceptionless.JavaScript:packages/core/src/ExceptionlessClient.ts --- -# Reference Ids +# Reference IDs -Reference Ids are unique identifiers that let you look up a submitted event. This is important because _event Ids are not created until after an event is processed, so there's no other way to look up an event_. +A reference ID is a short ID that a client gives an event before sending it. Show it to your users when something goes +wrong, and when they contact support with it, you can open the exact event in Exceptionless. -Reference Ids are also used to help deduplicate events on the server side. +You need a reference ID for this because an event's own ID only exists after the server processes it, so your app can't +show it to the user. -## Uses +## The support workflow -One example of using Reference Ids is to help support your users. For instance, we always include a Reference Id with every error message for our users, allowing them to contact us with that Reference Id and receive help faster because we can easily track it down. +1. Your app turns on reference IDs. Each error event gets a 10-character ID, such as `9f4a1c2b3d`. +2. When a request or action fails, your app shows the reference ID in the error message or response. +3. The user sends the reference ID to your support team. +4. Support opens `https://be.exceptionless.io/event/by-ref/9f4a1c2b3d`, or searches for `reference:9f4a1c2b3d`, and sees + the error with its stack trace, request, and user. -## Reference Id Example +Optionally, the user can add their email address and a description of what they were doing, which shows on the event as +**User Description**. See [Let users describe what happened](#let-users-describe-what-happened). -To attach Reference Ids to our errors in Exceptionless, we register a default Reference Id plugin that sets a Reference Id when the event is submitted and stores the Id in an implementation of ILastReferenceIdManager. With the default plugin, we enable this behavior by calling `UseReferenceIds()` on the configuration object. +## Turn on reference IDs -## C# Example +- **.NET:** call `UseReferenceIds()` on the configuration. It gives every error event a reference ID. +- **JavaScript:** error events get a reference ID by default. + +Both clients only give **error** events a reference ID. To get the last one your app sent, call `GetLastReferenceId()` +in .NET or `getLastReferenceId()` in JavaScript. + +You can also set your own with `SetReferenceId()` or `setReferenceId()` on the event builder, for example to reuse an ID +your app already logs. A reference ID must be 8 to 100 letters, digits, or dashes, and it must be unique: when two +events arrive with the same reference ID within a day, the server keeps the first and discards the second. + +## Return the reference ID from ASP.NET Core + +In an ASP.NET Core app, `builder.AddExceptionless()` registers an `IExceptionHandler` that reports unhandled exceptions. +This example adds the event's reference ID to the problem details response that `UseExceptionHandler()` returns. It +reads the reference ID from the event itself, so each response gets its own request's ID even under load. + + ```csharp using Exceptionless; -ExceptionlessClient.Default.Configuration.UseReferenceIds(); -``` -## JavaScript Example +var builder = WebApplication.CreateBuilder(args); + +// Reads the API key from the "Exceptionless" section of appsettings.json. +builder.AddExceptionless(c => +{ + // Give every error event a reference ID. + c.UseReferenceIds(); + + // Keep the reference ID on the current request so the error response can include it. + c.AddPlugin("RequestReferenceId", 50, context => + { + if (!String.IsNullOrEmpty(context.Event.ReferenceId) + && context.ContextData.TryGetValue("HttpContext", out object? value) + && value is HttpContext httpContext) + { + httpContext.Items["ExceptionlessReferenceId"] = context.Event.ReferenceId; + } + }); +}); + +// Add the reference ID to the problem details response for unhandled exceptions. +builder.Services.AddProblemDetails(options => +{ + options.CustomizeProblemDetails = context => + { + if (context.HttpContext.Items.TryGetValue("ExceptionlessReferenceId", out object? referenceId)) + context.ProblemDetails.Extensions["referenceId"] = referenceId; + }; +}); + +var app = builder.Build(); + +app.UseExceptionHandler(); +app.UseExceptionless(); + +app.MapGet("/", () => +{ + throw new InvalidOperationException("Something went wrong."); +}); + +app.Run(); +``` -The JavaScript client will automatically manage reference ids. +The plugin runs after the built-in reference ID plugin, which has priority 40. A request to `/` now returns: -You can also create your own plugin to create your own Reference Ids. +```json +{ + "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1", + "title": "An error occurred while processing your request.", + "status": 500, + "traceId": "00-1e00f1e67addf9cabd5a4c15024de614-18b7dfcc2181ee03-00", + "referenceId": "aa0310f620" +} +``` -## Get Last Used Reference Id +Your front end can show `referenceId` to the user, for example: "Something went wrong. If you contact support, include +reference aa0310f620." -Call `GetLastReferenceId()` on the `ExceptionlessClient` instance. +For the rest of the ASP.NET Core setup, see [ASP.NET Core](/docs/clients/dotnet/aspnet-core/). -### C# Last Reference Id Example +## Show the reference ID in a browser app -```csharp -using Exceptionless; -// Get the last created Reference Id -ExceptionlessClient.Default.GetLastReferenceId(); -``` + -### JavaScript Last Reference Id Example +```ts +import { Exceptionless } from "@exceptionless/browser" -```javascript -import { Exceptionless } from "@exceptionless/browser"; +await Exceptionless.startup("YOUR_API_KEY") -// Get the last created Reference Id -Exceptionless.getLastReferenceId(); +try { + await placeOrder() +} catch (error) { + await Exceptionless.submitException(error as Error) + const referenceId = Exceptionless.getLastReferenceId() + showError(`Something went wrong. If you contact support, include reference ${referenceId}.`) +} ``` -## Displaying Reference Ids to End Users +`placeOrder` and `showError` stand for your own code. -We do this for our end users because it allows them to better support their app users. +## Let users describe what happened {#let-users-describe-what-happened} -To do so, we add a custom `IExceptionHandler` and return a new error response to include the Reference Id as shown below: +After an error, you can ask the user what they were doing and attach their answer to the event by its reference ID. The +email address and description show on the event's **Overview** tab under **User Description**. -```csharp -public class ExceptionlessReferenceIdExceptionHandler : IExceptionHandler { - public Task HandleAsync(ExceptionHandlerContext context, CancellationToken cancellationToken) { - if (context == null) - throw new ArgumentNullException(nameof(context)); - - var exceptionContext = context.ExceptionContext; - var request = exceptionContext.Request; - if (request == null) - throw new ArgumentException($"{typeof(ExceptionContext).Name}.{"Request"} must not be null", nameof(context)); - - context.Result = new ResponseMessageResult(CreateErrorResponse(request, exceptionContext.Exception, HttpStatusCode.InternalServerError)); - return TaskHelper.Completed(); - } - - private HttpResponseMessage CreateErrorResponse(HttpRequestMessage request, Exception ex, HttpStatusCode statusCode) { - HttpConfiguration configuration = request.GetConfiguration(); - HttpError error = new HttpError(ex, request.ShouldIncludeErrorDetail()); - - string lastId = ExceptionlessClient.Default.GetLastReferenceId(); - if (!String.IsNullOrEmpty(lastId)) - error.Add("Reference", lastId); - - // CreateErrorResponse should never fail, even if there is no configuration associated with the request - // In that case, use the default HttpConfiguration to con-neg the response media type - if (configuration == null) { - using (HttpConfiguration defaultConfig = new HttpConfiguration()) { - return request.CreateResponse(statusCode, error, defaultConfig); - } - } + - return request.CreateResponse(statusCode, error, configuration); - } -} +```csharp tab=".NET" +using Exceptionless; + +await ExceptionlessClient.Default.UpdateUserEmailAndDescriptionAsync( + referenceId, "jane@example.com", "I clicked Place order twice."); ``` -Then we replace the existing `IExceptionFilter` +```ts tab="JavaScript" +import { Exceptionless } from "@exceptionless/browser" -```csharp -Config.Services.Replace(typeof(IExceptionHandler), new ExceptionlessReferenceIdExceptionHandler()); +await Exceptionless.updateUserEmailAndDescription(referenceId, "jane@example.com", "I clicked Place order twice.") ``` -Now you'll get a user friendly error response that contains a Reference Id, like: +```bash tab="curl" +curl -X POST "https://api.exceptionless.io/api/v2/events/by-ref/9f4a1c2b3d/user-description" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"email_address":"jane@example.com","description":"I clicked Place order twice."}' +``` -`{ - "message": "An error has occurred.", - “reference”: “411085622e” -}` +If the project removes user identifiable information, the server drops the email address and keeps the description. -## Looking up Events by Reference Id +## Find an event by reference ID -Link directly to an event by outputting a link in your UI or log files, like -`https://be.exceptionless.io/event/by-ref/YOUR_REFERENCE_ID` +- **Link:** open `https://be.exceptionless.io/event/by-ref/YOUR_REFERENCE_ID`. If one event matches, the app opens it. + If several match, it lists them with **View In Events**. Your app or logs can print this link next to the error. +- **Search:** filter the **Events** view with `reference:YOUR_REFERENCE_ID`. See + [Filtering and searching](/docs/filtering-and-searching/). +- **Command palette:** press / and type the reference ID to search events from the last 7 days. +- **API:** `GET /api/v2/events/by-ref/{referenceId}`. See [Querying events and stacks](/docs/api/getting-events/). -Or you can search via the api/ui with `reference:YOUR_REFERENCE_ID` +On an event's **Overview** tab, the **Reference** row shows its reference ID and links to the same lookup. ---- +## Ask Exie -[Next > User Sessions](/docs/user-sessions) +[Exie](/docs/ai/exie/) is on Medium plans and up. + +```prompt exie +Find the error with reference ID 9f4a1c2b3d and explain what went wrong. +``` + +```prompt exie +How many times has the error behind reference 9f4a1c2b3d happened this week? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can take a support ticket from reference ID to +fix: + +```prompt agent +A customer reported Exceptionless reference ID 9f4a1c2b3d. Find that event, read its stack trace and request, find the cause in this repository, and propose a fix. +``` diff --git a/docs/docs/saved-views.md b/docs/docs/saved-views.md new file mode 100644 index 0000000000..c7b9670ca7 --- /dev/null +++ b/docs/docs/saved-views.md @@ -0,0 +1,139 @@ +--- +title: "Saved views" +description: "Save a list's filters, date range, sort, and columns as a named view, share it with your organization or keep it private, and choose your home view." +sources: + - src/Exceptionless.Core/Seed/predefined-saved-views.json + - src/Exceptionless.Core/Models/SavedView.cs + - src/Exceptionless.Web/Models/SavedView/NewSavedView.cs + - src/Exceptionless.Web/Api/Handlers/SavedViewHandler.cs + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/components/saved-view-picker.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/components/save-view-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/components/rename-view-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/components/delete-view-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/components/column-management-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/components/saved-view-order-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/use-saved-views.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/saved-view-drafts.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/defaults.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/ordering.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/saved-views/slugs.ts + - src/Exceptionless.Web/ClientApp/src/routes/(app)/(components)/layouts/sidebar.svelte +--- + +# Saved views + +A saved view is a named list: its filters, date range, sort order, columns, and whether it shows the stat boxes and +chart. The **Stacks**, **Events**, and **Sessions** pages each show a saved view, and every view in the organization is +listed under its page in the sidebar. Save a view for anything you check often, such as production errors in the +checkout service, and share it with your team. + +Each view owns its own filters. There's no global project or date filter: changing the filters on one view doesn't +change any other view. + +## Built-in views + +Every organization starts with these views. They cover the last 7 days, and all of them except **Events** > **All** and +**Sessions** > **All** show only open and regressed stacks. + +| Page | View | Shows | +| ------------ | ------------------------ | --------------------------------------------------------------- | +| **Stacks** | **All** | Every open or regressed stack | +| **Stacks** | **Most Frequent Errors** | Error stacks, most events first | +| **Stacks** | **Most Frequent 404s** | 404 stacks, most events first | +| **Stacks** | **Most Used Features** | [Feature usage](/docs/feature-usage/) stacks, most events first | +| **Events** | **All** | Every event, newest first | +| **Events** | **Errors** | Error events, newest first | +| **Events** | **Logs** | Log events, newest first | +| **Sessions** | **All** | Every [session](/docs/user-sessions/), newest first | + +The built-in views are ordinary shared views in your organization. Anyone in it can change, rename, or delete them. When +Exceptionless updates a built-in view, it leaves the ones you've changed alone. + +## Create a view + +1. Open a view and set it up the way you want: add filters, change the date range, and arrange columns. +2. Select **View** at the top right, then **Save As...**. +3. In **Save View**, enter a **Name**. The **URL name** fills in from it; change it if you like. +4. Check **Private** if only you should see it. +5. Select **Save**. + +The view opens and appears in the sidebar under its page. Its address uses the URL name, such as +`/stack/production-errors`, `/event/production-errors`, or `/sessions/production-errors`. + +If your filters already match a saved view, **Save View** says so and offers to load that view instead. + +Names and URL names must be unique among the views on a page. A URL name can contain only lowercase letters, numbers, +and single dashes. An organization can have up to 100 saved views. + +## Unsaved changes + +When you change a view's filters, date range, sort, columns, or display settings, a dot appears on the **View** button. +Hover over it to see "This view has unsaved changes. Open to save or reset them." Then open **View** and select: + +- **Save** to update the view. For a shared view, everyone sees the change. +- **Save As...** to keep the original and save your changes as a new view. +- **Reset to Saved** to discard your changes. + +Unsaved changes stay with the view in your browser tab, so you can move between pages and come back to them. The address +bar includes your filter, date range, and sort changes, so a link you copy opens the view with them. + +## Rename or delete a view + +- **View** > **Rename** opens **Rename View**, where you can change the **Name** and **URL name**. Links that use the + old URL name no longer open the view. +- **View** > **Delete "** _name_ **"** asks for confirmation, then deletes the view for everyone who can see it. + +## Choose columns + +Open **View** > **Manage Columns...** to open the **Column Picker**: + +- **Selected Columns** are the columns in the table. Drag them, or use **Move up** and **Move down**, to reorder them. + Check **Wrap** to wrap long text instead of cutting it off. +- Pick one column to fill the remaining table width, or **None** to keep every column at a fixed width. +- **Available Columns** lists the columns you can add. Search them and select one to add it. +- **Reset to default** restores the page's default columns. + +You can also drag the edge of a column header to resize it. Column changes count as unsaved changes, so select **Save** +to keep them. + +Under **View** > **Display**, turn **Stat boxes** and **Chart** on or off. These are saved with the view too. + +## Share a view + +A view is shared with everyone in your organization unless you check **Private** when you create it. Shared views appear +in everyone's sidebar, and anyone in the organization can save changes to them, rename them, or delete them. Private +views appear only in your sidebar, and only you can change them. + +To send someone a view, copy the address from your browser. They need access to the organization to open it. + +## Set your home view + +When you open Exceptionless, it shows your home view. To choose it, open a view and select **View** > **Set as my home +view**. Select **Clear my home view** to undo it. + +To set the home view for everyone in the organization, open a shared view and select **Set as organization home**. A +personal home view takes precedence over the organization home. With neither set, Exceptionless opens a **Stacks** view. + +## Reorder views in the sidebar + +Views are listed alphabetically until you reorder them. Drag a view up or down in the sidebar, or hover over **Stacks**, +**Events**, or **Sessions** and select **Reorder** _page_ **views** to arrange them in a dialog. The dialog shows which +views are **Private** and which are **Shared**, and **Reset to alphabetical** undoes your order. + +The order is personal: it changes only your sidebar. + +## Ask Exie + +Exie can't create or change saved views, but it can answer the questions you'd build a view for: + +```prompt exie +What are the most frequent 404s this week? +``` + +```prompt exie +Which errors are new in production in the last 24 hours? +``` + +```prompt exie +Which features were used most in the last 30 days? +``` diff --git a/docs/docs/security.md b/docs/docs/security.md index 05902e30ac..7102947350 100644 --- a/docs/docs/security.md +++ b/docs/docs/security.md @@ -1,26 +1,160 @@ --- -title: "Security" -metaTitle: "Exceptionless security and data exclusions" -description: "Learn how Exceptionless protects data with SSL and how to use data exclusions with wildcards to remove passwords and other sensitive fields from reports." +title: "Security and privacy" +description: "How Exceptionless handles your event data: encryption in transit, private information clients collect and how to turn it off, data exclusions, and API keys." +navTitle: "Security and privacy" +sources: + - src/Exceptionless.Core/Plugins/EventProcessor/Default/90_RemovePrivateInformationPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/40_RequestInfoPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/Default/45_EnvironmentInfoPlugin.cs + - src/Exceptionless.Core/Plugins/EventProcessor/EventContext.cs + - src/Exceptionless.Core/Extensions/RequestInfoExtensions.cs + - src/Exceptionless.Core/Extensions/StringExtensions.cs + - src/Exceptionless.Core/Authorization/AuthorizationRoles.cs + - src/Exceptionless.Web/Api/Endpoints/EventEndpoints.cs + - src/Exceptionless.Web/Api/Endpoints/ProjectEndpoints.cs + - src/Exceptionless.Web/Api/Handlers/OrganizationHandler.cs + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/settings/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/api-keys/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(auth)/login/+page.svelte + - Exceptionless.Net:src/Exceptionless/Configuration/ExceptionlessConfiguration.cs + - Exceptionless.Net:src/Exceptionless/Extensions/ExceptionlessConfigurationExtensions.cs + - Exceptionless.Net:src/Platforms/Exceptionless.AspNetCore/RequestInfoCollector.cs + - Exceptionless.JavaScript:packages/core/src/configuration/Configuration.ts + - Exceptionless.JavaScript:packages/core/src/Utils.ts + - Exceptionless.JavaScript:packages/node/src/plugins/NodeRequestInfoPlugin.ts --- -# Security +# Security and privacy -Exceptionless follows industry best practices and uses SSL out of the box to be as secure as possible. We also provide you with the tools to take your information security to the next level. These tools include Data Exclusions. To accommodate various data protection laws, Exceptionless allows you to prevent the transmission of specified pieces of information through Data Exclusions. +Error reports can contain personal and sensitive data: user names, IP addresses, cookies, form fields. This page +explains what the clients collect, how to keep sensitive data out of Exceptionless, and who can see your data and send +events to your projects. -### Data Exclusions +For what Exie and the MCP server can see and do, see [AI privacy and security](/docs/ai/privacy/). For the hosted +service's privacy policy, see [Privacy](/privacy/). -These exclusions are simply a comma delimited list of field names that should be removed from any error report data (e.g., extended data properties, form fields, cookies and query parameters). Data Exclusions can be configured on the project settings page. You can also specify a field name with wildcards `*` to specify starts with, ends with, or contains just to be extra safe. +## Encryption in transit -#### Example usage: +The clients send events over HTTPS by default, and the hosted app and API at `be.exceptionless.io` and +`api.exceptionless.io` use HTTPS. On a self-hosted instance, you provide the TLS certificate; see +[Reverse proxies and HTTPS](/docs/self-hosting/reverse-proxy/). -Entering `Password` will remove any field **named** `Password` from the report. -Entering `Password*` will remove any field that **starts with** `Password` from the report. -Entering `*Password` will remove any field that **ends with** `Password` from the report. -Entering `*Password*` will remove any field that **contains** `Password` from the report. +## What the clients collect -[See more on data exclusions here](/docs/project-settings#data-exclusions). +Besides the error, log message, or other event you send, the clients add context that helps you debug it: ---- +- **Environment**: the OS, runtime, process, and machine name, and the machine's IP address. +- **Request** (web apps): the URL, HTTP method, user agent, referrer, client IP address, headers, cookies, query string, + and form or POST data. In ASP.NET Core, POST data is collected only for unhandled errors. +- **User**: the user identity you set in your app. In WinForms and WPF apps, the .NET client uses the signed-in OS user + name when you don't set one. + +The ASP.NET Core and Node.js clients never send the `Authorization` or `Proxy-Authorization` request headers. + +### Turn off private information + +The clients treat the user name, machine name, IP addresses, headers, cookies, POST data, and query string as private +information. One setting turns all of them off: + +```json tab=".NET" +{ + "Exceptionless": { + "ApiKey": "YOUR_API_KEY", + "IncludePrivateInformation": false + } +} +``` + +```ts tab="JavaScript" +import { Exceptionless } from "@exceptionless/browser" // or "@exceptionless/node" + +await Exceptionless.startup((c) => { + c.apiKey = "YOUR_API_KEY" + c.includePrivateInformation = false +}) +``` + +Each kind also has its own setting, such as `IncludeCookies` in .NET and `includeCookies` in JavaScript, so you can keep +some and drop others. See [.NET private information](/docs/clients/dotnet/private-information/) and +[JavaScript configuration](/docs/clients/javascript/client-configuration/). + +### Remove private information on the server + +To strip private information from every event a project receives, without changing your apps, open the project's +**Settings** page and turn on **Automatically remove user identifiable information from events**. Before an event is +stored, the server then removes: + +- the user identity, and the email address from user descriptions +- IP addresses, from both the request and the environment +- the machine name +- cookies, the query string, and POST data + +Request headers are not removed by this setting; turn them off in the client. + +When a client leaves IP addresses out, the server fills in the IP address that submitted the event. Turn on this setting +to keep IP addresses out entirely. It also turns off the project's +[bot protection](/docs/concepts/limits/#bots-and-spam), which works by IP address. + +## Data exclusions {#data-exclusions} + +Data exclusions remove fields by name: extended data properties, form fields, cookies, query string parameters, and +headers. Set them on the project's **Settings** page under **Data Exclusions**, as a comma-delimited list. + +![The Data Exclusions setting on a project's Settings page](/assets/img/docs/project-settings-data-exclusions-light.webp) + +Names are matched without regard to case, and `*` matches any text at the start or end: + +| Exclusion | Removes fields that | +| ------------ | ---------------------------------------------- | +| `Password` | are named `Password` | +| `Password*` | start with `Password`, such as `PasswordHash` | +| `*Password` | end with `Password`, such as `ConfirmPassword` | +| `*Password*` | contain `Password` anywhere | + +For example: `*Password*, CreditCard*, SSN`. + +The clients download the list with the project's +[client configuration values](/docs/project-settings/#client-configuration) and remove matching fields before the event +leaves your app. The server applies the list again to cookies, the query string, and POST data before storing an event, +which covers clients that haven't picked up a change yet. + +You can also add exclusions in code, so they apply from the first event: `AddDataExclusions` in .NET and +`addDataExclusions` in JavaScript. + +## Who can see your data + +Events belong to a project, and projects belong to an organization. Every user in an organization can see and manage all +of its projects, events, settings, users, and billing. There are no per-project or read-only roles, so use separate +organizations for people who shouldn't see each other's data. + +To take away someone's access, open the organization's **Users** page and choose **Remove User**. See +[Organizations and billing](/docs/organizations/). + +Users sign in with an email address and password, or with GitHub, Google, or Microsoft. Passwords are stored as salted +hashes. Self-hosted instances choose which sign-in options to offer; see +[Configuration](/docs/self-hosting/configuration/). + +## API keys + +Projects send events with a client API key, which you manage on the project's **API Keys** page. A client API key can +only: + +- submit events, user descriptions, and session heartbeats to its project +- read the project's client configuration values +- connect the project to Zapier, which then receives the project's new events + +It can't read events or stacks through the API or change project settings. That makes it fit to ship in browser, mobile, +and desktop apps, but anyone who has the key can do the things above. Don't store secrets in client configuration +values. + +A **Source map upload token**, added on the same page, is for uploading source maps to its project from CI. + +If a key leaks, add a new key with **Add token**, deploy it, and then choose **Disable Token** or **Delete** on the old +key from its row menu. You can enable a disabled key again later. + +To read data from the API, use a user token or OAuth instead; see [Authentication](/docs/api/authentication/). + +## Self-hosting -[Next > API Usage](/docs/api/) +A self-hosted instance keeps all event data in your own Elasticsearch, Redis, and storage. See +[Self-hosting](/docs/self-hosting/). diff --git a/docs/docs/self-hosting/administration.md b/docs/docs/self-hosting/administration.md new file mode 100644 index 0000000000..1398c26bef --- /dev/null +++ b/docs/docs/self-hosting/administration.md @@ -0,0 +1,162 @@ +--- +title: "Administration" +metaTitle: "Administer a self-hosted Exceptionless instance" +description: "Use the System pages to run migrations, stop event intake, control Exie, review AI usage, manage OAuth apps, and post banner notifications." +sources: + - src/Exceptionless.Web/ClientApp/src/routes/(app)/system/routes.svelte.ts + - src/Exceptionless.Web/ClientApp/src/routes/(app)/system/+layout.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/system/overview/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/system/elasticsearch/+layout.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/system/exie/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/system/settings/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/system/actions/[[category]]/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/system/notifications/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/system/saved-views/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/system/oauth-applications/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/system/migrations/+page.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/(components)/layouts/sidebar.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/admin/components/assistant-settings.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/admin/components/table/migration-actions-cell.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/admin/components/oauth-applications/oauth-application-form.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/admin/components/dialogs/run-maintenance-job-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/admin/models.ts + - src/Exceptionless.Core/Services/SystemSettingsService.cs + - src/Exceptionless.Core/Migrations/MigrationRerunService.cs + - src/Exceptionless.Job/JobRunnerOptions.cs + - src/Exceptionless.Web/Api/Handlers/AuthHandler.cs +--- + +# Administration + +Global administrators manage a self-hosted instance from the **System** pages: migrations, runtime settings, Exie, OAuth +apps, banner notifications, and maintenance jobs. + +## Open the System pages + +The first user who signs up on a new instance is a global administrator. In the sidebar, open **Settings** and select +**System**. Other users don't see it. + +The pages are tabs across the top: **Overview**, **Elasticsearch**, **Exie**, **Settings**, **Actions**, +**Notifications**, **Saved Views**, **OAuth Apps**, and **Migrations**. + +## See the state of the system + +- **Overview** shows totals for organizations, users, projects, stacks, open stacks, and events, with charts of event + volume by month, organization growth, and stack status by event type. +- **Elasticsearch** shows cluster health and storage on its **Overview** tab, every index on **Indices**, and snapshots + on **Backups**. + +## Change settings at runtime {#runtime-settings} + +**Settings** holds switches that take effect without a restart. Each one shows a **Deployment default** badge when it +uses the value from your configuration, or **Runtime override** after you change it here. A runtime override wins over +the configuration until you select **Reset**. + +| Setting | What it does | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| **Exie availability** | Turns Exie on or off for every organization. Exie needs an API key in the configuration before it can be turned on. | +| **Conversation sharing default** | Whether people share their Exie messages and replies by default to help improve the feature. People can change their own choice in Exie. | +| **Exie model** | The model ID used for new Exie conversations and turns. See [AI features](/docs/self-hosting/ai/#choose-the-model). | +| **Event submission** | Whether Exceptionless accepts new events. | + +### Stop accepting events {#event-submission} + +To stop taking in events, for example while you repair Elasticsearch: + +1. On **Settings**, turn off **Event submission**. +2. Select **Save**. + +New event submissions get HTTP 503 right away. Session heartbeats still succeed, but they don't record activity. To +accept events again, turn the switch back on and save, or select **Reset** to go back to the deployed setting. The +deployed setting is `EX_EventSubmissionDisabled`, which defaults to `false`. + +## Review Exie usage {#exie-usage} + +**Exie** shows this month's Exie usage across all organizations: **Active Organizations**, **Turns**, **Tokens**, +**Total Provider Cost**, **Tokens per Turn**, and **Average Cost**. + +The **Organization Usage** table lists each organization by provider cost, then tokens. For each one it shows when Exie +was last used, its activity, tokens and cost against the plan's monthly limits, outcomes, and how many turns were +blocked. Totals can lag by up to five minutes. + +## Run maintenance jobs + +**Actions** lists maintenance jobs by category: **Billing**, **Configuration**, **Elasticsearch**, **Maintenance**, +**Security**, and **Users**. Each one describes what it does, and destructive jobs are marked **DESTRUCTIVE**. + +1. Select **Run** next to the job. +2. Fill in any options. Some jobs accept a start date, an end date, or an organization ID. +3. Type the job's name to confirm, and select **Run Job**. + +For example, **Configure Indexes** creates missing indexes and applies current mappings, and **Fix Stack Stats** +recalculates each stack's first occurrence, last occurrence, and event count. + +## Post a banner notification + +**Notifications** shows a banner to every user of the app, for example before planned maintenance. + +1. Enter the **Message**. HTML is allowed and is sanitized before display. +2. Choose the **Level**: **Info**, **Warning**, or **Error**. +3. Select **Set Notification**, or **Update Notification** if one is already showing. + +Select **Clear Notification** to remove it. While no notification is set here, the app shows `EX_NotificationMessage` if +you configured one. + +## Manage predefined saved views + +**Saved Views** manages the predefined [saved views](/docs/saved-views/) that each organization starts with. The +**Predefined** tab shows their definitions as JSON. Select **Edit JSON** to change them, then **Save Predefined**. + +**Force Update** queues a background job that overwrites every organization-wide saved view whose predefined key matches +a saved definition, and creates missing predefined views. It discards customizations to those views. Private views and +views that don't match aren't changed. + +The **Current Org** tab exports the saved views of the organization you're in as predefined definitions. + +## Manage OAuth apps + +**OAuth Apps** lists the OAuth clients that can request access to the API and the [MCP server](/docs/ai/mcp-server/). +Filter the list by **Authorized**, **Not authorized**, or **All applications**, by name or client ID, or by +organization. + +Clients usually register themselves when someone connects an agent. To create one by hand: + +1. Select **New OAuth App**. +2. Enter a **Name** and a **Client ID**. +3. Enter the **Redirect URIs**, one per line. Each must match exactly, with no wildcards, and use HTTPS or HTTP on a + loopback address such as `localhost`. +4. Choose the **Scopes**: **MCP**, **Projects**, **Stacks**, **Stacks Write**, **Events**, and **Offline Access**. +5. Optionally add **Notes**, then select **Create App**. + +Open an app to edit it. Check **Disabled** to block a client: disabled clients can't authorize, refresh, or use existing +access tokens. To delete an app, open its menu in the list and select **Delete**. + +## Migrations {#migrations} + +Exceptionless updates Elasticsearch with migrations. They run on their own when the job process starts, or when the app +starts if it runs the jobs in process. In Kubernetes, you start them yourself; see +[Kubernetes](/docs/self-hosting/kubernetes/#run-migrations). + +**Migrations** shows the **Current Version** (the highest completed migration), how many have **Failed** or are +**Running**, and the **Total**. The table lists each migration's name, version, type, status, start and finish times, +duration, and error. Turn off **Show completed** to see only the ones that need attention. + +### Rerun a migration {#rerunning-a-completed-migration} + +Some completed migrations can be run again, for example after a fix to the data they change. Only those have an actions +menu. + +1. Take an Elasticsearch snapshot, and stop any Exceptionless instances still running an older version. +2. On **Migrations**, open the migration's menu and select **Rerun migration**. +3. Type the phrase shown, such as `RERUN 5`, and select **Rerun Migration**. + +The rerun runs in the background, and a message tells you when it finishes. It doesn't change the current migration +version or the original completion time. + +When the jobs run in a separate process, a rerun from this page needs Redis for the cache and a distributed queue. +Without them, run it from the job image instead, with the same settings as your other containers. Use the migration's +name from the **Name** column. With the [Docker Compose setup](/docs/self-hosting/docker/): + +```bash +docker compose run --rm jobs Migration --rerun MIGRATION_NAME +``` diff --git a/docs/docs/self-hosting/ai.md b/docs/docs/self-hosting/ai.md new file mode 100644 index 0000000000..a71611e8ba --- /dev/null +++ b/docs/docs/self-hosting/ai.md @@ -0,0 +1,137 @@ +--- +title: "AI features" +metaTitle: "AI features for self-hosted Exceptionless" +description: "Turn on Exie with a model provider key, choose the model, connect coding agents to the built-in MCP server, and turn AI off." +sources: + - src/Exceptionless.Core/Configuration/AssistantOptions.cs + - src/Exceptionless.Core/Configuration/OAuthServerOptions.cs + - src/Exceptionless.Core/Billing/BillingPlans.cs + - src/Exceptionless.Core/Services/OAuthService.cs + - src/Exceptionless.Core/Services/SystemSettingsService.cs + - src/Exceptionless.Web/Assistant/AssistantAccessService.cs + - src/Exceptionless.Web/Assistant/AssistantModelSettingsService.cs + - src/Exceptionless.Web/Assistant/AssistantService.cs + - src/Exceptionless.Web/Assistant/AssistantLimits.cs + - src/Exceptionless.Web/Mcp/McpOriginValidationMiddleware.cs + - src/Exceptionless.Web/Api/Endpoints/OAuthEndpoints.cs + - src/Exceptionless.Web/Api/Handlers/OAuthHandler.cs + - src/Exceptionless.Web/ClientApp/src/lib/features/admin/components/assistant-settings.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/admin/schemas.ts + - k8s/exceptionless/templates/config.yaml +--- + +# AI features + +Self-hosted Exceptionless has two AI features. [Exie](/docs/ai/exie/), the assistant in the app, calls a model provider +with your API key. The [MCP server](/docs/ai/mcp-server/) lets coding agents such as Claude Code and Codex use your data +with their own model, and works without any provider key. This page covers setting up both, and turning them off. + +## Turn on Exie + +1. Create an API key at [OpenRouter](https://openrouter.ai/). Exie uses OpenRouter by default. +2. Set the key on the containers that serve the API, such as `app`: + + ```yaml + EX_Assistant__ApiKey: YOUR_OPENROUTER_API_KEY + ``` + + Setting a key turns Exie on, unless you also set `EX_Assistant__Enabled` to `false`. + +3. Restart the containers. Exie appears in the app for organizations whose plan includes it. + +Organizations created on a self-hosted instance without billing are on the Unlimited plan, which includes Exie. The +server needs outbound HTTPS access to the provider. + +When someone asks Exie a question, Exceptionless sends the conversation and the results of Exie's tools, which include +event and stack data from your projects, to the provider. See [AI privacy and security](/docs/ai/privacy/). + +## Choose the model {#choose-the-model} + +Exie uses `openai/gpt-6.1-sol` unless you choose another model. There are two ways to change it: + +- **When you deploy:** set `EX_Assistant__Model` to an OpenRouter model ID, such as `provider/model`. +- **At runtime:** as a global administrator, go to **Settings** > **System** > **Settings**, enter a model ID under + **Exie model**, and select **Save**. The change applies to new conversations and turns without a restart. **Reset** + returns to the deployed model. + +The model must support tool calling, because Exie answers questions by calling tools. + +To use a provider other than OpenRouter, set `EX_Assistant__Endpoint` to its chat completions URL. The endpoint must +accept OpenAI-style streaming chat completion requests with tools and a bearer API key. Exceptionless is built and +tested against OpenRouter, so other endpoints may need changes. + +## Usage limits and cost + +Each organization's plan limits how much it can use Exie. On the Unlimited plan, an organization can run 20 turns at +once and 100 turns a minute, and use up to 500 million tokens and $100 of provider cost a month. When it reaches a +monthly limit, Exie stops answering for that organization until the next month. + +Exceptionless records the cost the provider reports for each turn. If the provider doesn't report a cost, Exceptionless +estimates it at $2 per million prompt tokens and $8 per million completion tokens. To see usage and cost by +organization, go to **Settings** > **System** > **Exie**. See +[Administration](/docs/self-hosting/administration/#exie-usage). + +## Turn off Exie + +Do any of these: + +- Go to **Settings** > **System** > **Settings**, turn off **Exie availability**, and select **Save**. This applies to + every organization right away, without a restart. **Reset** returns to the deployed setting. +- Set `EX_Assistant__Enabled` to `false` and restart. +- Remove `EX_Assistant__ApiKey`. Without a key, Exie can't be turned on at runtime. + +## Set up the MCP server + +The MCP server is built in at `/mcp` on your API URL: `EX_ApiUrl` if you set it, otherwise `EX_BaseURL`. For example, +`https://errors.example.com/mcp`. Agents sign in with OAuth, so a person approves each connection and chooses which +organizations and scopes it gets. For connecting each agent, see [MCP server](/docs/ai/mcp-server/). + +```bash +claude mcp add --transport http exceptionless https://errors.example.com/mcp +``` + +For the MCP server to work: + +- **Set the public URLs.** OAuth discovery at `/.well-known/oauth-protected-resource/mcp` and + `/.well-known/oauth-authorization-server` advertises the origin of `EX_ApiUrl`, or of `EX_BaseURL` when `EX_ApiUrl` + isn't set. Agents must be able to reach that origin. People approve connections on the web app at `EX_BaseURL`. +- **Trust your reverse proxy.** Client registration is limited per IP address, so set up + [forwarded headers](/docs/self-hosting/reverse-proxy/) when a proxy is in front. +- **Allow browser-based clients.** Requests to `/mcp` from a browser carry an `Origin` header. The origins of + `EX_BaseURL` and `EX_ApiUrl` are always allowed. Add others as `EX_Mcp__AllowedOrigins__0`, + `EX_Mcp__AllowedOrigins__1`, and so on. Other origins get a 403. Agents that run outside a browser don't send an + origin and aren't affected. +- **Make it reachable for hosted clients.** Agents that run on your machine can use a private or `localhost` URL. + Clients that run on a provider's servers can connect only if your instance is reachable from the internet over HTTPS. + +Agents register themselves in one of two ways, and both are on by default: + +- **Dynamic client registration.** The agent registers through `/api/v2/oauth/register`. Each IP address can make 20 + registration attempts an hour; change it with `EX_OAuthServer__DynamicClientRegistrationIpLimit`. +- **Client ID metadata documents.** The agent uses an HTTPS URL as its client ID, and Exceptionless downloads the + client's details from it. This needs outbound HTTPS access. Turn it off with + `EX_OAuthServer__EnableClientIdMetadataDocuments=false`. + +Global administrators can also create clients by hand under **Settings** > **System** > **OAuth Apps**. Token lifetimes +and the other OAuth settings are in the +[configuration reference](/docs/self-hosting/configuration/#oauth-server-and-mcp). + +## Limit or turn off MCP access + +There's no setting that removes the `/mcp` endpoint, but it accepts only OAuth tokens that a user approved with the MCP +scope. To control access: + +- **Allow only clients you create.** Set `EX_OAuthServer__DynamicClientRegistrationIpLimit` to `0` and + `EX_OAuthServer__EnableClientIdMetadataDocuments` to `false`. Then only the OAuth apps a global administrator creates + under **Settings** > **System** > **OAuth Apps** can connect. +- **Cut off one client.** Under **OAuth Apps**, open the client, check **Disabled**, and select **Save Changes**. + Disabled clients can't authorize, refresh, or use existing access tokens. +- **Turn it off.** Block `/mcp` at your reverse proxy. + +People can also disconnect apps from their own account. See [Your account](/docs/account/). + +## Set it up with a coding agent + +```prompt agent +Read https://exceptionless.com/docs/self-hosting/ai.md. Add the settings to my Exceptionless compose.yaml to turn on Exie with OpenRouter, reading the API key from an .env file, and allow MCP connections from https://agent.example.com. +``` diff --git a/docs/docs/self-hosting/configuration.md b/docs/docs/self-hosting/configuration.md new file mode 100644 index 0000000000..dfda4b7d52 --- /dev/null +++ b/docs/docs/self-hosting/configuration.md @@ -0,0 +1,281 @@ +--- +title: "Configuration" +metaTitle: "Self-hosted Exceptionless configuration reference" +description: "Every self-hosted Exceptionless setting: EX_ environment variables, connection strings, email, storage, sign-in providers, OAuth, and AI." +sources: + - src/Exceptionless.Web/Program.cs + - src/Exceptionless.Web/appsettings.yml + - src/Exceptionless.Web/appsettings.Production.yml + - src/Exceptionless.Core/Configuration/CustomEnvironmentVariablesConfiguration.cs + - src/Exceptionless.Core/Configuration/AppOptions.cs + - src/Exceptionless.Core/Configuration/AuthOptions.cs + - src/Exceptionless.Core/Configuration/AssistantOptions.cs + - src/Exceptionless.Core/Configuration/CacheOptions.cs + - src/Exceptionless.Core/Configuration/ElasticsearchOptions.cs + - src/Exceptionless.Core/Configuration/EmailOptions.cs + - src/Exceptionless.Core/Configuration/MessageBusOptions.cs + - src/Exceptionless.Core/Configuration/OAuthServerOptions.cs + - src/Exceptionless.Core/Configuration/QueueOptions.cs + - src/Exceptionless.Core/Configuration/SlackOptions.cs + - src/Exceptionless.Core/Configuration/SourceMapOptions.cs + - src/Exceptionless.Core/Configuration/StorageOptions.cs + - src/Exceptionless.Core/Configuration/StripeOptions.cs + - src/Exceptionless.Core/Authentication/ActiveDirectoryLoginProvider.cs + - src/Exceptionless.Core/Utility/SmtpUri.cs + - src/Exceptionless.Insulation/Bootstrapper.cs + - src/Exceptionless.Web/Mcp/McpOriginValidationMiddleware.cs + - src/Exceptionless.Web/Security/TrustedForwardedHeadersOptions.cs + - src/Exceptionless.Web/ClientApp/src/lib/features/auth/index.svelte.ts + - build/update-config.sh +--- + +# Configuration + +This page lists the settings for a self-hosted Exceptionless instance, with the environment variable for each, its +default, and what it does. Give the app, API, and job containers the same settings. + +## How settings are read + +Exceptionless reads settings from these sources. Later sources override earlier ones: + +1. `appsettings.yml`, then `appsettings..yml`, then `appsettings.Local.yml`, from the app folder (`/app` in the + containers). +2. Environment variables. +3. Command-line arguments. + +Environment variable names follow these rules: + +- The `EX_` prefix is optional and is removed when the variable is read. Use it to keep Exceptionless settings apart + from others. +- Double underscores (`__`) separate nested keys: `EX_ConnectionStrings__Redis` sets `ConnectionStrings:Redis`. +- Lists use numbered keys: `EX_Mcp__AllowedOrigins__0`, `EX_Mcp__AllowedOrigins__1`. A few settings, noted below, take a + comma-separated list instead. +- Server-side names aren't case-sensitive. + +The `app` and all-in-one images also copy some settings into the web UI when the container starts. The UI reads only +environment variables with these exact names: `EX_ApiUrl`, `EX_EnableAccountCreation`, `EX_EnableSsl`, +`EX_NotificationMessage`, `EX_ExceptionlessApiKey`, `EX_ExceptionlessServerUrl`, `EX_ClientSetupShowServerUrl`, and the +client IDs in `EX_ConnectionStrings__OAuth`. Set them as environment variables, not in YAML, and restart the container +after you change them. + +> [!IMPORTANT] +> Always set `EX_BaseURL`. The built-in production settings point at the hosted service at exceptionless.com. + +## App + +| Environment variable | Default | What it does | +| ----------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `EX_BaseURL` | The hosted service; always set it | The public URL of the web app, without a trailing slash, for example `https://errors.example.com`. Used in email links, OAuth sign-in, and the MCP server. | +| `EX_ApiUrl` | `EX_BaseURL` | The public URL of the API, if it's on a different host name than the web app. The web UI sends its API calls there, and OAuth and MCP discovery use it. | +| `EX_AppMode` | `Production` | `Production`, `Staging`, or `Development`. Picks `appsettings..yml` and changes several defaults below. Set it as an environment variable. | +| `EX_AppScope` | `prod`, `stage`, or `dev`, from `EX_AppMode` | A prefix for index, queue, cache, and storage names, so several instances can share Elasticsearch and Redis. Changing it, or changing `EX_AppMode`, on an existing instance points it at new, empty indexes. | +| `EX_RunJobsInProcess` | `true` in `Development`, otherwise `false` | Runs the background jobs inside the web process. The `app` and all-in-one images set it to `true`. Set it to `false` when you run the `job` image, which also needs Redis. | +| `EX_EventSubmissionDisabled` | `false` | Rejects new events with HTTP 503. A global administrator can override it at runtime under **System** > **Settings**. | +| `EX_MaximumEventPostSize` | `200000` | The largest event submission request body, in bytes. | +| `EX_MaximumRetentionDays` | `180` | The most days events are kept, for every organization. Organizations on the Unlimited plan keep events this long. | +| `EX_ApiThrottleLimit` | `3500`; unlimited in `Development` | API requests allowed in 15 minutes for each organization API key, user, or anonymous client IP address. | +| `EX_BotThrottleLimit` | `25` | For projects that delete bot data, the events from one public client IP address in five minutes that mark it as a bot. Its events in that window are removed. | +| `EX_EnableWebSockets` | `true` | Sends real-time updates to the web UI over a WebSocket at `/api/v2/push`. | +| `EX_EnableSsl` | `false` | Moves the web UI from `http://` to `https://` on the same host and port, and tells browsers to upgrade insecure requests. Use it when HTTPS is served on the same host name, such as behind a reverse proxy. | +| `EX_EnableArchive` | `false` | Keeps a copy of every raw event submission in storage. | +| `EX_NotificationMessage` | None | A banner message for every user of the web UI. A notification set under **System** > **Notifications** takes its place. | +| `EX_DisabledPlugins` | None | A comma-separated list of event processing plugins to turn off, by class name, such as `GeoPlugin,LocationPlugin`. | +| `EX_MaxMindGeoIpKey` | None | A MaxMind license key. A daily job downloads the GeoLite2 City database and uses it to look up locations from IP addresses. | +| `EX_GoogleGeocodingApiKey` | None | A Google Geocoding API key used to resolve locations. | +| `EX_ExceptionlessApiKey` | None | An API key for an Exceptionless project that receives this instance's own errors and logs. The web UI reports its errors there too. | +| `EX_ExceptionlessServerUrl` | None | The server URL shown in the app's client setup instructions. With `EX_ExceptionlessApiKey`, also where this instance sends its own errors. | +| `EX_InternalProjectId` | The hosted service's project | The ID of the project that receives this instance's own errors, so they aren't processed in a loop. | +| `EX_ClientSetupShowServerUrl` | `true` | Set to `false` to leave the server URL out of the client setup instructions. | + +## Connection strings + +Connection strings use `key=value` pairs separated by semicolons. The Cache, Queue, MessageBus, and Storage connection +strings name a `provider`. If another connection string has the provider's name, its values are added, so +`provider=redis` reuses `EX_ConnectionStrings__Redis`. + +| Environment variable | Example | What it does | +| ------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `EX_ConnectionStrings__Elasticsearch` | `server=http://elasticsearch:9200` | Elasticsearch. See [Elasticsearch options](#elasticsearch-options). | +| `EX_ConnectionStrings__Redis` | `redis:6379,abortConnect=false` | Redis, in [StackExchange.Redis format](https://stackexchange.github.io/StackExchange.Redis/Configuration). When set, the cache, queues, and message bus use it unless you configure them separately. | +| `EX_ConnectionStrings__Cache` | `provider=redis` | The shared cache. `redis` is the only provider. Without Redis, each process keeps its own in-memory cache. | +| `EX_ConnectionStrings__Queue` | `provider=redis` | The work queues. See [Queues](#queues). | +| `EX_ConnectionStrings__MessageBus` | `provider=redis` | The message bus between processes: `redis` or `rabbitmq`. | +| `EX_ConnectionStrings__Storage` | `provider=folder;path=/app/storage` | File storage. See [Storage](#storage). The `app` and all-in-one images default to this example; without it, files are kept in memory. | +| `EX_ConnectionStrings__Email` | `smtp://user:password@smtp.example.com:587` | The SMTP server. See [Email](#email). | +| `EX_ConnectionStrings__OAuth` | `GitHubId=...;GitHubSecret=...` | Sign-in providers and Slack. See [Sign-in providers](#sign-in-providers). | +| `EX_ConnectionStrings__LDAP` | `LDAP://ad.example.com/DC=example,DC=com` | Active Directory sign-in. See [Active Directory](#active-directory). | + +### Elasticsearch options {#elasticsearch-options} + +Add these keys to the Elasticsearch connection string, for example +`server=https://es.example.com:9200;username=exceptionless;password=secret;replicas=1`. + +| Key | Default | What it does | +| -------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------- | +| `server` | `http://localhost:9200` | The Elasticsearch URL. A connection string with only a URL uses it as the server. | +| `username` | None | The user name for basic authentication. | +| `password` | None | The password for basic authentication. | +| `shards` | `1` | Primary shards for new indexes. | +| `replicas` | `1` in `Production`, otherwise `0` | Replicas for new indexes. Use `0` on a single-node cluster. | +| `field-limit` | `1500` | The mapping field limit for event indexes. | +| `enable-size-plugin` | `true`, except in `Development` | Uses the `mapper-size` plugin. Set to `false` if your cluster doesn't have it installed. | +| `scope` | `EX_AppScope` | Overrides the index name prefix for Elasticsearch only. | + +### Queues {#queues} + +| Provider | Keys | Notes | +| -------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `redis` | Reuses `EX_ConnectionStrings__Redis` | The usual choice. | +| `sqs` | `accesskey`, `secretkey`, `region` | Amazon SQS. Without keys, the default AWS credential chain is used. The region defaults to `us-east-1`. Exceptionless doesn't create SQS queues; create `EventPost`, `EventUserDescription`, `EventNotification`, `WebHookNotification`, `MailMessage`, and `WorkItemData`, each prefixed with the scope, such as `prod-EventPost`. | +| `azurestorage` | An Azure Storage connection string | Azure Storage queues. You can also set `EX_ConnectionStrings__AzureQueues` to an Azure Storage connection string instead. | + +Without a queue provider, queues are kept in memory and work only when everything runs in one process. + +### Storage {#storage} + +| Provider | Keys | Notes | +| -------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `folder` | `path` | A folder on disk. When the app and jobs run in separate containers, they must share it. | +| `s3` | `bucket`, `region`, `accesskey`, `secretkey` | Amazon S3. The bucket defaults to the scope plus `ex-events`, such as `prod-ex-events`, and the region to `us-east-1`. Without keys, the default AWS credential chain is used. | +| `azurestorage` | An Azure Storage connection string | Azure Blob Storage, in a container named with the scope plus `ex-events`. You can also set `EX_ConnectionStrings__AzureStorage` to an Azure Storage connection string instead. | +| `aliyun` | An Alibaba Cloud OSS connection string | Alibaba Cloud Object Storage Service. | + +## Email {#email} + +| Environment variable | Default | What it does | +| ----------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `EX_ConnectionStrings__Email` | None | The SMTP server, as `smtp://user:password@host:port`. Without it, no email is sent. | +| `EX_SmtpFrom` | None; `Exceptionless ` in `Development` | The from address, such as `Exceptionless `. Required to send email. | +| `EX_SmtpEncryption` | From the port | `None`, `StartTLS`, or `SSL`. By default, port 465 uses SSL, ports 587 and 2525 use STARTTLS, and other ports use none. | +| `EX_EnableDailySummary` | `true` in `Production`, otherwise `false` | Sends daily summary emails to users who turn them on. | +| `EX_AllowedOutboundAddresses` | None | Outside `Production`, a comma-separated list of addresses or domains that may receive email. Other email goes to `EX_TestEmailAddress`. | +| `EX_TestEmailAddress` | None; `admin@exceptionless.test` in `Development` | Outside `Production`, receives email meant for addresses not in `EX_AllowedOutboundAddresses`. Without it, that email is dropped. | +| `EX_ContactEmailAddress` | None | Receives messages from the contact form. | + +Include the port in the SMTP connection string; `smtp://` and `smtps://` behave the same, and the port picks the +encryption. Percent-encode reserved characters in the user name and password, such as `@` as `%40` and `+` as `%2B`. If +you set a user name, you must also set a password. + +## Accounts and sign-in + +| Environment variable | Default | What it does | +| ------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `EX_EnableAccountCreation` | `true` | When `false`, people can create an account only from an organization invite. This applies to email and password sign-up and to sign-in providers. | +| `EX_ConnectionStrings__OAuth` | None | Client IDs and secrets for sign-in providers and Slack, as `key=value` pairs. | +| `EX_ConnectionStrings__LDAP` | None | The LDAP path for Active Directory sign-in. | +| `EX_EnableActiveDirectoryAuth` | `true` when an LDAP path is set | Uses Active Directory to check passwords. | + +The first user who signs up on a new instance becomes a global administrator. + +### Sign-in providers {#sign-in-providers} + +Users can sign in with Microsoft, GitHub, or Google once you add that provider's keys to `EX_ConnectionStrings__OAuth`. +Set it as an environment variable on the `app` or all-in-one container, so the web UI shows the matching buttons: + +```bash +EX_ConnectionStrings__OAuth=MicrosoftId=YOUR_ID;MicrosoftSecret=YOUR_SECRET;GitHubId=YOUR_ID;GitHubSecret=YOUR_SECRET;GoogleId=YOUR_ID;GoogleSecret=YOUR_SECRET +``` + +Include only the providers you use. Each provider sends users back to the origin of your web app, such as +`https://errors.example.com`, so register that exact URL as the redirect URI. + +| Provider | Keys | Where to register | +| --------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Microsoft | `MicrosoftId`, `MicrosoftSecret` | An app registration in Microsoft Entra with a **Web** redirect URI and a client secret. Sign-in uses the `common` endpoint and the `User.Read` scope, so choose an account type that includes accounts in any organizational directory. | +| GitHub | `GitHubId`, `GitHubSecret` | A GitHub OAuth app. Set its authorization callback URL to your web app's origin. Exceptionless asks for the `user:email` scope. | +| Google | `GoogleId`, `GoogleSecret` | An OAuth client ID of type **Web application** in Google Cloud, with your web app's origin as an authorized redirect URI. Exceptionless asks for `openid profile email`. | + +### Slack + +Slack notifications use the same connection string, with `SlackId` and `SlackSecret` from a Slack app: + +1. [Create a Slack app](https://api.slack.com/apps) in your workspace. Don't distribute it outside your organization. +2. Under **OAuth & Permissions**, add your web app's origin, such as `https://errors.example.com`, as a redirect URL. +3. Copy the client ID and client secret from **Basic Information** into `SlackId=...;SlackSecret=...`. +4. Restart the containers. Users can then connect Slack from their project's integrations. + +### Active Directory {#active-directory} + +With `EX_ConnectionStrings__LDAP` set, Exceptionless checks passwords against Active Directory instead of storing them. + +- Set the value to your domain's LDAP path, such as `LDAP://ad.example.com/DC=example,DC=com`. To narrow the search, use + a more specific path, such as `LDAP://ad.example.com/OU=Users,DC=example,DC=com`. +- Users still sign up once with their directory email address and password. Exceptionless finds the account by its + `mail` attribute and signs in with its `sAMAccountName`. +- Active Directory sign-in uses Windows directory APIs, so it works only when Exceptionless runs on Windows. The Docker + images run on Linux and can't use it. + +## OAuth server and MCP {#oauth-server-and-mcp} + +Exceptionless is an OAuth server for the [MCP server](/docs/ai/mcp-server/) and for apps that call the API with OAuth +tokens. See [AI features](/docs/self-hosting/ai/) for how these fit together. + +| Environment variable | Default | What it does | +| ------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `EX_OAuthServer__AuthorizationCodeLifetimeMinutes` | `5` | How long an authorization code is valid. | +| `EX_OAuthServer__AccessTokenLifetimeMinutes` | `60` | How long an access token is valid. | +| `EX_OAuthServer__RefreshTokenLifetimeDays` | `30` | How long a refresh token is valid. | +| `EX_OAuthServer__RefreshTokenReuseGracePeriodMinutes` | `60` | How long a client can reuse a refresh token after it has been exchanged, for clients that retry. `0` turns reuse off. | +| `EX_OAuthServer__EnableClientIdMetadataDocuments` | `true` | Lets clients use an HTTPS URL as their client ID. Exceptionless downloads the client's metadata document from that URL. | +| `EX_OAuthServer__DynamicClientRegistrationIpLimit` | `20` | Dynamic client registrations allowed from one IP address per hour. | +| `EX_OAuthServer__ClientMetadataDocumentCacheLifetimeMinutes` | `60` | How long a downloaded client metadata document is cached. | +| `EX_OAuthServer__ClientMetadataDocumentRequestTimeoutSeconds` | `5` | The timeout for downloading a client metadata document. | +| `EX_OAuthServer__ClientMetadataDocumentMaxBytes` | `32768` | The largest client metadata document accepted. | +| `EX_Mcp__AllowedOrigins__0` | None | Extra browser origins allowed to call `/mcp`, one per numbered key. The origins of `EX_BaseURL` and `EX_ApiUrl` are always allowed. Requests without an `Origin` header aren't affected. | + +## AI + +Exie needs an API key for a model provider. See [AI features](/docs/self-hosting/ai/). + +| Environment variable | Default | What it does | +| ------------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------- | +| `EX_Assistant__ApiKey` | None | The model provider's API key. Exie is unavailable without it. | +| `EX_Assistant__Enabled` | `true` when an API key is set, otherwise `false` | Turns Exie on or off. A global administrator can override it under **System** > **Settings**. | +| `EX_Assistant__Endpoint` | `https://openrouter.ai/api/v1/chat/completions` | The chat completions endpoint. | +| `EX_Assistant__Model` | `openai/gpt-6.1-sol` | The model. A global administrator can override it under **System** > **Settings**. | + +## Reverse proxies + +| Environment variable | Default | What it does | +| --------------------------------------- | ------- | ----------------------------------------------------------------------------- | +| `EX_ForwardedHeaders__Enabled` | `true` | Reads `X-Forwarded-For` and `X-Forwarded-Proto` from trusted proxies. | +| `EX_ForwardedHeaders__ForwardLimit` | `1` | How many proxy hops to process. | +| `EX_ForwardedHeaders__KnownProxies__0` | None | A trusted proxy IP address, one per numbered key. Loopback is always trusted. | +| `EX_ForwardedHeaders__KnownNetworks__0` | None | A trusted proxy network in CIDR form, one per numbered key. | + +See [Reverse proxies and HTTPS](/docs/self-hosting/reverse-proxy/) for how to set these. + +## Source maps + +Settings for [source maps](/docs/clients/javascript/source-maps/) are in the `SourceMaps` section. The most useful: + +| Environment variable | Default | What it does | +| --------------------------------------------- | ------------------- | --------------------------------------------------------------------------- | +| `EX_SourceMaps__EnableAutoDownload` | `true` | Downloads source maps for scripts served over HTTPS when none was uploaded. | +| `EX_SourceMaps__MaximumSourceMapSize` | `20971520` (20 MB) | The largest source map, in bytes. | +| `EX_SourceMaps__MaximumGeneratedFileSize` | `5242880` (5 MB) | The largest generated JavaScript file, in bytes. | +| `EX_SourceMaps__MaximumArtifactsPerProject` | `1000` | Source maps kept per project. | +| `EX_SourceMaps__MaximumStorageSizePerProject` | `1073741824` (1 GB) | Source map storage per project, in bytes. | +| `EX_SourceMaps__ArtifactRetentionDays` | `90` | Days to keep source maps. | +| `EX_SourceMaps__RequestTimeoutMilliseconds` | `3000` | The timeout for each download. | + +The rest of the limits, including separate limits for the Free plan, are in +[SourceMapOptions.cs](https://github.com/exceptionless/Exceptionless/blob/main/src/Exceptionless.Core/Configuration/SourceMapOptions.cs). + +## HTTPS, logging, and telemetry + +| Environment variable | Default | What it does | +| --------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `ASPNETCORE_URLS` | `http://+:8080` in the images | The addresses the app listens on, such as `http://+:8080;https://+:8443`. | +| `EX_Kestrel__Certificates__Default__Path` | None | A PFX certificate file for HTTPS. Use the `EX_` prefix; `ASPNETCORE_Kestrel__...` variables aren't read. | +| `EX_Kestrel__Certificates__Default__Password` | None | The certificate's password. | +| `EX_Serilog__MinimumLevel__Default` | `Warning` in `Production`, otherwise `Information` | The log level: `Verbose`, `Debug`, `Information`, `Warning`, `Error`, or `Fatal`. | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | None | An OpenTelemetry collector. When set, Exceptionless exports traces, metrics, and logs to it. | + +## Hosted service settings + +These settings run billing and support on the hosted service. Leave them unset on your own instance. Without +`EX_StripeApiKey`, billing is off and new organizations get the Unlimited plan. + +- `EX_StripeApiKey`, `EX_StripePublishableApiKey`, and `EX_StripeWebHookSigningSecret` +- `IntercomId` and `IntercomSecret` in `EX_ConnectionStrings__OAuth` diff --git a/docs/docs/self-hosting/docker.md b/docs/docs/self-hosting/docker.md index 4d637fdf6a..05430acf24 100644 --- a/docs/docs/self-hosting/docker.md +++ b/docs/docs/self-hosting/docker.md @@ -1,85 +1,236 @@ --- title: "Docker" -metaTitle: "Self-hosting Exceptionless with Docker" -description: "Run self-hosted Exceptionless with Docker: a throwaway test container, a setup with persisted Elasticsearch data, and a setup with SSL and SMTP email." +metaTitle: "Self-hosting Exceptionless with Docker Compose" +description: "Run self-hosted Exceptionless with Docker Compose, or try it in one container. Covers persistent data, email, and HTTPS." +sources: + - Dockerfile + - samples/docker-compose.yml + - samples/docker-compose.all-in-one.yml + - samples/hosting-samples.sh + - build/docker-entrypoint.sh + - build/update-config.sh + - src/Exceptionless.Web/Program.cs + - src/Exceptionless.Core/Configuration/CustomEnvironmentVariablesConfiguration.cs + - src/Exceptionless.Core/Configuration/EmailOptions.cs + - src/Exceptionless.Core/Utility/SmtpUri.cs + - src/Exceptionless.Core/Configuration/ElasticsearchOptions.cs --- # Docker -If you place a reverse proxy in front of the container, configure its [trusted forwarding peers](/docs/self-hosting/#reverse-proxies-and-https) before upgrading. The direct-port examples below do not require proxy trust settings. - -If you would like to test Exceptionless locally, please follow this section. +This guide runs Exceptionless with Docker Compose: the app, the background jobs, Elasticsearch, and Redis, each in its +own container, with data kept between restarts. To look around first, you can also +[run everything in one container](#try-it-with-one-container). + +You need [Docker](https://docs.docker.com/get-started/get-docker/) with Docker Compose. + +## Run Exceptionless with Docker Compose + +1. Save this file as `compose.yaml` in an empty folder: + + ```yaml + # Settings shared by the app and the jobs. + x-exceptionless-config: &exceptionless-config + EX_AppMode: Production + # The public URL of the web app. Used in email links, OAuth, and the MCP server. + EX_BaseURL: http://localhost:7110 + # The server URL shown in the app's client setup instructions. + EX_ExceptionlessServerUrl: http://localhost:7110 + EX_ConnectionStrings__Elasticsearch: server=http://elasticsearch:9200;replicas=0 + EX_ConnectionStrings__Redis: redis,abortConnect=false + EX_ConnectionStrings__Storage: provider=folder;path=/app/storage + EX_RunJobsInProcess: "false" + # Uncomment to send email. + # EX_ConnectionStrings__Email: smtp://user:password@smtp.example.com:587 + # EX_SmtpFrom: Exceptionless + + services: + app: + image: exceptionless/app:latest + environment: *exceptionless-config + ports: + - 7110:8080 + volumes: + - ex_storage:/app/storage + depends_on: + elasticsearch: + condition: service_healthy + redis: + condition: service_started + restart: unless-stopped + + jobs: + image: exceptionless/job:latest + environment: *exceptionless-config + volumes: + - ex_storage:/app/storage + depends_on: + app: + condition: service_started + restart: unless-stopped + + elasticsearch: + image: exceptionless/elasticsearch:8.19.22 + environment: + discovery.type: single-node + xpack.security.enabled: "false" + ES_JAVA_OPTS: -Xms1g -Xmx1g + volumes: + - ex_esdata:/usr/share/elasticsearch/data + healthcheck: + test: [ + "CMD-SHELL", + "curl -fsS 'http://localhost:9200/_cluster/health?wait_for_status=yellow&timeout=1s' > /dev/null", + ] + interval: 10s + timeout: 10s + retries: 30 + start_period: 20s + restart: unless-stopped + + redis: + image: redis:7.4-alpine + volumes: + - ex_redisdata:/data + restart: unless-stopped + + volumes: + ex_esdata: + ex_storage: + ex_redisdata: + ``` + +2. Start it: + + ```bash + docker compose up -d + ``` + + The first start takes a minute or two while Elasticsearch starts and Exceptionless creates its indexes. The jobs + container runs any pending migrations each time it starts. + +3. Open `http://localhost:7110` and sign up. The first account on a new instance is a global administrator. + +4. Create an organization and a project, then [send your first event](/docs/getting-started/). Point your client at your + server, for example `serverUrl: "http://localhost:7110"` in JavaScript or `ServerUrl` in .NET. + +What the file sets up: + +- The `app` container serves the web UI and the API on port 7110. `EX_RunJobsInProcess: "false"` leaves the background + work to the `jobs` container. +- The `jobs` container runs every background job. It shares the `ex_storage` volume with the app, because the app saves + incoming events there before the jobs process them. +- Redis carries the cache, queues, and messages between the two. Setting only `EX_ConnectionStrings__Redis` is enough; + the cache, queue, and message bus use it automatically. +- `replicas=0` creates indexes without replicas, because a single Elasticsearch node can't hold them. + +To see the logs, run `docker compose logs -f app jobs`. + +## Use your own domain + +When you serve Exceptionless at a real host name, change `EX_BaseURL` and `EX_ExceptionlessServerUrl` to that URL, for +example `https://errors.example.com`, and run `docker compose up -d` again. + +Put a reverse proxy such as nginx or Caddy in front of the app to handle HTTPS, and tell Exceptionless to trust it. See +[Reverse proxies and HTTPS](/docs/self-hosting/reverse-proxy/). Every setting you can add to the shared block is in the +[configuration reference](/docs/self-hosting/configuration/). + +## Send email + +Exceptionless sends email for sign-up verification, password resets, invites, notifications, and daily summaries. Add an +SMTP connection string and a from address to the shared settings: + +```yaml +EX_ConnectionStrings__Email: smtp://user:password@smtp.example.com:587 +EX_SmtpFrom: Exceptionless +``` -## Requirements +- Always include the port. Exceptionless picks the encryption from it: SSL for 465, STARTTLS for 587 and 2525, and none + for other ports. To choose yourself, set `EX_SmtpEncryption` to `None`, `StartTLS`, or `SSL`. +- Percent-encode reserved characters in the user name and password. For example, `@` becomes `%40`, `#` becomes `%23`, + and `+` becomes `%2B`. +- Use a from address that your SMTP provider allows you to send from. In `Production` mode there is no default, and + email fails without one. -* [Docker](https://www.docker.com) +## Try it with one container {#try-it-with-one-container} -## Testing Setup +The `exceptionless/exceptionless` image runs the app, the jobs, and Elasticsearch in one container, with in-memory +queues and cache. It's good for a first look and for testing, not for production. -Runs Exceptionless without persisting data between runs. Good for checking out Exceptionless for the first time and testing. +This command keeps nothing when the container stops: ```bash -docker run --rm -it -p 5200:8080 exceptionless/exceptionless:latest +docker run --rm -it -p 7110:8080 \ + -e EX_BaseURL=http://localhost:7110 \ + exceptionless/exceptionless:latest ``` -## Simple Setup +Open `http://localhost:7110` once the log shows the app has started. -Runs a very simple non-production setup for Exceptionless with data persisted between runs in a sub-directory of the current directory called `esdata`. It uses an embedded single node Elasticsearch cluster and does not have backups. It is recommended that you create your own Elasticsearch cluster for production deployments of Exceptionless. - -On Linux: +To keep your data between runs, store Elasticsearch's data in a named volume: ```bash -docker run --rm -it -p 5200:8080 \ - -v $(pwd)/esdata:/usr/share/elasticsearch/data \ - exceptionless/exceptionless:latest +docker run --rm -it -p 7110:8080 \ + -e EX_BaseURL=http://localhost:7110 \ + -v ex_esdata:/usr/share/elasticsearch/data \ + exceptionless/exceptionless:latest ``` -On PowerShell: +In PowerShell, end each line with a backtick (`` ` ``) instead of a backslash. -```powershell -docker run --rm -it -p 5200:8080 ` - -v ${PWD}/esdata:/usr/share/elasticsearch/data ` - exceptionless/exceptionless:latest -``` +## Add HTTPS and email to one container {#simple-setup-wssl-support-and-smtp} + +The app can serve HTTPS itself with a certificate file. This example serves HTTP on port 7110 and HTTPS on port 7111, +and sends email through SMTP. + +1. Create a certificate. For a local test, export the .NET development certificate: + + ```bash + dotnet dev-certs https -ep ~/.aspnet/https/aspnetapp.pfx -p password + ``` -## Simple Setup w/SSL Support and SMTP + For a real server, use a certificate for your host name in PFX format. The container runs as a non-root user, so the + file must be readable by others. -Runs a very simple non-production setup for Exceptionless with data persisted between runs in a sub-directory of the current directory called `esdata`. It uses an embedded single node Elasticsearch cluster and does not have backups. It is recommended that you create your own Elasticsearch cluster for production deployments of Exceptionless. In the SMTP password characters disallowed or reserved according to RFC-2396 (e.g. @:#/?+) need to be percent-encoded (e.g. # => %23). +2. Run the container: -Set `EX_BaseURL` to the externally accessible Exceptionless URL and use an `EX_SmtpFrom` address authorized by your SMTP provider. + ```bash + docker run --rm -it -p 7110:8080 -p 7111:8443 \ + -e ASPNETCORE_URLS="http://+:8080;https://+:8443" \ + -e EX_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx \ + -e EX_Kestrel__Certificates__Default__Password=password \ + -e EX_BaseURL=https://localhost:7111 \ + -e EX_ConnectionStrings__Email=smtp://user:password@smtp.example.com:587 \ + -e "EX_SmtpFrom=Exceptionless " \ + -v ~/.aspnet/https:/https:ro \ + -v ex_esdata:/usr/share/elasticsearch/data \ + exceptionless/exceptionless:latest + ``` -On Linux: + - `ASPNETCORE_URLS` makes the app listen for HTTP on port 8080 and HTTPS on port 8443 inside the container. The `-p` + options publish them as 7110 and 7111. + - The certificate settings use the `EX_` prefix. Exceptionless doesn't read `ASPNETCORE_Kestrel__...` variables. + - HTTP stays available on port 7110. + +3. Open `https://localhost:7111`. + +The same `ASPNETCORE_URLS` and certificate settings work on the `app` container in the Compose file. Most production +setups terminate HTTPS at a [reverse proxy](/docs/self-hosting/reverse-proxy/) instead. + +## Upgrade + +Pull the new images and recreate the containers: ```bash -docker run --rm -it -p 5200:8080 -p 5089:443 \ - -e EX_ConnectionStrings__Email=smtps://user:password@smtp.host.com:587 \ - -e EX_BaseURL=https://example.com \ - -e 'EX_SmtpFrom=Exceptionless ' \ - -e ASPNETCORE_URLS="https://+;http://+" \ - -e ASPNETCORE_HTTPS_PORT=5001 \ - -e ASPNETCORE_Kestrel__Certificates__Default__Password="password" \ - -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx \ - -v ~/.aspnet/https:/https/ \ - -v $(PWD)/esdata:/usr/share/elasticsearch/data \ - exceptionless/exceptionless:latest +docker compose pull +docker compose up -d ``` -On PowerShell: - -```powershell -docker run --rm -it -p 5200:8080 -p 5089:443 ` - -e EX_ConnectionStrings__Email=smtps://user:password@smtp.host.com:587 ` - -e EX_BaseURL=https://example.com ` - -e "EX_SmtpFrom=Exceptionless " ` - -e ASPNETCORE_URLS="https://+;http://+" ` - -e ASPNETCORE_HTTPS_PORT=5001 ` - -e ASPNETCORE_Kestrel__Certificates__Default__Password="password" ` - -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx ` - -v ~/.aspnet/https:/https/ ` - -v ${PWD}/esdata:/usr/share/elasticsearch/data ` - exceptionless/exceptionless:latest -``` +Migrations run when the jobs container starts. See [Upgrading](/docs/self-hosting/upgrading-self-hosted-instance/) for +what to check first. ---- +## Set it up with a coding agent -[Next > Kubernetes](/docs/self-hosting/kubernetes) +```prompt agent +Read https://exceptionless.com/docs/self-hosting/docker.md and https://exceptionless.com/docs/self-hosting/reverse-proxy.md. Write a compose.yaml that runs self-hosted Exceptionless at https://errors.example.com behind Caddy, with SMTP email through smtp.example.com on port 587. Trust only the Caddy container as a proxy. +``` diff --git a/docs/docs/self-hosting/index.md b/docs/docs/self-hosting/index.md index f0ce90a395..3276e3a715 100644 --- a/docs/docs/self-hosting/index.md +++ b/docs/docs/self-hosting/index.md @@ -1,59 +1,94 @@ --- -title: "Self Hosting" -metaTitle: "Self-hosting Exceptionless overview" -description: "Self-host Exceptionless with Docker or Kubernetes and configure trusted reverse proxies with ForwardedHeaders so client IPs and HTTPS are detected." +title: "Self-hosting" +metaTitle: "Self-hosting Exceptionless: overview and requirements" +description: "Run Exceptionless on your own servers: the Docker images, Elasticsearch and Redis requirements, and storage and email options." +sources: + - Dockerfile + - build/docker/elasticsearch/8.x/Dockerfile + - samples/docker-compose.yml + - samples/docker-compose.all-in-one.yml + - k8s/exceptionless/values.yaml + - src/Exceptionless.Core/Configuration/AppOptions.cs + - src/Exceptionless.Core/Configuration/ElasticsearchOptions.cs + - src/Exceptionless.Core/Configuration/StorageOptions.cs + - src/Exceptionless.Core/Configuration/EmailOptions.cs + - src/Exceptionless.Insulation/Bootstrapper.cs + - src/Exceptionless.Job/JobRunnerOptions.cs + - src/Exceptionless.Web/Api/Handlers/AuthHandler.cs + - src/Exceptionless.Web/Api/Handlers/OrganizationHandler.cs --- -# Self Hosting +# Self-hosting -Exceptionless can be self-hosted by either manually running the source code for the server and the frontend or by using our simply Docker image. +Exceptionless is open source, and you can run the same app that powers the hosted service on your own servers. This page +explains the pieces you run and what they need. To get started, follow the [Docker guide](/docs/self-hosting/docker/). -You can also use Kubernetes while self-hosting Exceptionless. We'll cover both topics in the following pages. +## Ways to run it -* [Docker](/docs/self-hosting/docker) -* [Kubernetes](/docs/self-hosting/kubernetes) -* [Upgrading](/docs/self-hosting/upgrading-self-hosted-instance) +- **Docker Compose** is the recommended setup. It runs the app, the background jobs, Elasticsearch, and Redis as + separate containers. See [Docker](/docs/self-hosting/docker/). +- **The all-in-one image** runs everything, including Elasticsearch, in one container. Use it to try Exceptionless, not + for production. See [Try it with one container](/docs/self-hosting/docker/#try-it-with-one-container). +- **Kubernetes** with the Helm chart in the repository. See [Kubernetes](/docs/self-hosting/kubernetes/). -## Reverse proxies and HTTPS +## Architecture -Direct HTTP/HTTPS hosting needs no forwarded-header configuration. The API accepts `X-Forwarded-For` and `X-Forwarded-Proto` only from loopback or explicitly trusted proxies. A known proxy is the **source IP of the connection reaching the API**, not its hostname, public frontend IP, Kubernetes Service IP, or proxy identifier. For Docker bridges or NAT, verify the address seen inside the API container. +Exceptionless is an ASP.NET Core app with a Svelte web UI. Clients post events to the API, which stores the raw +submission in file storage and queues it. A background job processes the queue, groups events into stacks, and writes +them to Elasticsearch. Other jobs send notifications and email, call webhooks, clean up old data, and run migrations. -Before upgrading from unrestricted forwarding, configure every non-loopback proxy that must supply client addresses or HTTPS schemes. Otherwise requests use the proxy IP and backend scheme: unrelated users can share IP-based limits and HTTPS detection can be incorrect. Set the public website `EX_BaseURL` and API `EX_ApiUrl` separately; forwarded headers do not configure public origins. +The images are published to Docker Hub: -Use this section in the web application's `appsettings.Local.yml`, replacing the example address with the verified proxy source IP: +| Image | What it runs | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `exceptionless/app` | The web UI and the API in one process on port 8080. It runs the background jobs in the same process unless you set `EX_RunJobsInProcess=false`. | +| `exceptionless/api` | The API without the web UI, on port 8080. | +| `exceptionless/job` | The background jobs. With no arguments it runs every job, including migrations. Pass a job name, such as `EventPosts` or `Migration`, to run one job. | +| `exceptionless/exceptionless` | The all-in-one image: the app, the jobs, and a single-node Elasticsearch in one container, on port 8080. | +| `exceptionless/elasticsearch` | Elasticsearch 8.19.22 with the `mapper-size` plugin installed. Use it, or install the plugin in your own cluster. | -```yaml -ForwardedHeaders: - Enabled: true - ForwardLimit: 1 - KnownProxies: - - 192.0.2.10 -``` +The app and job images run the same code and read the same [configuration](/docs/self-hosting/configuration/), so give +them the same settings. -The equivalent Docker Compose `environment` entries, or Helm values under the chart's existing `config` map, are: +## Requirements {#requirements} -```yaml -EX_ForwardedHeaders__Enabled: "true" -EX_ForwardedHeaders__ForwardLimit: "1" -EX_ForwardedHeaders__KnownProxies__0: "192.0.2.10" -``` +- **Elasticsearch 8.** The images and samples use Elasticsearch 8.19.22. Outside development mode, Exceptionless uses + the `mapper-size` plugin. Install it in your cluster, use the `exceptionless/elasticsearch` image, or add + `enable-size-plugin=false` to the Elasticsearch connection string. +- **Redis**, when the app and the jobs run in separate processes. Redis holds the shared cache, the queues, and the + message bus. Without it, Exceptionless uses in-memory versions that only work inside one process, like the all-in-one + image. The sample Compose file uses `redis:7.4-alpine`. +- **File storage** for queued event submissions and other files. Choose one: + - A folder, shared by the app and job containers (`provider=folder`). The `app` and all-in-one images default to + `/app/storage`. + - Amazon S3 (`provider=s3`). + - Azure Blob Storage (`provider=azurestorage`). + - Alibaba Cloud OSS (`provider=aliyun`). +- **An SMTP server** to send email: sign-up verification, password resets, invites, notifications, and daily summaries. + Without one, Exceptionless runs but sends no email. +- **The public URL** of your web app, set as `EX_BaseURL`. Links in email, OAuth sign-in, and the MCP server use it. -For changing proxy addresses, use `KnownNetworks` **instead of** `KnownProxies` with a verified, dedicated proxy CIDR, for example `EX_ForwardedHeaders__KnownNetworks__0: "192.0.2.0/24"`. Do not trust the whole cluster, Docker bridge, or private address space when other workloads can connect from it. Use network access controls to restrict backend access. IPv4 and IPv6 addresses/CIDRs are supported; IPv4 entries also match IPv4-mapped IPv6 peers. Use canonical network CIDRs; hostnames, ports, comma-separated scalar lists, malformed entries, and `/0` networks are rejected at startup. +Every setting, with its environment variable and default, is in the +[configuration reference](/docs/self-hosting/configuration/). -All supported Exceptionless settings belong under `ForwardedHeaders`. `Enabled` defaults to `true`; set `ForwardedHeaders:Enabled` to `false` (environment variable `EX_ForwardedHeaders__Enabled=false`) to leave client addresses and schemes unchanged. Exceptionless reads and validates this section once at startup into `TrustedForwardedHeadersOptions`, then configures ASP.NET Core's `ForwardedHeadersOptions` from those typed values through [.NET's options registration](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/options?view=aspnetcore-10.0). ASP.NET Core does not automatically bind this section. The group and `Enabled` switch are Exceptionless settings. +## Accounts and plans -`ForwardLimit` and `KnownProxies` match [ASP.NET Core's forwarded-header options](https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/proxy-load-balancer?view=aspnetcore-10.0#forwarded-headers-middleware-options). The `KnownNetworks` configuration key retains the older framework name; Exceptionless parses its CIDR strings into .NET 10's [`KnownIPNetworks` property](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.builder.forwardedheadersoptions.knownipnetworks?view=aspnetcore-10.0). Both address lists are parsed and validated explicitly while preserving the framework's loopback defaults. Boolean settings use .NET's typed `GetValue` conversion; malformed booleans fail startup. +The first user to sign up on a new instance becomes a global administrator and can open the +[system administration pages](/docs/self-hosting/administration/). To stop strangers from signing up, set +`EX_EnableAccountCreation=false` after you create your account; people can then join only through an organization +invite. -`ForwardLimit` defaults to one entry, processed from right to left. Multiple proxies require a finite limit matching the intended chain and trust for each traversed peer. Processing stops at an unknown peer even with unused hop budget. Zero also disables processing for compatibility; negative or non-integer limits are invalid. +Billing is off unless you configure Stripe, so new organizations get the Unlimited plan: no event, project, or user +limits, and events are kept for `EX_MaximumRetentionDays` (180 days by default). -Do not set the separate framework variable `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true`. [Microsoft documents that this shortcut clears the trusted-peer lists](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/8.0/forwarded-headers-unknown-proxies). ASP.NET Core exposes it internally as [`ForwardedHeaders_Enabled`](https://github.com/dotnet/aspnetcore/blob/release/10.0/src/DefaultBuilder/src/ForwardedHeadersOptionsSetup.cs#L21); Exceptionless rejects the active shortcut at startup. This framework key is not part of the Exceptionless configuration group and cannot replace `ForwardedHeaders:Enabled`. +## Reverse proxies and HTTPS {#reverse-proxies-and-https} -The public edge proxy must derive the scheme from its connection and replace untrusted forwarding headers, or append the observed client address so the configured hop limit cannot reach user-supplied entries. Configure Nginx, Caddy, Traefik, or other proxies accordingly. Loopback proxies and IIS out-of-process integration normally need no additional trust entries. A remote IIS/ARR proxy needs the same explicit peer configuration as other remote proxies. +If a reverse proxy or load balancer terminates HTTPS in front of Exceptionless, tell Exceptionless which proxy addresses +to trust. It reads `X-Forwarded-For` and `X-Forwarded-Proto` only from loopback and from the proxies you list, so +without that setting every request appears to come from the proxy. See +[Reverse proxies and HTTPS](/docs/self-hosting/reverse-proxy/). -Environment variables override YAML by key; command-line values override both. Use double underscores for nesting and numbered entries for lists. Overriding index `0` does not remove other entries inherited from YAML; remove obsolete trust entries from their source and restart after changes. Avoid defining the same key with both prefixed and unprefixed environment names. +## AI features -The API processes IP/scheme headers before redirect, authentication, and throttling middleware. It does not consume `X-Forwarded-Host` or `X-Forwarded-Prefix`; preserve the public Host and root paths. Verify HTTPS, client IPs, redirects, and IP-based limits through the actual proxy chain before rollout. Enable `EX_Serilog__MinimumLevel__Override__Microsoft.AspNetCore.HttpOverrides: "Debug"` temporarily to diagnose unknown peers. See [Microsoft's proxy guidance](https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/proxy-load-balancer?view=aspnetcore-10.0). - ---- - -[Next > Docker](/docs/self-hosting/docker) +Exie, the in-app assistant, needs an API key for a model provider. The MCP server for coding agents works without one. +See [AI features](/docs/self-hosting/ai/). diff --git a/docs/docs/self-hosting/kubernetes.md b/docs/docs/self-hosting/kubernetes.md index 18538b9210..66c2c62ab2 100644 --- a/docs/docs/self-hosting/kubernetes.md +++ b/docs/docs/self-hosting/kubernetes.md @@ -1,163 +1,265 @@ --- title: "Kubernetes" -metaTitle: "Self-hosting Exceptionless on Kubernetes" -description: "Deploy self-hosted Exceptionless on Kubernetes with Helm: EX_ config map values, connection strings, ingress proxy trust, Active Directory, and Slack." +metaTitle: "Self-hosting Exceptionless on Kubernetes with Helm" +description: "Deploy self-hosted Exceptionless on Kubernetes with the Helm chart: values, connection strings, ingress, proxy trust, and migrations." +sources: + - k8s/exceptionless/Chart.yaml + - k8s/exceptionless/values.yaml + - k8s/exceptionless/templates/config.yaml + - k8s/exceptionless/templates/app.yaml + - k8s/exceptionless/templates/api.yaml + - k8s/exceptionless/templates/jobs.yaml + - k8s/exceptionless/templates/storage.yaml + - k8s/exceptionless/templates/elasticsearch.yaml + - k8s/exceptionless/templates/redis.yaml + - k8s/exceptionless/templates/_helpers.tpl + - src/Exceptionless.Core/Authentication/ActiveDirectoryLoginProvider.cs + - src/Exceptionless.Web/Api/Endpoints/StatusEndpoints.cs --- -# Self-hosting Exceptionless on Kubernetes +# Kubernetes -Please follow this section to set up Exceptionless in a Kubernetes environment. Please note this section is a work in progress, any contributions is greatly appreciated. +The Exceptionless repository includes a Helm chart that runs the app, the API, and each background job as separate +deployments. This page shows how to install it, which values to set, and how to route traffic to it. ## Requirements -* [Kubernetes](https://kubernetes.io) -* [Helm](https://helm.sh) +- A Kubernetes cluster and [Helm](https://helm.sh/). +- Elasticsearch 8 with the `mapper-size` plugin, such as the `exceptionless/elasticsearch:8.19.22` image. See + [Requirements](/docs/self-hosting/#requirements). +- Redis. +- File storage that every pod can share: Amazon S3, Azure Blob Storage, or a `ReadWriteMany` volume. +- An ingress controller or gateway that terminates HTTPS. + +## What the chart deploys + +| Resource | What it runs | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| `-app` | The `exceptionless/app` image: the web UI and API for your app domains, with real-time updates. Jobs don't run in it. | +| `-api` | The `exceptionless/api` image: the API for your API domains, where clients send events. WebSockets are off. | +| `-jobs-*` deployments | One deployment per continuous job, such as `event-posts`, `event-notifications`, `mail-message`, `web-hooks`, and `work-item`. | +| `-jobs-*` cron jobs | Scheduled jobs: `cleanup-data`, `cleanup-orphaned-data`, `download-geoip-database`, and `maintain-indexes`. | +| `-jobs-migration` | A cron job that never runs on its own. You start it after each install or upgrade. See [Run migrations](#run-migrations). | +| `-config` | A config map with the `EX_` settings, shared by every pod. | -## Instructions +`` is the Helm release name. -Please note that we recommend you use Kubernetes for running in production. +## Install -1. Follow the steps [here](https://github.com/exceptionless/Exceptionless/blob/master/k8s/ex-setup.ps1) for how to create it in AKS -2. View the configuration settings below for more information on configuring Exceptionless. -3. [Configure your clients](/docs/clients/) to send errors to your website. +The chart isn't published to a Helm repository. Install it from a clone of the repository: -Now, you can create a local account, organization, and project and send events to it. +1. Clone the repository: -## Configuration + ```bash + git clone https://github.com/exceptionless/Exceptionless.git + ``` -The following section will cover how to configure exceptionless inside of a Kubernetes instance using the `exceptionless-config` config map. All exceptionless configuration keys are prefixed with `EX_`. Please note that these instructions also apply to docker using environment variables. +2. Create a values file, such as `exceptionless-values.yaml`. Replace the domains and connection strings with yours: -All configuration options and settings can be found in the various option classes located [here](https://github.com/exceptionless/Exceptionless/tree/master/src/Exceptionless.Core/Configuration). + ```yaml + version: "9.0.0" -The same `EX_` environment keys work in Docker Compose. Nested keys use double underscores. + app: + defaultDomain: errors.example.com + domains: + - errors.example.com -### Trusted ingress peers + api: + defaultDomain: api.errors.example.com + domains: + - api.errors.example.com -Before deploying behind ingress, configure [trusted forwarding peers](/docs/self-hosting/#reverse-proxies-and-https) through the Helm chart's existing `config` map. For example, after replacing the documentation address with a verified proxy source address: + elasticsearch: + connectionString: server=http://elasticsearch.example.svc:9200 -```yaml -config: - EX_ForwardedHeaders__KnownProxies__0: "192.0.2.10" - EX_ForwardedHeaders__Enabled: "true" - EX_ForwardedHeaders__ForwardLimit: "1" -``` + redis: + connectionString: redis.example.svc:6379,abortConnect=false -For a dedicated ingress subnet with a single proxy hop, configure the chart's `forwardedHeaders.knownNetworks` list instead. Replace this example with your verified proxy subnet: + storage: + connectionString: provider=s3;bucket=exceptionless-files;region=us-east-1 -```yaml -forwardedHeaders: - knownNetworks: - - 192.0.2.0/24 -``` + email: + connectionString: smtp://user:password@smtp.example.com:587 -The chart converts this list into indexed `EX_ForwardedHeaders__KnownNetworks__*` keys, enables forwarding, and sets a forward limit of one for both application hosts. Replacing the list removes obsolete subnet entries even with `--reuse-values`. Combining a nonempty list with manual `ForwardedHeaders` entries in `config` is rejected; remove conflicting entries from saved release values. The reusable chart's list is empty by default. For multiple proxy hops or other forwarding options, use explicit settings in `config` instead. + config: + EX_SmtpFrom: "Exceptionless " -The hosted development and production values files explicitly trust `10.60.64.0/24`, the dedicated `ex-net-v6/ex-agc` association subnet for `kube-system/public-alb`. Update both files with any gateway subnet change. Deployments use these reviewed values without querying Azure for proxy trust. Self-hosted installations must configure their own proxy addresses. + otel: + enabled: false + ``` -The repository's Azure Application Gateway for Containers ingress terminates TLS and routes directly to application Services on port 80 and pods on port 8080. Verify the API-visible peer and any intermediate proxies before the first rollout and whenever the network changes. The ALB controller pod and Service address are not substitutes for the gateway's [association subnet](https://learn.microsoft.com/en-us/azure/application-gateway/for-containers/application-gateway-for-containers-components). +3. Install the chart: -### Rollout checks and configuration failures + ```bash + helm install exceptionless ./Exceptionless/k8s/exceptionless \ + --namespace exceptionless --create-namespace \ + --values exceptionless-values.yaml + ``` -Before the first hosted rollout, verify the configured subnet against the gateway's association subnet and actual proxy path, and remove conflicting saved forwarding overrides. Repeat these checks when the network configuration changes. The separate framework `ForwardedHeaders_Enabled` shortcut must be absent or false. +4. [Run the migrations](#run-migrations). -| Failure | Result and recovery | -| --- | --- | -| Invalid application settings, such as a malformed IP, boolean, or `/0` network | New application processes fail at startup. Correct the configuration and redeploy. Production Helm waits up to five minutes for readiness and reports failure; it does not automatically roll back. | -| A valid CIDR does not contain the actual proxy, or forwarding is disabled | The app can remain ready while it ignores forwarded headers. Users can share the proxy's IP limits, and the request scheme reflects the backend connection. Readiness checks do not detect this. | -| The trusted range includes other callers | Those callers can supply forged client IPs or schemes. Use only the dedicated gateway subnet or verified proxy IPs. | +5. [Route traffic to the services](#ingress), then open your app domain and sign up. The first account is a global + administrator. -After the first authorized development rollout, verify client IPs, HTTPS detection, and rejection of spoofed forwarding headers before a production release. The existing version and readiness checks do not prove those behaviors. +## Values -Use the existing global-admin-only `GET /api/v2/admin/echo` endpoint for these checks. Its `ip_address` and `scheme` fields report the values the application sees after forwarded-header processing. Do not share the full echo response: its `headers` field can contain credentials and cookies. +| Value | Default | What it does | +| --------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `version` | `latest` | The image tag for the app, API, and job images. Pin it to a release version. | +| `appMode` | `Production` | Sets `EX_AppMode`. | +| `appScope` | None | Sets `EX_AppScope`, the prefix for index, queue, and cache names. | +| `app.defaultDomain` | None | Required. The web app's host name. The chart sets `EX_BaseUrl` to `https://` plus this value. | +| `app.domains` | `[]` | Every host name for the web app. Each is also allowed as an MCP browser origin. | +| `api.defaultDomain` | None | The API's host name. The chart sets `EX_ExceptionlessServerUrl` to `https://` plus this value, so the app's client setup instructions show it. | +| `api.domains` | `[]` | Every host name for the API. Each is also allowed as an MCP browser origin. | +| `app.image.repository` | `exceptionless/app` | The app image. | +| `api.image.repository` | `exceptionless/api` | The API image. | +| `jobs.image.repository` | `exceptionless/job` | The job image. | +| `app.replicaCount`, `api.replicaCount` | None | A fixed number of pods. | +| `app.maxReplicaCount`, `api.maxReplicaCount` | None | Adds a CPU-based autoscaler with this many pods at most. `minReplicaCount` sets the minimum, which defaults to 2. | +| `jobs..replicaCount` | None | Pods for one job. Names: `closeInactiveSessions`, `dailySummary`, `eventNotifications`, `eventPosts`, `eventUsage`, `eventUserDescriptions`, `mailMessage`, `stackEventCount`, `webhooks`, and `workitem`. `eventPosts` and `workitem` also accept `minReplicaCount` and `maxReplicaCount`. | +| `elasticsearch.connectionString` | None | The Elasticsearch connection string. | +| `redis.connectionString` | None | The Redis connection string. | +| `storage.connectionString` | None | The storage connection string. When empty, the chart creates a 5 GiB `ReadWriteMany` volume claim with the `managed-csi-premium` storage class, which exists only on Azure. | +| `email.connectionString` | `smtp://localhost` | The SMTP connection string. | +| `cache.connectionString`, `queue.connectionString`, `messagebus.connectionString` | `provider=redis;` | The cache, queue, and message bus. The defaults use Redis. | +| `config` | `{}` | Any other `EX_` settings, added to the config map as-is. | +| `forwardedHeaders.knownNetworks` | `[]` | Trusted ingress networks. See [Trust your ingress](#trust-your-ingress). | +| `ingress.enabled` | `false` | Creates ingress resources for Azure Application Gateway for Containers. Leave it off on other clusters. | +| `service.type` | `ClusterIP` | The type of the chart's services. | +| `otel.enabled` | `true` | Sends OpenTelemetry data to a collector on port 4317 of each node. Set it to `false` unless you run one. | -| Step | Check | Pass condition | -| --- | --- | --- | -| Before merge | Required CI and configured gateway trust | CI passes; environment values match the verified dedicated gateway subnet and proxy path. Merging main starts the dev deployment. | -| Configuration | Saved Helm values, rendered ConfigMap, and new app/API pod environment | `EX_ForwardedHeaders__Enabled=true`, `EX_ForwardedHeaders__ForwardLimit=1`, and indexed `EX_ForwardedHeaders__KnownNetworks__*` match environment values. No conflicting forwarding overrides remain. Inspect only these keys, not unrelated secrets. | -| Rollout | Pod readiness, startup logs, dev migrations, and `/api/v2/about` | New app/API pods are ready, no configuration errors occur, migrations finish, and the expected version is served. | -| Baseline request | Call admin echo through HTTPS ingress with no forwarding or `X-Original-*` headers supplied by the client | `ip_address` equals the caller's known public egress IP and `scheme` is `https`. The baseline `X-Original-For` identifies a gateway peer within the configured subnet. Repeat on both app and API ingress. | -| Spoofed request | Repeat through the same ingress with `X-Forwarded-For: 203.0.113.123` and `X-Forwarded-Proto: http` | `ip_address` stays equal to the caller's actual egress IP and `scheme` stays `https`. Fail if either supplied value controls the result. | -| Direct untrusted request | In an authorized dev check, request the backend directly from a source outside trusted networks with the same fake headers | Forwarded values are ignored; `ip_address` is the direct peer and `scheme` is the backend transport scheme. Loopback or port-forwarding cannot prove this because loopback is trusted. | -| Production release | After dev passes, use the normal release-tag workflow and repeat baseline/spoof checks | Production serves the expected version with correct IP and scheme on both hosts. Stop promotion on any failed check; readiness alone is insufficient. | +Always set `elasticsearch.connectionString` and `redis.connectionString` to services you run. When they're empty, the +chart adds single-pod Elasticsearch and Redis deployments that aren't suitable for real use; that Elasticsearch keeps +its data in an `emptyDir` volume, which is lost when the pod restarts. -For each request, retain only the observed IP, scheme, host, and pass/fail result. A global administrator can make the requests with their normal authenticated client. An unauthenticated request must still return `401`, and a non-admin request must return `403`. +The chart also sets `EX_EnableSsl` to `true` and turns off the `GeoPlugin` and `LocationPlugin` event plugins. -For an authorized rollout, the following commands prompt for the administrator's password and print only the diagnostic fields. Set `BASE_URL` to the HTTPS ingress being checked and `ADMIN_EMAIL` to the administrator's email. Run the baseline first, then the spoof check; both must report the same real client IP and `scheme: "https"`. +## Configuration {#configuration} -```sh -# Baseline: do not supply forwarding or X-Original-* headers. -curl --fail --silent --show-error --user "$ADMIN_EMAIL" \ - "$BASE_URL/api/v2/admin/echo" \ - | jq '{ip_address, scheme, gateway_peer: .headers["X-Original-For"]}' +Every Exceptionless setting can go in the `config` value, using the environment variable names from the +[configuration reference](/docs/self-hosting/configuration/). The chart writes them into the `-config` config +map, which every pod loads: -# Spoof check: these supplied values must not become the effective IP or scheme. -curl --fail --silent --show-error --user "$ADMIN_EMAIL" \ - --header 'X-Forwarded-For: 203.0.113.123' \ - --header 'X-Forwarded-Proto: http' \ - "$BASE_URL/api/v2/admin/echo" \ - | jq '{ip_address, scheme}' +```yaml +config: + EX_EnableAccountCreation: "false" + EX_Assistant__ApiKey: YOUR_OPENROUTER_API_KEY + EX_ConnectionStrings__OAuth: GitHubId=YOUR_ID;GitHubSecret=YOUR_SECRET ``` -## ConnectionStrings +Quote values that YAML would otherwise read as booleans or numbers. A config map isn't encrypted, so keep secrets such +as API keys and passwords in a values file you protect, or manage the config map with your own secrets tooling. + +Leave `EX_ApiUrl` unset. The web UI then calls the API on the app domain, where WebSockets are on, and OAuth and the MCP +server use the app domain too. Clients send events to the API domain. + +After changing values, run `helm upgrade` with the same values file. The pods restart when the config map changes. + +## Ingress {#ingress} + +Route each app domain to the `-app` service and each API domain to the `-api` service, both on port +80. This example uses the release name `exceptionless`; set `ingressClassName` and TLS for your controller: ```yaml -# connection string used for any provider specifying Redis. -EX_ConnectionStrings__Redis: localhost:6379,abortConnect=false - -EX_ConnectionStrings__Cache: provider=redis; -EX_ConnectionStrings__Elasticsearch: server=http://10.0.0.4:9200; -EX_ConnectionStrings__Email: smtps://user%40domain.com:password@smtp.domain.com:465 -EX_ConnectionStrings__MessageBus: provider=redis; -EX_ConnectionStrings__Metrics: provider=statsd;server=localhost -EX_ConnectionStrings__Queue: provider=redis; -EX_ConnectionStrings__Storage: provider=azurestorage; +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: exceptionless + namespace: exceptionless +spec: + ingressClassName: YOUR_INGRESS_CLASS + tls: + - hosts: + - errors.example.com + - api.errors.example.com + secretName: exceptionless-tls + rules: + - host: errors.example.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: exceptionless-app + port: + number: 80 + - host: api.errors.example.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: exceptionless-api + port: + number: 80 ``` -You can append values to any connection string using a `;`. For example, you can control many shards and replicas each Elasticsearch index should be created with by appending to the `EX_ConnectionStrings__Elasticsearch` connection string. For a Elasticsearch cluster (3 nodes, two masters), you would append `shards=3;replicas=1`. +Your ingress must also allow WebSockets on the app domain, request bodies up to about 25 MB for source map uploads, and +responses that stream for more than two minutes for Exie. See +[What the proxy needs to do](/docs/self-hosting/reverse-proxy/#what-the-proxy-needs-to-do). -The `provider` value determines what implementations to use for the various abstractions. We've made it easier to reuse a single connection string by automatically looking up a connection string by the provider name and adding any key value pairs to the current connection string (as shown above with redis). +### Trust your ingress {#trust-your-ingress} -## General Configuration +Exceptionless reads client IP addresses and the HTTPS scheme only from proxies it trusts. If your ingress controller or +gateway connects to the pods from a dedicated subnet, list it: -1. You'll want to set the `EX_ApiUrl` key to your external url of the api. -2. You'll want to set the `EX_BaseUrl` key to your external url of the website. If you are not following the clean urls optional section below, please make sure you also add the hashbang (`/#!`) to the base url. -3. `EX_AppMode` should be set to `Production` if you want to send unrestricted emails. -4. Please take a quick look at all the configuration options and settings that can be found in the various option classes located [here](https://github.com/exceptionless/Exceptionless/tree/master/src/Exceptionless.Core/Configuration). +```yaml +forwardedHeaders: + knownNetworks: + - 192.0.2.0/24 +``` + +The chart turns on forwarded headers with a forward limit of 1 and adds each network as +`EX_ForwardedHeaders__KnownNetworks__`. Replacing the list removes old entries, even with `--reuse-values`. Don't +also set `ForwardedHeaders` keys in `config`; the chart refuses to render when you combine them. For trusted proxy +addresses or more than one proxy hop, leave the list empty and use `config` instead: + +```yaml +config: + EX_ForwardedHeaders__KnownProxies__0: "192.0.2.10" + EX_ForwardedHeaders__ForwardLimit: "1" +``` -## Active Directory Authentication +Trust only addresses your ingress connects from, not the whole cluster network. Use the echo check in +[Reverse proxies and HTTPS](/docs/self-hosting/reverse-proxy/#trust-your-proxy) to find and verify them. -To enable Active Directory authentication, update the `exceptionless-config` config map to include the `EX_ConnectionStrings__LDAP` connection string. The value should be your domain's LDAP URI (e.g. `LDAP://ad.domain.com/` or `LDAP://ad.domain.com/DC=domain,DC=com`). +## Run migrations {#run-migrations} -Please note the following: +The migration job runs only when you start it. Start it after the first install and after every upgrade: -1. Users must still go through the registration process using their AD credentials. This allows account setup to proceed as normal. AD credentials are **not** stored. -2. Exceptionless relies on the following properties being available in AD: - * `mail`: user's email address - * `givenName`: user's first name - * `sn`: user's last name - * `sAMAccountName`: user's username -3. To ensure the correct account information is retrieved for a user, consider using a more specific connection string to narrow down the LDAP account type. For example: `LDAP://ad.domain.com/OU=Standard Users,OU=User Accounts,DC=domain,DC=com` +```bash +kubectl create job --from=cronjob/exceptionless-jobs-migration exceptionless-migration-1 --namespace exceptionless +kubectl wait --for=condition=complete --timeout=20m job/exceptionless-migration-1 --namespace exceptionless +``` -## Enabling Slack Integrations +Use a new job name each time. Check its progress with +`kubectl logs job/exceptionless-migration-1 --namespace +exceptionless`, or under **Settings** > **System** > +**Migrations** in the app. See [Administration](/docs/self-hosting/administration/#migrations). -1. Create a Slack app for your workspace - * __Please do not distribute your app outside of your organization.__ -2. Go to the `OAuth & Permissions` feature. Add a new redirect URL. The redirect URL should be your Exceptionless base URL. -3. On the *basic info* page of your Slack App, you will need to find the Client ID and Client Secret -4. Update the `exceptionless-config` config map `ConnectionStrings__OAuth` value to include `SlackId=YOUR_ID;SlackSecret=YOUR_SECRET;` and restart the associated pods. -5. If you've already loaded a page in Exceptionless, you will need to do a hard refresh for the config changes to apply. +## Upgrade {#upgrade} -## Upgrading +1. Set `version` to the new release in your values file. +2. Run + `helm upgrade exceptionless ./Exceptionless/k8s/exceptionless --namespace exceptionless --values exceptionless-values.yaml`, + from an up-to-date clone of the repository. +3. [Run the migrations](#run-migrations). -Please see the [Upgrading](/docs/self-hosting/upgrading-self-hosted-instance) for details on how to upgrade to the current version. +See [Upgrading](/docs/self-hosting/upgrading-self-hosted-instance/) for what changed between versions. -## Troubleshooting +## Active Directory authentication {#active-directory-authentication} -If you are having issues please try the following to resolve the issues. If this doesn't work please open an issue or contact us on [Discord](https://discord.gg/xv3sjurVwA). +Active Directory sign-in uses Windows directory APIs, so it doesn't work in the Linux containers this chart runs. See +[Active Directory](/docs/self-hosting/configuration/#active-directory) for how it works on Windows. -* Make sure you are running the latest release by visiting our [releases page](https://github.com/exceptionless/Exceptionless/releases). You can verify the version you are currently running by accessing the status page [`http://localhost/api/v2/about`](http://localhost/api/v2/about). -* You can also enable detailed logging by updating the `Serilog__MinimumLevel__Default` config map value to `Debug`. +## Troubleshooting ---- +- To check the version you're running, open `/api/v2/about` on your app domain. +- Each pod serves `/health` for liveness and `/ready` for readiness on port 8080. +- For more detailed logs, set `EX_Serilog__MinimumLevel__Default: Debug` in `config` and upgrade. -[Next > Upgrading](/docs/self-hosting/upgrading-self-hosted-instance) +If you're stuck, open an issue on [GitHub](https://github.com/exceptionless/Exceptionless/issues) or ask on +[Discord](https://discord.gg/xv3sjurVwA). diff --git a/docs/docs/self-hosting/reverse-proxy.md b/docs/docs/self-hosting/reverse-proxy.md new file mode 100644 index 0000000000..f8c4e509b8 --- /dev/null +++ b/docs/docs/self-hosting/reverse-proxy.md @@ -0,0 +1,230 @@ +--- +title: "Reverse proxies and HTTPS" +navTitle: "Reverse proxies" +metaTitle: "Run self-hosted Exceptionless behind a reverse proxy" +description: "Put nginx, Caddy, or a load balancer in front of self-hosted Exceptionless and trust it, so client IP addresses and HTTPS are detected." +sources: + - src/Exceptionless.Web/Security/TrustedForwardedHeadersOptions.cs + - src/Exceptionless.Web/Security/ForwardedHeadersConfiguration.cs + - src/Exceptionless.Web/Program.cs + - src/Exceptionless.Web/appsettings.yml + - src/Exceptionless.Web/Extensions/HttpExtensions.cs + - src/Exceptionless.Web/Utility/Handlers/ThrottlingMiddleware.cs + - src/Exceptionless.Web/Api/Handlers/AdminHandler.cs + - src/Exceptionless.Web/Api/Endpoints/AssistantEndpoints.cs + - src/Exceptionless.Web/Api/Endpoints/SourceMapEndpoints.cs + - k8s/exceptionless/templates/config.yaml +--- + +# Reverse proxies and HTTPS + +Most installations put a reverse proxy, such as nginx, Caddy, or a cloud load balancer, in front of Exceptionless to +serve HTTPS. This page shows how to tell Exceptionless which proxies to trust, so it sees each visitor's real IP address +and knows the request came in over HTTPS. + +## How Exceptionless reads forwarded headers + +A proxy passes the visitor's address in `X-Forwarded-For` and the original scheme in `X-Forwarded-Proto`. Anyone can +send those headers, so Exceptionless reads them only from loopback addresses and from proxies you list. + +When the proxy isn't trusted, every request appears to come from the proxy's address over plain HTTP. All anonymous +visitors then share one set of IP-based limits, including API rate limits, sign-up limits, and OAuth client registration +limits. + +Exceptionless doesn't read `X-Forwarded-Host` or `X-Forwarded-Prefix`. Its public URLs come from `EX_BaseURL` and +`EX_ApiUrl`, so set those to the URLs people use, and serve Exceptionless at the root of its host name. + +You don't need any of this if browsers and clients connect to Exceptionless directly. + +## Trust your proxy {#trust-your-proxy} + +1. **Find the proxy's address as Exceptionless sees it.** This is the source address of the connection that reaches the + Exceptionless container, which isn't always the proxy's public address. Sign in as a global administrator, then call + the echo endpoint through your proxy. Until the proxy is trusted, `ip_address` is the proxy's address: + + ```bash + curl --silent --user admin@example.com https://errors.example.com/api/v2/admin/echo | jq '{ip_address, scheme}' + ``` + + curl asks for your password. The full response also lists your request headers, including credentials, so don't share + it. + +2. **Add the address to the trusted list** on the `app` and `api` containers: + + ```yaml + EX_ForwardedHeaders__KnownProxies__0: "192.0.2.10" + ``` + + Add more addresses as `__1`, `__2`, and so on. If the proxy's address changes, trust its network instead, but only a + network that nothing else can connect from: + + ```yaml + EX_ForwardedHeaders__KnownNetworks__0: "192.0.2.0/28" + ``` + +3. **Restart Exceptionless.** It reads these settings only at startup. + +4. **Check the result.** Call the echo endpoint again. `ip_address` should now be your own public IP address and + `scheme` should be `https`. + +5. **Check that visitors can't fake it.** Send a made-up address. `ip_address` must still be your real address: + + ```bash + curl --silent --user admin@example.com -H "X-Forwarded-For: 203.0.113.123" https://errors.example.com/api/v2/admin/echo | jq '{ip_address, scheme}' + ``` + +You can also set these in `appsettings.Local.yml` in the app folder: + +```yaml +ForwardedHeaders: + KnownProxies: + - 192.0.2.10 +``` + +## Settings + +| Environment variable | Default | What it does | +| --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | +| `EX_ForwardedHeaders__Enabled` | `true` | Reads `X-Forwarded-For` and `X-Forwarded-Proto` from trusted proxies. Set to `false` to ignore them from everyone. | +| `EX_ForwardedHeaders__ForwardLimit` | `1` | How many proxies to read through, starting from the one closest to Exceptionless. `0` ignores forwarded headers. | +| `EX_ForwardedHeaders__KnownProxies__0` | None | A trusted proxy IP address, without a port. Loopback addresses are always trusted. | +| `EX_ForwardedHeaders__KnownNetworks__0` | None | A trusted proxy network in CIDR form, such as `192.0.2.0/24`. IPv4 and IPv6 both work. | + +Exceptionless refuses to start if the settings are invalid: + +- Addresses with ports or host names instead of IP addresses. +- A `/0` network, which would trust everyone. +- A list written as one comma-separated value instead of numbered keys. +- A negative `ForwardLimit`. +- ASP.NET Core's separate `ForwardedHeaders_Enabled` shortcut set to `true`, for example as the + `EX_ForwardedHeaders_Enabled` environment variable. That shortcut clears the trusted lists. Use the settings above + instead. + +Environment variables override YAML key by key. Setting `KnownProxies__0` in the environment replaces only the first +YAML entry, so remove old entries from YAML rather than relying on an override. + +### More than one proxy + +If requests pass through several proxies, such as a CDN and then a load balancer, set `ForwardLimit` to the number of +proxies and trust every one of them. Exceptionless reads `X-Forwarded-For` from right to left and stops when it reaches +a proxy it doesn't trust. + +### Troubleshooting + +To log why a forwarded header was ignored, raise the log level for ASP.NET Core's forwarded headers middleware and +restart: + +```yaml +EX_Serilog__MinimumLevel__Override__Microsoft.AspNetCore.HttpOverrides: Debug +``` + +## What the proxy needs to do {#what-the-proxy-needs-to-do} + +- **Set the forwarded headers itself.** The proxy that faces the internet must replace any `X-Forwarded-For` it receives + with the client's address, or append the client's address to it, and set `X-Forwarded-Proto` from its own connection. +- **Allow WebSockets** on `/api/v2/push`. The web UI gets real-time updates there. +- **Allow large uploads.** Source map uploads can be up to 20 MB. +- **Allow long responses.** Exie streams its answers for up to two minutes. Exceptionless sends `X-Accel-Buffering: no` + on those responses so nginx doesn't buffer them. + +## nginx + +This example runs nginx on the same server as the [Docker Compose setup](/docs/self-hosting/docker/), with the app +published on port 7110: + +```nginx +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} + +server { + listen 443 ssl; + server_name errors.example.com; + + ssl_certificate /etc/ssl/certs/errors.example.com.pem; + ssl_certificate_key /etc/ssl/private/errors.example.com.key; + + client_max_body_size 25m; + + location / { + proxy_pass http://127.0.0.1:7110; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_read_timeout 180s; + } +} +``` + +`X-Forwarded-For $remote_addr` replaces whatever the client sent, so nginx must be the first proxy. + +Because nginx reaches the container through a published Docker port, Exceptionless usually sees the Docker network's +gateway address, not `127.0.0.1`. Use the echo check above to find it. To keep that address the same when you recreate +the containers, give the Compose network a fixed subnet: + +```yaml +networks: + default: + ipam: + config: + - subnet: 172.30.0.0/24 +``` + +## Caddy in Docker Compose + +Caddy gets HTTPS certificates automatically, sets `X-Forwarded-For` and `X-Forwarded-Proto` itself, ignores forwarded +headers from clients by default, and passes WebSockets and streamed responses through. Its `Caddyfile` is short: + +```text +errors.example.com { + reverse_proxy app:8080 +} +``` + +Run it in the same Compose project as Exceptionless with a fixed address, and trust that address. The `ip_range` keeps +Docker from giving that address to another container. Add this to the [Compose file](/docs/self-hosting/docker/): + +```yaml +services: + caddy: + image: caddy:2 + ports: + - 80:80 + - 443:443 + volumes: + - ./Caddyfile:/etc/caddy/Caddyfile:ro + - caddy_data:/data + networks: + default: + ipv4_address: 172.30.0.10 + restart: unless-stopped + +networks: + default: + ipam: + config: + - subnet: 172.30.0.0/24 + ip_range: 172.30.0.128/25 + +volumes: + caddy_data: +``` + +Then add these to the shared Exceptionless settings, and remove the app's `ports` entry so all traffic goes through +Caddy: + +```yaml +EX_BaseURL: https://errors.example.com +EX_ExceptionlessServerUrl: https://errors.example.com +EX_EnableSsl: "true" +EX_ForwardedHeaders__KnownProxies__0: "172.30.0.10" +``` + +## Kubernetes + +In Kubernetes, the proxy is your ingress controller or gateway. The Helm chart can trust a dedicated ingress subnet with +`forwardedHeaders.knownNetworks`. See [Kubernetes](/docs/self-hosting/kubernetes/#trust-your-ingress). diff --git a/docs/docs/self-hosting/upgrading-self-hosted-instance.md b/docs/docs/self-hosting/upgrading-self-hosted-instance.md index a3bb38952b..40007f60bb 100644 --- a/docs/docs/self-hosting/upgrading-self-hosted-instance.md +++ b/docs/docs/self-hosting/upgrading-self-hosted-instance.md @@ -1,1128 +1,111 @@ --- title: "Upgrading" -metaTitle: "Upgrading a self-hosted Exceptionless server" -description: "Upgrade a self-hosted Exceptionless server from v1 through v8, including Elasticsearch reindexing, migration jobs, proxy trust changes, and config updates." +metaTitle: "Upgrade a self-hosted Exceptionless instance" +description: "Upgrade self-hosted Exceptionless to 9.0: run migrations, configure trusted reverse proxies, and review the changes for operators." +sources: + - src/Exceptionless.Core/Jobs/Elastic/MigrationJob.cs + - src/Exceptionless.Core/Bootstrapper.cs + - src/Exceptionless.Job/JobRunnerOptions.cs + - src/Exceptionless.Core/Migrations/MigrationRerunService.cs + - src/Exceptionless.Web/Security/TrustedForwardedHeadersOptions.cs + - src/Exceptionless.Core/Configuration/AppOptions.cs + - src/Exceptionless.Core/Configuration/AuthOptions.cs + - src/Exceptionless.Core/Configuration/AssistantOptions.cs + - src/Exceptionless.Web/Security/FrontendContentSecurityPolicy.cs + - src/Exceptionless.Web/ClientApp/src/lib/features/navigation/legacy-links.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/auth/index.svelte.ts + - build/update-config.sh + - Dockerfile + - k8s/exceptionless/templates/config.yaml --- # Upgrading -## Trusted proxy migration +This page explains how to upgrade a self-hosted instance and what changed in 9.0 for the people who run it. It covers +upgrades from 8.x. -Upgrading from unrestricted forwarding requires [explicit trust for non-loopback reverse proxies](/docs/self-hosting/#reverse-proxies-and-https). Configure and verify the actual ingress peers before rollout, or client-IP limits and HTTPS detection can change. Direct hosting needs no new settings. +## Before you upgrade -**Please ensure that you have created backups before upgrading!** +1. Check the version you're running at `/api/v2/about` on your instance. +2. Read [what changed in 9.0](#what-changed-in-9-0) and update your configuration first, especially if a reverse proxy + sits in front of Exceptionless. +3. Take an Elasticsearch snapshot. -**If you are upgrading from v1 or [v2](https://github.com/exceptionless/Exceptionless/releases/tag/v2.0.0) you will need to upgrade to [v3.0](https://github.com/exceptionless/Exceptionless/releases/tag/v3.0.0) before upgrading to the latest release.** +If you run a version older than 8.0, upgrade to 8.x first. Version 8 moved to Elasticsearch 8; see the +[8.0.0 release notes](https://github.com/exceptionless/Exceptionless/releases/tag/v8.0.0). -## Upgrading from v7.1 to v8 +## Upgrade -We simplified the self hosting process by integrating the UI into the existing app images. As such `exceptionless/ui` docker images are deprecated and we recommend using `exceptionless/app`. +**Docker Compose:** pull the new images and recreate the containers: -We also upgraded to Elasticsearch 8 in the base images. One requirement of upgrading with existing data is the Elasticsearch data is loaded with the latest Elasticsearch 7.x release. If you are using the all in one image, first use `exceptionless/exceptionless:8.0.0-elasticsearch7` and wait for the app to startup and give it some time. Then turn off the app and then use `exceptionless/exceptionless:8.0.0` image. We will be deprecating the `exceptionless/exceptionless:8.0.0-elasticsearch7` image in the future, this is only there to help with the upgrade process. - -You may also need to update the connection strings. In v8.2.7 we updated the Redis Connection String to remove the `server=` prefix. - -## Rerunning a completed migration - -Only migrations explicitly marked as safe to rerun can be started again. Create an Elasticsearch snapshot and stop older Exceptionless app and job instances before proceeding. - -- In the System UI, open **System → Migrations**, choose the migration's action menu, and select **Rerun migration**. The confirmation dialog shows the exact phrase you must enter. -- From the job image or CLI, run `dotnet Exceptionless.Job.dll Migration --rerun `, using the migration ID shown in the System UI. Pass the same Elasticsearch, Redis, and other configuration used by the normal migration job. - -A split deployment that runs jobs outside the web process must configure a distributed queue and Redis-backed cache to use the System UI action. If those services are unavailable, use the CLI command from the job instance instead. - -A rerun does not change the recorded current migration version or the original migration completion timestamp. Its outcome is reported separately in the UI and application logs. - -## Upgrading from v7 to v7.1 - -We made some changes to email configuration. You will now be required to set the `EX_SmtpFrom` config map/environment variable in order to send email. The value should be in the following format: `"Exceptionless "` - -## Upgrading from v6 to v7 - -A migration job will need to be run as there are several in place data migrations that need to be applied. The migrations will add new index mappings for soft delete support as well as stack status and populate various stack fields with data. - -1. You'll need to run an out of process `Migration` job. In order to do this you'll need to update configuration to ensure it's pointing to your Elasticsearch (e.g., `EX_ConnectionStrings__Elasticsearch` environment variable/connection string) and Redis instances. -2. Scale down existing Exceptionless apps and jobs. -3. Start the `Migration` job. - 1. For docker, you just need to pass the `Migration` argument to the `exceptionless/job` container image (e.g., `docker run exceptionless/job:latest Migration`). Please remember to pass any configuration settings (e.g., connection strings) to the migration job. - 2. For Kubernetes, you can run [`kubectl apply -f manual-migration-job.yaml`](https://github.com/exceptionless/Exceptionless/blob/master/k8s/manual-migration-job.yaml). Please note that you may have to tweak namespaces and container image version. -4. Scale back up and you should be good to go. - -## Upgrading from v5 to v6 - -Version 6 added support for Elasticsearch 7, which requires a complete data migration from Elasticsearch 5.x. This tutorial assumes you have docker/Kubernetes installed and have followed the [setup guide](/docs/self-hosting/). - -1. Create a new Elasticsearch 7 cluster or modify your existing `docker-compose` file to also include our Elasticsearch 7.x image. There will need to be two Elasticsearch docker instances (5.x and 7.x). Please note that we've included the Elasticsearch major version number in the docker data path, which allows you to run two versions side by side without losing the data. -2. Add a new environment variable or config map setting for `EX_ElasticsearchToMigrate` with the value of the `EX_Elasticsearch` 5.x connection string. -3. Add your existing Elasticsearch instance to `reindex.remote.whitelist` in Elasticsearch 7's `elasticsearch.yml`. Make sure you include the port as well, for example `reindex.remote.whitelist: 127.0.0.1:9200`. -4. Update the existing `EX_Elasticsearch` environment variable or config map entry to point to the Elasticsearch 7.x Cluster. -5. Scale down existing Exceptionless apps and jobs. -6. Start the Data Migration by running the `DataMigration` job. You can run it by opening the CLI and executing `dotnet Exceptionless.Job.dll DataMigration`. If you receive a warning that the port is already used, you need to change `ASPNETCORE_URLS` first, for example `ASPNETCORE_URLS=http://+:8080`. You can also run an incremental reindex by setting the `EX_ReindexCutOffDate` environment variable or config map entry to a date value (e.g., `2022-01-28T18:00:00.00Z`) and rerunning the Migration Job. -7. Scale up the rest of the app! - -## Upgrading from v4 to v5 - -We now only provide official docker images as release artifacts. This tutorial assumes you have docker/Kubernetes installed and have followed the [setup guide](/docs/self-hosting/). - -1. We now can run on linux or windows as we are running on ASP.NET Core! As a result we've completely redone the configuration. For the most part we've prefixed configuration with `EX_` and simplified it as much as possible. I'd recommend taking a look at your previous configuration settings and then read over the following [configuration document](/docs/self-hosting/kubernetes#configuration) to migrate your settings. -2. Please note that no Elasticsearch changes are required. You can continue to use your existing Elasticsearch cluster. You just need to update the connection string by following step 1. -3. Please note that the UI and API no longer run on the same port as they are now two different docker images. You may need to update your server url accordingly in your client applications. - -## Upgrading from v3 to v4 - -This process requires you to setup and configure a new Elasticsearch 5 instance and reindex your existing Elasticsearch 1.x data into the Elasticsearch 5 instance using [external reindexing](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html). This tutorial assumes you have Elasticsearch 5 Kibana instance installed and configured. - -1. Edit the Elasticsearch 5's `elasticsearch.yml` configuration file. - 1. Add the `reindex.remote.whitelist: 10.0.0.9:9200` setting with a value that contains the IP address or hostname of the 1.x server. This allows you to reindex the 1.x data into your new 5.x instance. - 2. Temporarily comment out (with a leading `#`) the following line: `#action.auto_create_index: .security,.monitoring*,.watches,.triggered_watches,.watcher-history*` - 3. Restart the elasticsearch service. -2. Open Kibana (E.G., [http://localhost:5601](http://localhost:5601)) and execute the following scripts to reindex your data. - -### Create Organization Index with the correct mappings: - -```json -PUT organizations-v1 -{ - "settings": { - "index.number_of_replicas": 1, - "index.number_of_shards": 3, - "analysis": { - "analyzer": { - "keyword_lowercase": { - "type": "custom", - "filter": [ - "lowercase" - ], - "tokenizer": "keyword" - } - } - } - }, - "aliases": { - "organizations": {} - }, - "mappings": { - "organization": { - "dynamic": false, - "properties": { - "id": { - "type": "keyword" - }, - "created_utc": { - "type": "date" - }, - "updated_utc": { - "type": "date" - }, - "name": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - }, - "stripe_customer_id": { - "type": "keyword" - }, - "has_premium_features": { - "type": "boolean" - }, - "plan_id": { - "type": "keyword" - }, - "plan_name": { - "type": "keyword", - "ignore_above": 256 - }, - "subscribe_date": { - "type": "date" - }, - "billing_status": { - "type": "float" - }, - "billing_price": { - "type": "double" - }, - "is_suspended": { - "type": "boolean" - }, - "retention_days": { - "type": "integer" - }, - "invites": { - "type": "object", - "properties": { - "token": { - "type": "keyword" - }, - "email_address": { - "type": "text", - "analyzer": "keyword_lowercase" - } - } - }, - "usage": { - "type": "object", - "properties": { - "date": { - "type": "date" - }, - "total": { - "type": "float" - }, - "blocked": { - "type": "float" - }, - "limit": { - "type": "float" - }, - "too_big": { - "type": "float" - } - } - }, - "overage_hours": { - "type": "object", - "properties": { - "date": { - "type": "date" - }, - "total": { - "type": "float" - }, - "blocked": { - "type": "float" - }, - "limit": { - "type": "float" - }, - "too_big": { - "type": "float" - } - } - } - } - }, - "project": { - "dynamic": false, - "properties": { - "id": { - "type": "keyword" - }, - "created_utc": { - "type": "date" - }, - "updated_utc": { - "type": "date" - }, - "organization_id": { - "type": "keyword" - }, - "name": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - }, - "next_summary_end_of_day_ticks": { - "type": "long" - } - } - }, - "token": { - "dynamic": false, - "properties": { - "id": { - "type": "keyword" - }, - "created_utc": { - "type": "date" - }, - "updated_utc": { - "type": "date" - }, - "expires_utc": { - "type": "date" - }, - "organization_id": { - "type": "keyword" - }, - "project_id": { - "type": "keyword" - }, - "default_project_id": { - "type": "keyword" - }, - "user_id": { - "type": "keyword" - }, - "refresh": { - "type": "keyword" - }, - "scopes": { - "type": "keyword" - }, - "type": { - "type": "byte" - } - } - }, - "user": { - "dynamic": false, - "properties": { - "id": { - "type": "keyword" - }, - "created_utc": { - "type": "date" - }, - "updated_utc": { - "type": "date" - }, - "organization_ids": { - "type": "keyword" - }, - "full_name": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - }, - "email_address": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "analyzer": "keyword_lowercase" - }, - "verify_email_address_token": { - "type": "keyword" - }, - "password_reset_token": { - "type": "keyword" - }, - "roles": { - "type": "keyword" - }, - "o_auth_accounts": { - "type": "object", - "properties": { - "provider": { - "type": "keyword" - }, - "provider_user_id": { - "type": "keyword" - }, - "username": { - "type": "keyword" - } - } - } - } - }, - "webhook": { - "dynamic": false, - "properties": { - "id": { - "type": "keyword" - }, - "created_utc": { - "type": "date" - }, - "organization_id": { - "type": "keyword" - }, - "project_id": { - "type": "keyword" - }, - "url": { - "type": "keyword" - }, - "event_types": { - "type": "keyword" - } - } - } - } -} +```bash +docker compose pull +docker compose up -d ``` -### Reindex Organization data from 1.x into 5.x **Please make sure you update the host name**: +If you pin image tags, change them to the new version first. -```json -POST _reindex -{ - "source": { - "remote": { - "host": "http://10.0.0.9:9200" - }, - "index": "organizations-v1" - }, - "dest": { - "index": "organizations-v1", - "op_type": "create" - }, - "script": { - "inline": "if (ctx._source.modified_utc != null) { ctx._source.updated_utc = ctx._source.remove('modified_utc'); }", - "lang": "painless" - } -} -``` +**Kubernetes:** set `version` in your values file, run `helm upgrade`, and then start the migration job. See +[Kubernetes](/docs/self-hosting/kubernetes/#upgrade). -### Create Stack Index with the correct mappings: +## Migrations -```json -PUT stacks-v1 -{ - "settings": { - "index.number_of_replicas": 1, - "index.number_of_shards": 3 - }, - "aliases": { - "stacks": {} - }, - "mappings": { - "stacks": { - "include_in_all": false, - "dynamic": false, - "properties": { - "id": { - "type": "keyword" - }, - "organization_id": { - "type": "keyword" - }, - "project_id": { - "type": "keyword" - }, - "signature_hash": { - "type": "keyword" - }, - "type": { - "type": "keyword" - }, - "first_occurrence": { - "type": "date" - }, - "last_occurrence": { - "type": "date" - }, - "title": { - "type": "text", - "boost": 1.1, - "include_in_all": true - }, - "description": { - "type": "text", - "include_in_all": true - }, - "tags": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "boost": 1.2, - "include_in_all": true - }, - "references": { - "type": "text", - "include_in_all": true - }, - "date_fixed": { - "type": "date" - }, - "fixed": { - "type": "boolean" - }, - "fixed_in_version": { - "type": "keyword" - }, - "is_hidden": { - "type": "boolean" - }, - "is_regressed": { - "type": "boolean" - }, - "occurrences_are_critical": { - "type": "boolean" - }, - "total_occurrences": { - "type": "integer" - } - } - } - } -} -``` +Some versions change how data is stored in Elasticsearch. Exceptionless applies these changes with migrations: -### Reindex Stack data from 1.x into 5.x **Please make sure you update the host name**: +- The `job` image runs pending migrations each time it starts with no arguments or with `Migration`. +- The `app` and all-in-one images run them at startup when jobs run in the same process. +- In Kubernetes, you start the migration job yourself after each upgrade. -```json -POST _reindex -{ - "source": { - "remote": { - "host": "http://10.0.0.9:9200" - }, - "index": "stacks-v1" - }, - "dest": { - "index": "stacks-v1", - "op_type": "create" - } -} -``` +To see progress and failures, go to **Settings** > **System** > **Migrations**, or read the job's logs. See +[Administration](/docs/self-hosting/administration/#migrations). -### Create Event Template so daily indexes can be created with the correct mappings: +## Rerun a migration {#rerunning-a-completed-migration} -```json -PUT _template/events-v1 -{ - "template": "events-v1-*", - "settings": { - "number_of_shards": 1, - "number_of_replicas": 1, - "analysis": { - "analyzer": { - "comma_whitespace": { - "type": "pattern", - "pattern": "[,\\s]+" - }, - "email": { - "type": "custom", - "filter": [ - "email", - "lowercase", - "unique" - ], - "tokenizer": "keyword" - }, - "version_index": { - "type": "custom", - "filter": [ - "version_pad1", - "version_pad2", - "version_pad3", - "version_pad4", - "version", - "lowercase", - "unique" - ], - "tokenizer": "whitespace" - }, - "version_search": { - "type": "custom", - "filter": [ - "version_pad1", - "version_pad2", - "version_pad3", - "version_pad4", - "lowercase" - ], - "tokenizer": "whitespace" - }, - "whitespace_lower": { - "type": "custom", - "filter": [ - "lowercase" - ], - "tokenizer": "whitespace" - }, - "typename": { - "type": "custom", - "filter": [ - "typename", - "lowercase", - "unique" - ], - "tokenizer": "typename_hierarchy" - }, - "standardplus": { - "type": "custom", - "filter": [ - "standard", - "typename", - "lowercase", - "stop", - "unique" - ], - "tokenizer": "comma_whitespace" - } - }, - "filter": { - "email": { - "type": "pattern_capture", - "patterns": [ - "(\\w+)", - "(\\p{L}+)", - "(\\d+)", - "(.+)@", - "@(.+)" - ] - }, - "typename": { - "type": "pattern_capture", - "patterns": [ - "\\.(\\w+)", - "([^\\()]+)" - ] - }, - "version": { - "type": "pattern_capture", - "patterns": [ - "^(\\d+)\\.", - "^(\\d+\\.\\d+)", - "^(\\d+\\.\\d+\\.\\d+)" - ] - }, - "version_pad1": { - "type": "pattern_replace", - "pattern": "(\\.|^)(\\d{1})(?=\\.|-|$)", - "replacement": "$10000$2" - }, - "version_pad2": { - "type": "pattern_replace", - "pattern": "(\\.|^)(\\d{2})(?=\\.|-|$)", - "replacement": "$1000$2" - }, - "version_pad3": { - "type": "pattern_replace", - "pattern": "(\\.|^)(\\d{3})(?=\\.|-|$)", - "replacement": "$100$2" - }, - "version_pad4": { - "type": "pattern_replace", - "pattern": "(\\.|^)(\\d{4})(?=\\.|-|$)", - "replacement": "$10$2" - } - }, - "tokenizer": { - "comma_whitespace": { - "type": "pattern", - "pattern": "[,\\s]+" - }, - "typename_hierarchy": { - "type": "path_hierarchy", - "delimiter": "." - } - } - } - }, - "mappings": { - "events": { - "dynamic": "false", - "include_in_all": false, - "_all": { - "analyzer": "standardplus", - "search_analyzer": "whitespace_lower" - }, - "_size": { - "enabled": true - }, - "dynamic_templates": [ - { - "idx_reference": { - "match": "*-r", - "mapping": { - "ignore_above": 256, - "type": "keyword" - } - } - } - ], - "properties": { - "count": { - "type": "integer" - }, - "created_utc": { - "type": "date" - }, - "data": { - "properties": { - "@environment": { - "properties": { - "architecture": { - "type": "keyword" - }, - "ip_address": { - "type": "text", - "index": false, - "copy_to": [ - "ip" - ], - "include_in_all": true - }, - "machine_name": { - "type": "text", - "boost": 1.1, - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "include_in_all": true - }, - "o_s_name": { - "type": "text", - "copy_to": [ - "os" - ] - } - } - }, - "@error": { - "properties": { - "data": { - "properties": { - "@target": { - "properties": { - "ExceptionType": { - "type": "text", - "index": false, - "copy_to": [ - "error.targettype" - ], - "include_in_all": true - }, - "Method": { - "type": "text", - "index": false, - "copy_to": [ - "error.targetmethod" - ], - "include_in_all": true - } - } - } - } - } - } - }, - "@level": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - }, - "@location": { - "properties": { - "country": { - "type": "keyword" - }, - "level1": { - "type": "keyword" - }, - "level2": { - "type": "keyword" - }, - "locality": { - "type": "keyword" - } - } - }, - "@request": { - "properties": { - "client_ip_address": { - "type": "text", - "index": false, - "copy_to": [ - "ip" - ], - "include_in_all": true - }, - "data": { - "properties": { - "@browser": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - }, - "@browser_major_version": { - "type": "text" - }, - "@browser_version": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - }, - "@device": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - }, - "@is_bot": { - "type": "boolean" - }, - "@os": { - "type": "text", - "index": false, - "copy_to": [ - "os" - ] - }, - "@os_major_version": { - "type": "text" - }, - "@os_version": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - } - } - }, - "path": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "include_in_all": true - }, - "user_agent": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - } - } - }, - "@simple_error": { - "properties": { - "data": { - "properties": { - "@target": { - "properties": { - "ExceptionType": { - "type": "text", - "index": false, - "copy_to": [ - "error.targettype" - ], - "include_in_all": true - } - } - } - } - } - } - }, - "@submission_method": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - }, - "@user": { - "properties": { - "identity": { - "type": "text", - "boost": 1.1, - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "analyzer": "email", - "search_analyzer": "whitespace_lower", - "include_in_all": true - }, - "name": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "include_in_all": true - } - } - }, - "@user_description": { - "properties": { - "description": { - "type": "text", - "include_in_all": true - }, - "email_address": { - "type": "text", - "boost": 1.1, - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "analyzer": "email", - "search_analyzer": "simple", - "include_in_all": true - } - } - }, - "@version": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "analyzer": "version_index", - "search_analyzer": "version_search" - } - } - }, - "date": { - "type": "date" - }, - "error": { - "include_in_all": true, - "properties": { - "code": { - "type": "keyword", - "boost": 1.1 - }, - "message": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - }, - "targetmethod": { - "type": "text", - "boost": 1.2, - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "analyzer": "typename", - "search_analyzer": "whitespace_lower" - }, - "targettype": { - "type": "text", - "boost": 1.2, - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "analyzer": "typename", - "search_analyzer": "whitespace_lower" - }, - "type": { - "type": "text", - "boost": 1.1, - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "analyzer": "typename", - "search_analyzer": "whitespace_lower" - } - } - }, - "geo": { - "type": "geo_point" - }, - "id": { - "type": "keyword", - "include_in_all": true - }, - "idx": { - "type": "object", - "dynamic": "true" - }, - "ip": { - "type": "text", - "analyzer": "comma_whitespace" - }, - "is_deleted": { - "type": "boolean" - }, - "is_first_occurrence": { - "type": "boolean" - }, - "is_fixed": { - "type": "boolean" - }, - "is_hidden": { - "type": "boolean" - }, - "message": { - "type": "text", - "include_in_all": true - }, - "organization_id": { - "type": "keyword" - }, - "os": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - } - }, - "project_id": { - "type": "keyword" - }, - "reference_id": { - "type": "keyword" - }, - "source": { - "type": "text", - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "include_in_all": true - }, - "stack_id": { - "type": "keyword" - }, - "tags": { - "type": "text", - "boost": 1.2, - "fields": { - "keyword": { - "type": "keyword", - "ignore_above": 256 - } - }, - "include_in_all": true - }, - "type": { - "type": "keyword" - }, - "updated_utc": { - "type": "date" - }, - "value": { - "type": "double" - } - } - } - } -} -``` +Some completed migrations can be run again. Take a snapshot first, and stop older instances. You can rerun one from +**Settings** > **System** > **Migrations**, or from the job image with `Migration --rerun MIGRATION_NAME`. See +[Rerun a migration](/docs/self-hosting/administration/#rerunning-a-completed-migration). -### Reindex Event data from 1.x into 5.x **Please make sure you update the host name**: +## What changed in 9.0 {#what-changed-in-9-0} -```json -POST _reindex -{ - "source": { - "remote": { - "host": "http://10.0.0.9:9200" - }, - "index": "events-v1-*", - "size": 200 - }, - "dest": { - "index": "events-v1-error" - }, - "script": { - "lang": "painless", - "inline": "ctx._index = 'events-v1-' + DateTimeFormatter.ofPattern('yyyy.MM.dd').format(OffsetDateTime.parse(ctx._source.date).toInstant().atZone(ZoneOffset.UTC)); if (ctx._source.updated_utc == null) { ctx._source.updated_utc = ctx._source.created_utc; } if (ctx._source.is_deleted == null) { ctx._source.is_deleted = false; } if (!ctx.containsKey('data') || !(ctx.data.containsKey('@error') || ctx.data.containsKey('@simple_error'))) return null;def types = [];def messages = [];def codes = [];def err = ctx.data.containsKey('@error') ? ctx.data['@error'] : ctx.data['@simple_error'];def curr = err;while (curr != null) { if (curr.containsKey('type')) types.add(curr.type); if (curr.containsKey('message')) messages.add(curr.message); if (curr.containsKey('code')) codes.add(curr.code); curr = curr.inner;}if (ctx.error == null) ctx.error = new HashMap();ctx.error.type = types;ctx.error.message = messages;ctx.error.code = codes;" - } -} -``` +### Reverse proxies need to be trusted -### Delete the previous Event Template: +Exceptionless now reads `X-Forwarded-For` and `X-Forwarded-Proto` only from loopback addresses and from proxies you +list. Earlier versions accepted them from anyone. -```json -DELETE _template/events-v1 -``` +If a reverse proxy, load balancer, or ingress controller sits in front of Exceptionless, add its address before you +upgrade. Otherwise every request appears to come from the proxy over HTTP, and all anonymous visitors share one set of +IP-based limits. See [Reverse proxies and HTTPS](/docs/self-hosting/reverse-proxy/). If clients connect directly, you +don't need to change anything. -## Upgrading from v2 to v3 +Exceptionless refuses to start if these settings are invalid, so check the logs after the upgrade. -_Please note that upgrading from [v2](https://github.com/exceptionless/Exceptionless/releases/tag/v2.0.0) to [v3](https://github.com/exceptionless/Exceptionless/releases/tag/v3.0.0) requires that `Redis` is installed and configured._ +### The new web UI replaces the old one -1. Download and extract the [v3](https://github.com/exceptionless/Exceptionless/releases/tag/v3.0.0) release to a temp folder. -2. Update the connection strings in the `App_Data\JobRunner\Job.exe.config` config file. - 1. You'll also need to add a `Migration:MongoConnectionString` connection string for the migration jobs to run. +The Angular UI is gone. The Svelte UI, which 8.x served at `/next`, is now at the root of the site. - ```xml - - ``` +- Remove `EX_Html5Mode`; it no longer does anything. +- Set `EX_BaseURL` to the plain URL of your app, such as `https://errors.example.com`, without `/#!`. +- Old bookmarks that use `#!/` links are redirected to the new pages. -3. Open the terminal and run the following jobs to migrate data from previous major versions of Exceptionless. `Jobs.exe` can be found in the `\wwwroot\App_Data\JobRunner\` folder. +### Sign-in providers -```powershell -Job.exe -t "Exceptionless.EventMigration.OrganizationMigrationJob, Exceptionless.EventMigration" -s "Exceptionless.Core.Jobs.JobBootstrapper, Exceptionless.Core" -``` - -## Upgrading from v1 to v3 +- Microsoft sign-in now uses the Microsoft identity platform: the `common` endpoint and the `User.Read` scope. Check + that your app registration in Microsoft Entra accepts accounts from any organizational directory and lists your web + app's origin as a **Web** redirect URI. The keys are still `MicrosoftId` and `MicrosoftSecret`. +- Facebook sign-in is removed, and `FacebookId` and `FacebookSecret` are ignored. People who signed in only with + Facebook can set a password with **Forgot password?** on the sign-in page. -_Please note that upgrading from v1 to [v3](https://github.com/exceptionless/Exceptionless/releases/tag/v3.0.0) requires that `Redis` is installed and configured._ +See [Sign-in providers](/docs/self-hosting/configuration/#sign-in-providers). -1. Download and extract the [v3](https://github.com/exceptionless/Exceptionless/releases/tag/v3.0.0) release to a temp folder. -2. Update the connection strings in the `App_Data\JobRunner\Job.exe.config` config file. - 1. You'll also need to add a `Migration:MongoConnectionString` connection string for the migration jobs to run. +### New and changed settings - ```xml - - ``` +- `EX_ApiUrl` is now also read by the server. OAuth discovery and the MCP server use it, and fall back to `EX_BaseURL`. + Set it only if the API is on a different host name than the web app. +- `EX_EnableSsl` now also makes the app send a Content Security Policy that upgrades insecure requests. +- `EX_ForwardedHeaders__*` settings control proxy trust. The Helm chart adds `forwardedHeaders.knownNetworks`. +- Exie's default model is now `openai/gpt-6.1-sol`. If you didn't set `EX_Assistant__Model` or choose a model under + **Settings** > **System** > **Settings**, Exie switches to it. -3. Open the terminal and run the following jobs to migrate data from previous major versions of Exceptionless. `Jobs.exe` can be found in the `\wwwroot\App_Data\JobRunner\` folder. +### Elasticsearch -```powershell -Job.exe -t "Exceptionless.EventMigration.StackMigrationJob, Exceptionless.EventMigration" -s "Exceptionless.Core.Jobs.JobBootstrapper, Exceptionless.Core" -Job.exe -t "Exceptionless.EventMigration.QueueEventMigrationsJob, Exceptionless.EventMigration" -s "Exceptionless.Core.Jobs.JobBootstrapper, Exceptionless.Core" -Job.exe -t "Exceptionless.EventMigration.EventMigrationJob, Exceptionless.EventMigration" -c -s "Exceptionless.Core.Jobs.JobBootstrapper, Exceptionless.Core" -Job.exe -t "Exceptionless.EventMigration.OrganizationMigrationJob, Exceptionless.EventMigration" -s "Exceptionless.Core.Jobs.JobBootstrapper, Exceptionless.Core" -``` +9.0 still uses Elasticsearch 8, so you don't need to reindex. The images and samples now use Elasticsearch 8.19.22. diff --git a/docs/docs/setting-log-levels.md b/docs/docs/setting-log-levels.md index cf7bcf62aa..16d7b1e262 100644 --- a/docs/docs/setting-log-levels.md +++ b/docs/docs/setting-log-levels.md @@ -1,33 +1,102 @@ --- -title: "Log Levels" -metaTitle: "Setting log levels in Exceptionless" -description: "Set minimum log levels for Exceptionless log events in project settings or per log stack, so clients stop sending lower-level logs without a redeploy." +title: "Logs and log levels" +navTitle: "Logs and log levels" +metaTitle: "Viewing logs and setting log levels in Exceptionless" +description: "Find log events in Exceptionless and set a project's minimum log level, or one per log source, without redeploying your app." +sources: + - src/Exceptionless.Core/Seed/predefined-saved-views.json + - src/Exceptionless.Core/Pipeline/010_AssignToStackAction.cs + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/settings/+page.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/projects/components/project-log-level.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/projects/components/table/config-options.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/stack-log-level.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/options.ts + - Exceptionless.Net:src/Exceptionless/Models/Collections/SettingsDictionary.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/010_EventExclusionPlugin.cs + - Exceptionless.JavaScript:packages/core/src/plugins/default/EventExclusionPlugin.ts --- -# Log Levels +# Logs and log levels -Setting log levels allows you to control the flow of data into your Exceptionless account. This is important when you are trying to filter the signal from the noise. In most error monitoring services, you would need to manually configure what log levels are used to send events by customizing your code. With Exceptionless, you can update the log levels used right in the Exceptionless UI. +Exceptionless stores log messages as `log` events, each with a source (usually the logger name) and a level. This page +shows where to find them and how to set the minimum level your apps send, for the whole project or for one log source, +without changing code or redeploying. -To configure your default log level, open **Settings > Projects** in the sidebar, click your project, and then open the **Settings** tab. The **Default Log Level** section is at the top. Click the dropdown and pick the lowest level you want to keep. +To send logs, see the sending events page for [.NET](/docs/clients/dotnet/sending-events/) or +[JavaScript](/docs/clients/javascript/sending-events/), or connect your logging framework with the +[.NET logging integrations](/docs/clients/dotnet/logging/). -![Default Log Level dropdown on the project Settings tab](/assets/img/docs/setting-log-levels-project-default-light.webp) +## Find your logs -You can set the level for the whole project here, or override it for a single log source on that log's stack. To find a log stack, open **Events > Logs** in the sidebar. You can also filter **Stacks > All** or **Events > All** by type. +- **Events** > **Logs** in the sidebar lists log messages from open and regressed stacks, newest first. +- Add a **Log Level** filter to any list to narrow it to levels such as **Error** and **Fatal**. In a raw filter, use + `type:log level:error`. +- Add the **Level** and **Source** columns with **View** > **Manage Columns...**. ![The Logs events view](/assets/img/docs/setting-log-levels-logs-view-light.webp) -Click a log event. The event details open with the log's stack card at the top. +Logs from the same source group into one stack, so you can mark a noisy source ignored, or snooze it, like any other +stack. See [Stacks](/docs/managing-stacks/). -### Overriding Global Log Levels +## Log levels -In the stack card header, click the log level button (the filter icon, first in the row of buttons) and select a new level. Events at that level or above are kept for this log source. Anything below it is no longer captured. The button only appears on log stacks that have a source. +From lowest to highest: **Trace**, **Debug**, **Information**, **Warning**, **Error**, and **Fatal**. A minimum level +keeps that level and everything above it. **Off** stops all logs. + +## Set the project's default level + +1. Open **Settings** > **Projects** in the sidebar and select the project. +2. Open the **Settings** tab. +3. Under **Default Log Level**, open the menu and pick the lowest level to keep. + +Every log source in the project uses this level unless it has its own. + +## Set the level for one log source + +1. Open a log event, or a log stack, from any list. +2. In the stack card, select the log level button, the first of the buttons at the top right. Its tooltip shows the + current level, such as "Log Level: Warning (Default)". +3. Pick a level. ![Log Level menu on a log stack](/assets/img/docs/setting-log-levels-stack-override-light.webp) -Once a stack has its own level, the menu also shows **Default** with the project's level. Click it to remove the override and go back to the project default. +The button appears only on log stacks that have a source. Once a source has its own level, the menu also shows +**Default** with the project's level. Select it to go back to the project default. -As with Data Exclusions, updates to project level and global log level settings will be passed down to the Exceptionless client in near real-time. While the Exceptionless server will catch event that should not be included in your dashboard, the client will catch them based on your configuration and prevent them from ever being sent to the server. Read more about [Project Settings](/docs/project-settings) here. +## How levels are applied ---- +Log levels are client configuration values that your apps download from Exceptionless. Each client checks a log event's +level and drops it before sending if it's below the minimum, so dropped logs never reach Exceptionless and don't count +against your plan. Your apps pick up a change the next time they sync their configuration. See client configuration +values for [.NET](/docs/clients/dotnet/client-configuration-values/) and +[JavaScript](/docs/clients/javascript/client-configuration-values/). + +- The project default is stored as `@@log:*`, and a source's level as `@@log:` followed by the source name. +- Per-source levels show up on the project's **Configuration** tab. There you can also add a level for a group of + sources with a wildcard, such as `@@log:Acme.Data.*` set to `debug`. The most specific match wins. See + [Projects](/docs/project-settings/#client-configuration). +- Logs without a level are always sent. +- With no level set for a source or the project, the .NET client sends **Warning** and above, and the JavaScript client + sends every level. + +Exceptionless doesn't filter logs on the server. Logs sent another way, such as straight to the API, are stored at any +level. + +## Ask Exie + +Exie can't change log levels, but it can tell you where your logs come from: + +```prompt exie +Which log sources sent the most error and fatal logs today? +``` + +```prompt exie +How many warning logs did Acme.Billing send each hour over the last 24 hours? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can trace a noisy log back to the code: -[Next > De-Duplication](/docs/deduplication) +```prompt agent +Find the log source in my Exceptionless project that sent the most error logs in the last 24 hours, then find where +this repository writes those logs and tell me whether they should be errors. +``` diff --git a/docs/docs/source-maps.md b/docs/docs/source-maps.md deleted file mode 100644 index 901faa2ee7..0000000000 --- a/docs/docs/source-maps.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: "JavaScript Source Maps" -description: "Get readable JavaScript stack traces in Exceptionless with source maps: discover public maps automatically or upload private maps from your CI/CD pipeline." ---- - -# JavaScript Source Maps - -Production JavaScript is usually bundled and minified. That makes it fast to download, but it can turn a useful stack frame such as `loadCurrentUser` into a short name such as `a`. - -Exceptionless uses source maps to restore the original function names, file names, line numbers, and column numbers before a new error is assigned to a stack. This gives you readable stack traces and helps Exceptionless group errors by the code that actually failed. - -You can make source maps available in either of these ways: - -| If your source maps are... | Recommended setup | -| --- | --- | -| Publicly available with your application | Deploy them with the generated JavaScript. Exceptionless discovers them automatically. | -| Private or stored only as build artifacts | Upload them to Exceptionless from your deployment pipeline. | - -Source maps are applied while new events are processed. Uploading a map does not rewrite events that Exceptionless has already processed. - -## Use public source maps - -Public source maps require no Exceptionless project configuration and no upload step. For each JavaScript stack frame, Exceptionless: - -1. Uses the absolute generated JavaScript URL, line number, and column number reported by the browser. -2. Looks for a source map already stored for that exact generated file URL. -3. If one is not stored, anonymously downloads the generated JavaScript over HTTPS. -4. Checks its `SourceMap` or `X-SourceMap` response header, then its `sourceMappingURL` comment. -5. If neither points to a map, tries the conventional `.map` URL. -6. Validates and caches the map for the project, then restores the original stack frame. - -For example, a production build can deploy these files: - -```text -https://cdn.example.com/assets/app.a1b2c3.js -https://cdn.example.com/assets/app.a1b2c3.js.map -``` - -The generated JavaScript normally ends with a relative reference: - -```js -//# sourceMappingURL=app.a1b2c3.js.map -``` - -Exceptionless can also follow an absolute `sourceMappingURL`, a relative URL in a `SourceMap` response header, or an inline data URL. - -### Public map requirements - -- The generated JavaScript URL in the stack frame must be an absolute HTTPS URL. -- The generated JavaScript and source map must be available without cookies, authentication headers, or an IP allowlist. -- The URL must use the standard HTTPS port. -- The map must be a version 3 flat source map. Indexed maps that contain a `sections` property are not supported. -- The source map must be generated by the same build as the deployed JavaScript. - -Content-hashed file names are strongly recommended. A URL such as `app.a1b2c3.js` permanently identifies one build, while a reused URL such as `app.js` can refer to different code over time. - -You can confirm that a deployed map is public before releasing it: - -```shell -curl --fail --silent --show-error \ - "https://cdn.example.com/assets/app.a1b2c3.js.map" \ - --output /dev/null -``` - -Public source maps can contain your original source code in `sourcesContent`. If that code should not be public, generate the map during the build but exclude it from the deployed assets and use the upload workflow instead. - -## Upload private source maps - -Uploaded maps do not need to be public. Exceptionless associates an upload with the exact generated JavaScript URL that appears in the stack frame, so it can use the map without downloading it from your site. - -To upload one map manually: - -1. Open your project in Exceptionless. -2. Go to **Project Settings** and select **Source Maps**. -3. Enter the exact absolute **Generated JavaScript URL** shown in the stack trace. -4. Select the matching `.map` file and choose **Upload**. - -The generated URL may use HTTP or HTTPS for a manual upload. It must not contain credentials or a fragment. Keep its path and query string exactly as they appear in the stack frame. - -Uploading another map for the same generated file URL replaces the existing map. The **Source Maps** page lists both uploaded and automatically discovered maps, when they were added and last used, and lets you delete them. - -## Upload source maps from CI/CD - -Generate the source maps and production JavaScript in the same build. Upload the maps from that build, then deploy the same generated JavaScript without rebuilding it. - -### 1. Create a deployment token - -Create the token once in Exceptionless: - -1. Open **Project Settings** and select **API Keys**. -2. Choose **Add token**. -3. Select **Source map upload token**. -4. Copy the token and save it as a protected secret named `EXCEPTIONLESS_SOURCE_MAP_TOKEN` in your CI/CD system. - -This token has only the `source-maps:write` scope and is restricted to the selected project. It cannot read events, change project settings, or upload maps to another project. Do not use the client API key embedded in your application. - -Your pipeline also needs: - -- `EXCEPTIONLESS_SERVER_URL`: `https://collector.exceptionless.io` for hosted Exceptionless, or your self-hosted server URL. -- `EXCEPTIONLESS_PROJECT_ID`: the project ID shown in the project URL or project settings. - -### 2. Add the upload to your deployment - -For each source map produced by the build, send a `multipart/form-data` request containing the map and the exact public URL of its generated JavaScript file: - -```shell -curl --fail-with-body --request POST \ - "${EXCEPTIONLESS_SERVER_URL}/api/v2/projects/${EXCEPTIONLESS_PROJECT_ID}/source-maps" \ - --header "Authorization: Bearer ${EXCEPTIONLESS_SOURCE_MAP_TOKEN}" \ - --form-string "generated_file_url=https://cdn.example.com/assets/app.a1b2c3.js" \ - --form "file=@dist/assets/app.a1b2c3.js.map;type=application/json" -``` - -A successful upload returns HTTP `201 Created`. - -Add this request after your production build and before the release step. If the build creates multiple JavaScript bundles, repeat it for each `.map` file. How you enumerate those files and construct their public URLs depends on your build tool and deployment layout. - -Deploy the same build artifacts that you uploaded maps for. Do not rebuild between the source-map upload and deployment. - -## Verify the setup - -After the deployment: - -1. Open **Project Settings > Source Maps**. -2. Confirm that the generated URL is listed as **Automatic** or **Uploaded**. -3. Send a new test error from the production build. -4. Open the event and confirm that its stack trace shows original file and function names. -5. Return to **Source Maps** later to confirm that **Last used** has been updated. Usage timestamps are persisted asynchronously. - -## Troubleshooting - -### The map was uploaded, but the stack is still minified - -- Compare the uploaded generated URL with the URL in the event stack frame. The path and query string must match. -- Confirm that the map and JavaScript came from the same build. -- Confirm that the stack frame includes a valid line and column number. -- Send a new event. Existing events are not reprocessed after an upload. -- Confirm that the file is a version 3 flat source map, not an indexed map. - -### A public map was not discovered - -- Confirm that both the generated JavaScript and map return successful responses without authentication. -- Use HTTPS on the standard port. Upload maps for HTTP, custom-port, private-network, or authenticated URLs. -- Check the generated file for `sourceMappingURL`, check its response for `SourceMap` or `X-SourceMap`, or publish the map at `.map`. -- Check **Project Settings > Source Maps**. Successfully discovered maps appear there automatically. - -### A deployment replaced files at the same URL - -Exceptionless periodically refreshes automatically discovered maps, but immutable content-hashed URLs are safer and avoid ambiguity between releases. Uploaded maps are replaced when you upload another map for the same generated URL. - -## Storage and retention - -Exceptionless validates downloads, limits their size and processing time, and applies plan-aware discovery and storage limits. Automatic discovery never rejects an event; if a map is unavailable or a limit is reached, Exceptionless keeps the generated stack frame. - -By default, free projects retain up to 100 maps and 100 MiB, and paid projects retain up to 1,000 maps and 1 GiB. Maps that have not been used are removed after 14 days on free plans and 90 days on paid plans. Self-hosted administrators can change these values in the `SourceMaps` configuration section. diff --git a/docs/docs/user-sessions.md b/docs/docs/user-sessions.md index 31d9943967..fc7d5c1ed7 100644 --- a/docs/docs/user-sessions.md +++ b/docs/docs/user-sessions.md @@ -1,87 +1,165 @@ --- -title: "User Sessions" -description: "Track user sessions in Exceptionless from .NET and JavaScript: set a user identity, enable sessions, send start, heartbeat, and end events, and view reports." +title: "Sessions" +metaTitle: "Track user sessions in Exceptionless" +description: "See what a user did before an error: how Exceptionless groups events into sessions, how clients start, heartbeat, and end them, and the Sessions view." +sources: + - src/Exceptionless.Core/Plugins/EventProcessor/Default/70_SessionPlugin.cs + - src/Exceptionless.Core/Jobs/CloseInactiveSessionsJob.cs + - src/Exceptionless.Core/Extensions/PersistentEventExtensions.cs + - src/Exceptionless.Web/Api/Endpoints/EventEndpoints.cs + - src/Exceptionless.Web/ClientApp/src/routes/(app)/sessions/+page.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/sessions/components/session-table-columns.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/sessions/components/sessions-stats-dashboard.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/events-overview.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/events/components/views/session-events.svelte + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs + - Exceptionless.Net:src/Exceptionless/Extensions/ExceptionlessConfigurationExtensions.cs + - Exceptionless.Net:src/Exceptionless/Extensions/ExceptionlessClientExtensions.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/100_HeartbeatPlugin.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/016_SetEnvironmentUserPlugin.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/900_CancelSessionsWithNoUserPlugin.cs + - Exceptionless.Net:src/Platforms/Exceptionless.AspNetCore/ExceptionlessAspNetCorePlugin.cs + - Exceptionless.JavaScript:packages/core/src/configuration/Configuration.ts + - Exceptionless.JavaScript:packages/core/src/ExceptionlessClient.ts + - Exceptionless.JavaScript:packages/core/src/plugins/default/HeartbeatPlugin.ts + - Exceptionless.JavaScript:packages/browser/src/plugins/BrowserLifeCyclePlugin.ts + - Exceptionless.JavaScript:packages/core/test/DocumentationExamples.test.ts --- -# User Sessions +# Sessions -With user session tracking, you can easily see what a user is doing that leads up to an event occurrence, or just see how they are using your app. +A session is one user's visit to your app: every error, log, feature usage, and 404 they triggered, in order. Use +sessions to see what a user did before an error, or how people use your app. Sessions are on paid plans. -Each session has a list of events (feature usages, exceptions, log messages, etc.) that the user triggered. Open any event in the session and click the **Session Events** tab to see them. Click an event to drill down, or use the events button above the list to open the Events view filtered to that session. +## How sessions work -![Session Events tab on an event](/assets/img/docs/user-sessions-session-events-light.webp) +Every event that has a **user identity** belongs to a session. Exceptionless groups a user's events on the server, so +you get sessions as soon as your events carry a user identity: -Browser and environment information, along with any other data that persists throughout the user session, is stored as well. +- The first event from a user starts a session. Exceptionless creates a session start event for it, with the user, the + version, the location, and the environment information from that first event. +- Later events from the same user, in the same project and environment, join that session. +- A session ends when the client sends a session end, or when the user has had no events and no heartbeats for five + minutes. +- The session's duration runs from its first event to its last activity. -Once you set up session tracking, click **Sessions** in the sidebar to see every session in the selected time range, with totals for sessions, users, and average duration. Turn on **View Active** to show only sessions that have not ended. Click a session to open its details. You can also click the session ID on any event's **Overview** tab. +Events without a user identity or a session ID don't belong to a session. -![Sessions dashboard](/assets/img/docs/user-sessions-dashboard-light.webp) +A client can also manage sessions itself: -## Turn On Session Tracking +- **Session start**, **heartbeat**, and **session end** events mark when a session begins, show that the user is still + active while nothing else is being sent, and close the session. +- A client can give events its own session ID instead of relying on the user identity. Session IDs are 8 to 100 letters, + digits, or dashes. -Set a default user identity via the following client methods to send the user ID for each event. Once set, it will be applied for all future events. +## Set the user identity -### C# Set User Identity Example +Set the user identity once your app knows who the user is, and every event after that carries it. Use a stable, unique +value such as a user ID or email address, and optionally a display name. -```csharp -using Exceptionless; -ExceptionlessClient.Default.Configuration.SetUserIdentity("UNIQUE_ID_OR_EMAIL_ADDRESS", "Display Name"); -``` +Some clients set it for you: -### JavaScript Set User Identity Example +- In ASP.NET Core, the .NET client uses the signed-in user's name when you haven't set an identity. +- In WinForms and WPF apps, the .NET client uses the Windows user name. -```javascript -import { Exceptionless } from "@exceptionless/browser"; +To set it in code, see [sending events in .NET](/docs/clients/dotnet/sending-events/) and +[sending events in JavaScript](/docs/clients/javascript/sending-events/). -Exceptionless.config.setUserIdentity("UNIQUE_ID_OR_EMAIL_ADDRESS", "Display Name"); -``` +> [!NOTE] +> If the project removes user identifiable information (see [data exclusions](/docs/project-settings/#data-exclusions)), +> events still group into sessions, but the user identity isn't stored on them. + +## Turn on client sessions -**Please Note: In WinForms and WPF applications**, a plugin will automatically set the default user to the `Environment.UserName` if the default user hasn’t been already set. Likewise, if you are in a web environment, we will set the default user to the request principal’s identity if the default user hasn’t already been set. +In apps with one user at a time, such as browser, desktop, and mobile apps, turn on sessions in the client. The client +then: -**If you are using WinForms, WPF, or a Browser App**, you can enable sessions by calling the `UseSessions` extension method. +- sends a session start when it starts up, +- sends a heartbeat every minute while the app stays open, counting from the last event, so an idle user's session stays + open, +- sends a session end when the app shuts down. In the browser, that's when the page unloads. -### C# Use Sessions Example + -```csharp +```csharp tab=".NET" using Exceptionless; -ExceptionlessClient.Default.Configuration.UseSessions(); -``` -### JavaScript Use Sessions Example +var client = ExceptionlessClient.Default; +client.Configuration.SetUserIdentity("user-123", "Jane Doe"); +client.Configuration.UseSessions(); +client.Startup("YOUR_API_KEY"); +``` -```javascript -import { Exceptionless } from "@exceptionless/browser"; +```ts tab="JavaScript" +import { Exceptionless } from "@exceptionless/browser" -Exceptionless.config.useSessions(); +await Exceptionless.startup((c) => { + c.apiKey = "YOUR_API_KEY" + c.setUserIdentity("user-123", "Jane Doe") + c.useSessions() +}) ``` -## Manually Send SessionStart, SessionEnd, and heartbeat Events +Both clients accept options on `UseSessions()` and `useSessions()`: whether to send heartbeats, the heartbeat interval +(one minute by default, at least 30 seconds), and whether the client generates its own session ID. -You can use our client API to start, update, or end a session. Just remember, a user identity must be set. +Don't turn on client sessions in a server app that handles many users. Set the user identity on each event instead, as +ASP.NET Core does, and Exceptionless groups each user's events into sessions on the server. -### C# Submit Session Events Example +You can also send session start, heartbeat, and end events yourself, for example when a user signs in or out. The client +pages show how: -```csharp -using Exceptionless; -ExceptionlessClient.Default.SubmitSessionStart(); -await ExceptionlessClient.Default.SubmitSessionHeartbeatAsync(); -await ExceptionlessClient.Default.SubmitSessionEndAsync(); -``` +- [.NET: sending events](/docs/clients/dotnet/sending-events/) +- [JavaScript: sending events](/docs/clients/javascript/sending-events/) +- [Client specification](/docs/reference/client-spec/) for the heartbeat endpoint that custom clients call + +## View sessions + +Click **Sessions** in the sidebar to see every session in the date range. + +![Sessions view with totals, a chart, and the session list](/assets/img/docs/user-sessions-dashboard-light.webp) -### JavaScript Submit Session Events Example +- The cards show the **Total** number of sessions, the average sessions per hour (**Avg/hr**), the number of **Users**, + and the average **Duration**. +- The chart shows sessions over time. Drag across it to zoom into a time range. +- The list shows each session's **Summary**, **Duration**, **User**, and **Date**. The **Environment** column is hidden + by default; turn it on from the column options. +- Turn on **View Active** to show only sessions that haven't ended. +- Filter by project, date, environment, version, tag, and more with the filter bar. See + [Filtering and searching](/docs/filtering-and-searching/). +- Save a filtered list as a view with **View**. See [Saved views](/docs/saved-views/). -```javascript -import { Exceptionless } from "@exceptionless/browser"; +Click a session to open its session start event. -await Exceptionless.submitSessionStart(); -await Exceptionless.submitSessionHeartbeat(); -await Exceptionless.submitSessionEnd(); +## See the events in a session + +Any event that belongs to a session has a **Session Events** tab in its details. It lists every event in the session +with its **Summary**, **User**, and **Session Time**. On a session start event, the tab also shows the session's +**Duration** and the user. + +![Session Events tab on an event](/assets/img/docs/user-sessions-session-events-light.webp) + +Click an event in the list to open it. Click **Open events filtered to this session** (the button above the list) to see +the session's events in the **Events** view, where you can filter and sort them. + +## Ask Exie + +[Exie](/docs/ai/exie/) is on Medium plans and up. + +```prompt exie +How many sessions started in production over the last 7 days? ``` -## Disable Heartbeat +```prompt exie +Which users had the most sessions this week? +``` -If you would like to disable the near real-time session tracking heartbeat that goes out ever 30 seconds, you can pass `false` as an argument to the `UseSessions()` method. +```prompt exie +What errors did jane@example.com run into today? +``` ---- +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can follow a user's session while it debugs: -[Next > Notifications](/docs/notifications) +```prompt agent +Find the latest error for user jane@example.com in Exceptionless, list her events from the hour before it in order, and tell me what she did before it happened. +``` diff --git a/docs/docs/versioning.md b/docs/docs/versioning.md index 4a0d4a96fd..3fc7511bfc 100644 --- a/docs/docs/versioning.md +++ b/docs/docs/versioning.md @@ -1,48 +1,124 @@ --- -title: "Versioning" -metaTitle: "Versioning and regression detection" -description: "Set an application version in Exceptionless so stacks marked fixed in a version reopen as regressed only when a newer version hits the same error." +title: "Releases and regressions" +metaTitle: "Versions and regression detection" +description: "Send your app's version with every event, mark stacks fixed in a release, and learn when Exceptionless reopens a fixed stack as regressed." +sources: + - src/Exceptionless.Core/Pipeline/030_CheckForRegressionAction.cs + - src/Exceptionless.Core/Utility/SemanticVersionParser.cs + - src/Exceptionless.Core/Extensions/StackExtensions.cs + - src/Exceptionless.Web/Api/Handlers/StackHandler.cs + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/dialogs/mark-stack-fixed-in-version-dialog.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/schemas.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/stacks/components/stack-card.svelte + - src/Exceptionless.Core/Repositories/Configuration/Indexes/EventIndex.cs + - tests/Exceptionless.Tests/Pipeline/EventPipelineTests.cs + - Exceptionless.Net:src/Exceptionless/Extensions/ExceptionlessConfigurationExtensions.cs + - Exceptionless.Net:src/Exceptionless/Plugins/Default/080_VersionPlugin.cs + - Exceptionless.JavaScript:packages/core/src/configuration/Configuration.ts --- -# Versioning +# Releases and regressions -Stacks and their fixed version are shared across [environments](/docs/environments/). Continue sending application versions so older deployments can report occurrences without incorrectly reopening a stack fixed in a newer version. +Send your app's version with every event, and Exceptionless can tell which release an error came from. When you mark a +stack fixed in a version, only events from that version or later reopen it, so older releases that are still running +don't undo your fix. -You can mark error stacks fixed and they won't show up or notify you until they regress! +## Send your app's version -## How does this work? +Set the version once when the client starts. Every event it sends then includes it. -When an event comes into Exceptionless, we figure out what makes it unique and place it into a stack of similar events. This means that an error comes in, it will be placed in a stack of similar error events. All events may contain an application version, this can be used to track what versions of an application are causing errors or being actively used. +```csharp tab=".NET" +// Program.cs (Exceptionless.AspNetCore) +builder.AddExceptionless(c => c.SetVersion("2.4.1")); +``` -## How do I specify an application version? +```ts tab="JavaScript" +import { Exceptionless } from "@exceptionless/browser" -An application version will try and be resolved if possible, but it's a good idea to specify a version if you can. Please view the client specific documentation below to learn more about setting an app version. +await Exceptionless.startup((c) => { + c.apiKey = "YOUR_API_KEY" + c.version = "2.4.1" +}) +``` -## Choose your Client +If you don't set it, the .NET client uses the version of your app's entry assembly when it can find one. The JavaScript +client sends no version unless you set it. For other clients, put the version in the event's `@version` data. See the +configuration page for [.NET](/docs/clients/dotnet/configuration/) or +[JavaScript](/docs/clients/javascript/client-configuration/), and the [event format](/docs/reference/event-format/). -* [.NET](/docs/clients/dotnet/) -* [JavaScript / Node.js](/docs/clients/javascript/client-configuration) +The version appears on the event's **Overview** tab, with a filter icon to filter by it. Add the **Version** column to +an event list with **View** > **Manage Columns...**. -## What does mark fixed do? +## Mark a stack fixed in a version -To mark a stack fixed, open the stack, click the status button in the top-right corner (it shows the current status, such as **Open**), and choose **Fixed**. You can also select several stacks in a list and choose **Mark Fixed** from the [**Actions**](/docs/bulk-actions) menu. Enter the version that contains the fix in the **Version** box, or leave it empty, and then click **Mark Stack Fixed**. +1. Open the stack and select its status button, which shows the current status, such as **Open**. +2. Choose **Fixed**. +3. In **Mark Stack As Fixed**, enter the **Version** that contains the fix, such as `2.4.1`, or leave it empty. +4. Select **Mark Stack Fixed**. ![Mark Stack As Fixed dialog with an optional version](/assets/img/docs/versioning-mark-fixed-light.webp) -When you mark a stack as fixed, the following meta data is recorded on the stack: +To fix several stacks at once, select them in a list and choose **Actions** > **Mark Fixed**. See +[Bulk actions](/docs/managing-stacks/#bulk-actions). -* when the stack was fixed -* and **optionally** the semantic version that you fixed this behavior in. +The version must be a semantic version, such as `1.2.3` or `1.2.3-beta.1`. The dialog rewrites two common formats for +you: a two-part version such as `1.2` becomes `1.2.0`, and a four-part version such as `1.2.3.4` becomes `1.2.3-4`. -> **NOTE:** Versions are semantic versions. If you enter a **four-part version number** (E.G., `1.2.3.4`), the dialog changes it to `1.2.3-4` for you, and a two-part version like `1.2` becomes `1.2.0`. We automatically handle four-part versions when processing events. +The stack card then shows **Fixed** with the version and date, and the stack leaves the built-in views, which show only +open and regressed stacks. -Next, the stack is hidden from the default stack lists, which only show open and regressed stacks. To see fixed stacks, include **Fixed** in the list's **Status** filter. +## When a fixed stack regresses -This meta data is then inspected when an matching event is processed to determine if the stack and all occurrences should be regressed (_marked not fixed_). There are two scenarios where a stack will be marked as regressed: +When a new event arrives for a fixed stack, Exceptionless compares it with the fix: -1. If no fixed in version is specified, any occurrence with a date newer than the date the stack was marked as fixed. -2. If a fixed in version is specified, any occurrence that has a newer version specified (Example: `1.0.0` > `1.0.0-beta`). +| Fixed in | New event's version | Result | +| ---------- | --------------------------------- | ---------------------------------------------- | +| No version | Any, or none | Regressed, if the event occurred after the fix | +| `2.4.1` | `2.4.1` or later, such as `2.5.0` | Regressed | +| `2.4.1` | Earlier, such as `2.4.0` | Stays fixed | +| `2.4.1` | None | Stays fixed | ---- +A regressed stack shows **Regressed**, appears in the built-in views again, and can send a regression notification. See +[Notifications](/docs/notifications/). + +When a stack fixed in a version stays fixed, what happens to the event depends on your plan. On paid plans, the event is +dropped and not stored. On the Free plan, it's stored with the stack, which stays fixed. + +Versions are compared as semantic versions, so `2.10.0` is later than `2.9.0`, and a prerelease such as `2.4.1-beta` is +earlier than `2.4.1`. A leading `v` in an event's version, as in `v2.4.1`, is ignored. + +## Fixes across environments + +A stack and its fixed version are shared across [environments](/docs/environments/). If staging already runs `2.4.1` and +production still runs `2.4.0`, mark the stack fixed in `2.4.1`. Production's errors from `2.4.0` then don't reopen it. +If you mark it fixed without a version, the next production error reopens it. + +## Search by version + +- `version:2.4` finds events from any `2.4.x` version, and `version:2.4.1` from exactly that one. +- `version_fixed:2.4.1` finds events in stacks marked fixed in `2.4.1`. +- Version ranges, such as `version:>2.4`, aren't supported. + +See the [search syntax](/docs/reference/search-syntax/#versions). + +## Ask Exie + +```prompt exie +Which versions of my app had the most errors in the last 7 days? +``` + +```prompt exie +Which stacks regressed since we released 2.4.1? +``` + +```prompt exie +Mark this stack fixed in version 2.4.2. +``` + +With the [MCP server](/docs/ai/mcp-server/) connected and `stacks:write` granted, your coding agent can close the loop +after a fix: -[Next > Reference Ids](/docs/references-ids) +```prompt agent +Read the version from this project's build file, then mark the Exceptionless stacks for the errors fixed on this branch +as fixed in that version. +``` diff --git a/docs/docs/whats-new.md b/docs/docs/whats-new.md new file mode 100644 index 0000000000..3ba51ee897 --- /dev/null +++ b/docs/docs/whats-new.md @@ -0,0 +1,205 @@ +--- +title: "What's new in Exceptionless 9.0" +navTitle: "What's new" +description: "Exceptionless 9.0 for returning users: the new app, saved views, Exie, the MCP server, environments, Microsoft sign-in, and where things moved." +sources: + - src/Exceptionless.Web/ClientApp/src/lib/features/navigation/legacy-links.ts + - src/Exceptionless.Web/ClientApp/src/routes/(app)/routes.svelte.ts + - src/Exceptionless.Web/ClientApp/src/routes/(app)/(components)/layouts/sidebar-user.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(app)/account/routes.svelte.ts + - src/Exceptionless.Web/ClientApp/src/routes/(app)/project/[projectId]/routes.svelte.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/shared/keyboard-shortcuts.ts + - src/Exceptionless.Web/ClientApp/src/lib/features/shared/components/date-range-picker/date-range-picker.svelte + - src/Exceptionless.Web/ClientApp/src/lib/features/assistant/components/assistant-fix-button.svelte + - src/Exceptionless.Web/ClientApp/src/routes/(auth)/oauth/authorize/+page.svelte + - src/Exceptionless.Core/Seed/predefined-saved-views.json + - src/Exceptionless.Core/Models/Event.cs + - src/Exceptionless.Core/Configuration/AuthOptions.cs + - src/Exceptionless.Core/Authorization/AuthorizationRoles.cs + - src/Exceptionless.Core/Migrations/010_AddEventEnvironment.cs + - src/Exceptionless.Web/Api/Handlers/AuthHandler.cs + - src/Exceptionless.Web/Api/Endpoints/AuthEndpoints.cs + - src/Exceptionless.Web/Assistant/AssistantAccessService.cs + - src/Exceptionless.Web/Assistant/AssistantToolDefinitions.cs + - src/Exceptionless.Web/Mcp/ExceptionlessMcpTools.cs + - src/Exceptionless.Web/Security/TrustedForwardedHeadersOptions.cs + - src/Exceptionless.Web/Program.cs + - src/Exceptionless.Web/appsettings.yml + - Dockerfile + - docker/docker-compose.yml + - Exceptionless.Net:src/Platforms/Exceptionless.AspNetCore/ExceptionlessExtensions.cs + - Exceptionless.JavaScript:packages/react-native/package.json +--- + +# What's new in Exceptionless 9.0 + +Exceptionless 9.0 replaces the classic app with the new one. During the 8.x releases the new app ran as a preview at +`/next` next to the classic app, and several of the features below arrived there first. If you last used the classic +app, everything on this page is new to you. + +Your data, projects, API keys, and clients carry over. The event submission endpoints are unchanged, so apps that send +events today keep working without a client update. + +## A new app + +The new app is now the only app, served at the root of the site. The classic app and the `/next` preview are gone. + +- **Your old links still work.** Bookmarks to classic dashboards, account notification settings, organization billing, + and project integrations open the matching page in the new app. See [Where things moved](#where-things-moved). +- **Command palette.** Press / to search events and stacks, jump to a page, switch organizations, or run an + action. +- **Keyboard shortcuts.** Press ? to see them all. For example, I opens **Stacks**, E + opens **Events**, and A opens Exie. +- **Guided tours.** Short walkthroughs of setup and investigation. Start one from **Help** > **Guided Tours** in your + user menu. +- **Light and dark themes.** Pick one, or follow your system setting, on your account's **Appearance** page. + +See [Navigating the app](/docs/navigation/). + +## Saved views replace the fixed dashboards + +The classic app had a fixed set of dashboards for each event type: a dashboard, most frequent, new, and recent. The new +app has three pages, **Stacks**, **Events**, and **Sessions**, and each one shows a saved view: a filter, a time range, +a sort order, and the columns and charts to show. + +Every organization starts with built-in views that cover the classic dashboards: + +- **Stacks**: All, Most Frequent Errors, Most Frequent 404s, and Most Used Features. +- **Events**: All, Errors, and Logs. +- **Sessions**: All. + +Change the filter or date range, then save your own view. Views are shared with the organization unless you mark them +**Private**, and they appear in the sidebar under their page. The project and date range are filters on each view, and +they are saved with it, instead of a global picker at the top of the app. See [Saved views](/docs/saved-views/). + +### Custom date ranges + +Choose **Custom range** in the date filter to pick dates on a calendar or type them into **From** and **To** fields on +the **Absolute** tab. The **Relative** tab keeps the date math expressions, such as `now-7d`. The quick ranges, from +**Last 5 minutes** to **Last 90 days**, still apply with one click. See +[Filtering and searching](/docs/filtering-and-searching/). + +## Exie, the AI assistant + +Exie is an assistant built into the app. Ask it which errors matter this week, what changed after a release, or why a +stack keeps happening. It searches your stacks and events, counts events over time, and reads stack traces. When you ask +it to, it also marks a stack fixed, snoozes or ignores it, marks it critical, or adds a reference link. It changes +nothing unless you ask for that exact change. + +- Open it in a side panel with **Ask Exie** in the top bar or A, or full page with **Exie** in the sidebar. +- On a stack, **Fix with Exie** starts a conversation about that error. +- In 9.0, Exie shows each lookup and change as it works, lets you stop, retry, or edit a question, and keeps recent + chats in your browser. + +Exie is on Medium plans and up. See [Exie](/docs/ai/exie/). + +## The MCP server and connected apps + +The Exceptionless MCP server lets your coding agent, such as Claude Code or Codex, work with your Exceptionless data on +every plan. The agent signs in through your browser: you approve the request, choose the organizations it can use, and +choose what it can do. It can read projects, stacks, and events. Changing stacks needs the separate `stacks:write` +permission. + +- **AI Tools** in your user menu shows the setup command for each agent. +- The **Applications** page in your account lists the apps you've connected, and lets you revoke them. + +See [MCP server](/docs/ai/mcp-server/) and [AI privacy and security](/docs/ai/privacy/). + +## Environments + +Events can now carry a top-level `environment`, such as `production` or `staging`. **Stacks**, **Events**, and +**Sessions** have an **Environment** filter, including **Unspecified** for events without one, and the filter is saved +with your views. Environments don't split stacks: one error in staging and production is still one stack with one +status. See [Environments](/docs/environments/) for how to send it. + +## JavaScript source maps + +Exceptionless downloads public source maps for minified JavaScript errors and shows the original file names, functions, +and lines in the stack trace. For maps that are private or not published with your scripts, choose **Manage source +maps** on the project's **Settings** page and upload them, or upload them from CI with a project-scoped token. See +[Source maps](/docs/clients/javascript/source-maps/). + +## Sign-in changes + +- **Microsoft sign-in** replaces Windows Live. If you used Windows Live before, sign in with **Microsoft** using the + same email address, and your account picks up the new login. +- **Facebook sign-in is gone.** If you signed in with Facebook, sign in with Microsoft, Google, or GitHub using the same + email address, or use **Forgot password?** on the login page to set a password. + +Manage your logins on your account's **External Logins** page. + +## API changes + +- **API reference.** The interactive reference is at `/docs` on the API host, for example + `https://api.exceptionless.io/docs`, with the OpenAPI document at `/docs/v2/openapi.json`. Choose **Help** > **API + Reference** in your user menu to open it. +- **OAuth access tokens.** Besides API keys and user tokens, the REST API accepts OAuth access tokens issued to apps you + connect, limited by scopes such as `projects:read`, `stacks:read`, `stacks:write`, and `events:read`. See + [Authentication](/docs/api/authentication/). +- **Environment.** Events accept and return a top-level `environment` string, and webhook payloads include it. A valid + root `environment` is no longer stored as `data.environment`. See the [event format](/docs/reference/event-format/). +- **Saved views.** Saved views have their own endpoints under `/api/v2/organizations/{organizationId}/saved-views` and + `/api/v2/saved-views/{id}`. +- **Sign-in endpoints.** `POST /api/v2/auth/microsoft` replaces `/api/v2/auth/live`, and `/api/v2/auth/facebook` is + removed. + +## Clients + +The current clients are Exceptionless.Net 6.2.0 and Exceptionless.JavaScript 3.2.1. + +- **.NET 6.2.** The `Exceptionless.AspNetCore`, `Exceptionless.Extensions.Hosting`, and + `Exceptionless.Extensions.Logging` packages require .NET 8 or later. ASP.NET Core setup uses + `builder.AddExceptionless()` and `app.UseExceptionless()`; `app.UseExceptionless(Configuration)` is gone. See + [Upgrading the .NET client](/docs/clients/dotnet/upgrading/). +- **JavaScript 3.2.** Adds `@exceptionless/react-native` for React Native and Expo apps. See + [React Native and Expo](/docs/clients/javascript/guides/react-native/). +- **Agent skills.** Both client repositories include an agent skill that teaches coding agents how to set up the client. + See [Coding agents](/docs/ai/coding-agents/). + +## Self-hosting + +- **Runtime.** Exceptionless runs on .NET 10 and Elasticsearch 8.19. The Docker images and Compose files use + `exceptionless/elasticsearch:8.19.22`. +- **One app.** The `app` and all-in-one images serve only the new app. +- **Trusted reverse proxies.** The API now accepts `X-Forwarded-For` and `X-Forwarded-Proto` only from loopback or from + proxies you list under `ForwardedHeaders` (`KnownProxies` or `KnownNetworks`). If a reverse proxy or load balancer + sits in front of the API on another host, configure it before you upgrade, or client IPs and HTTPS detection will be + wrong. Don't set `ASPNETCORE_FORWARDEDHEADERS_ENABLED`; the API refuses to start when it's enabled. See + [Reverse proxies and HTTPS](/docs/self-hosting/reverse-proxy/). +- **Login providers.** Microsoft sign-in still reads `MicrosoftId` and `MicrosoftSecret` from the OAuth connection + string. `FacebookId` and `FacebookSecret` are no longer used. See [Configuration](/docs/self-hosting/configuration/). +- **Environments migration.** A migration adds the `environment` field to existing event indexes. Let it finish before + the new API and job instances process events. +- **AI features.** Exie needs an `Assistant` endpoint, model, and API key, and the MCP server uses the built-in OAuth + server. See [AI features](/docs/self-hosting/ai/). + +To upgrade, follow [Upgrading a self-hosted instance](/docs/self-hosting/upgrading-self-hosted-instance/). + +## Where things moved {#where-things-moved} + +| In the classic app | In 9.0 | +| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| Most frequent and new dashboards | **Stacks**, with a saved view for each kind of event | +| Dashboard and recent (timeline) pages | **Events** | +| Sessions dashboard | **Sessions** | +| Project and date pickers at the top of the app | Filters on each page, saved with the view | +| Download & Configure Client | **Client Setup**, in the project's actions menu under **Settings** > **Projects** | +| Project settings tabs | Project pages: **General**, **API Keys**, **Settings**, **Configuration**, **Integrations**, **Stack Management**, and **Usage** | +| My Account | **Account**, **Notifications**, and **AI Tools** in your user menu | +| Organization billing tab | **Billing** in your user menu | + +## Ask Exie + +```prompt exie +What are my top errors this week? +``` + +```prompt exie +Which stacks regressed in the last 7 days? +``` + +With the [MCP server](/docs/ai/mcp-server/) connected, your coding agent can do the same: + +```prompt agent +Find the most frequent open error in my Exceptionless project, fix it in this codebase, and mark the stack fixed. +``` diff --git a/docs/index.vto b/docs/index.vto index 851e0c48f6..1877fda81f 100644 --- a/docs/index.vto +++ b/docs/index.vto @@ -71,81 +71,7 @@ description: Open source error monitoring for .NET, JavaScript, and React Native
-
-
- - - - - -
-
-
// dotnet add package Exceptionless.AspNetCore
-var builder = WebApplication.CreateBuilder(args);
-builder.AddExceptionless();
-
-var app = builder.Build();
-app.UseExceptionHandler();
-app.UseExceptionless();
-
-app.Run();
-

{{ icons["circle-check"] }} Reads your API key from the Exceptionless section of appsettings.json.

-
- - - - -
+ {{ homeClientTabs() }} @@ -389,7 +315,7 @@ for guest checkouts. I'll add a guard and a regression test.
Which languages and frameworks does Exceptionless support? {{ icons["chevron-down"] }} -
Exceptionless has clients for .NET (ASP.NET Core, console and worker services, WPF, and Windows Forms, plus NLog, log4net, and Serilog integrations), JavaScript in the browser and Node.js (including React, Vue, Angular, and Express), and React Native with Expo. Anything that can make an HTTP request can send events through the REST API.
+
{{ clientsSentence() }} Anything that can make an HTTP request can send events through the REST API.
How does Exceptionless use AI? {{ icons["chevron-down"] }} diff --git a/docs/public/assets/css/site.css b/docs/public/assets/css/site.css index 340ad138d3..1bd192252c 100644 --- a/docs/public/assets/css/site.css +++ b/docs/public/assets/css/site.css @@ -39,6 +39,8 @@ --link: #3c7d18; --accent-blue: #2f7fd1; --danger: #d23b3b; + --accent-violet: #7f56d9; + --accent-amber: #a86a00; --code-bg: #f6f8fa; --code-border: #e3e7ed; @@ -79,6 +81,8 @@ --link: #8fd65a; --accent-blue: #7cc4ff; --danger: #ff6b6b; + --accent-violet: #b9a2ff; + --accent-amber: #f0b44c; --code-bg: #0b1118; --code-border: #1d2631; @@ -2641,6 +2645,291 @@ pre:hover > .copy-code, } } +/* ---------- Docs components: callouts, prompts, tabs, badges ---------- */ + +.prose .callout { + --callout-color: var(--accent-blue); + margin: 0 0 1.25em; + padding: 14px 18px 14px 16px; + border: 1px solid color-mix(in srgb, var(--callout-color) 28%, var(--border)); + border-left: 4px solid var(--callout-color); + border-radius: var(--radius); + background: color-mix(in srgb, var(--callout-color) 7%, var(--surface)); + color: var(--text); +} + +.prose .callout > :last-child { + margin-bottom: 0; +} + +.prose .callout p { + margin-top: 0; +} + +.prose .callout-tip { + --callout-color: var(--primary-strong); +} + +.prose .callout-important { + --callout-color: var(--accent-violet); +} + +.prose .callout-warning { + --callout-color: var(--accent-amber); +} + +.prose .callout-caution { + --callout-color: var(--danger); +} + +.prose .callout-title { + display: flex; + align-items: center; + gap: 8px; + margin: 0 0 6px; + color: var(--callout-color); + font-size: 14px; + font-weight: 700; + letter-spacing: 0.01em; +} + +.prose .callout-tip .callout-title { + color: var(--link); +} + +.prose .callout-title .icon { + width: 18px; + height: 18px; + flex: none; +} + +.prose .prompt { + margin: 0 0 1.5em; + overflow: hidden; + border: 1px solid var(--border-strong); + border-radius: var(--radius); + background: var(--bg-subtle); +} + +.prose .prompt-exie { + border-color: var(--primary-ring); + background: color-mix(in srgb, var(--primary) 6%, var(--surface)); +} + +.prompt-header { + display: flex; + align-items: center; + justify-content: space-between; + gap: 12px; + padding: 8px 8px 8px 16px; + border-bottom: 1px solid var(--border); +} + +.prose .prompt-exie .prompt-header { + border-bottom-color: var(--primary-ring); +} + +.prompt-title { + display: inline-flex; + align-items: center; + gap: 8px; + font-size: 13.5px; + font-weight: 700; +} + +.prompt-exie .prompt-title { + color: var(--link); +} + +.prompt-title .icon { + width: 18px; + height: 18px; + flex: none; +} + +.prompt-copy { + display: inline-flex; + align-items: center; + gap: 6px; + height: 30px; + padding: 0 11px; + border: 1px solid var(--border-strong); + border-radius: 7px; + background: var(--surface); + color: var(--text-muted); + font: inherit; + font-size: 12.5px; + font-weight: 600; + cursor: pointer; +} + +.prompt-copy:hover { + color: var(--text); +} + +.prompt-copy .icon { + width: 14px; + height: 14px; +} + +.prompt-text { + padding: 14px 16px; + font-size: 15.5px; + line-height: 1.65; + white-space: pre-wrap; +} + +:root:not(.js) .prompt-copy { + display: none; +} + +.prose .code-window { + margin: 0 0 1.5em; + box-shadow: none; +} + +.prose .code-window pre { + margin: 0; + border: 0; + border-radius: 0; + background: transparent; +} + +.prose .code-window pre + pre { + border-top: 1px solid var(--code-border); +} + +.prose .code-window .code-caption { + margin: 0; + padding: 0 20px 14px; +} + +.tab-label { + margin: 0; + padding: 10px 20px 0; + color: var(--text-muted); + font-size: 12.5px; + font-weight: 700; + letter-spacing: 0.04em; + text-transform: uppercase; +} + +.js .doc-tabs .tab-label { + display: none; +} + +:root:not(.js) .doc-tabs .tab-list { + display: none; +} + +:root:not(.js) .doc-tabs [role="tabpanel"][hidden] { + display: block; +} + +:root:not(.js) .doc-tabs [role="tabpanel"] + [role="tabpanel"] { + border-top: 1px solid var(--code-border); +} + +.prose .docs-plan-row { + margin: -12px 0 1.25em; +} + +.docs-plan { + display: inline-flex; + align-items: center; + padding: 3px 12px; + border: 1px solid var(--primary-ring); + border-radius: 999px; + background: var(--primary-soft); + color: var(--link); + font-size: 12.5px; + font-weight: 650; + text-decoration: none; +} + +.prose a.docs-plan:hover { + text-decoration: none; + filter: brightness(0.97); +} + +.prose .feature-matrix td small, +.prose .feature-matrix th small { + display: block; + margin-top: 4px; + color: var(--text-muted); + font-size: 12.5px; + font-weight: 400; + line-height: 1.45; +} + +.feature-status { + font-weight: 650; +} + +.feature-yes { + color: var(--link); +} + +.feature-opt-in, +.feature-partial { + color: var(--accent-amber); +} + +.feature-no, +.feature-na { + color: var(--text-muted); +} + +.docs-pager { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 16px; + max-width: 780px; + margin-top: 56px; + padding-top: 24px; + border-top: 1px solid var(--border); +} + +.docs-pager a { + display: flex; + flex-direction: column; + gap: 2px; + padding: 14px 18px; + border: 1px solid var(--border); + border-radius: var(--radius); + color: var(--text); +} + +.docs-pager a:hover { + border-color: var(--primary); + text-decoration: none; +} + +.docs-pager-next { + grid-column: 2; + text-align: right; +} + +.docs-pager-label { + color: var(--text-muted); + font-size: 12.5px; +} + +.docs-pager-title { + color: var(--link); + font-weight: 650; +} + +@media (max-width: 600px) { + .docs-pager { + grid-template-columns: 1fr; + } + + .docs-pager-next { + grid-column: auto; + } +} + /* ---------- Syntax highlighting (highlight.js classes) ---------- */ .hljs-comment, @@ -2814,12 +3103,64 @@ pre:hover > .copy-code, text-decoration: none; } -.toc-list li.toc-active > a { +.toc-list a[aria-current="page"] { background: var(--primary-soft); box-shadow: inset 2px 0 0 var(--primary); color: var(--link); } +.toc-list .toc-section > ul { + margin: 0; + padding: 0; + border-left: 0; +} + +.toc-group > details > summary { + display: flex; + align-items: center; + cursor: pointer; + list-style: none; +} + +.toc-group > details > summary::-webkit-details-marker { + display: none; +} + +.toc-group > details > summary::after { + content: ""; + flex: none; + width: 6px; + height: 6px; + margin: 0 12px 0 4px; + border-right: 1.5px solid var(--text-subtle); + border-bottom: 1.5px solid var(--text-subtle); + transform: rotate(-45deg); + transition: transform 0.15s; +} + +.toc-group > details[open] > summary::after { + transform: rotate(45deg); +} + +.toc-group > details > summary > a, +.toc-group > details > summary > span { + flex: 1; + padding: 6px 10px; + border-radius: 7px; + color: var(--text-muted); + font-size: 14.5px; + font-weight: 500; + line-height: 1.4; +} + +.toc-group > details > summary > a { + display: block; +} + +.toc-group > details > summary:hover > span { + color: var(--text); +} + .docs-main { min-width: 0; padding: 40px 0 96px; diff --git a/docs/public/assets/img/logo-dark.svg b/docs/public/assets/img/logo-dark.svg index e29b7f1fe0..d44beb6193 100644 --- a/docs/public/assets/img/logo-dark.svg +++ b/docs/public/assets/img/logo-dark.svg @@ -1,20 +1,20 @@ - - - - - - - \ No newline at end of file + + + + + + + diff --git a/docs/public/assets/img/logo.svg b/docs/public/assets/img/logo.svg index a986d516b0..4ed57fead5 100644 --- a/docs/public/assets/img/logo.svg +++ b/docs/public/assets/img/logo.svg @@ -1,20 +1,20 @@ - - - - - - - \ No newline at end of file + + + + + + + diff --git a/docs/public/assets/js/site.js b/docs/public/assets/js/site.js index d7a7a8a519..309fce8e47 100644 --- a/docs/public/assets/js/site.js +++ b/docs/public/assets/js/site.js @@ -113,7 +113,11 @@ function initializeDocsNav() { }) } +const tabStorageKey = "docs-tab" + function initializeTabs() { + const syncedSets = [] + document.querySelectorAll("[data-tabs]").forEach((container) => { const tabs = Array.from(container.querySelectorAll('[role="tab"]')) const panels = tabs.map((tab) => document.getElementById(tab.getAttribute("aria-controls") ?? "")) @@ -133,19 +137,64 @@ function initializeTabs() { } } + const choose = (index, focus = false) => { + select(index, focus) + const label = tabs[index].dataset.tabLabel + if (label && container.hasAttribute("data-tab-sync")) { + syncTabs(syncedSets, label, container) + try { + localStorage.setItem(tabStorageKey, label) + } catch { + // The choice still applies to this page view when storage is unavailable. + } + } + } + tabs.forEach((tab, index) => { - tab.addEventListener("click", () => select(index)) + tab.addEventListener("click", () => choose(index)) tab.addEventListener("keydown", (event) => { if (event.key === "ArrowRight") { event.preventDefault() - select((index + 1) % tabs.length, true) + choose((index + 1) % tabs.length, true) } else if (event.key === "ArrowLeft") { event.preventDefault() - select((index - 1 + tabs.length) % tabs.length, true) + choose((index - 1 + tabs.length) % tabs.length, true) + } else if (event.key === "Home" || event.key === "End") { + event.preventDefault() + choose(event.key === "Home" ? 0 : tabs.length - 1, true) } }) }) + + if (container.hasAttribute("data-tab-sync")) { + syncedSets.push({ container, tabs, select }) + } }) + + let stored = null + try { + stored = localStorage.getItem(tabStorageKey) + } catch { + stored = null + } + + if (stored) { + syncTabs(syncedSets, stored) + } +} + +/** Selects the tab with `label` in every synced tab set that has one, except the set the reader used. */ +function syncTabs(sets, label, source) { + for (const set of sets) { + if (set.container === source) { + continue + } + + const index = set.tabs.findIndex((tab) => tab.dataset.tabLabel === label) + if (index !== -1) { + set.select(index) + } + } } function initializeHeadingAnchors() { @@ -159,6 +208,21 @@ function initializeHeadingAnchors() { }) } +/** Copies text and shows the result on the button label for a moment. Falls back to a hint when copying is blocked. */ +async function copyWithFeedback(text, label) { + label.dataset.defaultLabel ??= label.textContent + try { + await navigator.clipboard.writeText(text) + label.textContent = "Copied" + } catch { + label.textContent = "Press Ctrl+C" + } + + setTimeout(() => { + label.textContent = label.dataset.defaultLabel + }, 1800) +} + function initializeCopyButtons() { const blocks = document.querySelectorAll(".prose pre, .code-window [role='tabpanel'] pre, .inline-code-block pre") blocks.forEach((pre) => { @@ -166,21 +230,22 @@ function initializeCopyButtons() { button.type = "button" button.className = "copy-code" button.textContent = "Copy" - button.addEventListener("click", async () => { + button.addEventListener("click", () => { const code = pre.querySelector("code") ?? pre - try { - await navigator.clipboard.writeText(code.innerText.trimEnd()) - button.textContent = "Copied" - } catch { - button.textContent = "Press Ctrl+C" - } - - setTimeout(() => { - button.textContent = "Copy" - }, 1800) + void copyWithFeedback(code.innerText.trimEnd(), button) }) pre.append(button) }) + + document.querySelectorAll("[data-copy-target]").forEach((button) => { + const label = button.querySelector("[data-copy-label]") ?? button + button.addEventListener("click", () => { + const target = document.getElementById(button.dataset.copyTarget) + if (target) { + void copyWithFeedback(target.innerText.trim(), label) + } + }) + }) } function initializeCopyMarkdown() { diff --git a/docs/public/favicon.svg b/docs/public/favicon.svg index b780320896..c0aa919c74 100644 --- a/docs/public/favicon.svg +++ b/docs/public/favicon.svg @@ -1 +1,26 @@ - \ No newline at end of file + + + + + + + + + + + + + + + + + + diff --git a/docs/scripts/clients.ts b/docs/scripts/clients.ts new file mode 100644 index 0000000000..326235cadb --- /dev/null +++ b/docs/scripts/clients.ts @@ -0,0 +1,249 @@ +import { escapeHtml, type Icons, renderCodeBlock, renderTabSet, type Tab } from "./docs-components.ts" + +/** The client data in `_data/clients.json` and `_data/client_features.json`. */ + +export type ClientSnippet = { + label: string + package: string + install: string + language: string + code: string + caption: string + docsUrl: string +} + +export type ClientPackage = { + name: string + registry: string + url: string + description: string + minimumRuntime: string +} + +export type FeatureStatus = "yes" | "opt-in" | "partial" | "no" | "n/a" + +export type ClientFeature = { status: FeatureStatus; note?: string } + +export type Client = { + id: string + language: string + name: string + support: "Official" | "Community" | "Preview" + repo: string + docsUrl: string + version: string + minimumRuntime: string + summary: string + packages: ClientPackage[] + snippets: ClientSnippet[] + features: Record +} + +export type FeatureDefinition = { id: string; label: string; description: string } + +export const featureStatusLabels: Record = { + "yes": "Yes", + "opt-in": "Opt-in", + "partial": "Partial", + "no": "No", + "n/a": "Not applicable", +} + +/** Checks the shape of the client data so a typo fails the build instead of rendering a broken page. */ +export function validateClients(clients: Client[], features: FeatureDefinition[]): void { + const ids = new Set() + for (const client of clients) { + if (ids.has(client.id)) { + throw new Error(`clients.json: duplicate client id "${client.id}".`) + } + ids.add(client.id) + + for (const key of ["language", "name", "support", "repo", "docsUrl", "version", "minimumRuntime"] as const) { + if (!client[key]) { + throw new Error(`clients.json: client "${client.id}" is missing "${key}".`) + } + } + + if (!["Official", "Community", "Preview"].includes(client.support)) { + throw new Error(`clients.json: client "${client.id}" has unknown support level "${client.support}".`) + } + + for (const snippet of client.snippets) { + for (const key of ["label", "package", "install", "language", "code", "caption", "docsUrl"] as const) { + if (!snippet[key]) { + throw new Error(`clients.json: a "${client.id}" snippet is missing "${key}".`) + } + } + } + + for (const feature of features) { + const value = client.features[feature.id] + if (!value || !Object.hasOwn(featureStatusLabels, value.status)) { + throw new Error(`clients.json: client "${client.id}" needs a valid status for feature "${feature.id}".`) + } + } + + for (const key of Object.keys(client.features)) { + if (!features.some((feature) => feature.id === key)) { + throw new Error(`clients.json: client "${client.id}" has an unknown feature "${key}".`) + } + } + } +} + +type SnippetEntry = { client: Client; snippet: ClientSnippet } + +function allSnippets(clients: Client[]): SnippetEntry[] { + return clients.flatMap((client) => client.snippets.map((snippet) => ({ client, snippet }))) +} + +/** + * Tabs with each client's install command and a minimal setup snippet, for a `clients` block in a docs page. The + * install command is its own copyable block above the code. + */ +export function renderClientTabs(id: string, clients: Client[], icons: Icons): string { + const tabs: Tab[] = allSnippets(clients).map(({ snippet }) => ({ + label: snippet.label, + html: `
${renderCodeBlock("bash", snippet.install)}${ + renderCodeBlock(snippet.language, snippet.code) + }

${icons["circle-check"] ?? ""}${escapeHtml(snippet.caption)} Read the guide.

`, + })) + + return renderTabSet(id, tabs, "Client setup examples") +} + +/** + * The marketing home page's setup tabs. The look matches the docs tabs, but the install command is a comment on the + * first line of the snippet, as on the original page. + */ +export function renderHomeClientTabs(clients: Client[], icons: Icons, ariaLabel = "Client setup examples"): string { + const entries = allSnippets(clients) + const buttons = entries.map(({ snippet }, index) => { + const selected = index === 0 + return `` + }).join("\n ") + + const panels = entries.map(({ snippet }, index) => { + const code = `${installComment(snippet.install, snippet.language)}\n${snippet.code}` + return `
\n${renderCodeBlock(snippet.language, code)}\n

${icons["circle-check"] ?? ""} ${ + escapeHtml(snippet.caption) + }

\n
` + }).join("\n") + + return `
+
+ ${buttons} +
+${panels} +
` +} + +function tabId(snippet: ClientSnippet): string { + return `tab-${slug(snippet.label)}` +} + +function panelId(snippet: ClientSnippet): string { + return `panel-${slug(snippet.label)}` +} + +function slug(value: string): string { + return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") +} + +/** Wraps a long install command in a comment, breaking at spaces with a trailing backslash like a shell would. */ +export function installComment(install: string, language: string, maxLength = 62): string { + const prefix = ["python", "ruby", "bash", "sh", "yaml"].includes(language) ? "#" : "//" + const words = install.split(/\s+/) + const lines: string[] = [] + let line = "" + for (const word of words) { + if (line && `${line} ${word}`.length > maxLength) { + lines.push(`${line} \\`) + line = word + } else { + line = line ? `${line} ${word}` : word + } + } + lines.push(line) + + return lines.map((text, index) => `${prefix} ${index ? " " : ""}${text}`).join("\n") +} + +/** The feature matrix as an HTML table. */ +export function renderFeatureMatrix(clients: Client[], features: FeatureDefinition[]): string { + const head = clients.map((client) => + `${escapeHtml(client.language)}
${ + escapeHtml(client.name) + } ${escapeHtml(client.version)}` + ).join("") + + const rows = features.map((feature) => { + const cells = clients.map((client) => { + const value = client.features[feature.id] + const note = value.note ? `${escapeHtml(value.note)}` : "" + return `${ + featureStatusLabels[value.status] + }${note}` + }).join("") + return `${escapeHtml(feature.label)}${cells}` + }).join("") + + return `${head}${rows}
Feature
\n` +} + +/** Markdown for a `clients` block, used by the page's `.md` copy and llms-full.txt. */ +export function clientTabsMarkdown(clients: Client[]): string { + return allSnippets(clients).map(({ client, snippet }) => + [ + `**${snippet.label}** (${ + snippet.label === client.language ? "" : `${client.language}, ` + }package \`${snippet.package}\`)`, + "```bash\n" + snippet.install + "\n```", + "```" + snippet.language + "\n" + snippet.code + "\n```", + snippet.caption, + ].join("\n\n") + ).join("\n\n") +} + +/** Markdown for a `clients features` block. */ +export function featureMatrixMarkdown(clients: Client[], features: FeatureDefinition[]): string { + const header = `| Feature | ${clients.map((client) => `${client.language} ${client.version}`).join(" | ")} |` + const divider = `| --- | ${clients.map(() => "---").join(" | ")} |` + const rows = features.map((feature) => { + const cells = clients.map((client) => { + const value = client.features[feature.id] + const note = value.note ? ` (${value.note.replace(/\.$/, "")})` : "" + return `${featureStatusLabels[value.status]}${note}`.replaceAll("|", "\\|") + }) + return `| ${feature.label} | ${cells.join(" | ")} |` + }) + + return [header, divider, ...rows].join("\n") +} + +/** + * Replaces `clients` and `clients features` fences in page Markdown with real Markdown. Everything else, including + * prompts, tabs, and alerts, stays as written. + */ +export function expandClientBlocks(markdown: string, clients: Client[], features: FeatureDefinition[]): string { + return markdown.replace( + /^(?`{3,}|~{3,})[ \t]*clients(?[ \t]+features)?[ \t]*\r?\n(?:(?!\k)[^\n]*\n)*\k[`~]*[ \t]*\r?$/gm, + (_match, _fence, featureGroup) => + featureGroup ? featureMatrixMarkdown(clients, features) : clientTabsMarkdown(clients), + ) +} + +/** A sentence for marketing pages that names every client and what it covers, linking each to its docs. */ +export function clientsSentence(clients: Client[]): string { + const parts = clients.map((client) => + `${escapeHtml(client.language)} (${escapeHtml(client.summary)})` + ) + const list = parts.length > 2 ? `${parts.slice(0, -1).join(", ")}, and ${parts.at(-1)}` : parts.join(" and ") + return `Exceptionless has clients for ${list}.` +} diff --git a/docs/scripts/docs-components.ts b/docs/scripts/docs-components.ts new file mode 100644 index 0000000000..9bcb6d68a3 --- /dev/null +++ b/docs/scripts/docs-components.ts @@ -0,0 +1,101 @@ +/** HTML for the docs components that Markdown pages and `_data/clients.json` render: tab sets, prompts, and callouts. */ + +export type Icons = Record + +export type Tab = { + label: string + /** Rendered panel content. */ + html: string +} + +export function escapeHtml(value: string): string { + return value + .replaceAll("&", "&") + .replaceAll("<", "<") + .replaceAll(">", ">") + .replaceAll('"', """) +} + +/** Opens a tab set: the container and its tablist. The caller adds the panels and closes the container. */ +export function renderTabSetOpen(id: string, labels: string[], ariaLabel = "Code examples"): string { + const buttons = labels.map((label, index) => { + const selected = index === 0 + return `` + }).join("") + + return `
${buttons}
` +} + +/** One tab panel. Every panel keeps a visible label for readers without JavaScript. */ +export function renderTabPanel(id: string, index: number, label: string, html: string): string { + return `

${escapeHtml(label)}

${html}
` +} + +/** + * An accessible tab set. The first tab is selected in the HTML, and every panel keeps a visible label that is shown when + * JavaScript is off, so no content is hidden from readers without scripts. site.js turns it into a tablist and keeps + * tab sets with the same label in sync. + */ +export function renderTabSet(id: string, tabs: Tab[], ariaLabel = "Code examples"): string { + const panels = tabs.map((tab, index) => renderTabPanel(id, index, tab.label, tab.html)).join("") + return `${renderTabSetOpen(id, tabs.map((tab) => tab.label), ariaLabel)}${panels}
\n` +} + +/** A code block that Lume's highlight.js pass picks up through its `language-` class. */ +export function renderCodeBlock(language: string, code: string): string { + const className = language ? ` class="language-${escapeHtml(language)}"` : "" + return `
${escapeHtml(code.replace(/\n$/, ""))}\n
` +} + +export type PromptKind = "exie" | "agent" + +const promptKinds: Record = { + exie: { title: "Ask Exie", icon: "exie" }, + agent: { title: "Paste into your coding agent", icon: "terminal" }, +} + +export function isPromptKind(value: string): value is PromptKind { + return Object.hasOwn(promptKinds, value) +} + +export function promptKindList(): string { + return Object.keys(promptKinds).join(", ") +} + +/** A copyable prompt card. The copy button works through site.js and is hidden without JavaScript. */ +export function renderPrompt(id: string, kind: PromptKind, text: string, icons: Icons): string { + const { title, icon } = promptKinds[kind] + return `
${ + icons[icon] ?? "" + }${title}
${ + escapeHtml(text.trim()) + }
\n` +} + +export type CalloutKind = "note" | "tip" | "important" | "warning" | "caution" + +export const calloutKinds: Record = { + note: { label: "Note", icon: "info" }, + tip: { label: "Tip", icon: "lightbulb" }, + important: { label: "Important", icon: "circle-alert" }, + warning: { label: "Warning", icon: "triangle-alert" }, + caution: { label: "Caution", icon: "octagon-alert" }, +} + +export function renderCalloutTitle(kind: CalloutKind, icons: Icons): string { + const { label, icon } = calloutKinds[kind] + return `

${icons[icon] ?? ""}${label}

\n` +} + +/** The "Medium plan and up" badge, linked to the pricing page. */ +export function renderPlanBadge(plan: string): string { + return `

${escapeHtml(plan)} plan and up

\n` +} diff --git a/docs/scripts/docs-markdown.test.ts b/docs/scripts/docs-markdown.test.ts new file mode 100644 index 0000000000..ea30ddb63d --- /dev/null +++ b/docs/scripts/docs-markdown.test.ts @@ -0,0 +1,295 @@ +import { assert, assertEquals, assertStringIncludes, assertThrows } from "./test-helpers.ts" +import { markdownIt, markdownItAttrs, markdownItDeflist } from "lume/deps/markdown_it.ts" +import { + type Client, + clientsSentence, + expandClientBlocks, + type FeatureDefinition, + installComment, + validateClients, +} from "./clients.ts" +import { docsMarkdown, parseFenceInfo } from "./docs-markdown.ts" + +const icons = { + exie: "exie", + terminal: "terminal", + copy: "copy", + info: "info", +} + +const features: FeatureDefinition[] = [ + { id: "logs", label: "Log messages", description: "Sends logs." }, + { id: "sessions", label: "Sessions", description: "Sends sessions." }, +] + +const clients: Client[] = [ + { + id: "dotnet", + language: ".NET", + name: "Exceptionless.Net", + support: "Official", + repo: "https://example.com/net", + docsUrl: "/docs/clients/dotnet/", + version: "6.2.0", + minimumRuntime: ".NET 8", + summary: "ASP.NET Core and console apps", + packages: [], + snippets: [{ + label: ".NET", + package: "Exceptionless", + install: "dotnet add package Exceptionless", + language: "csharp", + code: 'ExceptionlessClient.Default.Startup("YOUR_API_KEY");', + caption: "Works in console apps.", + docsUrl: "/docs/clients/dotnet/console/", + }], + features: { logs: { status: "yes" }, sessions: { status: "opt-in", note: "Call UseSessions() | now" } }, + }, + { + id: "javascript", + language: "JavaScript", + name: "Exceptionless.JavaScript", + support: "Official", + repo: "https://example.com/js", + docsUrl: "/docs/clients/javascript/", + version: "3.2.1", + minimumRuntime: "ES2022", + summary: "browser and Node.js", + packages: [], + snippets: [{ + label: "Browser", + package: "@exceptionless/browser", + install: "npm install @exceptionless/browser", + language: "js", + code: 'await Exceptionless.startup("YOUR_API_KEY");', + caption: "Source maps are supported.", + docsUrl: "/docs/clients/javascript/guides/browser/", + }], + features: { logs: { status: "yes" }, sessions: { status: "n/a" } }, + }, +] + +function render(source: string, env: Record = {}): string { + const md = markdownIt({ html: true }).use(markdownItAttrs).use(markdownItDeflist) + docsMarkdown(md, { icons, clients, features, plans: ["Free", "Medium"] }) + return md.render(source, env) +} + +Deno.test("headings: explicit ids are applied and the suffix is stripped", () => { + const html = render("## Client configuration {#client-configuration}\n\n## Plain heading") + assertStringIncludes(html, '

Client configuration

') + assertStringIncludes(html, '

Plain heading

') + assert(!html.includes("{#")) +}) + +Deno.test("headings: automatic ids are unique and never reuse an explicit id", () => { + const html = render("## Setup {#setup}\n\n## Setup\n\n## Setup\n\n## Docs v1.2") + assertStringIncludes(html, '

Setup

') + assertStringIncludes(html, '

Setup

') + assertStringIncludes(html, '

Setup

') + assertStringIncludes(html, 'id="docs-v12"') +}) + +Deno.test("alerts: each kind renders a labeled callout with an icon", () => { + for ( + const [marker, kind, label] of [["NOTE", "note", "Note"], ["TIP", "tip", "Tip"], [ + "IMPORTANT", + "important", + "Important", + ], ["WARNING", "warning", "Warning"]] + ) { + const html = render(`> [!${marker}]\n> Be careful with **bold** text.`) + assertStringIncludes(html, `
`) + assertStringIncludes(html, `

`) + assertStringIncludes(html, `${label}`) + assertStringIncludes(html, "bold") + assert(!html.includes("[!"), html) + assert(!html.includes(" { + const html = render("> [!TIP]\n>\n> First paragraph.\n>\n> Second paragraph.") + assertStringIncludes(html, "callout-tip") + assertStringIncludes(html, "

First paragraph.

") + assertStringIncludes(html, "

Second paragraph.

") + assert(!html.includes("

")) + assertEquals(html.match(/<\/div>/g)?.length, 1) +}) + +Deno.test("alerts: ordinary blockquotes are unchanged", () => { + const html = render("> Just a quote\n> [!NOTE] not at the start of a line") + assertStringIncludes(html, "
") + assert(!html.includes("callout")) +}) + +Deno.test("prompts: exie and agent prompts render cards with a copy button", () => { + const exie = render("```prompt exie\nWhich stacks appeared since the deploy?\n```") + assertStringIncludes(exie, 'class="prompt prompt-exie"') + assertStringIncludes(exie, "Ask Exie") + assertStringIncludes(exie, "exie") + assertStringIncludes(exie, 'data-copy-target="prompt-1-text"') + assertStringIncludes(exie, 'id="prompt-1-text">Which <new> stacks appeared since the deploy?
') + assertStringIncludes(exie, 'aria-label="Copy prompt"') + + const agent = render("```prompt agent\nFix my top error.\n```\n\n```prompt exie\nSecond.\n```") + assertStringIncludes(agent, "Paste into your coding agent") + assertStringIncludes(agent, "terminal") + assertStringIncludes(agent, 'id="prompt-2-text"') +}) + +Deno.test("prompts: an unknown kind fails the build", () => { + assertThrows(() => render("```prompt robot\nHi\n```"), Error, "Prompt blocks need a kind") + assertThrows(() => render("```prompt\nHi\n```"), Error, "Prompt blocks need a kind") +}) + +Deno.test("tabs: adjacent labeled fences group into one accessible tab set", () => { + const html = render( + '```csharp tab=".NET"\nvar a = 1;\n```\n\n```ts tab="JavaScript"\nconst a = 1\n```\n\n```bash tab="curl"\ncurl x\n```', + ) + assertEquals(html.match(/data-tab-sync/g)?.length, 1) + assertEquals(html.match(/role="tab"/g)?.length, 3) + assertEquals(html.match(/role="tabpanel"/g)?.length, 3) + assertStringIncludes(html, 'role="tablist"') + assertStringIncludes(html, 'id="tabs-1-tab-0" aria-controls="tabs-1-panel-0" aria-selected="true"') + assertStringIncludes(html, 'id="tabs-1-tab-1" aria-controls="tabs-1-panel-1" aria-selected="false" tabindex="-1"') + assertStringIncludes(html, 'data-tab-label="JavaScript"') + // Panels keep their language class for highlighting and a visible label for readers without JavaScript. + assertStringIncludes(html, 'var a = 1;') + assertStringIncludes(html, 'const a = 1') + assertStringIncludes(html, '

curl

') + assertEquals(html.match(/ hidden>/g)?.length, 2) + assert(!html.includes("tab=""), html) +}) + +Deno.test("tabs: separate groups stay separate and unlabeled fences break a group", () => { + const html = render( + '```csharp tab="A"\n1\n```\n\n```js tab="B"\n2\n```\n\ntext\n\n```csharp tab="A"\n3\n```\n\n```js tab="B"\n4\n```\n\n```js\nplain\n```', + ) + assertEquals(html.match(/data-tab-sync/g)?.length, 2) + assertStringIncludes(html, 'id="tabs-2-tab-0"') + assertStringIncludes(html, '
plain')
+})
+
+Deno.test("tabs: one labeled fence is a plain code block, duplicate labels fail", () => {
+  const single = render('```csharp tab=".NET"\nvar a = 1;\n```')
+  assert(!single.includes("data-tabs"))
+  assertStringIncludes(single, '')
+  assertThrows(
+    () => render('```js tab="A"\n1\n```\n\n```ts tab="A"\n2\n```'),
+    Error,
+    'share the tab label "A"',
+  )
+})
+
+Deno.test("fence info: language, words, and attributes", () => {
+  assertEquals(parseFenceInfo('csharp tab=".NET Core"'), {
+    language: "csharp",
+    words: [],
+    attributes: { tab: ".NET Core" },
+  })
+  assertEquals(parseFenceInfo("prompt exie"), { language: "prompt", words: ["exie"], attributes: {} })
+  assertEquals(parseFenceInfo('tab="X"'), { language: "", words: [], attributes: { tab: "X" } })
+})
+
+Deno.test("clients block: renders install commands and snippets for every client", () => {
+  const html = render("```clients\n```")
+  assertEquals(html.match(/role="tab"/g)?.length, 2)
+  assertStringIncludes(html, 'data-tab-label="Browser"')
+  assertStringIncludes(html, 'dotnet add package Exceptionless')
+  assertStringIncludes(
+    html,
+    'ExceptionlessClient.Default.Startup("YOUR_API_KEY");',
+  )
+  assertStringIncludes(html, 'href="/docs/clients/javascript/guides/browser/"')
+})
+
+Deno.test("clients features block: renders the feature matrix", () => {
+  const html = render("```clients features\n```")
+  assertStringIncludes(html, '')
+  assertStringIncludes(html, '')
+  assertStringIncludes(html, "Opt-in")
+  assertStringIncludes(html, "Call UseSessions() | now")
+  assertStringIncludes(html, "Not applicable")
+})
+
+Deno.test("clients block: content or unknown words fail the build", () => {
+  assertThrows(() => render("```clients\nsomething\n```"), Error, "must be empty")
+  assertThrows(() => render("```clients nope\n```"), Error, "Unknown clients block")
+})
+
+Deno.test("markdown copy: clients blocks expand to real Markdown, everything else is untouched", () => {
+  const source = [
+    "# Title",
+    "",
+    "```clients",
+    "```",
+    "",
+    "```clients features",
+    "```",
+    "",
+    "```prompt exie",
+    "Ask something",
+    "```",
+    "",
+    "> [!NOTE]",
+    "> Keep this",
+    "",
+    '```csharp tab=".NET"',
+    "var a = 1;",
+    "```",
+  ].join("\n")
+  const markdown = expandClientBlocks(source, clients, features)
+  assert(!markdown.includes("```clients"), markdown)
+  assertStringIncludes(markdown, "**.NET** (package `Exceptionless`)")
+  assertStringIncludes(markdown, "```bash\ndotnet add package Exceptionless\n```")
+  assertStringIncludes(markdown, '```csharp\nExceptionlessClient.Default.Startup("YOUR_API_KEY");\n```')
+  assertStringIncludes(markdown, "| Feature | .NET 6.2.0 | JavaScript 3.2.1 |")
+  assertStringIncludes(markdown, "| Sessions | Opt-in (Call UseSessions() \\| now) | Not applicable |")
+  assertStringIncludes(markdown, "```prompt exie\nAsk something\n```")
+  assertStringIncludes(markdown, "> [!NOTE]\n> Keep this")
+  assertStringIncludes(markdown, '```csharp tab=".NET"')
+})
+
+Deno.test("plan badge: renders under the title and rejects unknown plans", () => {
+  const html = render("# Exie\n\nText", { filename: "docs/ai/exie.md", data: { plan: "Medium" } })
+  assertStringIncludes(html, 'Medium plan and up')
+  assert(html.indexOf("") < html.indexOf("docs-plan"))
+  assertThrows(
+    () => render("# Exie", { filename: "docs/ai/exie.md", data: { plan: "Gold" } }),
+    Error,
+    'plan "Gold" is not in _data/plans.json',
+  )
+  assert(!render("# Exie").includes("docs-plan"))
+})
+
+Deno.test("client data: validation catches missing features and bad support levels", () => {
+  validateClients(clients, features)
+  const missing = structuredClone(clients)
+  delete missing[0].features.sessions
+  assertThrows(() => validateClients(missing, features), Error, 'valid status for feature "sessions"')
+  const bad = structuredClone(clients)
+  bad[0].support = "Maybe" as Client["support"]
+  assertThrows(() => validateClients(bad, features), Error, "unknown support level")
+})
+
+Deno.test("client data: the real files pass validation", async () => {
+  const realClients = JSON.parse(await Deno.readTextFile("_data/clients.json")) as Client[]
+  const realFeatures = JSON.parse(await Deno.readTextFile("_data/client_features.json")) as FeatureDefinition[]
+  validateClients(realClients, realFeatures)
+})
+
+Deno.test("install comments wrap long commands like a shell would", () => {
+  assertEquals(installComment("dotnet add package Exceptionless", "csharp"), "// dotnet add package Exceptionless")
+  assertEquals(
+    installComment("npx expo install @exceptionless/react-native @react-native-async-storage/async-storage", "js"),
+    "// npx expo install @exceptionless/react-native \\\n//   @react-native-async-storage/async-storage",
+  )
+})
+
+Deno.test("clients sentence names every client and links its docs", () => {
+  assertEquals(
+    clientsSentence(clients),
+    'Exceptionless has clients for .NET (ASP.NET Core and console apps) and JavaScript (browser and Node.js).',
+  )
+})
diff --git a/docs/scripts/docs-markdown.ts b/docs/scripts/docs-markdown.ts
new file mode 100644
index 0000000000..f9b5f7649e
--- /dev/null
+++ b/docs/scripts/docs-markdown.ts
@@ -0,0 +1,305 @@
+import {
+  type CalloutKind,
+  calloutKinds,
+  escapeHtml,
+  type Icons,
+  isPromptKind,
+  promptKindList,
+  renderCalloutTitle,
+  renderPlanBadge,
+  renderPrompt,
+  renderTabPanel,
+  renderTabSetOpen,
+} from "./docs-components.ts"
+import { type Client, type FeatureDefinition, renderClientTabs, renderFeatureMatrix } from "./clients.ts"
+
+// deno-lint-ignore no-explicit-any
+type MarkdownIt = any
+// deno-lint-ignore no-explicit-any
+type Token = any
+// deno-lint-ignore no-explicit-any
+type Env = Record
+type TokenConstructor = new (type: string, tag: string, nesting: number) => Token
+
+export type DocsMarkdownOptions = {
+  icons: Icons
+  clients: Client[]
+  features: FeatureDefinition[]
+  /** Plan names from `_data/plans.json`, for the `plan` frontmatter badge. */
+  plans: string[]
+}
+
+type FenceInfo = {
+  /** The first word when it is a language, such as `csharp`. */
+  language: string
+  /** The words after the language that are not `name=value` attributes. */
+  words: string[]
+  attributes: Record
+}
+
+/**
+ * Adds the docs Markdown features to a markdown-it instance: unique heading ids (explicit `{#id}` suffixes come from
+ * markdown-it-attrs, which Lume enables), GitHub alerts, prompt blocks, tab groups, `clients` blocks, and the plan badge.
+ */
+export function docsMarkdown(md: MarkdownIt, options: DocsMarkdownOptions): void {
+  md.core.ruler.push("docs_heading_ids", headingIds)
+  md.core.ruler.push(
+    "docs_callouts",
+    (state: { tokens: Token[]; Token: TokenConstructor }) => callouts(state, options.icons),
+  )
+  md.core.ruler.push("docs_tabs", tabGroups)
+  md.core.ruler.push(
+    "docs_plan_badge",
+    (state: { tokens: Token[]; env: Env; Token: TokenConstructor }) => planBadge(state, options.plans),
+  )
+
+  const defaultFence = md.renderer.rules.fence
+  md.renderer.rules.fence = (tokens: Token[], index: number, rendererOptions: unknown, env: Env, self: unknown) => {
+    const token = tokens[index]
+    const info = parseFenceInfo(token.info)
+
+    if (info.language === "prompt") {
+      const kind = info.words[0]
+      if (!kind || !isPromptKind(kind)) {
+        throw new Error(
+          `Prompt blocks need a kind (${promptKindList()}), for example \`\`\`prompt exie. Got "${token.info}".`,
+        )
+      }
+      return renderPrompt(nextId(env, "prompt"), kind, token.content, options.icons)
+    }
+
+    if (info.language === "clients") {
+      if (token.content.trim()) {
+        throw new Error("A clients block must be empty. The content comes from _data/clients.json.")
+      }
+      if (info.words[0] === "features") {
+        return renderFeatureMatrix(options.clients, options.features)
+      }
+      if (info.words.length) {
+        throw new Error(`Unknown clients block "${token.info}". Use \`\`\`clients or \`\`\`clients features.`)
+      }
+      return renderClientTabs(nextId(env, "clients"), options.clients, options.icons)
+    }
+
+    if (token.meta?.tabPanel) {
+      const { label, setId, index: tabIndex } = token.meta.tabPanel
+      // The language is the only part highlight.js needs; drop the tab attribute before the default renderer.
+      token.info = info.language
+      const code = defaultFence(tokens, index, rendererOptions, env, self).trimEnd()
+      return renderTabPanel(setId, tabIndex, label, code)
+    }
+
+    return defaultFence(tokens, index, rendererOptions, env, self)
+  }
+
+  // tabs_open renders the container and tablist; each fence in the group renders its own panel.
+  md.renderer.rules.tabs_open = (tokens: Token[], index: number) => {
+    const { setId, labels } = tokens[index].meta
+    return renderTabSetOpen(setId, labels)
+  }
+  md.renderer.rules.tabs_close = () => "\n"
+}
+
+/** Splits a fence info string such as `csharp tab=".NET"` into a language, words, and attributes. */
+export function parseFenceInfo(info: string): FenceInfo {
+  const attributes: Record = {}
+  const rest: string[] = []
+  const pattern = /([A-Za-z][\w-]*)=(?:"([^"]*)"|'([^']*)'|(\S+))|(\S+)/g
+  for (const match of (info ?? "").matchAll(pattern)) {
+    if (match[1]) {
+      attributes[match[1]] = match[2] ?? match[3] ?? match[4]
+    } else {
+      rest.push(match[5])
+    }
+  }
+
+  return { language: rest[0] ?? "", words: rest.slice(1), attributes }
+}
+
+function nextId(env: Env, prefix: string): string {
+  const key = "__docsIds"
+  const counts: Record = env[key] ??= {}
+  counts[prefix] = (counts[prefix] ?? 0) + 1
+  return `${prefix}-${counts[prefix]}`
+}
+
+/** Assigns every heading an id: explicit ids stay, and the rest get a unique slug. */
+function headingIds(state: { tokens: Token[]; env: Env }): void {
+  const used = new Set()
+  const headings = state.tokens.filter((token) => token.type === "heading_open")
+  for (const heading of headings) {
+    const id = heading.attrGet("id")
+    if (id) {
+      used.add(id)
+    }
+  }
+
+  for (const heading of headings) {
+    if (heading.attrGet("id")) {
+      continue
+    }
+
+    const index = state.tokens.indexOf(heading)
+    const base = slugifyHeading(state.tokens[index + 1]?.content ?? "") || "section"
+    let id = base
+    for (let count = 1; used.has(id); count++) {
+      id = `${base}-${count}`
+    }
+
+    used.add(id)
+    heading.attrSet("id", id)
+  }
+}
+
+export function slugifyHeading(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/\./g, "")
+    .replace(/[^a-z0-9_-]/g, "")
+    .replace(/^-+|-+$/g, "")
+}
+
+const calloutPattern = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*(?:\r?\n|$)/i
+
+/** Turns `> [!NOTE]` blockquotes into styled callouts with an icon and a label. */
+function callouts(state: { tokens: Token[]; Token: TokenConstructor }, icons: Icons): void {
+  const tokens = state.tokens
+  for (let index = 0; index < tokens.length; index++) {
+    const open = tokens[index]
+    if (open.type !== "blockquote_open") {
+      continue
+    }
+
+    const paragraph = tokens[index + 1]
+    const inline = tokens[index + 2]
+    const match = paragraph?.type === "paragraph_open" && inline?.type === "inline"
+      ? inline.content.match(calloutPattern)
+      : null
+    if (!match) {
+      continue
+    }
+
+    const kind = match[1].toLowerCase() as CalloutKind
+    if (!Object.hasOwn(calloutKinds, kind)) {
+      continue
+    }
+
+    // Drop the marker line from the paragraph.
+    inline.content = inline.content.slice(match[0].length)
+    const breakIndex = inline.children.findIndex((child: Token) =>
+      child.type === "softbreak" || child.type === "hardbreak"
+    )
+    inline.children = breakIndex === -1 ? [] : inline.children.slice(breakIndex + 1)
+
+    const close = findClose(tokens, index, "blockquote_close")
+    open.tag = "div"
+    open.attrJoin("class", `callout callout-${kind}`)
+    open.attrSet("role", "note")
+    if (close) {
+      close.tag = "div"
+    }
+
+    const title = new state.Token("html_block", "", 0)
+    title.content = renderCalloutTitle(kind, icons)
+    title.block = true
+    title.level = open.level + 1
+
+    if (inline.children.length === 0) {
+      tokens.splice(index + 1, 3, title)
+    } else {
+      tokens.splice(index + 1, 0, title)
+    }
+  }
+}
+
+function findClose(tokens: Token[], openIndex: number, type: string): Token | undefined {
+  const level = tokens[openIndex].level
+  for (let index = openIndex + 1; index < tokens.length; index++) {
+    if (tokens[index].type === type && tokens[index].level === level) {
+      return tokens[index]
+    }
+  }
+}
+
+/** Groups adjacent fenced code blocks that carry `tab="Label"` into one tab set. */
+function tabGroups(state: { tokens: Token[]; env: Env; Token: TokenConstructor }): void {
+  const tokens = state.tokens
+  const result: Token[] = []
+  let index = 0
+
+  while (index < tokens.length) {
+    const token = tokens[index]
+    if (!isTabFence(token)) {
+      result.push(token)
+      index++
+      continue
+    }
+
+    const group: Token[] = []
+    while (index < tokens.length && isTabFence(tokens[index]) && tokens[index].level === token.level) {
+      group.push(tokens[index])
+      index++
+    }
+
+    if (group.length === 1) {
+      // A single labeled block is just a code block.
+      result.push(group[0])
+      continue
+    }
+
+    const labels = group.map((fence) => parseFenceInfo(fence.info).attributes.tab)
+    const duplicate = labels.find((label, position) => labels.indexOf(label) !== position)
+    if (duplicate) {
+      throw new Error(`Two code blocks in one tab group share the tab label "${duplicate}".`)
+    }
+
+    const setId = nextId(state.env, "tabs")
+    const open = new state.Token("tabs_open", "div", 1)
+    open.block = true
+    open.level = token.level
+    open.meta = { setId, labels }
+    const close = new state.Token("tabs_close", "div", -1)
+    close.block = true
+    close.level = token.level
+
+    group.forEach((fence, position) => {
+      fence.meta = { ...fence.meta, tabPanel: { label: labels[position], setId, index: position } }
+    })
+
+    result.push(open, ...group, close)
+  }
+
+  state.tokens = result
+}
+
+function isTabFence(token: Token): boolean {
+  return token.type === "fence" && Boolean(parseFenceInfo(token.info).attributes.tab)
+}
+
+/** Shows a "Medium plan and up" badge under the page title when the page declares a `plan`. */
+function planBadge(
+  state: { tokens: Token[]; env: Env; Token: TokenConstructor },
+  plans: string[],
+): void {
+  const plan = state.env?.data?.plan
+  if (plan === undefined) {
+    return
+  }
+
+  if (typeof plan !== "string" || !plans.includes(plan)) {
+    const file = state.env?.filename ?? "this page"
+    throw new Error(`${file}: plan "${plan}" is not in _data/plans.json (${plans.join(", ")}).`)
+  }
+
+  const heading = state.tokens.findIndex((token) => token.type === "heading_open" && token.tag === "h1")
+  if (heading === -1) {
+    return
+  }
+
+  const badge = new state.Token("html_block", "", 0)
+  badge.content = renderPlanBadge(plan)
+  badge.block = true
+  state.tokens.splice(heading + 3, 0, badge)
+}
diff --git a/docs/scripts/docs-nav.test.ts b/docs/scripts/docs-nav.test.ts
new file mode 100644
index 0000000000..9fb0f9f7e5
--- /dev/null
+++ b/docs/scripts/docs-nav.test.ts
@@ -0,0 +1,97 @@
+import { clientOverviewUrls, crumbsFor, flattenNav, navUrls, pagerFor, parseDocsNav, sectionPages } from "./docs-nav.ts"
+import { assertEquals, assertThrows } from "./test-helpers.ts"
+
+const yaml = `
+- section: Get started
+  items:
+    - /docs/
+    - /docs/getting-started/
+- section: Send data
+  items:
+    - /docs/clients/
+    - group: .NET
+      url: /docs/clients/dotnet/
+      items:
+        - /docs/clients/dotnet/aspnet-core/
+        - group: Guides
+          items:
+            - /docs/clients/dotnet/guides/one/
+    - group: Other languages
+      items:
+        - /docs/clients/custom-clients/
+`
+
+const titles = new Map([
+  ["/docs/", "Overview"],
+  ["/docs/getting-started/", "Quickstart"],
+  ["/docs/clients/", "Choose a client"],
+  ["/docs/clients/dotnet/", ".NET"],
+  ["/docs/clients/dotnet/aspnet-core/", "ASP.NET Core"],
+  ["/docs/clients/custom-clients/", "Other languages"],
+])
+const titleFor = (url: string) => titles.get(url)
+
+Deno.test("nav: pages flatten in reading order, with a group's overview first", () => {
+  const nav = parseDocsNav(yaml)
+  assertEquals(navUrls(nav), [
+    "/docs/",
+    "/docs/getting-started/",
+    "/docs/clients/",
+    "/docs/clients/dotnet/",
+    "/docs/clients/dotnet/aspnet-core/",
+    "/docs/clients/dotnet/guides/one/",
+    "/docs/clients/custom-clients/",
+  ])
+  assertEquals(sectionPages(nav, "Get started"), ["/docs/", "/docs/getting-started/"])
+  assertEquals(flattenNav(nav)[5].groups.map((group) => group.title), [".NET", "Guides"])
+})
+
+Deno.test("nav: previous and next skip entries with no page yet", () => {
+  const nav = parseDocsNav(yaml)
+  assertEquals(pagerFor(nav, "/docs/clients/dotnet/aspnet-core/", titleFor), {
+    previous: { url: "/docs/clients/dotnet/", title: ".NET" },
+    next: { url: "/docs/clients/custom-clients/", title: "Other languages" },
+  })
+  assertEquals(pagerFor(nav, "/docs/", titleFor).previous, undefined)
+  assertEquals(pagerFor(nav, "/docs/missing/", titleFor), {})
+})
+
+Deno.test("nav: breadcrumbs come from the section and the groups", () => {
+  const nav = parseDocsNav(yaml)
+  assertEquals(crumbsFor(nav, "/docs/clients/dotnet/aspnet-core/", titleFor), [
+    { name: "Send data", url: "/docs/clients/" },
+    { name: ".NET", url: "/docs/clients/dotnet/" },
+  ])
+  assertEquals(crumbsFor(nav, "/docs/clients/dotnet/", titleFor), [{ name: "Send data", url: "/docs/clients/" }])
+  assertEquals(crumbsFor(nav, "/docs/", titleFor), [])
+})
+
+Deno.test("nav: client overview pages are the clients index and each language overview", () => {
+  assertEquals(clientOverviewUrls(parseDocsNav(yaml)), ["/docs/clients/", "/docs/clients/dotnet/"])
+})
+
+Deno.test("nav: duplicates, bad URLs, and unknown keys fail", () => {
+  assertThrows(
+    () => parseDocsNav("- section: A\n  items:\n    - /docs/a/\n    - /docs/a/\n"),
+    Error,
+    "listed more than once",
+  )
+  assertThrows(() => parseDocsNav("- section: A\n  items:\n    - /docs/a\n"), Error, "must be a /docs/ URL")
+  assertThrows(() => parseDocsNav("- section: A\n  items:\n    - /other/\n"), Error, "must be a /docs/ URL")
+  assertThrows(() => parseDocsNav("- section: A\n  items: []\n  extra: 1\n"), Error, "unknown keys")
+  assertThrows(() => parseDocsNav("- section: A\n  items:\n    - 5\n"), Error, "neither a URL nor a group")
+})
+
+Deno.test("nav: the real docs_nav.yml has the eight sections in order", async () => {
+  const nav = parseDocsNav(await Deno.readTextFile("_data/docs_nav.yml"))
+  assertEquals(nav.map((section) => section.title), [
+    "Get started",
+    "AI",
+    "Send data",
+    "Use Exceptionless",
+    "How it works",
+    "Reference",
+    "REST API",
+    "Self-hosting",
+  ])
+})
diff --git a/docs/scripts/docs-nav.ts b/docs/scripts/docs-nav.ts
new file mode 100644
index 0000000000..521c636e0c
--- /dev/null
+++ b/docs/scripts/docs-nav.ts
@@ -0,0 +1,197 @@
+import { parse } from "lume/deps/yaml.ts"
+
+/** A docs page in the nav, identified by its URL. */
+export type NavPage = { kind: "page"; url: string }
+
+/** A collapsible sub-group. When `url` is set, the group heading links to that overview page. */
+export type NavGroup = { kind: "group"; title: string; url?: string; items: NavEntry[] }
+
+export type NavEntry = NavPage | NavGroup
+
+export type NavSection = { title: string; items: NavEntry[] }
+
+/** A page in reading order, with the section and groups that contain it. */
+export type NavLocation = { url: string; section: NavSection; groups: NavGroup[] }
+
+/** Parses and validates the text of `_data/docs_nav.yml`. */
+export function parseDocsNav(yamlText: string): NavSection[] {
+  return normalizeDocsNav(parse(yamlText))
+}
+
+/** Validates the parsed nav, which Lume also exposes to templates as `docs_nav`. Throws with a readable message. */
+export function normalizeDocsNav(raw: unknown): NavSection[] {
+  if (!Array.isArray(raw)) {
+    throw new Error("docs_nav.yml must be a list of sections.")
+  }
+
+  const seen = new Set()
+  const sections = raw.map((section, index) => {
+    if (!isRecord(section) || typeof section.section !== "string" || !section.section.trim()) {
+      throw new Error(`docs_nav.yml: entry ${index + 1} must have a "section" name.`)
+    }
+
+    const unknown = Object.keys(section).filter((key) => key !== "section" && key !== "items")
+    if (unknown.length) {
+      throw new Error(`docs_nav.yml: section "${section.section}" has unknown keys: ${unknown.join(", ")}.`)
+    }
+
+    return {
+      title: section.section.trim(),
+      items: parseEntries(section.items, section.section, seen),
+    }
+  })
+
+  const titles = sections.map((section) => section.title)
+  if (new Set(titles).size !== titles.length) {
+    throw new Error("docs_nav.yml: section names must be unique.")
+  }
+
+  return sections
+}
+
+function parseEntries(value: unknown, where: string, seen: Set): NavEntry[] {
+  if (!Array.isArray(value)) {
+    throw new Error(`docs_nav.yml: "${where}" must have an "items" list.`)
+  }
+
+  return value.map((entry): NavEntry => {
+    if (typeof entry === "string") {
+      return { kind: "page", url: claimUrl(entry, where, seen) }
+    }
+
+    if (isRecord(entry) && typeof entry.group === "string") {
+      const unknown = Object.keys(entry).filter((key) => !["group", "url", "items"].includes(key))
+      if (unknown.length) {
+        throw new Error(`docs_nav.yml: group "${entry.group}" has unknown keys: ${unknown.join(", ")}.`)
+      }
+
+      const url = typeof entry.url === "string" ? claimUrl(entry.url, entry.group, seen) : undefined
+      return { kind: "group", title: entry.group, url, items: parseEntries(entry.items, entry.group, seen) }
+    }
+
+    throw new Error(`docs_nav.yml: "${where}" has an item that is neither a URL nor a group.`)
+  })
+}
+
+function claimUrl(url: string, where: string, seen: Set): string {
+  if (!/^\/docs\/(?:[^\s?#]*\/)?$/.test(url)) {
+    throw new Error(`docs_nav.yml: "${url}" in "${where}" must be a /docs/ URL that ends with a slash.`)
+  }
+
+  if (seen.has(url)) {
+    throw new Error(`docs_nav.yml: "${url}" is listed more than once.`)
+  }
+
+  seen.add(url)
+  return url
+}
+
+/** Lists every page in reading order: a group's overview page first, then its items. */
+export function flattenNav(sections: NavSection[]): NavLocation[] {
+  const pages: NavLocation[] = []
+
+  const visit = (entries: NavEntry[], section: NavSection, groups: NavGroup[]) => {
+    for (const entry of entries) {
+      if (entry.kind === "page") {
+        pages.push({ url: entry.url, section, groups })
+        continue
+      }
+
+      const inner = [...groups, entry]
+      if (entry.url) {
+        pages.push({ url: entry.url, section, groups: inner })
+      }
+
+      visit(entry.items, section, inner)
+    }
+  }
+
+  for (const section of sections) {
+    visit(section.items, section, [])
+  }
+
+  return pages
+}
+
+export function navUrls(sections: NavSection[]): string[] {
+  return flattenNav(sections).map((page) => page.url)
+}
+
+/** The pages that make up a section, in reading order. */
+export function sectionPages(sections: NavSection[], title: string): string[] {
+  return flattenNav(sections).filter((page) => page.section.title === title).map((page) => page.url)
+}
+
+/**
+ * The client overview pages: the clients index and the overview page of each language group directly under
+ * "Send data". These are the pages `llms-small.txt` includes next to Get started and AI.
+ */
+export function clientOverviewUrls(sections: NavSection[]): string[] {
+  const section = sections.find((candidate) => candidate.title === "Send data")
+  if (!section) {
+    return []
+  }
+
+  const urls: string[] = []
+  for (const entry of section.items) {
+    if (entry.kind === "page" && entry.url === "/docs/clients/") {
+      urls.push(entry.url)
+    } else if (entry.kind === "group" && entry.url) {
+      urls.push(entry.url)
+    }
+  }
+
+  return urls
+}
+
+export type PagerLink = { url: string; title: string }
+
+/** Finds the previous and next pages around `currentUrl`, skipping nav entries that have no page yet. */
+export function pagerFor(
+  sections: NavSection[],
+  currentUrl: string,
+  titleFor: (url: string) => string | undefined,
+): { previous?: PagerLink; next?: PagerLink } {
+  const pages = flattenNav(sections)
+    .map((page) => ({ url: page.url, title: titleFor(page.url) }))
+    .filter((page): page is PagerLink => Boolean(page.title))
+  const index = pages.findIndex((page) => page.url === currentUrl)
+  if (index === -1) {
+    return {}
+  }
+
+  return { previous: pages[index - 1], next: pages[index + 1] }
+}
+
+export type NavCrumb = { name: string; url: string }
+
+/** Builds the trail between "Docs" and the page: the section, then each group, linking to the first page where one exists. */
+export function crumbsFor(
+  sections: NavSection[],
+  currentUrl: string,
+  titleFor: (url: string) => string | undefined,
+): NavCrumb[] {
+  const pages = flattenNav(sections)
+  const location = pages.find((page) => page.url === currentUrl)
+  if (!location) {
+    return []
+  }
+
+  const crumbs: NavCrumb[] = []
+  const firstPage = pages.find((page) => page.section === location.section && titleFor(page.url))
+  if (firstPage && firstPage.url !== currentUrl) {
+    crumbs.push({ name: location.section.title, url: firstPage.url })
+  }
+
+  for (const group of location.groups) {
+    if (group.url && group.url !== currentUrl && titleFor(group.url)) {
+      crumbs.push({ name: group.title, url: group.url })
+    }
+  }
+
+  return crumbs
+}
+
+function isRecord(value: unknown): value is Record {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
diff --git a/docs/scripts/docs-urls.txt b/docs/scripts/docs-urls.txt
new file mode 100644
index 0000000000..b9607e5746
--- /dev/null
+++ b/docs/scripts/docs-urls.txt
@@ -0,0 +1,127 @@
+# Every docs URL published before the 9.0 rewrite. deno task verify fails if one stops resolving.
+/docs.md
+/docs/
+/docs/ai/
+/docs/ai/exie/
+/docs/ai/mcp-server/
+/docs/api/
+/docs/api/api-getting-started/
+/docs/api/getting-events/
+/docs/api/posting-events/
+/docs/api/project-tokens/
+/docs/bulk-actions/
+/docs/clients/
+/docs/clients/custom-clients/
+/docs/clients/dotnet/
+/docs/clients/dotnet/client-configuration-values/
+/docs/clients/dotnet/configuration/
+/docs/clients/dotnet/guides/
+/docs/clients/dotnet/guides/console-apps-example/
+/docs/clients/dotnet/guides/logging-with-generic-host/
+/docs/clients/dotnet/guides/web-server-example/
+/docs/clients/dotnet/plugins/
+/docs/clients/dotnet/private-information/
+/docs/clients/dotnet/sending-events/
+/docs/clients/dotnet/settings/
+/docs/clients/dotnet/supported-platforms/
+/docs/clients/dotnet/troubleshooting/
+/docs/clients/dotnet/upgrading/
+/docs/clients/javascript/
+/docs/clients/javascript/client-configuration/
+/docs/clients/javascript/client-configuration-values/
+/docs/clients/javascript/express-example/
+/docs/clients/javascript/guides/
+/docs/clients/javascript/guides/angular/
+/docs/clients/javascript/guides/express/
+/docs/clients/javascript/guides/more-guides/
+/docs/clients/javascript/guides/react/
+/docs/clients/javascript/guides/vue/
+/docs/clients/javascript/javascript-example/
+/docs/clients/javascript/node-example/
+/docs/clients/javascript/react-example/
+/docs/clients/javascript/sending-events/
+/docs/clients/javascript/troubleshooting/
+/docs/clients/javascript/vue-example/
+/docs/comparison/
+/docs/deduplication/
+/docs/environments/
+/docs/FAQ/
+/docs/filtering-and-searching/
+/docs/getting-started/
+/docs/integrations/
+/docs/managing-stacks/
+/docs/manual-stacking/
+/docs/notifications/
+/docs/project-settings/
+/docs/references-ids/
+/docs/security/
+/docs/self-hosting/
+/docs/self-hosting/docker/
+/docs/self-hosting/kubernetes/
+/docs/self-hosting/upgrading-self-hosted-instance/
+/docs/setting-log-levels/
+/docs/source-maps/
+/docs/user-sessions/
+/docs/versioning/
+/docs/ai/exie.md
+/docs/ai/mcp-server.md
+/docs/ai.md
+/docs/api/api-getting-started.md
+/docs/api/getting-events.md
+/docs/api.md
+/docs/api/posting-events.md
+/docs/api/project-tokens.md
+/docs/bulk-actions.md
+/docs/clients/custom-clients.md
+/docs/clients/dotnet/client-configuration-values.md
+/docs/clients/dotnet/configuration.md
+/docs/clients/dotnet/guides/console-apps-example.md
+/docs/clients/dotnet/guides/logging-with-generic-host.md
+/docs/clients/dotnet/guides.md
+/docs/clients/dotnet/guides/web-server-example.md
+/docs/clients/dotnet.md
+/docs/clients/dotnet/plugins.md
+/docs/clients/dotnet/private-information.md
+/docs/clients/dotnet/sending-events.md
+/docs/clients/dotnet/settings.md
+/docs/clients/dotnet/supported-platforms.md
+/docs/clients/dotnet/troubleshooting.md
+/docs/clients/dotnet/upgrading.md
+/docs/clients/javascript/client-configuration.md
+/docs/clients/javascript/client-configuration-values.md
+/docs/clients/javascript/express-example.md
+/docs/clients/javascript/guides/angular.md
+/docs/clients/javascript/guides/express.md
+/docs/clients/javascript/guides.md
+/docs/clients/javascript/guides/more-guides.md
+/docs/clients/javascript/guides/react.md
+/docs/clients/javascript/guides/vue.md
+/docs/clients/javascript/javascript-example.md
+/docs/clients/javascript.md
+/docs/clients/javascript/node-example.md
+/docs/clients/javascript/react-example.md
+/docs/clients/javascript/sending-events.md
+/docs/clients/javascript/troubleshooting.md
+/docs/clients/javascript/vue-example.md
+/docs/clients.md
+/docs/comparison.md
+/docs/deduplication.md
+/docs/environments.md
+/docs/FAQ.md
+/docs/filtering-and-searching.md
+/docs/getting-started.md
+/docs/integrations.md
+/docs/managing-stacks.md
+/docs/manual-stacking.md
+/docs/notifications.md
+/docs/project-settings.md
+/docs/references-ids.md
+/docs/security.md
+/docs/self-hosting/docker.md
+/docs/self-hosting/kubernetes.md
+/docs/self-hosting.md
+/docs/self-hosting/upgrading-self-hosted-instance.md
+/docs/setting-log-levels.md
+/docs/source-maps.md
+/docs/user-sessions.md
+/docs/versioning.md
diff --git a/docs/scripts/postbuild.ts b/docs/scripts/postbuild.ts
index cbbf6c44e6..7658459e89 100644
--- a/docs/scripts/postbuild.ts
+++ b/docs/scripts/postbuild.ts
@@ -1,10 +1,22 @@
+import { type Client, expandClientBlocks, type FeatureDefinition } from "./clients.ts"
+import { clientOverviewUrls, flattenNav, type NavSection, parseDocsNav, sectionPages } from "./docs-nav.ts"
+import {
+  markdownPathFor,
+  type Redirect,
+  redirectTarget,
+  renderRedirectHtml,
+  renderRedirectMarkdown,
+} from "./redirects.ts"
+
 type GeneratedData = {
   docsPages: ContentPage[]
   newsPosts: ContentPage[]
+  redirects: Redirect[]
 }
 
 type ContentPage = {
   title: string
+  plan?: string
   description?: string
   url: string
   sourcePath: string
@@ -39,6 +51,7 @@ type SearchCodeToken = {
 type SiteData = {
   description?: string
   appUrl?: string
+  apiUrl?: string
   githubUrl?: string
 }
 
@@ -59,21 +72,12 @@ const llmsProductPages = [
   { title: "About", url: "/about/" },
 ]
 
-const llmsDocsSections = [
-  { title: "Using Exceptionless", match: (path: string) => !/^docs\/(?:ai|clients|api|self-hosting)\//.test(path) },
-  { title: "AI", match: (path: string) => path.startsWith("docs/ai/") },
-  { title: ".NET client", match: (path: string) => path.startsWith("docs/clients/dotnet/") },
-  { title: "JavaScript and Node.js clients", match: (path: string) => path.startsWith("docs/clients/javascript/") },
-  {
-    title: "Other clients",
-    match: (path: string) => path.startsWith("docs/clients/") && !/^docs\/clients\/(?:dotnet|javascript)\//.test(path),
-  },
-  { title: "REST API", match: (path: string) => path.startsWith("docs/api/") },
-  { title: "Self-hosting", match: (path: string) => path.startsWith("docs/self-hosting/") },
-]
 const siteData = JSON.parse(await Deno.readTextFile("_data/site.json")) as SiteData
 const fallbackDescription = normalizeHtmlText(siteData.description ?? "")
 const generated = JSON.parse(await Deno.readTextFile("_site/site-data.json")) as GeneratedData
+const navSections = parseDocsNav(await Deno.readTextFile("_data/docs_nav.yml"))
+const clients = JSON.parse(await Deno.readTextFile("_data/clients.json")) as Client[]
+const clientFeatures = JSON.parse(await Deno.readTextFile("_data/client_features.json")) as FeatureDefinition[]
 
 await copyDir("public", "_site")
 await copyDirIfExists("docs/img", "_site/docs/img")
@@ -86,15 +90,18 @@ await rewriteNewsIndex(generated.newsPosts)
 
 const routes = await collectHtmlRoutes("_site")
 await writeSearchIndex("_site", routes)
+// Redirect stubs are written after the sitemap and search routes are collected, so they never appear in either.
+await writeRedirectStubs(generated.redirects)
 const aliases = await collectRedirectAliases("_site", generated.newsPosts)
 await createRedirectAliasPages(aliases)
 
 await Deno.writeTextFile("_site/feed.xml", renderFeed(generated.newsPosts.slice(0, 25)))
 await Deno.writeTextFile("_site/sitemap.xml", renderSitemap(routes))
 await Deno.writeTextFile("_site/robots.txt", renderRobots())
-await Deno.writeTextFile("_site/llms.txt", renderLlms(generated.docsPages, false))
-await Deno.writeTextFile("_site/llms-full.txt", renderLlms(generated.docsPages, true))
-await Deno.writeTextFile("_site/_redirects", renderRedirects(aliases))
+await Deno.writeTextFile("_site/llms.txt", renderLlms(generated.docsPages, "index"))
+await Deno.writeTextFile("_site/llms-full.txt", renderLlms(generated.docsPages, "full"))
+await Deno.writeTextFile("_site/llms-small.txt", renderLlms(generated.docsPages, "small"))
+await Deno.writeTextFile("_site/_redirects", renderRedirects(aliases, generated.redirects))
 await removeIfExists("_site/site-data.json")
 
 async function copyDirIfExists(source: string, destination: string): Promise {
@@ -233,9 +240,14 @@ async function writeDocsMarkdown(pages: ContentPage[]): Promise {
 }
 
 function renderDocsMarkdown(page: ContentPage): string {
-  const markdown = absolutizeMarkdownLinks(markdownBody(page.sourcePath)).trim()
+  const markdown = absolutizeMarkdownLinks(expandClientBlocks(markdownBody(page.sourcePath), clients, clientFeatures))
+    .trim()
   const [, heading = `# ${page.title}`, body = markdown] = markdown.match(/^(# [^\n]+)\n+([\s\S]*)$/) ?? []
-  const summary = page.description ? `> ${page.description}\n\n` : ""
+  const summary = [
+    page.description ? `> ${page.description}` : "",
+    page.plan ? `> Available on the ${page.plan} plan and up (${siteUrl}/pricing/).` : "",
+  ].filter(Boolean).join("\n>\n")
+    .concat(page.description || page.plan ? "\n\n" : "")
   return `${heading}\n\n${summary}${body}\n\n---\n\nSource: ${siteUrl}${page.url}\nAll Exceptionless documentation: ${siteUrl}/llms.txt\n`
 }
 
@@ -723,7 +735,24 @@ async function createRedirectAliasPages(aliases: RedirectAlias[]): Promise
   for (const alias of aliases) {
     const destination = `_site/${alias.from.replace(/^\/+/, "")}index.html`
     await Deno.mkdir(destination.replace(/\/index\.html$/, ""), { recursive: true })
-    await Deno.writeTextFile(destination, renderRedirectPage(alias.to))
+    await Deno.writeTextFile(destination, renderRedirectHtml({ to: alias.to }))
+  }
+}
+
+/** Writes the HTML and Markdown stubs for `redirectFrom` pages. Fails when a stub would overwrite a real file. */
+async function writeRedirectStubs(redirects: Redirect[]): Promise {
+  for (const redirect of redirects) {
+    const htmlPath = `_site${redirect.from}index.html`
+    const markdownPath = `_site${markdownPathFor(redirect.from)}`
+    for (const path of [htmlPath, markdownPath]) {
+      if (existsFile(path)) {
+        throw new Error(`${redirect.source}: redirectFrom ${redirect.from} would overwrite the real file ${path}.`)
+      }
+    }
+
+    await Deno.mkdir(htmlPath.replace(/\/index\.html$/, ""), { recursive: true })
+    await Deno.writeTextFile(htmlPath, renderRedirectHtml(redirect))
+    await Deno.writeTextFile(markdownPath, renderRedirectMarkdown(redirect))
   }
 }
 
@@ -798,6 +827,7 @@ function renderRobots(): string {
   return `# Exceptionless welcomes search engines and AI assistants.
 # Summary for language models: ${siteUrl}/llms.txt
 # Complete documentation as Markdown: ${siteUrl}/llms-full.txt
+# Core documentation only (Get started, AI, clients): ${siteUrl}/llms-small.txt
 User-agent: *
 Allow: /
 
@@ -805,9 +835,46 @@ Sitemap: ${siteUrl}/sitemap.xml
 `
 }
 
-function renderLlms(pages: ContentPage[], includeBodies: boolean): string {
+type LlmsMode = "index" | "full" | "small"
+type LlmsSection = { title: string; pages: ContentPage[] }
+
+/** Groups docs pages into the nav sections, in nav order. Pages the nav does not list go in a final "More" section. */
+function llmsSections(pages: ContentPage[], sections: NavSection[], only?: Set): LlmsSection[] {
+  const byUrl = new Map(pages.map((page) => [page.url, page]))
+  const grouped: LlmsSection[] = sections.map((section) => ({
+    title: section.title,
+    pages: sectionPages(sections, section.title)
+      .filter((url) => !only || only.has(url))
+      .map((url) => byUrl.get(url))
+      .filter((page): page is ContentPage => Boolean(page)),
+  }))
+
+  const listed = new Set(flattenNav(sections).map((page) => page.url))
+  const unlisted = pages.filter((page) => !listed.has(page.url) && (!only || only.has(page.url)))
+  if (unlisted.length) {
+    grouped.push({ title: "More", pages: unlisted })
+  }
+
+  return grouped.filter((section) => section.pages.length)
+}
+
+/** The page URLs `llms-small.txt` covers: Get started, AI, and the client overview pages. */
+function llmsSmallUrls(sections: NavSection[]): Set {
+  return new Set([
+    ...sectionPages(sections, "Get started"),
+    ...sectionPages(sections, "AI"),
+    ...clientOverviewUrls(sections),
+  ])
+}
+
+function renderLlms(pages: ContentPage[], mode: LlmsMode): string {
   const plans = JSON.parse(Deno.readTextFileSync("_data/plans.json")) as Plan[]
   const pricing = plans.map((plan) => `${plan.name} $${plan.monthlyPrice}`).join(", ")
+  const clientSummary = clients.map((client) =>
+    `${client.language} (${client.name} ${client.version}, ${client.support.toLowerCase()}): ${client.summary}.`
+  ).join(" ")
+  const only = mode === "small" ? llmsSmallUrls(navSections) : undefined
+  const sections = llmsSections(pages, navSections, only)
   const lines = [
     "# Exceptionless",
     "",
@@ -819,28 +886,45 @@ function renderLlms(pages: ContentPage[], includeBodies: boolean): string {
     "- It notifies you about new errors, regressions (fixed errors that come back), and critical events by email, Slack, Zapier, and webhooks.",
     "- Exie is the built-in AI assistant: ask it about your errors in plain English and it investigates stacks and events using your permissions.",
     "- The Exceptionless MCP server (https://be.exceptionless.io/mcp, OAuth sign-in) lets AI coding agents such as Claude Code, Codex, GitHub Copilot, and OpenCode search your errors, read event details, and, with permission, update stacks. It is included on every plan, including Free.",
-    "- Clients: .NET (ASP.NET Core, console and worker services, WPF, WinForms, Microsoft.Extensions.Logging, NLog, log4net, Serilog), JavaScript (browser, Node.js, React, Vue, Angular, Express), and React Native with Expo. Any language can send events to the REST API.",
+    `- Clients: ${clientSummary} Any language can send events to the REST API at ${siteData.apiUrl}.`,
     `- Hosted plans are priced by monthly events, not seats. Monthly prices: ${pricing}. Yearly billing is priced at 11 months. Exie is included on Medium and larger plans.`,
     "- Exceptionless is open source under the Apache 2.0 license and can be self-hosted with Docker or Kubernetes (requires Elasticsearch).",
     `- Hosted app: ${siteData.appUrl}. Source code: ${siteData.githubUrl}.`,
     `- Every documentation page is available as Markdown by replacing the trailing slash with .md, for example ${siteUrl}/docs/getting-started.md.`,
     "",
-    "## Product",
-    "",
-    ...llmsProductPages
-      .filter((page) => existsLocalRoute(page.url, "_site"))
-      .map((page) => llmsLink(page.title, page.url, productPageDescription(page.url))),
-    "",
   ]
 
-  for (const section of llmsDocsSections) {
-    const sectionPages = pages.filter((page) => section.match(page.sourcePath))
-    if (!sectionPages.length) {
-      continue
-    }
+  if (mode !== "small") {
+    lines.push(
+      "## Product",
+      "",
+      ...llmsProductPages
+        .filter((page) => existsLocalRoute(page.url, "_site"))
+        .map((page) => llmsLink(page.title, page.url, productPageDescription(page.url))),
+      "",
+    )
+  }
+
+  if (mode === "index") {
+    lines.push(
+      "## Clients",
+      "",
+      ...clients.map((client) =>
+        llmsLink(
+          `${client.name} for ${client.language}`,
+          markdownUrl(client.docsUrl),
+          `${client.support} client, version ${client.version}. Packages: ${
+            client.packages.map((pkg) => pkg.name).join(", ")
+          }.`,
+        )
+      ),
+      "",
+    )
+  }
 
+  for (const section of sections) {
     lines.push(`## Docs: ${section.title}`, "")
-    for (const page of sectionPages) {
+    for (const page of section.pages) {
       lines.push(llmsLink(page.title, markdownUrl(page.url), page.description))
     }
     lines.push("")
@@ -850,13 +934,23 @@ function renderLlms(pages: ContentPage[], includeBodies: boolean): string {
     "## Optional",
     "",
     llmsLink("News and release notes", "/news/", "Product announcements and release notes."),
-    includeBodies
-      ? ""
-      : llmsLink("Full documentation", "/llms-full.txt", "Every documentation page in one Markdown file."),
   )
 
-  if (includeBodies) {
-    for (const page of pages) {
+  if (mode === "index") {
+    lines.push(
+      llmsLink(
+        "Core documentation",
+        "/llms-small.txt",
+        "Get started, AI, and the client overview pages in one Markdown file.",
+      ),
+      llmsLink("Full documentation", "/llms-full.txt", "Every documentation page in one Markdown file."),
+    )
+  } else if (mode === "small") {
+    lines.push(llmsLink("Full documentation", "/llms-full.txt", "Every documentation page in one Markdown file."))
+  }
+
+  if (mode !== "index") {
+    for (const page of sections.flatMap((section) => section.pages)) {
       lines.push("", "---", "", renderDocsMarkdown(page).trim())
     }
   }
@@ -876,31 +970,16 @@ function productPageDescription(url: string): string | undefined {
   }
 }
 
-function renderRedirects(aliases: RedirectAlias[]): string {
+function renderRedirects(aliases: RedirectAlias[], redirects: Redirect[]): string {
   return [
     "/docs/index /docs/ 301",
     "/news/index /news/ 301",
+    ...redirects.map((redirect) => `${redirect.from} ${redirectTarget(redirect)} 301`),
     ...aliases.map((alias) => `${alias.from} ${alias.to} 301`),
     "",
   ].join("\n")
 }
 
-function renderRedirectPage(target: string): string {
-  return `
-
-
-  
-  
-  
-  Redirecting - Exceptionless
-
-
-  

Redirecting

- - -` -} - function markdownBody(path: string): string { try { return Deno.readTextFileSync(path).replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "") @@ -938,6 +1017,14 @@ function existsLocalRoute(pathname: string, root: string): boolean { }) } +function existsFile(path: string): boolean { + try { + return Deno.statSync(path).isFile + } catch { + return false + } +} + function routeForPage(path: string, root: string): string { const relative = slash(path).slice(root.length + 1) if (relative.endsWith("/index.html")) { diff --git a/docs/scripts/redirects.test.ts b/docs/scripts/redirects.test.ts new file mode 100644 index 0000000000..3c8f202eb2 --- /dev/null +++ b/docs/scripts/redirects.test.ts @@ -0,0 +1,95 @@ +import { + collectRedirects, + markdownPathFor, + redirectTarget, + renderRedirectHtml, + renderRedirectMarkdown, +} from "./redirects.ts" +import { assert, assertEquals, assertStringIncludes, assertThrows } from "./test-helpers.ts" + +const stacking = { + url: "/docs/concepts/stacking/", + title: "Stacking", + sourcePath: "docs/concepts/stacking.md", + redirectFrom: ["/docs/manual-stacking/", { from: "/docs/bulk-actions/", anchor: "bulk-actions" }], +} + +Deno.test("redirects: strings and { from, anchor } entries are collected and sorted", () => { + const redirects = collectRedirects([stacking, { url: "/docs/", title: "Docs", sourcePath: "docs/index.md" }]) + assertEquals(redirects.map((redirect) => [redirect.from, redirect.to, redirect.anchor]), [ + ["/docs/bulk-actions/", "/docs/concepts/stacking/", "bulk-actions"], + ["/docs/manual-stacking/", "/docs/concepts/stacking/", undefined], + ]) + assertEquals(redirects[0].toTitle, "Stacking") +}) + +Deno.test("redirects: Vento pages can declare redirects too", () => { + const redirects = collectRedirects([{ + url: "/why/", + title: "Why", + sourcePath: "why.vto", + redirectFrom: ["/docs/comparison/"], + }]) + assertEquals(redirects.map((redirect) => redirectTarget(redirect)), ["/why/"]) +}) + +Deno.test("redirects: a path that collides with a real page or its Markdown copy fails the build", () => { + const manualStacking = { + url: "/docs/manual-stacking/", + title: "Manual stacking", + sourcePath: "docs/manual-stacking.md", + } + assertThrows(() => collectRedirects([stacking, manualStacking]), Error, "collides with the real page") + assertThrows( + () => collectRedirects([stacking, { url: "/docs/bulk-actions/", sourcePath: "docs/bulk-actions.md" }]), + Error, + "collides with the real page", + ) +}) + +Deno.test("redirects: two pages cannot claim the same old path", () => { + const other = { url: "/docs/other/", sourcePath: "docs/other.md", redirectFrom: ["/docs/manual-stacking/"] } + assertThrows(() => collectRedirects([stacking, other]), Error, "already declared by docs/concepts/stacking.md") +}) + +Deno.test("redirects: malformed entries are rejected with the source file", () => { + const page = (redirectFrom: unknown) => [{ url: "/docs/new/", sourcePath: "docs/new.md", redirectFrom }] + assertThrows(() => collectRedirects(page("/docs/old/")), Error, "redirectFrom must be a list") + assertThrows(() => collectRedirects(page(["docs/old/"])), Error, "must be a site path") + assertThrows(() => collectRedirects(page(["/docs/old"])), Error, "must be a site path") + assertThrows(() => collectRedirects(page(["/docs/old.md"])), Error, "must be a site path") + assertThrows(() => collectRedirects(page([{ from: "/docs/old/", anchor: "#x" }])), Error, 'without "#"') + assertThrows(() => collectRedirects(page([{ from: "/docs/old/", extra: 1 }])), Error, "unknown keys") + assertThrows(() => collectRedirects(page(["/docs/new/"])), Error, "page's own URL") +}) + +Deno.test("redirect stub: HTML redirects, keeps the hash, and is not indexable", () => { + const html = renderRedirectHtml({ to: "/docs/concepts/stacking/", anchor: "manual-stacking" }) + assertStringIncludes(html, '') + assertStringIncludes(html, '') + assertStringIncludes(html, '') + assertStringIncludes(html, 'location.replace("/docs/concepts/stacking/" + (location.hash || "#manual-stacking"))') + assertStringIncludes(html, '') +}) + +Deno.test("redirect stub: without an anchor the script keeps only the visitor's hash", () => { + const html = renderRedirectHtml({ to: "/why/" }) + assertStringIncludes(html, 'location.replace("/why/" + (location.hash || ""))') + assertStringIncludes(html, 'content="0; url=/why/"') +}) + +Deno.test("redirect stub: Markdown says where the page moved and links the new .md URL", () => { + const [redirect] = collectRedirects([stacking]).filter((candidate) => candidate.from === "/docs/bulk-actions/") + const markdown = renderRedirectMarkdown(redirect) + assertStringIncludes(markdown, "https://exceptionless.com/docs/bulk-actions/ moved to") + assertStringIncludes(markdown, "[Stacking](https://exceptionless.com/docs/concepts/stacking.md#bulk-actions)") + + const [why] = collectRedirects([{ url: "/why/", title: "Why Exceptionless?", redirectFrom: ["/docs/comparison/"] }]) + assertStringIncludes(renderRedirectMarkdown(why), "(https://exceptionless.com/why/)") +}) + +Deno.test("Markdown paths follow the docs convention", () => { + assertEquals(markdownPathFor("/docs/"), "/docs.md") + assertEquals(markdownPathFor("/docs/manual-stacking/"), "/docs/manual-stacking.md") + assert(markdownPathFor("/docs/clients/dotnet/") === "/docs/clients/dotnet.md") +}) diff --git a/docs/scripts/redirects.ts b/docs/scripts/redirects.ts new file mode 100644 index 0000000000..921632d1c1 --- /dev/null +++ b/docs/scripts/redirects.ts @@ -0,0 +1,159 @@ +/** + * Redirects for moved pages. GitHub Pages ignores `_redirects`, so every old URL gets a static stub: an HTML page at + * `index.html` and a Markdown page at the old `.md` URL. + */ + +export type RedirectPage = { + url: string + title?: string + sourcePath?: string + redirectFrom?: unknown +} + +export type Redirect = { + /** The old URL, for example `/docs/manual-stacking/`. */ + from: string + /** The page the old URL moved to. */ + to: string + /** The heading id on the new page the redirect lands on, without `#`. */ + anchor?: string + /** The new page's title, for the Markdown stub. */ + toTitle: string + /** The source file that declares the redirect, for error messages. */ + source: string +} + +const siteUrl = "https://exceptionless.com" + +/** Reads the `redirectFrom` frontmatter of every page and checks that the old URLs are well formed and unique. */ +export function collectRedirects(pages: RedirectPage[]): Redirect[] { + const redirects: Redirect[] = [] + const declaredBy = new Map() + + for (const page of pages) { + if (page.redirectFrom === undefined) { + continue + } + + const source = page.sourcePath || page.url + if (!Array.isArray(page.redirectFrom)) { + throw new Error(`${source}: redirectFrom must be a list.`) + } + + for (const entry of page.redirectFrom) { + const { from, anchor } = parseRedirectEntry(entry, source) + if (from === page.url) { + throw new Error(`${source}: redirectFrom ${from} is the page's own URL.`) + } + + const previous = declaredBy.get(from) + if (previous) { + throw new Error(`${source}: redirectFrom ${from} is already declared by ${previous}.`) + } + + declaredBy.set(from, source) + redirects.push({ from, to: page.url, anchor, toTitle: page.title || page.url, source }) + } + } + + const realUrls = new Map() + for (const page of pages) { + realUrls.set(page.url, page.sourcePath || page.url) + if (page.url.startsWith("/docs/")) { + realUrls.set(markdownPathFor(page.url), page.sourcePath || page.url) + } + } + + for (const redirect of redirects) { + for (const path of [redirect.from, markdownPathFor(redirect.from)]) { + const collision = realUrls.get(path) + if (collision) { + throw new Error(`${redirect.source}: redirectFrom ${redirect.from} collides with the real page ${collision}.`) + } + } + } + + return redirects.sort((a, b) => a.from.localeCompare(b.from)) +} + +function parseRedirectEntry(entry: unknown, source: string): { from: string; anchor?: string } { + const value = typeof entry === "string" ? { from: entry } : entry + if (typeof value !== "object" || value === null || Array.isArray(value)) { + throw new Error(`${source}: each redirectFrom entry must be a URL or { from, anchor }.`) + } + + const { from, anchor, ...rest } = value as Record + if (Object.keys(rest).length) { + throw new Error(`${source}: redirectFrom has unknown keys: ${Object.keys(rest).join(", ")}.`) + } + + if (typeof from !== "string" || !/^\/(?:[^\s?#.]+\/)+$/.test(from)) { + throw new Error( + `${source}: redirectFrom ${JSON.stringify(from)} must be a site path that starts and ends with a slash.`, + ) + } + + if (anchor !== undefined && (typeof anchor !== "string" || !/^[^\s#]+$/.test(anchor))) { + throw new Error(`${source}: redirectFrom anchor for ${from} must be a heading id without "#".`) + } + + return { from, anchor: anchor as string | undefined } +} + +/** The Markdown URL of a page: `/docs/` is `/docs.md` and `/docs/a/b/` is `/docs/a/b.md`. */ +export function markdownPathFor(url: string): string { + return url === "/docs/" ? "/docs.md" : `${url.replace(/\/$/, "")}.md` +} + +export function redirectTarget(redirect: Pick): string { + return `${redirect.to}${redirect.anchor ? `#${redirect.anchor}` : ""}` +} + +/** + * An HTML stub that sends the visitor to the new page. A hash on the old URL wins over the declared anchor, so links + * such as `/docs/bulk-actions/#some-heading` keep working. + */ +export function renderRedirectHtml(target: { to: string; anchor?: string }, origin = siteUrl): string { + const destination = redirectTarget(target) + return ` + + + + + Redirecting - Exceptionless + + + + + +

This page moved. Continue to the new page.

+ + +` +} + +/** A Markdown stub for the old `.md` URL, for readers and agents that fetch Markdown. */ +export function renderRedirectMarkdown(redirect: Redirect, origin = siteUrl): string { + const markdownTarget = redirect.to.startsWith("/docs/") ? markdownPathFor(redirect.to) : redirect.to + const link = `${origin}${markdownTarget}${redirect.anchor ? `#${redirect.anchor}` : ""}` + return `# This page moved + +The page at ${origin}${redirect.from} moved to [${redirect.toTitle}](${link}). + +Read it at: ${link} + +--- + +All Exceptionless documentation: ${origin}/llms.txt +` +} + +function attribute(value: string): string { + return value.replaceAll("&", "&").replaceAll('"', """).replaceAll("<", "<") +} + +function scriptString(value: string): string { + return JSON.stringify(value).replaceAll("<", "\\u003c") +} diff --git a/docs/scripts/site-collections.ts b/docs/scripts/site-collections.ts index dfb9591ad9..ef89d0d04f 100644 --- a/docs/scripts/site-collections.ts +++ b/docs/scripts/site-collections.ts @@ -1,3 +1,6 @@ +import { crumbsFor, type NavEntry, type NavGroup, normalizeDocsNav, pagerFor } from "./docs-nav.ts" +import { collectRedirects, type Redirect } from "./redirects.ts" + type Searcher = { pages>(query?: string, sort?: string, limit?: number): Array } @@ -8,6 +11,9 @@ type LumePageData = { url?: string | false date?: Date | string | number order?: number + navTitle?: string + plan?: string + redirectFrom?: unknown hidden?: boolean draft?: boolean llms?: boolean @@ -18,6 +24,8 @@ type LumePageData = { export type ContentPage = { title: string + navTitle?: string + plan?: string description?: string url: string sourcePath: string @@ -26,18 +34,6 @@ export type ContentPage = { llms?: boolean } -type NavItem = { - text: string - href?: string - items?: NavItem[] -} - -type TreeNode = { - segment: string - page?: ContentPage - children: Map -} - const excludedNews = new Set([ "news/2020/2020-11-11-self-hosted-error-monitoring-on-azure.md", "news/index.md", @@ -64,9 +60,94 @@ export function newsPosts(search: Searcher): ContentPage[] { .sort((a, b) => (b.date || "").localeCompare(a.date || "") || a.url.localeCompare(b.url)) } -export function docsNavHtml(search: Searcher, currentUrl = ""): string { - const nav = buildDocsNav(docsPages(search)) - return `
    ${renderNavItems(nav, currentUrl)}
` +/** The label a page has in the sidebar, breadcrumbs, and previous/next links. */ +function pageLabel(page: ContentPage): string { + return page.navTitle || page.title +} + +function labelsByUrl(search: Searcher): Map { + return new Map(docsPages(search).map((page) => [page.url, pageLabel(page)])) +} + +/** Renders the docs sidebar from `_data/docs_nav.yml`. Entries without a page yet are skipped. */ +export function docsNavHtml(search: Searcher, currentUrl: string, rawNav: unknown): string { + const sections = normalizeDocsNav(rawNav) + const labels = labelsByUrl(search) + + const renderEntries = (entries: NavEntry[]): string => + entries.map((entry) => { + if (entry.kind === "page") { + const label = labels.get(entry.url) + return label ? renderPageItem(entry.url, label, currentUrl) : "" + } + + return renderGroup(entry, labels, currentUrl, renderEntries) + }).filter(Boolean).join("\n") + + const items = sections.map((section) => { + const children = renderEntries(section.items) + return children ? `
  • ${escapeHtml(section.title)}
      ${children}
  • ` : "" + }).filter(Boolean).join("\n") + + return `
      ${items}
    ` +} + +function renderPageItem(url: string, label: string, currentUrl: string): string { + const href = escapeHtml(url) + const current = url === currentUrl + return `${escapeHtml(label)}` +} + +function renderGroup( + group: NavGroup, + labels: Map, + currentUrl: string, + renderEntries: (entries: NavEntry[]) => string, +): string { + const children = renderEntries(group.items) + const groupHasPage = group.url ? labels.has(group.url) : false + if (!children && !groupHasPage) { + return "" + } + + const open = containsUrl(group, currentUrl) ? " open" : "" + const current = group.url === currentUrl + const heading = group.url && groupHasPage + ? `${escapeHtml(group.title)}` + : `${escapeHtml(group.title)}` + const list = children ? `
      ${children}
    ` : "" + return `
  • ${heading}${list}
  • ` +} + +function containsUrl(group: NavGroup, url: string): boolean { + return group.url === url || + group.items.some((entry) => entry.kind === "page" ? entry.url === url : containsUrl(entry, url)) +} + +/** Renders the previous and next links at the bottom of a docs page, following the nav order. */ +export function docsPagerHtml(search: Searcher, currentUrl: string, rawNav: unknown): string { + const labels = labelsByUrl(search) + const { previous, next } = pagerFor(normalizeDocsNav(rawNav), currentUrl, (url) => labels.get(url)) + if (!previous && !next) { + return "" + } + + const link = (kind: "previous" | "next", target: { url: string; title: string } | undefined) => + target + ? `${kind === "next" ? "Next" : "Previous"}${ + escapeHtml(target.title) + }` + : "" + + return `` } export type Breadcrumb = { @@ -74,22 +155,24 @@ export type Breadcrumb = { url: string } -/** Returns the Home > Docs > section > page trail for a docs URL, using page titles where they exist. */ -export function docsBreadcrumbs(search: Searcher, currentUrl: string): Breadcrumb[] { +/** + * Returns the Home > Docs > section > group > page trail for a docs URL. The sections and groups come from the nav, + * and each links to its first page. + */ +export function docsBreadcrumbs(search: Searcher, currentUrl: string, rawNav?: unknown): Breadcrumb[] { if (!currentUrl.startsWith("/docs/")) { return [] } - const titles = new Map(docsPages(search).map((page) => [page.url, page.title])) + const labels = labelsByUrl(search) const crumbs: Breadcrumb[] = [{ name: "Home", url: "/" }, { name: "Docs", url: "/docs/" }] - const segments = currentUrl.split("/").filter(Boolean).slice(1) - let path = "/docs/" - for (const segment of segments) { - path += `${segment}/` - const title = titles.get(path) - if (title) { - crumbs.push({ name: title, url: path }) - } + if (rawNav) { + crumbs.push(...crumbsFor(normalizeDocsNav(rawNav), currentUrl, (url) => labels.get(url))) + } + + const current = labels.get(currentUrl) + if (current && currentUrl !== "/docs/") { + crumbs.push({ name: current, url: currentUrl }) } return crumbs @@ -100,12 +183,28 @@ export function siteDataJson(search: Searcher): string { { docsPages: visibleDocsPages(search), newsPosts: newsPosts(search), + redirects: redirects(search), }, null, 2, ) } +/** Every `redirectFrom` declared by a published page, checked for bad paths and collisions. */ +export function redirects(search: Searcher): Redirect[] { + const pages = search.pages() + .filter((page) => !page.draft && !page.hidden && typeof page.url === "string") + .map((page) => ({ + url: page.url as string, + title: page.title, + sourcePath: slash(page.page?.sourcePath || "").replace(/^\/+/, ""), + redirectFrom: page.redirectFrom, + })) + .filter((page) => page.sourcePath !== "(generated)") + + return collectRedirects(pages) +} + function toContentPage(page: LumePageData): ContentPage | undefined { if (page.draft || page.hidden) { return undefined @@ -122,6 +221,8 @@ function toContentPage(page: LumePageData): ContentPage | undefined { return { title: page.title || titleFromPath(sourcePath), + navTitle: page.navTitle, + plan: page.plan, description: page.description, url: page.url, sourcePath, @@ -131,60 +232,6 @@ function toContentPage(page: LumePageData): ContentPage | undefined { } } -function buildDocsNav(pages: ContentPage[]): NavItem[] { - const root: TreeNode = { segment: "docs", children: new Map() } - - for (const page of pages) { - const relative = page.sourcePath.replace(/^docs\//, "").replace(/\.md$/, "") - const parts = relative.split("/") - const isIndex = parts.at(-1) === "index" - const nodeParts = isIndex ? parts.slice(0, -1) : parts - let current = root - - for (const part of nodeParts) { - let child = current.children.get(part) - if (!child) { - child = { segment: part, children: new Map() } - current.children.set(part, child) - } - current = child - } - - current.page = page - } - - const rootItem = nodeToNav(root) - return rootItem ? [rootItem] : [] -} - -function nodeToNav(node: TreeNode): NavItem | undefined { - const children = [...node.children.values()] - .sort(compareNodes) - .map(nodeToNav) - .filter((item): item is NavItem => Boolean(item)) - - if (node.page) { - return { - text: node.page.title, - href: node.page.url, - items: children.length ? children : undefined, - } - } - - if (!children.length) { - return undefined - } - - return { - text: titleFromSegment(node.segment), - items: children, - } -} - -function compareNodes(a: TreeNode, b: TreeNode): number { - return compareOptionalNumbers(a.page?.order, b.page?.order) || nodeTitle(a).localeCompare(nodeTitle(b)) -} - function comparePages(a: ContentPage, b: ContentPage): number { return compareOptionalNumbers(a.order, b.order) || a.url.localeCompare(b.url) } @@ -205,24 +252,6 @@ function compareOptionalNumbers(a?: number, b?: number): number { return 0 } -function nodeTitle(node: TreeNode): string { - return node.page?.title || titleFromSegment(node.segment) -} - -function renderNavItems(items: NavItem[], currentUrl: string): string { - return items.map((item) => { - const label = escapeHtml(item.text) - const childHtml = item.items?.length ? `
      ${renderNavItems(item.items, currentUrl)}
    ` : "" - if (!item.href) { - return `
  • ${label}${childHtml}
  • ` - } - - const href = escapeHtml(item.href) - const activeClass = item.href === currentUrl ? ' class="toc-active"' : "" - return `${label}${childHtml}` - }).join("\n") -} - function titleFromPath(path: string): string { const normalized = slash(path).replace(/\.md$/, "") const name = normalized.endsWith("/index") diff --git a/docs/scripts/structured-data.ts b/docs/scripts/structured-data.ts index 1edf63257f..e71f15a576 100644 --- a/docs/scripts/structured-data.ts +++ b/docs/scripts/structured-data.ts @@ -11,6 +11,7 @@ type PageData = { image?: string layout?: string robots?: string + docs_nav?: unknown } type Plan = { @@ -43,7 +44,7 @@ export function structuredData(data: PageData, search: Searcher): string { const image = `${siteUrl}${data.image || defaultSocialImage}` const isDocs = data.url.startsWith("/docs/") const isPost = data.layout === "layouts/post.vto" - const breadcrumbs = isDocs ? docsBreadcrumbs(search, data.url) : pageBreadcrumbs(data) + const breadcrumbs = isDocs ? docsBreadcrumbs(search, data.url, data.docs_nav) : pageBreadcrumbs(data) const graph: Record[] = [ { diff --git a/docs/scripts/test-helpers.ts b/docs/scripts/test-helpers.ts new file mode 100644 index 0000000000..49ab804ba6 --- /dev/null +++ b/docs/scripts/test-helpers.ts @@ -0,0 +1,37 @@ +/** Small assertions for the Deno tests, so the tests do not need an extra dependency. */ + +export function assert(condition: unknown, message = "Assertion failed"): asserts condition { + if (!condition) { + throw new Error(message) + } +} + +export function assertEquals(actual: T, expected: T): void { + const actualJson = JSON.stringify(actual, null, 2) + const expectedJson = JSON.stringify(expected, null, 2) + if (actualJson !== expectedJson) { + throw new Error(`Expected:\n${expectedJson}\n\nActual:\n${actualJson}`) + } +} + +export function assertStringIncludes(actual: string, expected: string): void { + if (!actual.includes(expected)) { + throw new Error(`Expected to find:\n${expected}\n\nIn:\n${actual}`) + } +} + +export function assertThrows(action: () => unknown, ErrorClass: typeof Error, message: string): void { + try { + action() + } catch (error) { + if (!(error instanceof ErrorClass)) { + throw new Error(`Expected a ${ErrorClass.name}, got ${error}`) + } + if (!error.message.includes(message)) { + throw new Error(`Expected the error to include "${message}", got "${error.message}"`) + } + return + } + + throw new Error(`Expected an error that includes "${message}", but nothing was thrown.`) +} diff --git a/docs/scripts/verify-docs.ts b/docs/scripts/verify-docs.ts new file mode 100644 index 0000000000..b5b248f248 --- /dev/null +++ b/docs/scripts/verify-docs.ts @@ -0,0 +1,227 @@ +/** + * Verifies the docs rewrite rules against the built site and the page sources: + * - every URL in docs-urls.txt still resolves to a page or a redirect stub, + * - docs_nav.yml lists exactly the published docs pages, + * - every docs page has a title, a short description, a known plan, and `sources` paths that exist, + * - published pages use one API hostname (see the constants below). + * + * Run it after `deno task build`. + */ +import { parse } from "lume/deps/yaml.ts" +import { navUrls, parseDocsNav } from "./docs-nav.ts" + +/** The only hostname for the hosted API. The value lives in _data/site.json as `apiUrl`. */ +const site = JSON.parse(Deno.readTextFileSync("_data/site.json")) as { apiUrl: string; appUrl: string } +const apiHostname = new URL(site.apiUrl).hostname +const appHostname = new URL(site.appUrl).hostname +/** Hostnames that must never appear in published pages outside /news/. */ +const bannedHostnames = ["collector.exceptionless.io"] +/** Paths that belong to the API. The web app hostname must not serve them in docs. */ +const apiPathsOnAppHost = ["/api", "/docs"] +/** Routes allowed to use an API path on the app host. The contact form posts to the app origin that allows its CORS. */ +const appHostApiRoutes = new Set(["/contact/"]) + +const siteRoot = "_site" +const repoRoot = ".." +const maxDescriptionLength = 160 +const externalSourcePrefixes = ["Exceptionless.Net:", "Exceptionless.JavaScript:"] + +const errors: string[] = [] + +const navYaml = await Deno.readTextFile("_data/docs_nav.yml") +const plans = (JSON.parse(await Deno.readTextFile("_data/plans.json")) as { name: string }[]).map((plan) => plan.name) + +await verifyDocsUrls() +await verifyNav() +await verifyFrontmatter() +await verifyHostnames() + +if (errors.length) { + console.error(`Docs verification failed with ${errors.length} problem(s):`) + for (const error of errors) { + console.error(`- ${error}`) + } + Deno.exit(1) +} + +console.log("Docs verification passed.") + +/** Every URL published before the rewrite must still resolve, as a page or a redirect stub. */ +async function verifyDocsUrls(): Promise { + const urls = (await Deno.readTextFile("scripts/docs-urls.txt")) + .split(/\r?\n/) + .map((line) => line.trim()) + .filter((line) => line && !line.startsWith("#")) + + for (const url of urls) { + const path = url.endsWith("/") ? `${siteRoot}${url}index.html` : `${siteRoot}${url}` + if (!isFile(path)) { + errors.push(`${url}: no longer resolves (expected ${path}). Keep the page or add a redirectFrom.`) + } + } +} + +async function verifyNav(): Promise { + let listed: string[] + try { + listed = navUrls(parseDocsNav(navYaml)) + } catch (error) { + errors.push(error instanceof Error ? error.message : String(error)) + return + } + + const published = new Set(await publishedDocsRoutes()) + const listedSet = new Set(listed) + + for (const url of listed) { + if (!published.has(url)) { + errors.push(`docs_nav.yml lists ${url}, which is not a published page.`) + } else if (!isFile(`${siteRoot}${markdownPath(url)}`)) { + errors.push(`docs_nav.yml lists ${url}, but its Markdown copy ${markdownPath(url)} is missing.`) + } + } + + for (const route of published) { + if (!listedSet.has(route)) { + errors.push(`${route} is published but missing from docs_nav.yml.`) + } + } +} + +/** Docs routes that are real pages: the built HTML files that are not redirect stubs. */ +async function publishedDocsRoutes(): Promise { + const routes: string[] = [] + for await (const path of walk(`${siteRoot}/docs`)) { + if (!path.endsWith("/index.html")) { + continue + } + + const html = await Deno.readTextFile(path) + if (html.includes('http-equiv="refresh"')) { + continue + } + + routes.push(path.slice(siteRoot.length, -"index.html".length)) + } + + return routes.sort() +} + +async function verifyFrontmatter(): Promise { + for await (const path of walk("docs")) { + if (!path.endsWith(".md")) { + continue + } + + const text = await Deno.readTextFile(path) + const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/) + if (!match) { + errors.push(`${path}: missing frontmatter.`) + continue + } + + const data = parse(match[1]) as Record | null + if (!data || data.hidden === true || data.draft === true || data.url === false) { + continue + } + + if (typeof data.title !== "string" || !data.title.trim()) { + errors.push(`${path}: missing title.`) + } + + if (typeof data.description !== "string" || !data.description.trim()) { + errors.push(`${path}: missing description.`) + } else if (data.description.length > maxDescriptionLength) { + errors.push(`${path}: description is ${data.description.length} characters (max ${maxDescriptionLength}).`) + } + + if (data.plan !== undefined && (typeof data.plan !== "string" || !plans.includes(data.plan))) { + errors.push(`${path}: plan ${JSON.stringify(data.plan)} is not in _data/plans.json (${plans.join(", ")}).`) + } + + if (data.sources !== undefined) { + if (!Array.isArray(data.sources) || data.sources.some((source) => typeof source !== "string")) { + errors.push(`${path}: sources must be a list of paths.`) + continue + } + + for (const source of data.sources as string[]) { + if (externalSourcePrefixes.some((prefix) => source.startsWith(prefix))) { + continue + } + + if (!exists(`${repoRoot}/${source}`)) { + errors.push(`${path}: source ${source} does not exist in the repository.`) + } + } + } + } +} + +/** Published pages (not news, not redirect stubs) use the API hostname, never the old collector or API paths on the app host. */ +async function verifyHostnames(): Promise { + const apiPathPattern = new RegExp( + `${appHostname.replaceAll(".", "\\.")}(?::\\d+)?(${ + apiPathsOnAppHost.map((path) => `\\${path}`).join("|") + })(?![\\w-])`, + "g", + ) + + for await (const path of walk(siteRoot)) { + const relative = path.slice(siteRoot.length) + if (relative.startsWith("/news/") || !/\.(?:html|md|txt)$/.test(relative)) { + continue + } + + const route = relative.replace(/index\.html$/, "") + const allowAppHostApi = appHostApiRoutes.has(route) + + const text = await Deno.readTextFile(path) + if (text.includes('http-equiv="refresh"') && text.length < 2000) { + continue + } + + for (const hostname of bannedHostnames) { + if (text.includes(hostname)) { + errors.push(`${relative}: mentions ${hostname}. Use ${site.apiUrl} for the hosted API.`) + } + } + + for (const match of allowAppHostApi ? [] : text.matchAll(apiPathPattern)) { + errors.push(`${relative}: ${appHostname}${match[1]} is an API path. Use ${apiHostname}${match[1]}.`) + break + } + } +} + +function markdownPath(url: string): string { + return url === "/docs/" ? "/docs.md" : `${url.replace(/\/$/, "")}.md` +} + +function isFile(path: string): boolean { + try { + return Deno.statSync(path).isFile + } catch { + return false + } +} + +function exists(path: string): boolean { + try { + Deno.statSync(path) + return true + } catch { + return false + } +} + +async function* walk(dir: string): AsyncGenerator { + for await (const entry of Deno.readDir(dir)) { + const path = `${dir}/${entry.name}` + if (entry.isDirectory) { + yield* walk(path) + } else if (entry.isFile) { + yield path + } + } +} diff --git a/docs/why.vto b/docs/why.vto index cf7ce1e2a0..980836abbf 100644 --- a/docs/why.vto +++ b/docs/why.vto @@ -1,6 +1,8 @@ --- title: Why Exceptionless? layout: layouts/base.vto +redirectFrom: + - /docs/comparison/ description: Why developers choose Exceptionless for error monitoring - open source, self-hostable, predictable pricing, real-time configuration, and an AI assistant that works with your data. ---
    @@ -100,7 +102,6 @@ description: Why developers choose Exceptionless for error monitoring - open sou -
    From 3cb072a6237a4ab556b8d771507e52c5f941b782 Mon Sep 17 00:00:00 2001 From: "Eric J. Smith" Date: Tue, 27 Oct 2026 23:48:54 -0500 Subject: [PATCH 3/3] Fact-check fixes, MCP URL, and verify cleanup for the 9.0 docs Co-Authored-By: Claude Opus 5.5 --- docs/STYLE.md | 9 ++++--- docs/_data/clients.json | 15 ++++++++--- docs/docs-rewrite-plan.md | 4 ++- docs/docs/ai/exie.md | 10 ++++---- docs/docs/ai/mcp-server.md | 12 ++++----- docs/docs/ai/privacy.md | 5 ++-- docs/docs/api/authentication.md | 16 +++++++----- docs/docs/api/index.md | 2 +- docs/docs/clients/custom-clients/index.md | 20 +++++++++++++-- docs/docs/clients/dotnet/blazor.md | 1 + docs/docs/clients/dotnet/index.md | 2 +- docs/docs/clients/dotnet/plugins.md | 1 + docs/docs/clients/dotnet/sending-events.md | 2 +- docs/docs/clients/dotnet/troubleshooting.md | 2 +- .../javascript/client-configuration.md | 6 +++-- .../clients/javascript/guides/react-native.md | 5 ++-- docs/docs/project-settings.md | 6 ++--- docs/docs/reference/client-spec.md | 5 ++-- docs/docs/reference/search-syntax.md | 4 +-- docs/docs/saved-views.md | 10 +++++--- docs/docs/self-hosting/configuration.md | 24 +++++++++--------- docs/docs/self-hosting/docker.md | 4 ++- docs/docs/self-hosting/kubernetes.md | 4 +-- docs/docs/setting-log-levels.md | 4 ++- docs/docs/whats-new.md | 4 +-- .../img/codesmith-client-logo-bar-left.png | Bin 13663 -> 0 bytes ...ltering-and-searching-date-range-dark.webp | Bin 20622 -> 0 bytes ...ring-and-searching-date-range-dark@2x.webp | Bin 42980 -> 0 bytes ...tering-and-searching-date-range-light.webp | Bin 18778 -> 0 bytes ...ing-and-searching-date-range-light@2x.webp | Bin 41396 -> 0 bytes ...tting-log-levels-project-default-dark.webp | Bin 19664 -> 0 bytes ...ng-log-levels-project-default-dark@2x.webp | Bin 41702 -> 0 bytes ...ting-log-levels-project-default-light.webp | Bin 17710 -> 0 bytes ...g-log-levels-project-default-light@2x.webp | Bin 38562 -> 0 bytes docs/scripts/verify-docs.ts | 8 +++++- 35 files changed, 118 insertions(+), 67 deletions(-) delete mode 100644 docs/public/assets/img/codesmith-client-logo-bar-left.png delete mode 100644 docs/public/assets/img/docs/filtering-and-searching-date-range-dark.webp delete mode 100644 docs/public/assets/img/docs/filtering-and-searching-date-range-dark@2x.webp delete mode 100644 docs/public/assets/img/docs/filtering-and-searching-date-range-light.webp delete mode 100644 docs/public/assets/img/docs/filtering-and-searching-date-range-light@2x.webp delete mode 100644 docs/public/assets/img/docs/setting-log-levels-project-default-dark.webp delete mode 100644 docs/public/assets/img/docs/setting-log-levels-project-default-dark@2x.webp delete mode 100644 docs/public/assets/img/docs/setting-log-levels-project-default-light.webp delete mode 100644 docs/public/assets/img/docs/setting-log-levels-project-default-light@2x.webp diff --git a/docs/STYLE.md b/docs/STYLE.md index 70d0b74c5d..50fb279b41 100644 --- a/docs/STYLE.md +++ b/docs/STYLE.md @@ -23,8 +23,10 @@ How the Exceptionless docs are written. Every writer, person or agent, follows i starts with a matching `# Heading`. - Headings use sentence case: "Mark a stack fixed", not "Mark A Stack Fixed". - To keep an anchor that other pages or the app link to, give the heading an explicit id: - `## Client configuration - {#client-configuration}`. + + ```markdown + ## Client configuration {#client-configuration} + ``` ## Frontmatter @@ -89,7 +91,8 @@ Use GitHub alert syntax, and use it sparingly: > Self-hosted instances use your own API URL instead. ``` -`[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, and `[!WARNING]` are supported. +`[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]` are supported. The marker goes on its own first +line. ## Prompts diff --git a/docs/_data/clients.json b/docs/_data/clients.json index dcc0734210..7098132d0b 100644 --- a/docs/_data/clients.json +++ b/docs/_data/clients.json @@ -52,6 +52,13 @@ "description": "log4net appender.", "minimumRuntime": ".NET Standard 2.0, .NET Framework 4.6.2" }, + { + "name": "Exceptionless.MessagePack", + "registry": "NuGet", + "url": "https://www.nuget.org/packages/Exceptionless.MessagePack", + "description": "MessagePack serialization for the stored queue.", + "minimumRuntime": ".NET Standard 2.0, .NET 8" + }, { "name": "Exceptionless.Wpf", "registry": "NuGet", @@ -143,7 +150,7 @@ }, "configValues": { "status": "yes", - "note": "Settings, with a Changed event. Checked every 2 minutes while idle." + "note": "Settings, with a Changed event. Checked every 2 minutes while idle after Startup()." }, "plugins": { "status": "yes", @@ -155,7 +162,7 @@ }, "offlineQueue": { "status": "opt-in", - "note": "The queue is in memory by default. Call UseFolderStorage or UseIsolatedStorage to persist it." + "note": "The queue is in memory by default. Call UseFolderStorage or set StoragePath to persist it." }, "deduplication": { "status": "yes", @@ -253,7 +260,7 @@ "install": "npx expo install @exceptionless/react-native @react-native-async-storage/async-storage", "language": "js", "code": "import { Exceptionless } from \"@exceptionless/react-native\";\n\nawait Exceptionless.startup((c) => {\n c.apiKey = \"YOUR_API_KEY\";\n});\n\n// JavaScript errors and promise rejections are captured automatically.\nawait Exceptionless.submitFeatureUsage(\"Checkout\");", - "caption": "Works with Expo and bare React Native. Add the Expo config plugin for native iOS crash reporting.", + "caption": "Works with Expo and bare React Native. Native iOS crash reporting needs a development or release build, not Expo Go.", "docsUrl": "/docs/clients/javascript/guides/react-native/" } ], @@ -308,7 +315,7 @@ }, "deduplication": { "status": "yes", - "note": "Identical errors are merged into one event with a count." + "note": "Identical errors within 30 seconds are merged into one with a count." }, "sourceMaps": { "status": "yes", diff --git a/docs/docs-rewrite-plan.md b/docs/docs-rewrite-plan.md index 4cd6773229..5b44b22cb0 100644 --- a/docs/docs-rewrite-plan.md +++ b/docs/docs-rewrite-plan.md @@ -396,7 +396,9 @@ A short `docs/STYLE.md` that every writer and agent follows: 4. **Comparison page.** It goes away and redirects to `/why/`. 5. **Clients.** The docs and the marketing site are built for many languages (see [Send data](#3-send-data-clients)). Only clients that work with 9.0 are listed. -6. **API hostname.** `api.exceptionless.io`, kept in one place so it can move to `api.exceptionless.com`. +6. **API hostname.** `api.exceptionless.io`, kept in one place so it can move to `api.exceptionless.com`. The MCP server + URL and OAuth resource identifiers use `be.exceptionless.io`, because production derives them from `BaseURL` (no + `EX_ApiUrl` is set). Setting `EX_ApiUrl` in production would let them move to the API host too. 7. **MCP clients.** Document only the clients that pass [verification](#mcp-client-verification). ## Redirect map diff --git a/docs/docs/ai/exie.md b/docs/docs/ai/exie.md index a42594b7d3..e16cab0ebe 100644 --- a/docs/docs/ai/exie.md +++ b/docs/docs/ai/exie.md @@ -81,8 +81,8 @@ Exie answers from your live data with these tools: | `list_projects` | The projects in the organization | | `get_project_setup` | The project's **Client Setup** page and which clients are supported | -Every tool call appears in **Exie's steps** above the answer, with the project, filter, and time range it used. Expand a -step to see its details. +Every tool call appears as a step above the answer, with the project, filter, and time range it used. Expand a step to +see its request and response. Exie can't see data outside the current organization, delete anything, change project or organization settings, or read your source code. To work with your code, connect a coding agent to the [MCP server](/docs/ai/mcp-server/). @@ -101,7 +101,7 @@ When you ask, Exie can: Exie doesn't show a confirmation dialog. Instead, it changes a stack only when your message asks for that exact change. Asking it to look at, investigate, or explain something never changes data. After a change, Exie says what changed, or -that nothing needed to change, and the step always appears in **Exie's steps**. +that nothing needed to change, and the change always appears as a step above the answer. Exie can make mistakes, so check important changes. You can reverse any of them on the stack in the app. See [Stacks](/docs/managing-stacks/). @@ -168,8 +168,8 @@ Each answer also has limits that keep it fast: ## Self-hosting -Exie needs an AI provider API key on a self-hosted instance, and the plan limits above apply the same way. See -[AI features](/docs/self-hosting/ai/). +Exie needs an AI provider API key on a self-hosted instance. Organizations created there without billing are on the +Unlimited plan, which has higher limits than the plans above. See [AI features](/docs/self-hosting/ai/). ## Ask Exie diff --git a/docs/docs/ai/mcp-server.md b/docs/docs/ai/mcp-server.md index e2e9cbbacb..ce70415739 100644 --- a/docs/docs/ai/mcp-server.md +++ b/docs/docs/ai/mcp-server.md @@ -26,7 +26,7 @@ traces and request details, and, with your permission, update stacks while it fi | Setting | Value | | -------------- | --------------------------------------------------- | -| Server URL | `https://api.exceptionless.io/mcp` | +| Server URL | `https://be.exceptionless.io/mcp` | | Transport | Streamable HTTP | | Authentication | OAuth in your browser. No API key or client secret. | | Access | Read-only unless you grant **Stacks Write** | @@ -48,7 +48,7 @@ Add the server to your agent, then approve access in the browser window that ope 1. Add the server: ```bash - claude mcp add --transport http exceptionless https://api.exceptionless.io/mcp + claude mcp add --transport http exceptionless https://be.exceptionless.io/mcp ``` This adds it for you in the current project. Add `--scope user` to use it in every project, or `--scope project` to @@ -69,14 +69,14 @@ Add the server to your agent, then approve access in the browser window that ope 1. Add the server: ```bash - codex mcp add exceptionless --url https://api.exceptionless.io/mcp + codex mcp add exceptionless --url https://be.exceptionless.io/mcp ``` Or add it to `~/.codex/config.toml`: ```toml [mcp_servers.exceptionless] - url = "https://api.exceptionless.io/mcp" + url = "https://be.exceptionless.io/mcp" ``` 2. Sign in: @@ -96,7 +96,7 @@ Add the server to your agent, then approve access in the browser window that ope "servers": { "exceptionless": { "type": "http", - "url": "https://api.exceptionless.io/mcp" + "url": "https://be.exceptionless.io/mcp" } } } @@ -105,7 +105,7 @@ Add the server to your agent, then approve access in the browser window that ope To add it to your user profile instead, run: ```bash - code --add-mcp '{"name":"exceptionless","type":"http","url":"https://api.exceptionless.io/mcp"}' + code --add-mcp '{"name":"exceptionless","type":"http","url":"https://be.exceptionless.io/mcp"}' ``` 2. Start the server and ask Copilot Chat a question that uses it. VS Code opens your browser to sign in the first time diff --git a/docs/docs/ai/privacy.md b/docs/docs/ai/privacy.md index 7dc30a61eb..44bf19b911 100644 --- a/docs/docs/ai/privacy.md +++ b/docs/docs/ai/privacy.md @@ -33,7 +33,8 @@ Exie acts as you, inside the organization you're viewing: - It can read projects, stacks, and events, including stack traces, request details, and custom data. - It can change stacks in five ways: status, snooze, critical, and adding or removing reference links. These are things you can already do in the app. It can't delete data or change settings. -- It changes a stack only when your message asks for that change, and every change appears in **Exie's steps**. +- It changes a stack only when your message asks for that change, and every change appears as a step above Exie's + answer. See [Exie](/docs/ai/exie/) for the full list of tools. @@ -103,7 +104,7 @@ How Exie limits this: inside them. - It changes data only when your own message asks for that change, never because of something it read. - It has no way to run code, browse the web, send messages, or reach other organizations, so the most it can do is one - of the five stack changes, which appear in **Exie's steps** and can be reversed. + of the five stack changes, which appear as steps above Exie's answer and can be reversed. How to limit it with the MCP server: diff --git a/docs/docs/api/authentication.md b/docs/docs/api/authentication.md index 503d834857..b73a77c7c2 100644 --- a/docs/docs/api/authentication.md +++ b/docs/docs/api/authentication.md @@ -77,7 +77,7 @@ curl https://api.exceptionless.io/api/v2/auth/login \ OAuth lets an app or tool use the API on a user's behalf without seeing their password. The user signs in, chooses the organizations to share, and approves the scopes the app asks for. -For the REST API, request the resource `https://api.exceptionless.io/api/v2` and one or more of these scopes: +For the REST API, request the resource `https://be.exceptionless.io/api/v2` and one or more of these scopes: | Scope | Allows | | ---------------- | -------------------------------------------------------------------------------------------------------- | @@ -91,13 +91,17 @@ An OAuth access token works only on the routes its scopes allow, and only in the still belongs to. It can't send events or manage projects, tokens, or users. Access tokens last one hour and refresh tokens 30 days by default. -The server supports the authorization code flow with PKCE (`S256`) for public clients. Apps find the endpoints through -discovery: +The server supports the authorization code flow with PKCE (`S256`) for public clients. The OAuth server and its +resources are identified by the web app's origin, `https://be.exceptionless.io`, even though you send the API requests +themselves to `https://api.exceptionless.io`. Apps find the endpoints through discovery: -- `https://api.exceptionless.io/.well-known/oauth-protected-resource/api/v2` describes the REST API resource and its +- `https://be.exceptionless.io/.well-known/oauth-protected-resource/api/v2` describes the REST API resource and its scopes. -- `https://api.exceptionless.io/.well-known/oauth-authorization-server` lists the authorization, token, registration, - and revocation endpoints. +- `https://be.exceptionless.io/.well-known/oauth-authorization-server` lists the authorization, token, registration, and + revocation endpoints. + +> [!NOTE] +> On a self-hosted instance, the origin is `EX_ApiUrl` if you set it, otherwise `EX_BaseURL`. Users see and revoke the apps they've approved under their account's **Applications** page. AI tools use the same OAuth server with the MCP resource; see [MCP server](/docs/ai/mcp-server/). diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index 94e26173c2..d987fe8d72 100644 --- a/docs/docs/api/index.md +++ b/docs/docs/api/index.md @@ -129,5 +129,5 @@ readable from JavaScript: `ETag`, `Link`, `X-Result-Count`, `X-RateLimit-Limit`, ## MCP server {#mcp} -AI tools connect to Exceptionless through the MCP server at `https://api.exceptionless.io/mcp`, which uses OAuth sign-in +AI tools connect to Exceptionless through the MCP server at `https://be.exceptionless.io/mcp`, which uses OAuth sign-in and its own scopes. See [MCP server](/docs/ai/mcp-server/). diff --git a/docs/docs/clients/custom-clients/index.md b/docs/docs/clients/custom-clients/index.md index 2f834be7de..0fb6e53233 100644 --- a/docs/docs/clients/custom-clients/index.md +++ b/docs/docs/clients/custom-clients/index.md @@ -181,7 +181,8 @@ import ( "fmt" "net/http" "os" - "runtime/debug" + "runtime" + "strings" "time" ) @@ -217,6 +218,21 @@ func submit(events []event) (int, error) { return resp.StatusCode, nil } +// stackTrace lists function, file, and line for each caller. Unlike debug.Stack, it has no +// goroutine IDs or argument values, so the same error from the same place stacks together. +func stackTrace() string { + pcs := make([]uintptr, 32) + frames := runtime.CallersFrames(pcs[:runtime.Callers(2, pcs)]) + var sb strings.Builder + for { + frame, more := frames.Next() + fmt.Fprintf(&sb, "%s\n\t%s:%d\n", frame.Function, frame.File, frame.Line) + if !more { + return sb.String() + } + } +} + func reportError(err error) (int, error) { return submit([]event{{ Type: "error", @@ -225,7 +241,7 @@ func reportError(err error) (int, error) { "@simple_error": map[string]string{ "message": err.Error(), "type": fmt.Sprintf("%T", err), - "stack_trace": string(debug.Stack()), + "stack_trace": stackTrace(), }, }, }}) diff --git a/docs/docs/clients/dotnet/blazor.md b/docs/docs/clients/dotnet/blazor.md index c182d42186..6c3846bf43 100644 --- a/docs/docs/clients/dotnet/blazor.md +++ b/docs/docs/clients/dotnet/blazor.md @@ -35,6 +35,7 @@ Start the client at the top of `Program.cs`: using Exceptionless; using Microsoft.AspNetCore.Components.Web; using Microsoft.AspNetCore.Components.WebAssembly.Hosting; +using MyBlazorApp; // your app's root namespace, for App ExceptionlessClient.Default.Startup("YOUR_API_KEY"); diff --git a/docs/docs/clients/dotnet/index.md b/docs/docs/clients/dotnet/index.md index b22d1ccc20..d1a4d2d472 100644 --- a/docs/docs/clients/dotnet/index.md +++ b/docs/docs/clients/dotnet/index.md @@ -108,7 +108,7 @@ The source code, samples, and release notes are in the ## Ask Exie ```prompt exie -Help me set up Exceptionless in my .NET worker service. Which package do I need? +How do I connect my .NET worker service to this project? ``` ```prompt exie diff --git a/docs/docs/clients/dotnet/plugins.md b/docs/docs/clients/dotnet/plugins.md index 7f357a008b..6331a66b3c 100644 --- a/docs/docs/clients/dotnet/plugins.md +++ b/docs/docs/clients/dotnet/plugins.md @@ -41,6 +41,7 @@ This plugin adds how long the machine has been up to every feature usage event. ```csharp using System; using System.Diagnostics; +using Exceptionless; using Exceptionless.Models; using Exceptionless.Plugins; diff --git a/docs/docs/clients/dotnet/sending-events.md b/docs/docs/clients/dotnet/sending-events.md index 3166f4d094..773a6bed6f 100644 --- a/docs/docs/clients/dotnet/sending-events.md +++ b/docs/docs/clients/dotnet/sending-events.md @@ -50,7 +50,7 @@ don't need to add anything. ```csharp using Exceptionless; -using Exceptionless.Logging; +using LogLevel = Exceptionless.Logging.LogLevel; ExceptionlessClient.Default.SubmitLog("Import finished"); ExceptionlessClient.Default.SubmitLog(typeof(OrderImporter).FullName, "Import took longer than expected", LogLevel.Warn); diff --git a/docs/docs/clients/dotnet/troubleshooting.md b/docs/docs/clients/dotnet/troubleshooting.md index 076ec30070..e976849d8c 100644 --- a/docs/docs/clients/dotnet/troubleshooting.md +++ b/docs/docs/clients/dotnet/troubleshooting.md @@ -33,7 +33,7 @@ The client writes nothing about itself unless you give it a logger. Turn on its ```csharp tab="Code" using Exceptionless; -using Exceptionless.Logging; +using LogLevel = Exceptionless.Logging.LogLevel; ExceptionlessClient.Default.Configuration.UseFileLogger("exceptionless.log", LogLevel.Trace); ``` diff --git a/docs/docs/clients/javascript/client-configuration.md b/docs/docs/clients/javascript/client-configuration.md index 3de2991484..55e48cd19e 100644 --- a/docs/docs/clients/javascript/client-configuration.md +++ b/docs/docs/clients/javascript/client-configuration.md @@ -118,8 +118,10 @@ A user is attached to events only when you call `setUserIdentity`, on the config names or email addresses you don't need. > [!NOTE] -> The project setting **Automatically remove user identifiable information from events** is not read by the JavaScript -> client 3.2.1. Set `includePrivateInformation = false` in code instead. +> The project setting **Automatically remove user identifiable information from events** is applied by the server when +> it processes events, not by the JavaScript client. The client still sends the data, and the server removes the user, +> email address, IP addresses, machine name, and request cookies, query strings, and bodies before storing the event. To +> keep that data from leaving your app, set `includePrivateInformation = false` in code. ### Data exclusions {#data-exclusions} diff --git a/docs/docs/clients/javascript/guides/react-native.md b/docs/docs/clients/javascript/guides/react-native.md index 5061714178..774398ebef 100644 --- a/docs/docs/clients/javascript/guides/react-native.md +++ b/docs/docs/clients/javascript/guides/react-native.md @@ -47,7 +47,7 @@ Use this package instead of `@exceptionless/browser` or `@exceptionless/react` i npx expo install @exceptionless/react-native @react-native-async-storage/async-storage ``` -Add the config plugin to `app.json` so development and standalone builds include the native crash reporter: +Add the package's config plugin to `app.json`: ```json { @@ -58,7 +58,8 @@ Add the config plugin to `app.json` so development and standalone builds include ``` Then rebuild the native app, for example with `npx expo run:ios` after installing `expo-dev-client`, or with an EAS -build. Expo Go can't load the native module, so it reports JavaScript errors but not native crashes. +build. The native crash reporter is linked into the build automatically. Expo Go can't load the native module, so it +reports JavaScript errors but not native crashes. ### React Native CLI diff --git a/docs/docs/project-settings.md b/docs/docs/project-settings.md index acdf0cf2c3..212fb7053b 100644 --- a/docs/docs/project-settings.md +++ b/docs/docs/project-settings.md @@ -192,9 +192,9 @@ The **Spam Detection** section of the **Settings** tab filters out bots and craw ![Spam Detection section on the project Settings tab](/assets/img/docs/project-settings-spam-detection-light.webp) -- **User agents**: a comma-separated list of user agent patterns, with `*` wildcards. New projects start with - `*bot*,*crawler*,*spider*,*aolbuild*,*teoma*,*yahoo*`. The .NET and JavaScript clients don't send events from requests - whose user agent matches. The server marks matching events as bots and doesn't send notifications for them. +- The user agent list: a comma-separated list of user agent patterns to ignore, with `*` wildcards. New projects start + with `*bot*,*crawler*,*spider*,*aolbuild*,*teoma*,*yahoo*`. The .NET and JavaScript clients don't send events from + requests whose user agent matches. The server marks matching events as bots and doesn't send notifications for them. - **Reduce noise by automatically hiding high volumes of events coming from a single client IP address**: when more than 25 events arrive from one public IP address within five minutes, the server discards them and deletes the events from that window. This needs IP addresses, so it doesn't apply while the project removes user identifiable information. diff --git a/docs/docs/reference/client-spec.md b/docs/docs/reference/client-spec.md index 3cf6099210..4e3356b729 100644 --- a/docs/docs/reference/client-spec.md +++ b/docs/docs/reference/client-spec.md @@ -292,8 +292,9 @@ should set a `reference_id` on every error event; both official clients can gene ## Environment {#environment} A client should let the app set a default deployment environment and override it per event, and send it in the top-level -`environment` field. See [Event format](/docs/reference/event-format/#environment) for the rules and -[Environments](/docs/environments/) for how the app uses it. +`environment` field. The current .NET (6.2.0) and JavaScript (3.2.1) clients don't set it yet. See +[Event format](/docs/reference/event-format/#environment) for the rules and [Environments](/docs/environments/) for how +the app uses it. ## Errors in the client {#client-errors} diff --git a/docs/docs/reference/search-syntax.md b/docs/docs/reference/search-syntax.md index 09521aa453..59b9fa9e85 100644 --- a/docs/docs/reference/search-syntax.md +++ b/docs/docs/reference/search-syntax.md @@ -98,8 +98,8 @@ whole value must match, including case. "Whole value" means the whole value must | `cmd` | Process command line | Exact | `cmd:"MyApp.exe --run"` | | `country` | Country | Whole value | `country:US` | | `level1` | Region, such as a state | Exact | `level1:TX` | -| `level2` | City | Exact | `level2:Dallas` | -| `locality` | Locality | Exact | `locality:Downtown` | +| `level2` | Second-level region, such as a county | Exact | `level2:"Dallas County"` | +| `locality` | City | Exact | `locality:Dallas` | | `user` | The user's identity | Words | `user:jane@example.com` | | `user.email` | The user's email address (matches the user identity) | Words | `user.email:jane@example.com` | | `user.name` | The user's name | Whole value | `user.name:"Jane Doe"` | diff --git a/docs/docs/saved-views.md b/docs/docs/saved-views.md index c7b9670ca7..0a06c89129 100644 --- a/docs/docs/saved-views.md +++ b/docs/docs/saved-views.md @@ -54,7 +54,7 @@ Exceptionless updates a built-in view, it leaves the ones you've changed alone. 1. Open a view and set it up the way you want: add filters, change the date range, and arrange columns. 2. Select **View** at the top right, then **Save As...**. 3. In **Save View**, enter a **Name**. The **URL name** fills in from it; change it if you like. -4. Check **Private** if only you should see it. +4. Turn on **Private** if only you should see it. 5. Select **Save**. The view opens and appears in the sidebar under its page. Its address uses the URL name, such as @@ -74,6 +74,8 @@ Hover over it to see "This view has unsaved changes. Open to save or reset them. - **Save As...** to keep the original and save your changes as a new view. - **Reset to Saved** to discard your changes. +![The View menu with Save, Save As, Rename, Reset to Saved, home view, and display options](/assets/img/docs/filtering-and-searching-save-view-light.webp) + Unsaved changes stay with the view in your browser tab, so you can move between pages and come back to them. The address bar includes your filter, date range, and sort changes, so a link you copy opens the view with them. @@ -100,9 +102,9 @@ Under **View** > **Display**, turn **Stat boxes** and **Chart** on or off. These ## Share a view -A view is shared with everyone in your organization unless you check **Private** when you create it. Shared views appear -in everyone's sidebar, and anyone in the organization can save changes to them, rename them, or delete them. Private -views appear only in your sidebar, and only you can change them. +A view is shared with everyone in your organization unless you turn on **Private** when you create it. Shared views +appear in everyone's sidebar, and anyone in the organization can save changes to them, rename them, or delete them. +Private views appear only in your sidebar, and only you can change them. To send someone a view, copy the address from your browser. They need access to the organization to open it. diff --git a/docs/docs/self-hosting/configuration.md b/docs/docs/self-hosting/configuration.md index dfda4b7d52..a0ac18716c 100644 --- a/docs/docs/self-hosting/configuration.md +++ b/docs/docs/self-hosting/configuration.md @@ -54,12 +54,12 @@ Environment variable names follow these rules: The `app` and all-in-one images also copy some settings into the web UI when the container starts. The UI reads only environment variables with these exact names: `EX_ApiUrl`, `EX_EnableAccountCreation`, `EX_EnableSsl`, -`EX_NotificationMessage`, `EX_ExceptionlessApiKey`, `EX_ExceptionlessServerUrl`, `EX_ClientSetupShowServerUrl`, and the -client IDs in `EX_ConnectionStrings__OAuth`. Set them as environment variables, not in YAML, and restart the container -after you change them. +`EX_NotificationMessage`, `EX_ExceptionlessApiKey`, `EX_ExceptionlessServerUrl`, `EX_ClientSetupShowServerUrl`, +`EX_StripePublishableApiKey`, and the client IDs in `EX_ConnectionStrings__OAuth`. Set them as environment variables, +not in YAML, and restart the container after you change them. > [!IMPORTANT] -> Always set `EX_BaseURL`. The built-in production settings point at the hosted service at exceptionless.com. +> Always set `EX_BaseURL`. The built-in production settings point at the hosted service, `https://be.exceptionless.io`. ## App @@ -83,7 +83,7 @@ after you change them. | `EX_MaxMindGeoIpKey` | None | A MaxMind license key. A daily job downloads the GeoLite2 City database and uses it to look up locations from IP addresses. | | `EX_GoogleGeocodingApiKey` | None | A Google Geocoding API key used to resolve locations. | | `EX_ExceptionlessApiKey` | None | An API key for an Exceptionless project that receives this instance's own errors and logs. The web UI reports its errors there too. | -| `EX_ExceptionlessServerUrl` | None | The server URL shown in the app's client setup instructions. With `EX_ExceptionlessApiKey`, also where this instance sends its own errors. | +| `EX_ExceptionlessServerUrl` | None | The server URL shown in the app's client setup instructions. With `EX_ExceptionlessApiKey`, also where this instance sends its own errors; without it, they go to the hosted service in `Production`. | | `EX_InternalProjectId` | The hosted service's project | The ID of the project that receives this instance's own errors, so they aren't processed in a loop. | | `EX_ClientSetupShowServerUrl` | `true` | Set to `false` to leave the server URL out of the client setup instructions. | @@ -264,13 +264,13 @@ The rest of the limits, including separate limits for the Free plan, are in ## HTTPS, logging, and telemetry -| Environment variable | Default | What it does | -| --------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `ASPNETCORE_URLS` | `http://+:8080` in the images | The addresses the app listens on, such as `http://+:8080;https://+:8443`. | -| `EX_Kestrel__Certificates__Default__Path` | None | A PFX certificate file for HTTPS. Use the `EX_` prefix; `ASPNETCORE_Kestrel__...` variables aren't read. | -| `EX_Kestrel__Certificates__Default__Password` | None | The certificate's password. | -| `EX_Serilog__MinimumLevel__Default` | `Warning` in `Production`, otherwise `Information` | The log level: `Verbose`, `Debug`, `Information`, `Warning`, `Error`, or `Fatal`. | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | None | An OpenTelemetry collector. When set, Exceptionless exports traces, metrics, and logs to it. | +| Environment variable | Default | What it does | +| --------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | +| `ASPNETCORE_URLS` | `http://+:8080` in the images | The addresses the app listens on, such as `http://+:8080;https://+:8443`. | +| `EX_Kestrel__Certificates__Default__Path` | None | A PFX certificate file for HTTPS. Use the `EX_` prefix; `ASPNETCORE_Kestrel__...` variables aren't read. | +| `EX_Kestrel__Certificates__Default__Password` | None | The certificate's password. | +| `EX_Serilog__MinimumLevel__Default` | `Information`; `Warning` in `Production` and `Staging` | The log level: `Verbose`, `Debug`, `Information`, `Warning`, `Error`, or `Fatal`. | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | None | An OpenTelemetry collector. When set, Exceptionless exports traces, metrics, and logs to it. | ## Hosted service settings diff --git a/docs/docs/self-hosting/docker.md b/docs/docs/self-hosting/docker.md index 05430acf24..e91eeeb5ec 100644 --- a/docs/docs/self-hosting/docker.md +++ b/docs/docs/self-hosting/docker.md @@ -197,6 +197,7 @@ and sends email through SMTP. ```bash docker run --rm -it -p 7110:8080 -p 7111:8443 \ -e ASPNETCORE_URLS="http://+:8080;https://+:8443" \ + -e EX_HTTPS_PORT=7111 \ -e EX_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx \ -e EX_Kestrel__Certificates__Default__Password=password \ -e EX_BaseURL=https://localhost:7111 \ @@ -210,7 +211,8 @@ and sends email through SMTP. - `ASPNETCORE_URLS` makes the app listen for HTTP on port 8080 and HTTPS on port 8443 inside the container. The `-p` options publish them as 7110 and 7111. - The certificate settings use the `EX_` prefix. Exceptionless doesn't read `ASPNETCORE_Kestrel__...` variables. - - HTTP stays available on port 7110. + - Requests to HTTP on port 7110 are redirected to HTTPS. `EX_HTTPS_PORT` makes the redirect use the published port, + 7111, instead of 8443. 3. Open `https://localhost:7111`. diff --git a/docs/docs/self-hosting/kubernetes.md b/docs/docs/self-hosting/kubernetes.md index 66c2c62ab2..9be19f552d 100644 --- a/docs/docs/self-hosting/kubernetes.md +++ b/docs/docs/self-hosting/kubernetes.md @@ -39,7 +39,7 @@ deployments. This page shows how to install it, which values to set, and how to | `-api` | The `exceptionless/api` image: the API for your API domains, where clients send events. WebSockets are off. | | `-jobs-*` deployments | One deployment per continuous job, such as `event-posts`, `event-notifications`, `mail-message`, `web-hooks`, and `work-item`. | | `-jobs-*` cron jobs | Scheduled jobs: `cleanup-data`, `cleanup-orphaned-data`, `download-geoip-database`, and `maintain-indexes`. | -| `-jobs-migration` | A cron job that never runs on its own. You start it after each install or upgrade. See [Run migrations](#run-migrations). | +| `-jobs-migration` | A cron job for migrations. Start it by hand after each install or upgrade. See [Run migrations](#run-migrations). | | `-config` | A config map with the `EX_` settings, shared by every pod. | `` is the Helm release name. @@ -228,7 +228,7 @@ Trust only addresses your ingress connects from, not the whole cluster network. ## Run migrations {#run-migrations} -The migration job runs only when you start it. Start it after the first install and after every upgrade: +Start the migration job by hand after the first install and after every upgrade: ```bash kubectl create job --from=cronjob/exceptionless-jobs-migration exceptionless-migration-1 --namespace exceptionless diff --git a/docs/docs/setting-log-levels.md b/docs/docs/setting-log-levels.md index 16d7b1e262..cb88086d07 100644 --- a/docs/docs/setting-log-levels.md +++ b/docs/docs/setting-log-levels.md @@ -77,7 +77,9 @@ values for [.NET](/docs/clients/dotnet/client-configuration-values/) and [Projects](/docs/project-settings/#client-configuration). - Logs without a level are always sent. - With no level set for a source or the project, the .NET client sends **Warning** and above, and the JavaScript client - sends every level. + sends every level. The .NET logging integrations, such as the Microsoft.Extensions.Logging provider and the NLog + target, change that default to **Trace**, so your logging rules decide. See + [.NET logging](/docs/clients/dotnet/logging/). Exceptionless doesn't filter logs on the server. Logs sent another way, such as straight to the API, are stored at any level. diff --git a/docs/docs/whats-new.md b/docs/docs/whats-new.md index 3ba51ee897..a3bc61e481 100644 --- a/docs/docs/whats-new.md +++ b/docs/docs/whats-new.md @@ -76,7 +76,7 @@ they are saved with it, instead of a global picker at the top of the app. See [S Choose **Custom range** in the date filter to pick dates on a calendar or type them into **From** and **To** fields on the **Absolute** tab. The **Relative** tab keeps the date math expressions, such as `now-7d`. The quick ranges, from -**Last 5 minutes** to **Last 90 days**, still apply with one click. See +**Last 15 minutes** to **Last 90 days**, still apply with one click. See [Filtering and searching](/docs/filtering-and-searching/). ## Exie, the AI assistant @@ -87,7 +87,7 @@ it to, it also marks a stack fixed, snoozes or ignores it, marks it critical, or nothing unless you ask for that exact change. - Open it in a side panel with **Ask Exie** in the top bar or A, or full page with **Exie** in the sidebar. -- On a stack, **Fix with Exie** starts a conversation about that error. +- On a stack, **Fix** starts a conversation with Exie about that error. - In 9.0, Exie shows each lookup and change as it works, lets you stop, retry, or edit a question, and keeps recent chats in your browser. diff --git a/docs/public/assets/img/codesmith-client-logo-bar-left.png b/docs/public/assets/img/codesmith-client-logo-bar-left.png deleted file mode 100644 index 198bc6e5a004219f5467b65d8e66137f6521cedc..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 13663 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 diff --git a/docs/public/assets/img/docs/filtering-and-searching-date-range-light.webp b/docs/public/assets/img/docs/filtering-and-searching-date-range-light.webp deleted file mode 100644 index e2f899246d7397ee52ee36f3365987510a919506..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 18778 zcmV)4K+3;TNk&FeNdN#>MM6+kP&gn)NdN#aAOW2LDrEte0zOG1k42)QArWY`SSSR9 zv$uQtH0byPj6gqWA5b5}f13I?`Ztgs;DqD;e~-V+@ng9A`Y>};d*z0`@A)of;t9oj zwsO9gho_Jj75-fz)2_m5DY=ilZ1U;ps?E`N0Ynd|}Ot^1?! z!TrDfucltCN0R@sekb{z{YUy&_OI4|?qB>pb^J5sKd$~se^%!4*1zq25B?$bPwQXV z|Gl5X^3VG}6MjK|XZFqV3;56RpY1=^|HJ>W{@?q%?vJzcLjQCAE7S|qUzY!Z z{}KC%{v-Em!&|K)G1-`{^KKgECl`~dzd{Ez$J_5bi6?EkTU|NpP| z5BVPv52=5D|5yFH@)PU}`499z^8evK$$!rO9smFS|Ke}(AMQWOf1>}h{@4Hi{hy2f zmH&DFbN(~@hyO3}|Ns91Kaqbu|2O@|{Ga}B@xTB7{C(^D5&fM1|L$M<-~Y$+{Ek5r zQDx#m{^CaXq2r(S0c9wLJaS68g#>C*LA%2qCgpCDSgn^ZDAgy~h-_$w#;$US*}}K> z&H5Oi+i&8bLZ`I$(bF&Gz zolmwc!2(X3g8=>0I{B#Y7`Z%9_#Gf;<^fZV@mugeN-7vB;Q#CqZfbH{qGn0UBS&>( zP-wf>YAn1+O5(UTJ(`cOC7{CZ;fDREs4#xA*$@`8L2`m+d}yT)fzd)26zFxK$3w@Z z3_nE~tCU!gN_hh6M^I=+#YUbednSZ0NeMAEYRTq3U2kQ-j{Oa%C51kxfz*NAOszng zn7KPnt9YUCIzaCduZbbcnId89M>LY8xhikhJH-!y(H!LaR=4O4o}c7*FpJ<&qJ7~? zqoL%TT*V;EW2e!yr21XM5hnFg;r3=bPl{sMs!PD=vhf8CJ6lV(?AYMy#unF%n>xgpDQ+y7KF9f$>uV=NZ z2Mo#zySKLZP-mLn6X!UkO>#Zaz9@VR+6xDe>7XI1ZOot5SGkSH%hzpCP;8ivDpXyo zO83DYPVYN#Lia2vLiOT7{^nDUsPXy77kYvR^>Q2^+U9)PkLjpq*2|JbFkc0I1wh)=X)#N3__79IllX_A_tllE9^UkyHhEB zSCW%(m(%4D3DM*Nr~^}^G9>svs6%p<-Wg)0hE>{GhrXXY>QXg%t{>}t_Q%)FLu5nS z!@?+e;TTeFX1)7O!742QY30$jx|utb8e2h0n0d@3a>UVq1zapmh$B)jTg7N|!0C2p z50S+kAN#~B&f|9*F3a$G_#2<}n5*?~zi>d%ok|J#A7{euR%=5~>{KB~5yV2~Ym%51 zU;F;c@?wJdVW#%2BPw3jvM=o>8-%(w-YfVZ)sHAES;gX3z>T+um-Cgm_&4Nq}A~>F9OtUd#tR2St~O2oFudvH%Io2vShhU+!4H zS;nB$D|fqEEs&1Zx#Z9+u~b3o^ZJ_{Z1>Wjq*?~-<`m`BH$;wOf{^N?HqVH?TDle! z>NNY^nr%R}7%2)Yb8b5+=Je~siZA|q*I8n*JYT(OWo*(DyDpHL+HRQYn%Y*!Bjcm) z_vcMc54d5!T;Iuii!V?S)6GzzmOsG!!zf!sH_&w=TtxfsFn5xl3y($uy#%NKi+!n7=kW5B=o3G@X#ZTo2t9YtJ!J4eHBq5JF5xF-Hz54_?6`DqiC_tSqhfK)#a=qB0&&3ac(P6dMA`t1}NbJe)8BBx{@L=9}>fRx^WkH!S z_#cgP*rVKy$68j=UleQ&j+_v)g92Y)r2-|svIm5QRJ~C#lrnu!le7ZRF77_%H}23( zp*daU`TBTJV7>lNAwGno#ggw# z?9~xQ3cgc+y^kwd%sa#u`6DImj1ii_w=n=fc35G{FU?lDG}-1K-`lCR=Klo-_C(>& z@o`+Heig3bD)XEWE^8%BQ0M67DAjAnQO!FFj4U$mCkF`)@1&WuK`YdsaO%>C1E-JM zkq~i&F39P`@*M0Y75>i6mO1ZRDC8Zt*`ptd>MP&mV8nYM!oA5$k5aKB5L+Do0+%qv zj|=J)W=_4}s9t8)M+nQuzqoSsurETQ`|ak^BHqF>IyB@q zn&t>V3T7oH8w*frTcq5iR-syK@i4aWc*f^JPStPH?J_Ku~< zsIYy&VVWWGJntt18u3+;>TSz#|B+h<1#L;JI|u=~R(f1^hY-?;G=E z%Y}id%$Y!7NZv5- zYH5P5MLJ0;+}Pcv_pNz;ox1?YEoIUWuf@% z_I^(ZU3D(bq547|!z*Z9w!fu}zOf{5QEq^RWlU0OFBV?t2PsBH&Uw&!>5+~so8;*+ zwn`fM&`Y)9pufvZ1v>>jpr%L{G(M>@{Qta?n&x#juN>DDR7l4G5wgI(O7(?=D% zNOa5BOqH;iOs3QBko8*WYboL187eU^i-Wx2Ulpf9yHd!jZoI|%f=Bbmqc%VM-H7a__pqYf2b-cCT5nSAV z{KJ3b$n%Q{`3e&fAQAM+ezMwzwwqxsI1HHYYTsPsLr`V1Ib07ZqY4H&Zv|<_uRc6) ziHpIA+(_@y2kFY|5Q>4m>qP9(jwqZQD5$NweHQxP;DnvNKALQm>gp(Aed5|tPDMR!?Kw? zh;dy9%{4olqN&oCmV3`CCQF!}MGJL(ENymJ9P_@eDCLOHHzB=sl2KTv*KN0NOEEvw zDieu13w#f0O6z>H?TgwaeKgMB7b)X)>;U0;nRTBnO${tOxF5Ui?i)dAw~wW=euyIc zla&9Pjtgx7-ykRfhvq`9p!ENhJt(MYl4Xn0tDTu6S&+TFTs>f%7DsNgi_3m-6_;7U zY~d8<*vHYdp-ckCT2E8jlTxmm13T;?0Hq_7lRy2MxU;9(JJIPkxXP7Lk?VNH?A0>A z9Q@0bmCm4KSNw1JL;ZIo6|NotdiJo~$Qbm#52063h1ctD8ud=FEd;WYz`L*+Vq@I0 zcxrI03J%}5&-gVfeK3Cx>~aRnJmj;js&Ld)#s*Z_Gzj>WJL9X5Ay3}i@Moj z?zULFt%-spcHm6zhUQ$-m+F;M7GZ;cN`XM-)TT`1rZ$g=i@rTN9u_AR-T(RgYVw>i^h z7G2`Poc<2mKC5cm`tdk zw0_Lvm~SluOcm`T>SYsMU(p$|(UI-rjVQcM3cQUf{e;)|MV85FcuI$( z`Kb5_?Alwhi?U?r6cH9P9DVj0+w7R?0n~>xhl!#pro*{?hO6Zpk~TOk{$){jm*LPh z6C9>@MWZb`J4I{-asgfNVPDtONsq)lY}*zF_V+44D#{*M-8-=8EyrKpWt9tlh2o$2 z=Qdt5O$b-X-7n|fGMofsayffMNo3BM85nP?=90``2*Wsb!aK8{}cdiXud2bq&Lb@^c#3a`uVB6Y#D2 zSo$dZ-=H@>)RC8l^}lF63BJld_pUX&;%4!ymIuils@+i#bJR)gW5)?lJ*#UFvYXsb zIKz?%dx_unmjN?04ii=V{7@;({VqSBPXkzRe4(_{zPABt4vS8=f(&6uL+1LEj(B0e zpLO)QAZuWtOKPMoX+!z>IF%Z)WjItb=v5?*_rN;}_bO1lYCd!Of4c@pJjZg8dPj|1 z!mqfs@vY*0nkp{nZ^Ry!c#TK&Tv4O$XzxzGIKwUV*HysSDh&dhrb9e%%ybInOl3QR zCxqZ|{%(-4e#Bf8q6|T(ek#b8%VU=#xM0YfaMH}FcXqnQ`2vI4bu$9%XiTU7zmBjK ziy=eAj1%lI24OH9aE0uc5!FdbR*5+SRt|^i>`KKDCNhG1NR`MUGM^i7&$8f8ZGwNZ4VQ z0o^}(pmRB@YR#DY6`-JC-tQ8w$6X~YU!=Tw@!Qzg=nHmU7x>Y6l$}Wi5S3?kY)02k zDN4bk{Wr>zU%QF(Ho;XuYJ^%PO{(s$o@3)s%5v$MEk>60g>MAo63?hNnabp5PF&BB z(8}y$ewoAPZR82D<;Uhx@6d3G4SvHPc(E8Ahu6}vgk`GSSeoXLV;T>Bat|R@b(}&! zr)8<_R{(i1QL?v(@=WTGvUdjxB@vVn4pa-+69p{-J=43KQP#iao7T-BQ#pCQ3+*S! zPp?r?@9%4veteB5dI81T2>gO-gF{5|c)(pdV6?EZahx_CU!0N1hwd9QzO`-adRMd| z1>v2q3hbdtd;kIzrV7?0KWzu7-gU>?wgN^JW4H1fj{bIgt5F>kBU!F*em~_RK3!%u zAijQI$|Zz3J-|7*u!|Lpb0TC~sC&SYPtJcb`)|tl=h&Kd>d&O=w%Q9xVSr4ddA(Fo zf#!`{5{T=Kj)wWZJZO*u-dJOL?p@Dx0gv2pySQGynx*-5*L@_0##AgXKe{bwpKys# z`E(8uing&1zyNEdw3!4t6^&HWHfpUxSsmL9``SE)&txDAD*DVb{6C#|Wy_%;ei=9L z*&nI}arGgC9)2ROCl-c7P-a`%I&70m#7U=()0o%{(}2Wo6&{opZvqqC^L>Na4QAd=z}Wx~>9nNUH>nG|n}`c7*F4%;7~zF~#kVJI@?RP%YT0K# zKgOFQ^NCj6Rk(BheLK(NKhgcAwUA<+(kEV1mmiC1eH8k0AwiX#YML8K7^j@MV$?$u zFJyC?0!Eg#VOH8o4Zi~6+Js)4cHt9HzdzFO&D=*hKZ-CG$~vtuomAO_Ay3SArsUyX z>nuk~6hkyCp?lWFKz!1u(;S6;&jP8wf-&I=?O8Mu2dOw$CM#GVVhxn(ft;s*)@%ky z-U6ndZWFVHlS@Nslb0)4cV5>7%RIf!&%Jg-SNN{{@F`MuZw7kv9#9~b-(Y72gg?8J zuZ`esPenW*>>bTw`$1`h5Vh{k5a+rL26`Ii_O+L}ln#bce(C(jxbOL~3SE0~PqL?x zW}Lpqlj#`GTwYmom7&W#Y@jXozeUH~pk83=897W$M4;H?b{x(uS(SCfG&-1U<2_{R z3Vptbr45lCZ81w);_#3e^HMVmaJPWL9zQxj+Nom1GeG5q=+OOa*|1Q55#RN2frY4r zLCbcm)%>kV=kz5!GcjzS7=}UQ^@gPbczdwN)GVI@d+2N*7BEPR$;z+A5x7n&?W&mK z6`1qu%y=)CUpUmeocSW4H1fj)v?)Wn{2f zZ!`u?qq6PDm*{4Jb{zchZuU^lj|h*~+Y$nqVS3{cJ2}}yxYSm+Sh2rF$K0S^VCyn@ zS?xashFCLgVZFqten;V%pWERv09wG4S zVM*WwTU#dDDNw#O)>V~KCYkY1wl=u4vcW30v79cHI7P3vj8a5*G%yPr!$M9(#k0K! zID{;p0(Hj z2$EOHL9uB0lem|hCi}$el(<+K6&z<0?L~5)y>8h;mYI@q`=!HfsS=GH<238l&DCR! zS7MhN(zEDnQv+rIFyBrMDpB&OI~2BejwTm5m{Cdr&0h{~@LYr~xG<>muv;a}doUa1 z!@Ezw{0*iY%Sc!H4`XyTw+diF>C{+#W&~T@Y-IRooF`mLu^s0BM8u58L>OXUO8Z|w z);{(k57D*VhY`s2KGGc8C;X|S;C$=`jwk_6pZkwr5jBu~kzc(D+>pvnf#86iXFh54 zrffE20)U3lFsY(=rm4V%PM_)8fPhkv<27~U_EV4&-Rgf=2KL~`CW%bBO{JOJlg~3; z|4^aGBDqH-hXU_?t%f*QZJ)&2i9^A#=sI>7st(_p3sQH(E)`mAh!5Qma)q-&T z-aED2Ky5r|ZA^rZ&cWjh!@j3oE)IK2>QTMM9&YVnOmx2{5gZt-%ng&ZlDm8v`Y=Cf zIqDsFiyzy*gd6N_C8(6yUN>Si{J0+kb(7q0C~CQJ*~)PU|XU4;`e>6{PPiBgca$ z)FZJHax)uL>~F*HlE30T!jgAo_KHw#q>)CJSDg%>0!2{p4&*HVDJhzol|borq*C9q z)+4$q{VvN~r)S)@=fxu!h#e#X@K#R!VlW1d2M)*FD^OZ#Y()rexQz1ioBq4yds5n?^Hov)!+RMSf={9}VHrG;;y- zP+u3)V5H=XSB)k4%2)g6!Kd&XE>t~wkXZp`=BMz|2XYEVi5RnO+9T?K70*`bGW+Y_N3d;|E;FbME(nivWBBBMtD|BK+4m@%|y~or|6y-m6-(v08MK`aw!yV>u=J$9;qZAgDe~ z-RJM{yX97q<2N4>IqDglK6c(fn;u+#Wgh(p2$0w8G53oRf!KY0D;P#vt;LD1X$CQ% z_vaw;6<1lrBl>n)>Qy5WI3hv4CiZJGR0dd>xU=0Ku!Gm>a~dh?`IBmC1FlV*`~`PO zoHN9M>P{8Oiq;Ks<%tL1l-m2<7sup7hzSYdw6uU;wzQ4F4jm3Nm&`knKGXfqaDH5w zP%*LO6+-lXqQ~Go3RB&7=`l#UC{IzW%_zB*#OxzBC|goYJx>z$z~z{fLOVMtyjOL| zuy+)-E-?7s1F3LuvRoqA&9a;UkxvMRp(3-(Cg+^{EsR1|MsNF90yBA{g=<-Tzzt<3 zEtqQ}ot>wLJB{W$-6ExtuSO`O_2+sU$o?7Gp73Aeq94|jXm2*0qIVGRt@<9l_R^p} zD6q8%0XC_YttXMQJQ(SdmSBe;6vFEu_m(e+dWO7`xeKEShz)}tqL#+Jn&JQ(;jby+Sv>P z4*q(iT~>?00LNX=px`^K3UEGpvL>1FcfP&tb=%6)79a*vT~Kr23vP`vjUWIi%kf$y z1cJM$tpB*nB>u3HU-}DmtXJui2L5SO8_eZ$Gbb)*$Y^DDF@s!itWv_}Wk=f2A2bAw zEo#E8w3Hiu1;e!ny*BN_CZT?RrQw^nj&gq#U@eq&T46e>7cp-D<$oE|o*j}eQ;*Dc z0I_I|siHH7Qp}7L@WsaqZ;|tT1QXL`l6jk4X3GUK&)JSyd>#>|5f0Tkr|0%wQjD-w z_%sEN>PzY7oq~bz+cYyJpzwrIu~ORPEU@BU(%lLuAS2DyjYsuchwUQ%aXA7rA22~l zN6(!o22!lo`m?k1XFbGSm$ENDkIXJ>-Lw)HcfQWLR*JS^fb6!Tr4HWXKqpa@%alp9|?QV`ZxE|CLR@v}O!&ki!s zKxMgC6IFYGJ+;xBb8xj;9{Euj?~#SLtk%c~n^Wa*bz3}&ZXRxsWK+9yrF&8m^^}V! zOdWaq;c2h1mdcJg{YcPGzZ!K_Gv}w?RcM#@fyO+6imcOhq4K?T9j0}g zz4aU&DA!C<=ZXPk6IIvnc^uJUoc1Na+WLd-NTfbkPHf+y1Zk2oos&@+JXR)xywJtP z);Jj<{!DgA+m5_}BIBPYqxghZEN5>cKe*I>DFa?^Z|tM5<5{~u(Pt=d!{nd(qQDme ztta&X9%POhBa!K&-lD(W+m|_Gkt#u;g+@>qdkW78kOi@uu>Xc=umBjI>}pMAxSxlW z{*% z59zO%a_4Y-)qgWks06n~J?a_#^#|~&yv_h8w`{6i{W7&2lSlau6ratZO6Bx$Ab~Z1 z!JQ2ae*>NY9&Rke^>e_R7nJtd`Ps<5etrF zt|Ct})-3*KQ9CtW8irsTfNm;WWXUQv6~{5*`AxFR25-M}elY2WR2{8$6f*P|h`*>?PLO!esZ;-?Jcsl_6SzqR+2Xm&azm(%*NPl&?8-){9ol>NEn15_Bx- z`A>*^P^w>{^qy6&HKDioxS;FX`H_hzNka<%JjeUXm{>WEsh89A8)QIzyUu%<*YPUF zLV~Q47rxZF(FCP1k}Qw9`E6aFQG$$0$bLjz;Sc~hPtOQ^3pO4ZRM>_;xXNNZLq^Mp zcgJv04;lyQkQUCiYvh0-a;Q|(25^vn&Uso|&+_!MLg^{iF5EyQd5nXs_*RJsnqxMj z)mkUO3%DzjnQKXIV2r{x(`-?=u)oQK;A$#ICFks%F3uXA4B>5nO)CTjocks21Lo$x zcY{bey4{erp!{CL1!9=Q$Py!_yZUH?}}t)4IA8P2IJ3 zVNN%{EK-pmF|YN)!1G@k(G!Pk0QBn}Bw#&7BL|?q(?tha{ja?UjL}f z0>RyfEcz(+g8s!_|8Irzt?bfcnNnyfzYiSLvWX9Aslz|tWM@mt&`bQOr+tZdhWQY7 zzZd1md#H6Uv=)xU(F5^N)3{BUnuwpQoPiLNdE#3f4M8y?W?%tk_*n6_YTFwriXtFs zDsMA(EO8hE-~7D}EQ}*9?S$jIwk?Ie#&*bAm9b=h$dyn;`oq0wf5}ACgbM|roaB|%)}unK#XubA z8acLN7lOv-UK81~jo&=Za-zzHuu_2osVnrc_^!|Vht@u8KJW@4t`;%fS!bfj6K{m_ zV9)|~uN68S2*Ls4E>}1QDrVMYG3c8=+Z|#Qiny1Y?c!Rki&GzouYHwIvgt?$;v!F| zTt~MR8d~jRtqFlv+ZhF(m^@R*JXz8CP%Qx#NEyms5$VwYLz0n_za$kdnQD0(zI2)T(2m3Nt4X zUVl=DkQ7Qga>2mWPV=(hrQW>iSJbyBakgnc;#rz%99VE1sB5+~nS*U>m!zK9{Xsh` z%E%d%t0fqfv+$D+ncpUyW3yZbEp%={$;~`&I~VF|;Eevk`(JgRbvHM{ zcRtrjThU*?6gI}u4%vK)Me&)svs64KW04PcB5QD5J1#`5NH+oT8uDJa%(;6j zB^Vpm8=w$U*hbN*Z|irqM6Ts)P^Tfy{(mkRAmCnxhw5*a{z1d3k|ZM8T_Eex_Yck$ zZb>2l-DIWKlVn>NA?}PR8Ed(!qbitL%YMOPSkmt-` zT^gu)XKAKg1n3&_n6T$j{i;4_*nC%&ch@9@{^9U{@Bkcf?)Xu}+e22mefwbuS-eZZ zu3EtS{yhgGB>z3XQcgqwZ6L>fIo8Z|;N!)y<1U|t3*S@$brf-d zQ2m3ZSAtf$e_|N*FUF__)p`BK8vc7QtpbJq)FV(LR>(o1drFp5@37+3TN&p6HHA+8 z)%zEDK?zg31K?QCxKfQQB#7CQ_T!?s&kdmf4UHH%TWXIGi7~q77eTxAdG*cIB*d{K z{55-l=N;f(jitWcLnig$fDOgeuW z-aiw=$rpy_m979EGoRf)O)C|W$@O~jZ;F&+LC!Q1Z%V=EiQd}2SLbLv!a8q}2e9nxCq4D3%BM;Iwsm4|u; zCmz&IcNcGBN7CERz}ZL)%Wy3iq<4>SZnR@vReRB75u}iy0t{u*JP8T=`XRK!q7%NX z>cA!23|VKDMBw2x4pcxo$7z*2yiwtuz2Kx6-X>w~1Lp9h$a1~7sd8JppoR3h#$p-Y ze*4nJkcKc_7Za_cd2~sMkPcEEeiK9bz0c44=W%*XOyTtRT*+8n7GgtG$h@YkUjK28 z#@l9hge_;i7j4=-smhsB^wZHKD1z{YMGUt*g3(fu+_7&63CaCmc#-3DMpEN5iq5Tb zeWQzJCXG`ZXX2CcBeH?{yDyj(yW$$7YqEN*Wc2Z?fLP`>#Q%~6*J2$4UDfQfrb*F| zy&d-qmQU)duXRB_@C>t(y?_2;6-BSNs6-kZ!5>AA9s>EKrG2TE6vu{o?q>awiF5zZ zGHo+sch_-axPHYsRNT6KYqlb@32 z}TBa&P}%GfYIMtGBsSyb1H3vuLiT=^^VLTD!t7t|5=tPhiAG3BhWUD;rcpI25ybwwOf;c$1#>k+)I=1Nb(%Qxr!0 zn=>d@*PfqX@MbM)RHwGAz?ShP7gzmaN?5gx>ZC!c8;76}JT!>!Y!@-kr#3zxzkxCA zRVD&#Gs|uPIz-v{*GeSU_H1sL<6~jAz}`pdyn4bsgF|In{mDY5)g%9jpX)NZ--ZL9 zxYMy7Tpbs@aPCBX!+f*`)m7KXt;u9=Dku;c!fB+_-H$Pjn15Kt-C+xX+q+-x(fH}y zXqM09-{659^_p}9?Td@7q|;DCMSWM27}WNdn~|v+TiEncwNUZ` z0ky#0018ZF{V~$4A#JQXY!3N}n~a?nmPdYfLHq%d=wE2UdkF)Sf(#DNOL7W(L^5q@ zSk)M4{@w^kk@OY*BH(Vu8e4XFz^I51`p7@*jLjYBB8vV##}nDY!?63B+yHM8MF5jbxH1A{7`F!+7ml zDKkhtX)LPUe>Qw8iN@yW|ICdMQ;aW6K!)2_e~FehOM;XD&rt5vZ+A#+#0dj4x;}c` zA>?#Hkao(~2;ZAiy>*t39%;8YN$V61lckxmCFZBJvdsBQ{CsssklO|&(E0qJjck+V zNmgmT#aP?)FLHqTSz?rRD{x=h{N*Koc=;(ni?pF%4x>_;q?cw+-LjM7!p{i@78zpu zz3BZWLCnlrnszES0OXC! zvo3N8td#=E9mzMj3xXAOexgM05Nrb=HAN~&B2C0$WG#_)S)JOY7o340V6Fp*I1oHk zDw2B@`65fJ^y9BxQFqEIS&|8yjH_CWv6i|R8e?bN697vvvASd> z6;CZ{pj)RWt>ZF9;+nf3cB7M?$?#XIzRSxv000u>=mrTVzsHQ{<-Dz=_(2MVAbwPXd6Ys4l69A8{oeBfO(tP1NF8`7 zeN0#HXuv`EsBoIdplh@7UqVv1LUsn$GwY1pB7RpV$7p|q3%ni2;XnyYR0au4%qTq9 z^EU$ShmIT$N%(;-{LV|lQZOq@qd1DKo-yIX{P8>Lbk7|KF}8ZSUdYTOhE~B08#mhd zm8`5MuQlD9Ghx{j-tu1AU%b6&Zt^39abIHpb%dI3j(n_-s8dU0@A7*Teg7Y<`mL)bAX*=^$(A^0xWwhngtyLrBskfZ^9oG+N@e!2=!D!l%!br%%FyVKVMMUf z5zs~)i*B`Ey<=R~7D;1B<_L4Qr9AJ7fj-RixqeOOtd@Bb)$y7_ew~W&BZW)IVt83Gt18xAk^)TL zt{(gK_#trqwyiQ2UsNTmztF1=d@^orP=8ukMKTOIVkWxD!!)ZXT^S>e?Cz#<+3Wzo^tpj9z)qd+ z#-!6Qb{Xxqc;8!q288MYb=rP2db!~7!?B^oy_f5@AwtPG7+Z0hZx`m)hCG^Hgnvo` z@5tAq`mo%$f~!f{NL8LeKXY)rt5x}zt1jmtulR=O{}dx{`z&O#B2~E>;G5Fv`93Ag z59?)iK$hQtcj9^)lsl|}Lu$yGsWD~UK&B;h>4qagt)s%BZ1O*Zjr?$R_R+2>^u2j7 zd%a4L2xw4))GMyHT(RZ}$6&j_JA627)(9LxfJlP$T_ZVz)xzH>q)er^v`thsF%ro1 z*5S)KzDF6in6HMQW!CCvv33{{!#=xl6tV@=#;Da~iomgY0^u?>7IQDdGAA*Cuhv-r zSsb;#Taj#ptGo~nvlIWwqB+IA{lO8o3t!&;|ElyJ!<}_9w+&8|ab%1&i|+xq|G36r zU`FcMM#u@6SRa*9a}@dZ9l|jw+}}uZLk9f=yo0cPAT1)cG&e(tz0b)KqcKquh_>YQW}k;L!Pz`7Qs@v%lrZ2J_DOgb#sLjj!6_I6?%VYQ5F| zd`L~wkc}(-mf1OP4GVwmFuq)|vRvbG%t$J`7J3jrMTwHvr`^10nDhP8LTT`5eabhm z@CJ>StF}#m1}mj5`5HPOIZ57A>6o%U>*ck13ZTh+%|Qd5Yme1zb%%O!d7W`bD$1iF z+R-DH&>TXrxC`$=|JPb{)@O`ArK1ze{Ol|gf41D?^GSjIW}I<2>0XiDOY|I{(R3S{ zMX?bs3=%bn!Q_~w@#G; z2x0Tu5#ms>C{wA)Ckhig>SG2^Yg|WYrK}t1os8{-=TLN+Qb)3)+4m;%R=Yz&MP zkLm=%2h#^6HiGTnwRCUyl;v-z7#D)RLDS+eY=x6+4_+TiR8)WTtx|k z20@Wx=L-;7+%rf{nvhW;`0$BiW>_;;8B)`gDFx;MDJc#AN z)$Y*8g}NGwUr5op^EHB75fJOEVzN*TQ-82fBi~cFsA>FzkJXXNL%>0QfImdLrK=Ju zBJOg1qzcOt7@2pf~3zSf;tZd@3Y5;WJEg=pCVdQl$9pE zt#-s`jIH!5x?6{X-0jKRYmbOXa2)z#!?;*mm;UcgL7^^6y$Ms~2;8$!wS6&6KAOb6 zA`^J=$C4`qW7MzSDo+%nd@KJ7!-rD}-{Ss%foA9snu6_s2A$PEXmle82Z*^`;2f!& zS(L}3Z2fN0tquD1UqUOiy9p9wIOd&0gpr4tiMav&nZ8%$hne& z7^_VQzoSfVsPMIyGoiH{pWYSTqrA>nBgyW&wI#^2RT{+}x_C%Wx}`KWQ;FI|We8Pn z?8<~IM0yn2JqlIxoY@(u$^0Hy_w9%f`uda@NTBFsP1_9xrHYPxstaWH0u%9+aH`4PVv)Su&S3@%d->@XYPUjPt z)Ic1cycT@X4!-1i114WlNFL+Tw;(8gWBx7^UBQ>8XN3>&zbK6OU!uMdQ)3W-rwYzo z5v$OmOXNz?qCIa!$Z&F`pYmvf#_qVbM7bvcTz@oBi0z2MkH6!8ww3xj77;l-up%} z{_sW%T7V0>JkYlKSa`07=r+*AM+{H5iyrnl9j)r(xlckliZo{CiERxf$aaWOUGRq- zjnA*B*L&nbN}l21qGsS|%%x1=(+|K*-Ip4rX-VWWHk-$`L4!7tQO7GV_$kK-IA-CW86z6&pj$!A6LbB)pfuiXZ#dS(u^V#zf0~THIHL*CpEeA zLYmK^$IjF$UuWq*ySYudwbT7L_~wEmVh?3;1c1~c{yX&H6IW#Cx)@=oo|5heX`ZC{ ziRE~Z!LCIbmxl1FrUwV3~^ODDoE$4<1EyfsvLK|8P z2UljQ=0D(iLhZZ^$6xk4SINWxwd|{;762#Lz&rZNFNjNlC*3U_*0vw_Qb!#Tne!2e z3FPnie@p7npfo%8>PYF*S3{xXBUu=S?cYdGWp%Z!%y?B!TjhE1S@9&Aj?z!1af431 zy6my)bZyRh5aov4$Ef?y^1kvQMN1z&l5e=_+HvbdiTTF-N37SdOf;>{+@*)O1Rke) zDNKs>kDp$PXmHHS_^ps7t*_DIarglgyjUxErgb-{;X*C_48S}_gjcUqH6HTX8Zygo zhWX(iM+NYI@BH{ghka#x{X{qfUF+z=OKui|n8$t;YbRqYG4-r3|3S+mGeo*eb$kwC z2JrgiN!J&A;r7oE@qM;hN*-tP<*`Rd0sw7OuO5H0p9_jhN;pu6$MTNE9RTQZ8e+EIQ($;%?N2`t0+{~SDJbH5OhTZ2^Oo_9qN+Fl9N*JGU8!?IZ~A)-qyfsi0# zz|KmgRd^VXTFox|o5zkJO!FY*;GXwYcJea9Qs-6R^Ngk3cmv}A>Yk+@O|xSU z@;{>L@=tzoYw=A4AO~=sYwx?U;_bj-f%ovys%O7dEz0d61J=W;>pPrhfK}onpv+0S z)kon!jZJyKi=)B7(C=SDSIStNVw#UxzPNR8e!`^hc?~146vCOuia-8=8W>Z#%3ao^ zqYeX@c@s<|mD*UnIi4B72Zp=y>dXjvASIvQdFMP;2RY-0VDDO}`!Cyn-J?>9l(W;& z3h50EfU}(v?~t$=fCX`BOY9lSX=TVYkMg3H2)Z=7 zBdyAuFvMEn>m{<5+(1Ke=|pLlCS3v3811w+gMh&l{O9e%n6^ zc>lDMh(qWqy^&JD^66`bC=1IL168>*YhNygG}T96M$Y2an`{9Z@!Ny1+(MihdMm~)3<*P83>Ue)ITkp6anxAH(Xjdl@E@tmlGVeA;qd4>u?5zbFBhPM1MW+Mg0v}>T zZr^VVP(`3gQ+~6L;O1MN?*C0M%9sHykhp4dgwBWqRgc+x{_xxvXQN*#uX$*`-TeM9 z^z@IKoN{S_N#Z;6jNutMmI06!y_X!=-WK%_0>6tG68xTph=sj-`gz2Ri{YB0?-;?c zs2rq)chXY$i(3L^TVfV32@}7Eawy;co2+)lDzP$KLPEQ$J&!9(wP zAqo#CQ8Rq?tw_TWwF6>v~jpf5XFS zW|yzQ;DKmabV~3%bKhjVG*N#wgnabJsXhG+bKJDQEp^(5?DtqLncpDp9lv=o z$cl#vR5KPZ1>ioLFtcRK=6?_?TNJt_X)|EQ31K*n`uGuCmPryOqCF^%>|w*_WD@?(5! zvS(1|#$K|@28F}4GFH1ulf%`S_i`O?JDT*Gd!403rO0&wh4NDNQ1)l%uXk`Ralg|r28#YN{~dMp*PhZ!=cXV41RA{AeEnZ|mD0j$ zy8&z1o0Arf)W3CP5B|nZDU&VgAby&*>a5v128`8UKDRWb3Q~BdkY^a9dG5`aH z0ZG|PO=>(a4izNdu7#s*Etwt2cu~cBWZL1#o2%^fOUXjm( z;$$nI!J!CJp=&{_t^?;&J#nV0?J;^#SiK)-9h2fN86ApEXre?(r`fiA zqzVMUBQ*-gu$A?ZwVBtkeSv0*^<{9)VyMKD&8zWxBWmfM>Qb}s z#W4Sg5mVB{4z=_dpN=q6sSd-`JxMOZ9N6Z%zx)ES* z@$zUyNY+X|C-E=w+#$9&;1(NhyCZjuJ#u&64K1ROydaW^EX+C=Nsu__U^1WDc81Im z@+jZb3n4SjK_4IM2r$;XmqpH(q{xTrA1=Bm=(XT7cCy3Ar9a|?a`QHr?@Ga26d%B+ zq8_=~FfkOTD?V7rNrdE6Dw@>#-h3MIdCY56eA14i>`(!s$>@82wY~9-fB;TC6QofN z$8S$MK8Li)GJ7uSl0Y1unQ1LtX~cA~5iA+>u+a$LI7CKOJ)B;M$lqTI&|{Y_=QqCU z$okGvHO8pRP^0_9Toom>AJuylp6yHVbi&le)REGTswx0M!z3WYGgqMlO!_{a;R$9; zsWo!D_sd`p{cZ{Ii_u59k@DkcYfCx4 zK$3rYo;qNQnF95$b6cvBK^-@wRIO6HzH{0yYA9eFyTwe@-BIYS53_S^v>6i@1TDn7 VvLW|MBk-FzX<-^AVZ0jv003SB^(z1X diff --git a/docs/public/assets/img/docs/filtering-and-searching-date-range-light@2x.webp b/docs/public/assets/img/docs/filtering-and-searching-date-range-light@2x.webp deleted file mode 100644 index 6a4925b7e3fafd145c2788b11b8f4bb6cae9052b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 41396 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 diff --git a/docs/public/assets/img/docs/setting-log-levels-project-default-dark.webp b/docs/public/assets/img/docs/setting-log-levels-project-default-dark.webp deleted file mode 100644 index 04591fa852ad6af76bc35e2181abb83779af9418..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 19664 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 yRDwlnoBOD%O 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 A*Z=?k diff --git a/docs/public/assets/img/docs/setting-log-levels-project-default-light.webp b/docs/public/assets/img/docs/setting-log-levels-project-default-light.webp deleted file mode 100644 index b7a50c02732e1a64ff26ebd1c157d6ecbaa6ac93..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 17710 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 diff --git a/docs/public/assets/img/docs/setting-log-levels-project-default-light@2x.webp b/docs/public/assets/img/docs/setting-log-levels-project-default-light@2x.webp deleted file mode 100644 index 440f23ef89dddd6eea1c5632b59e89d0f546b82a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 38562 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 { } } - for (const match of allowAppHostApi ? [] : text.matchAll(apiPathPattern)) { + const checkedText = text.replaceAll(appHostOAuthResource, "") + for (const match of allowAppHostApi ? [] : checkedText.matchAll(apiPathPattern)) { errors.push(`${relative}: ${appHostname}${match[1]} is an API path. Use ${apiHostname}${match[1]}.`) break }

    Log messages