> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arguserror.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Core Concepts: How Argus Works
> Learn how DSNs, envelopes, issues, events, fingerprinting, and alert rules fit together in Argus.
Before you dive into the SDK reference or platform guides, it helps to understand the vocabulary Argus uses throughout its dashboard, API, and documentation. This page explains each key term and shows how the pieces connect — from the moment your SDK captures an error to the alert that lands in your inbox.
A DSN is a connection string that uniquely identifies your Argus project. You paste it into `init()` once; every SDK call after that uses it automatically.
**Format:**
```
https://PUBLIC_KEY@your-domain.com/PROJECT_ID
```
Argus parses the DSN into four parts at startup:
| Part | Where in the URL | Purpose |
| ----------- | -------------------------- | -------------------------------------------- |
| `protocol` | `https` (or `http`) | Determines whether the request is encrypted |
| `publicKey` | The username before `@` | Authenticates your SDK with the ingest API |
| `host` | Hostname and optional port | Routes the request to the right Argus server |
| `projectId` | The path segment after `/` | Scopes the event to your project |
A malformed DSN (missing public key, missing project ID, or an invalid URL) throws an error immediately at `init()` — loudly, so you catch misconfiguration at startup rather than silently dropping events in production.
You can find your DSN at any time under **Project Settings → DSN**.
An envelope is the JSON payload that the SDK builds and sends to the Argus ingest endpoint every time an error is captured.
**Envelope fields:**
| Field | Type | Description |
| ------------- | ---------------------------------------------------- | -------------------------------------------------------------- |
| `level` | `fatal` \| `error` \| `warning` \| `info` \| `debug` | Severity of the event |
| `timestamp` | number (milliseconds) | `Date.now()` at capture time — **must be ms**, not seconds |
| `environment` | string | e.g. `"production"`, `"staging"` — set in `init()` |
| `release` | string | Your app version — ties errors to a specific deploy |
| `exception` | object | `{ type, value, stacktrace: { frames[] } }` |
| `user` | object | Optional `{ id, email }` for user-scoped error views |
| `breadcrumbs` | array | Ordered trail of events leading up to the error |
| `tags` | object | Arbitrary key–value strings for filtering |
| `request` | object | `{ url, method, headers }` — auto-populated in the browser SDK |
Invalid envelopes return `HTTP 400` with details. The timestamp field is strictly enforced in milliseconds — a Unix seconds value is rejected.
An event is one captured occurrence of an error in your application. Every time the SDK sends an envelope and Argus accepts it, Argus creates an event record containing:
* The full **stack trace** with filenames, function names, line numbers, and column numbers
* **Context** such as the browser or OS, the URL where the crash happened, and any tags you attached
* **Metadata** including the severity level, timestamp, environment, and release
Events are the raw material Argus works with. On their own they're detailed records of individual crashes; grouped together they become **Issues** (see below).
You can browse all events for a specific issue on the **Issue Detail** page in the dashboard, filtered and paginated by time.
An issue is a deduplicated group of events that share the same **fingerprint** (see below). Where an event represents one crash by one user at one moment, an issue represents the underlying bug — no matter how many users trigger it or how many times.
Each issue tracks:
* **First seen** and **last seen** timestamps
* A running **event count** across all occurrences
* The **status** — `UNRESOLVED`, `RESOLVED`, or `IGNORED`
* The **culprit** — the most relevant stack frame, surfaced at the top of the detail view
When Argus receives a new event, it checks whether a matching issue already exists. If it does, Argus increments that issue's event count and updates the last-seen time. If it doesn't, Argus creates a new issue and fires any matching alert rules.
Manage issues from the **Issues** page in the dashboard or via the REST API.
Argus automatically groups identical errors into the same issue using a fingerprint — a hash derived from the top stack frames of an exception. This means:
* The same bug triggered by different users maps to the **same issue**
* The same bug occurring across multiple deploys maps to the **same issue** (until the relevant code locations change)
* Different bugs with the same error message but different stack traces map to **different issues**
The same error thrown in Chrome and Firefox also produces the same fingerprint — Argus normalises both stack formats to a common structure before computing the hash.
Minified production builds can cause multiple distinct bugs to collapse into a single fingerprint if minification maps many source lines to the same output line. Source map resolution (planned) will address this.
Every issue moves through a simple lifecycle controlled by you:
| Status | Meaning |
| ------------ | ----------------------------------------------------------------------- |
| `UNRESOLVED` | The issue is active. New matching events increment its count. |
| `RESOLVED` | You've fixed the bug. Argus stops alerting on this fingerprint. |
| `IGNORED` | You've acknowledged the issue but don't plan to fix it. Alerts silence. |
Change an issue's status from the **Issue Detail** page using the **Resolve** or **Ignore** buttons, or via the REST API (`PATCH /api/v1/issues/:id`).
If a resolved issue reappears after a deploy — meaning a new event with the same fingerprint arrives — Argus automatically moves it back to `UNRESOLVED` and fires your alert rules again.
An alert rule defines the condition that triggers a notification and where that notification goes.
**Current rule type:**
| Type | When it fires |
| ----------- | ------------------------------------------------------------------------------------- |
| `NEW_ISSUE` | The first time a new fingerprint is seen — i.e., a bug Argus has never grouped before |
**Delivery channels:**
* **Email** — Argus sends a formatted notification to the address you configure on the rule
* **Webhook** — Argus POSTs a JSON payload to any HTTPS URL you provide, so you can pipe alerts into Slack, PagerDuty, or your own tooling
Each rule is scoped to a single project. You can create, enable, disable, and delete rules from the **Alerts** page in the dashboard. Every delivery attempt is logged — check **Alert Logs** if a notification doesn't arrive as expected.
Argus enforces a monthly event quota per organization, reset at the start of each billing period.
| Plan | Monthly limit |
| ---- | -------------- |
| Free | 10,000 events |
| Pro | 500,000 events |
When your organization hits its cap:
* The ingest endpoint returns **HTTP 429**
* The SDK detects the 429 response and **drops the event silently** — no retry, no exception thrown in your app
* Your application continues running normally
Monitor your current usage on the **Usage** page in the dashboard. When you're approaching your limit, Argus prompts you to upgrade.
Events dropped due to quota are gone permanently. If error visibility during high-traffic periods matters to your team, upgrade to Pro before you hit the cap rather than after.
## Explore the Platform
Browse, filter, and triage the issues Argus has grouped from your events.
Configure email and webhook rules so the right people hear about new bugs instantly.
Track transaction durations and web vitals across your application.
Monitor your monthly event consumption and manage your plan.