Telemetry Data Model

Tenant       -- Organization or individual account
  |
  +-- User   -- Human participant (owner, team member)
  |
  +-- Agent  -- AI agent registered to the tenant

{
  "entity_id": "agt_7f3a2b9c-1234-5678-abcd-ef0123456789",
  "entity_type": "agent | user | system",
  "tenant_id": "tnt_a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "display_name": "Claude Code Assistant",
  "hub_address": "claude-coder.alice.agentvault.hub",
  "capabilities": ["code_review", "deployment", "testing"],
  "trust_level": "tenant_verified | federation_verified | unverified"
}

{
  "envelope_version": "1.0.0",
  "message_id": "msg_uuid_v7",
  "trace_id": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
  "span_id": "1234567890abcdef",
  "parent_span_id": "abcdef1234567890",
  "timestamp": "2026-02-16T14:32:00Z",
  "sender": {
    "entity_id": "agt_uuid",
    "entity_type": "agent",
    "hub_address": "cortina.agentvault.hub"
  },
  "recipient": {
    "entity_id": "usr_uuid",
    "entity_type": "user"
  },
  "message_type": "decision_request",
  "priority": "high",
  "payload": { },
  "metadata": { }
}

import uuid

AGENTVAULT_NAMESPACE = uuid.UUID("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

def conversation_to_trace_id(conversation_id: str) -> str:
    """Deterministic mapping from conversation ID to OTel trace ID."""
    derived = uuid.uuid5(AGENTVAULT_NAMESPACE, conversation_id)
    return derived.hex  # 32-char hex, OTel compatible

def generate_span_id() -> str:
    """Random span ID for each message exchange."""
    return uuid.uuid4().hex[:16]  # 16-char hex, OTel compatible

{
  "audit_event_id": "evt_uuid_v7",
  "timestamp": "2026-02-16T14:32:00.123456789Z",
  "observed_timestamp": "2026-02-16T14:32:00.125000000Z",

  "trace_id": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
  "span_id": "1234567890abcdef",
  "parent_span_id": "abcdef1234567890",
  "trace_flags": 1,

  "severity_number": 9,
  "severity_text": "INFO",

  "body": {
    "event_type": "message_delivered",
    "message_id": "msg_uuid",
    "message_type": "decision_request",
    "summary": "Decision request delivered: Deploy v2.3.1 to production?"
  },

  "resource": {
    "service.name": "agentvault",
    "service.version": "0.1.0",
    "av.tenant.id": "tnt_uuid",
    "av.environment": "production"
  },

  "attributes": {
    "av.sender.entity_id": "agt_uuid",
    "av.sender.entity_type": "agent",
    "av.sender.hub_address": "claude-coder.alice.agentvault.hub",
    "av.recipient.entity_id": "usr_uuid",
    "av.recipient.entity_type": "user",
    "av.conversation.id": "conv_uuid",
    "av.message.type": "decision_request",
    "av.message.priority": "high",
    "av.delivery.latency_ms": 42
  },

  "hash_chain": {
    "event_hash": "sha256:a1b2c3d4...",
    "previous_hash": "sha256:e5f6a7b8...",
    "sequence_number": 10847
  }
}

import hashlib
import json

def compute_event_hash(event: dict, previous_hash: str) -> str:
    hash_input = {
        "previous_hash": previous_hash,
        "timestamp": event["timestamp"],
        "trace_id": event["trace_id"],
        "span_id": event["span_id"],
        "body": event["body"],
        "sender": event["attributes"].get("av.sender.entity_id"),
        "recipient": event["attributes"].get("av.recipient.entity_id"),
        "sequence_number": event["hash_chain"]["sequence_number"]
    }
    canonical = json.dumps(hash_input, sort_keys=True, separators=(",", ":"))
    return "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()

GENESIS_HASH = "sha256:" + hashlib.sha256(b"agentvault_genesis_v1").hexdigest()

def verify_chain(events: list[dict]) -> tuple[bool, int | None]:
    """Returns (True, None) if valid or (False, break_index) if tampered."""
    for i, event in enumerate(events):
        expected_previous = GENESIS_HASH if i == 0 else events[i-1]["hash_chain"]["event_hash"]
        if event["hash_chain"]["previous_hash"] != expected_previous:
            return (False, i)
        recomputed = compute_event_hash(event, expected_previous)
        if event["hash_chain"]["event_hash"] != recomputed:
            return (False, i)
    return (True, None)

Tenant A: genesis -> evt_1 -> evt_2 -> evt_3 -> ...
Tenant B: genesis -> evt_1 -> evt_2 -> ...

-- Full audit trail for a conversation
SELECT * FROM audit_events
WHERE trace_id = :trace_id
ORDER BY sequence_number ASC;

-- Critical/error events for tenant in last 24h
SELECT * FROM audit_events
WHERE tenant_id = :tenant_id
  AND severity_number >= 17
  AND timestamp > now() - interval '24 hours'
ORDER BY timestamp DESC;

-- Hash chain integrity verification
SELECT
    sequence_number,
    event_hash,
    previous_hash,
    LAG(event_hash) OVER (ORDER BY sequence_number) as expected_previous
FROM audit_events
WHERE tenant_id = :tenant_id
ORDER BY sequence_number;

GET /v1/audit/trace/{trace_id}
GET /v1/audit/tenant?since=...&until=...&severity_min=17
GET /v1/audit/entity/{entity_id}?limit=100

POST /v1/audit/verify

{
  "tenant_id": "tnt_uuid",
  "from_sequence": 1,
  "to_sequence": 10847
}

{
  "valid": true,
  "events_verified": 10847,
  "first_hash": "sha256:...",
  "last_hash": "sha256:...",
  "verified_at": "2026-02-16T15:00:00Z"
}

GET /v1/decisions/pending?user_id={user_id}

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:
    timeout: 5s
  filter:
    logs:
      include:
        match_type: strict
        resource_attributes:
          - key: av.tenant.id
            value: "tnt_enterprise_customer"

exporters:
  splunkhec:
    endpoint: "https://customer-splunk.example.com:8088"
  datadog:
    api:
      key: "${DD_API_KEY}"

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch, filter]
      exporters: [splunkhec, datadog]

import { buildTraceparent, propagateContext } from "@agentvault/crypto";

// Create a traceparent header
const header = buildTraceparent(traceId, spanId);
// "00-{traceId}-{spanId}-01"

// Propagate context to a child span
const child = propagateContext(parentTraceparent);