> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Observability

> Dashboards, metrics, and audit logs available to Platform projects.

## Overview

Observability on **sovseal** respects the zero-trust data boundary. The Edge servers measure request flows and resource allocations solely at **Layer A** (unencrypted metadata). This design allows you to monitor sync operations and storage sizes without compromising cryptographic confidentiality.

***

## Per-Project Metrics

The **sovseal** Dashboard visualizes operational health metrics:

* **Replication Lag**: Time delta between local client commit and remote Edge receipt.
* **Ciphertext Bytes Stored**: Total volume of encrypted payloads residing in the storage bucket.
* **Operation Counts**: Total number of `store_memory` (write), `recall_memory` (read), and `check_in` requests.
* **Sync Devices**: Number of concurrent devices actively replication-synced.

All metrics are compiled from metadata tables (`usage_counters`) and never traverse decryption blocks.

***

## Webhooks

Wired to real-time events, **sovseal** webhooks trigger callbacks in your backend when memories are updated.

<Warning>
  **Zero-Knowledge Webhook Security Invariant**

  Webhook payloads carry only metadata and client-side payload hashes. Plaintext memory values are **never** transmitted in webhook bodies to prevent leakage to external servers.
</Warning>

### Supported Events

* `key.revoked`: Triggered when an API key is revoked.
* `memory.write`: Triggered when a new encrypted snapshot is replication-synced.
* `quota.hit`: Triggered when a plan quota limit is reached.
* `retention.purged`: Triggered when retention policy purges expired records.
* `sync.completed`: Triggered when a replication sync cycle finishes.

***

## Tamper-Evident Audit Log

Every privileged team action — granting or revoking key access, rotating a DEK, adding or removing a member, writing shared memory — is appended to a per-team, **append-only** ledger. Each entry commits to the one before it with a SHA-256 hash chain:

```text theme={null}
entry_hash = SHA-256( seq | org_id | actor | action | resource_type
                      | resource_id | metadata | prev_hash )
```

The first entry's `prev_hash` is 64 zeros (genesis); every subsequent entry's `prev_hash` is the previous entry's `entry_hash`. Because each link commits to all prior history, **any** retroactive edit, deletion, or reorder breaks the chain — and verification reports the exact sequence number where it broke. `UPDATE` and `DELETE` on the ledger are rejected at the database level.

### Zero-knowledge boundary

Audit entries carry only **non-secret descriptors** — member ids, roles, sequence/epoch numbers, byte sizes, and rotation reasons. They never contain a cleartext or wrapped DEK, a private key, or any plaintext/ciphertext memory.

### Verify & export from the dashboard

The **Audit Log** page lets administrators view the ledger (filtered by actor, action, or date), run a one-click **Verify Chain Integrity** check that returns `valid` or the exact `broken_seq` and reason, and **Export** the trail as JSON (with embedded verification) or CSV.

***

## Telemetry Opt-In

Dashboard telemetry is **off by default**, not on — there is no SDK-level environment variable for this. To enable it, toggle `telemetry_opt_in` on the project's Settings page (`PUT /settings`). Once enabled, the platform accepts only a strict whitelist of aggregate numeric counters (memory count, device count, bytes stored, sync ops) — no payload contents, keys, or user identifiers, and any non-whitelisted field is rejected outright. See [Project Settings](/platform/console/settings) for the toggle and [Settings Persistence](/api-reference/settings) for the API.