Runtime Events and Observability Reference

Hypertag records one immutable event document per scan attempt in events.

Event schema reference

Core fields:

• `tagId` (string): associated tag document id
• `timestamp` (timestamp): event capture time
• `executionType` (`Direct` | `Hyper`)
• `status` (`success` | `failed`)
• `responseTimeMs` (number)
• `webhookStatus` (number, optional)
• `error` (string, nullable)
• `ipHash` (string)
• `userAgent` (string)

Success and failure semantics

• `success`: execution completed expected routing/trigger behavior.
• `failed`: execution did not complete as intended; inspect `error` and transport context.

For Hyper tags, webhookStatus is key for downstream diagnosis.

Response time interpretation

Use responseTimeMs to track performance trends:

• Stable range indicates healthy execution.
• Gradual increase can signal integration or network degradation.
• Spikes clustered by tag often indicate endpoint-level issues.

Recommended dashboards and alert thresholds

Minimum dashboard set:

• Scan volume by day (last 30 days)
• Success rate by tag
• Median and p95 response time
• Failures by execution type

Suggested starter alerts:

• Success rate below 98% over rolling 60 minutes
• p95 response time above agreed SLA threshold
• Consecutive Hyper failures above defined limit

Firestore prerequisites

To support event-powered UI features:

• Rules: allow authorized users to read eligible `events` documents.
• Index: composite index for query pattern `tagId ASC, timestamp ASC`.

Without these, active drawer analytics queries will fail with permission or index errors.