Observability & Error Taxonomy
What it is
Section titled “What it is”AetheriusDB does not hand out opaque integers or generic exception strings.
Every rejection — schema mismatch, capacity exhaustion, authentication failure,
constraint violation — is reported with a typed identifier from a published
taxonomy. Codes follow a predictable shape, AE-DOMAIN-NNNN, so error handlers
in your client code can branch on them without parsing message text, and so an
on-call engineer can look up the exact remediation directly.
Metrics follow the same philosophy. Per-operator counters and live telemetry are exposed as SQL-queryable system views, so you can watch a busy database in real time using the same connection you already use for queries.
Why it matters
Section titled “Why it matters”The two most expensive ingredients in a production outage are ambiguous errors and observability that slows things down further when you turn it on. Ambiguous errors send you down wrong investigation paths; heavy telemetry makes the problem worse. AetheriusDB removes both.
- Stable error codes — branch on them in client code without parsing messages.
- Documented remediation — every code names the limit it hit and how to fix it.
- Low-overhead telemetry — metrics surface as system views; reading them does not slow the query path.
- SQLSTATE-compatible — codes also surface through standard PostgreSQL-style channels, so existing tools handle them naturally.
How you use it
Section titled “How you use it”Catch errors by code rather than by message, and read recent errors or live counters straight from SQL.
-- Operator-side: list recent typed errors via SQL.SELECT code, count(*), max(occurred_at) FROM system.errors WHERE occurred_at > now() - INTERVAL '5 minutes' GROUP BY code ORDER BY count(*) DESC;On the client side, branch on the code, never the message text:
-- Pseudocode: react to a specific code, re-raise everything else.try { conn.execute("INSERT INTO pinned_table VALUES (...)");} catch (err) { if (err.code == "AE-VMM-3041") { fallback(); // pinned-memory saturation — spill to a regular table } else { throw; }}Code-based handling makes client retry policies precise: a spike in one code tells you exactly which kind of pressure your workload is putting on the cluster without parsing a single log line.
What you see
Section titled “What you see”| Surface | What it gives you |
|---|---|
AE-DOMAIN-NNNN code | A stable, documented identifier — the contract your client relies on. |
| SQLSTATE bridge | Each code maps to a SQLSTATE so PostgreSQL-aware tools handle it. |
system.errors view | Recent typed errors, queryable by code and time window. |
system.telemetry view | Live per-operator counters over the same data. |
flowchart LR
classDef a fill:#1f2640,stroke:#7c5cff,color:#e8eaf0
classDef b fill:#1f2640,stroke:#00d4ff,color:#e8eaf0
classDef g fill:#1f2640,stroke:#4ade80,color:#4ade80
classDef w fill:#1f2640,stroke:#fbbf24,color:#fbbf24
Q[Query]:::a --> R{Result}:::b
R -->|success| OK[Rows]:::g
R -->|rejection| E[Typed error<br/>AE-DOMAIN-NNNN]:::w
Q -. counters .-> M[system.telemetry<br/>system.errors]:::g