Audit Trail & Logging

Define.wtf uses structured logging to track key events and changes across your workspace. While a fully queryable audit trail UI is planned for a future release, all critical mutations are logged with full context.

Structured Logging

Every mutation (create, edit, delete, vote, user action) is captured with:

• Who: User ID and email who made the change
• What: Type of change (e.g., "definition.created", "user.role_changed")
• When: Exact timestamp in ISO 8601 format
• Where: IP address and user agent
• Why: Context and reason (if applicable)

What Gets Logged?

All mutations are logged:

Read-Only Operations (Not Logged)

Performance-critical reads are not logged to avoid overwhelming logs:

• View acronym
• Search
• API read requests
• Dashboard visits

Structured Log Format

Each log entry captures:

{
  "userId": "user-123",
  "userEmail": "jane.doe@acme.com",
  "action": "definition.created",
  "resource": {
    "type": "definition",
    "id": "def-456",
    "acronymId": "acr-789"
  },
  "timestamp": "2024-03-28T10:30:00Z",
  "metadata": {
    "ipAddress": "203.0.113.45",
    "userAgent": "Mozilla/5.0...",
    "source": "web"
  }
}

Accessing Logs

Via Structured Logging

Logs are captured in your application logs and can be accessed via:

• Application log aggregation (Sentry, Datadog, etc.)
• Server logs in your deployment platform
• Standard output/stderr

Logs include full context for debugging and monitoring:

[2024-03-28T10:30:00Z] action=definition.created userId=user-123 userEmail=jane.doe@acme.com resource=def-456 acronymId=acr-789

Compliance & Audit

While the audit trail UI is being developed, logs can be:

• Exported from your log aggregation system for compliance
• Searched programmatically via your logging infrastructure
• Retained according to your organization's log retention policy

For SOC 2, HIPAA, ISO 27001, and GDPR compliance, ensure:

• Logs are retained for the required period (typically 1+ year)
• Log access is restricted to authorized personnel
• Logs are stored securely and encrypted in transit
• Log export capabilities are tested regularly

Future: Queryable Audit Trail UI

A dedicated Admin interface for querying audit logs is planned for a future release and will include:

• Full-text search across all events
• Advanced filtering by user, action type, resource, date range
• Event detail view with before/after comparisons
• Audit trail export for compliance reporting
• Real-time alerts for sensitive actions

Best Practices

For Admins

1. Monitor logs regularly — Check application logs weekly or monthly
2. Watch for unusual patterns — Bulk deletions, permission escalations
3. Export important logs — Save logs when investigating incidents
4. Retention strategy — Plan for long-term log storage if needed

For Security Teams

1. Set up log aggregation — Centralize logs from all instances
2. Configure alerts — Alert on sensitive actions (SSO changes, bulk imports)
3. Regular reviews — Audit logs periodically for compliance
4. Access control — Ensure only authorized users access logs

See Also

• Concepts: Multi-Tenancy — Logs scoped by tenant
• API Reference: Activity Logs — Programmatic access to activity data