Events & Logging

Events are the core building block of LogVault. Every action in your application that needs to be audited becomes an event.

What is an Event?

An event is a record of something that happened in your application. It captures who did what, when, and with what context. Events are:

• Immutable - Once created, they cannot be changed
• Timestamped - Automatically recorded with server time
• Signed - Cryptographically verified for integrity
• Searchable - Indexed for fast retrieval

Event Structure

Every event has these core fields:

1{
2  "id": "evt_8f92a3b4c5d6e7f8",
3  "action": "user.login",
4  "actor_id": "user_123",
5  "actor_type": "user",
6  "target_id": "session_456",
7  "target_type": "session",
8  "timestamp": "2025-11-28T12:00:00Z",
9  "metadata": {
10    "ip_address": "82.10.22.1",
11    "user_agent": "Mozilla/5.0...",
12    "location": "Amsterdam, NL"
13  },
14  "signature": "sha256:a1b2c3d4..."
15}

Required vs Optional Fields

Action Naming Convention

We recommend using a resource.action format for your action names. This makes filtering and searching much easier:

• user.login / user.logout
• document.created / document.deleted
• payment.processed / payment.failed
• settings.updated
• api_key.rotated

Logging an Event

Here's how to log an event with our Python SDK:

1import logvault
2
3client = logvault.Client("lv_live_...")
4
5# Simple event
6client.log(
7    action="user.login",
8    actor_id="user_123"
9)
10
11# Event with full context
12client.log(
13    action="document.exported",
14    actor_id="user_123",
15    target_id="doc_456",
16    target_type="document",
17    metadata={
18        "format": "pdf",
19        "file_size": 1024000,
20        "ip_address": request.ip
21    }
22)

Best Practices

1. Be specific with actions - Use invoice.paid instead of just update
2. Include relevant metadata - IP addresses, user agents, and request IDs help with investigations
3. Don't log PII directly - Let LogVault's automatic scrubbing handle sensitive data
4. Use consistent actor IDs - Always use the same ID format for the same user across events