Yammi Audit Log Laravel Laravel Package

Technical Evaluation

Architecture Fit

• Distributed Laravel Systems: Yammi excels in queue-heavy, multi-job workflows where traditional audit logs fail to trace execution chains (e.g., HTTP → Job → Job → Model). Its provenance chain (actor/origin/correlation) aligns perfectly with event-sourced or CQRS-like architectures where causality matters.
• Multi-Tenancy: Built-in support for tenant-aware auditing (via middleware or model binding) makes it ideal for SaaS platforms.
• Compliance-Centric: GDPR, tamper-evidence (hash chains), and subject-access reports address regulatory needs without forcing architectural changes.
• Observability: Anomaly detection and SIEM streaming integrate with existing monitoring (e.g., Datadog, Splunk) for incident response.

Misalignment:

• Non-Eloquent Writes: Raw SQL/Query Builder updates require explicit AuditLog::record() calls, which may not fit high-throughput or legacy systems.
• No Event Sourcing: While it offers a "time machine," it’s read-only forensics, not a source of truth for replaying state.

Integration Feasibility

• Zero-Model Setup: No traits/observers → minimal migration risk. Global listener on Eloquent events ensures backward compatibility.
• Async Writes: AUDIT_LOG_WRITE_ASYNC=true decouples audit logging from business logic, reducing write contention.
• Dedicated Database: Supports separate schema/connection for audit data, isolating performance impact.
• Laravel Ecosystem: Works with Laravel 9–13, PHP 8.1+, and any supported database (MySQL, PostgreSQL, SQLite).

Challenges:

• Legacy Systems: If using raw SQL or non-Eloquent ORMs, additional instrumentation is needed.
• Queue Workers: Requires context propagation (e.g., correlation_id in job payloads) for accurate tracing across workers.

Technical Risk

Critical Questions:

1. How will we handle non-Eloquent writes (e.g., raw SQL, GraphQL mutations)?
2. What’s the acceptable latency for async writes? (Configurable via AUDIT_LOG_WRITE_ASYNC.)
3. Do we need tamper-evidence? (Enables audit-log:verify but adds storage overhead.)
4. How will we manage retention? (Default 180 days; can be extended or archived.)

Key Questions for Stakeholders

1. Compliance: Do we need GDPR subject-access reports or tamper-proof audit trails?
2. Incident Response: Is execution chain reconstruction critical for post-mortems?
3. Performance: Can we tolerate ~1–2ms overhead per write (configurable via sampling)?
4. Observability: Should we integrate with SIEM tools (e.g., Splunk, Datadog) for alerts?
5. Multi-Tenancy: Do we need tenant-isolated audit logs?

Integration Approach

Stack Fit

• Laravel Core: Designed for Eloquent, Queues, and Middleware (e.g., auth, web).
• Database: Works with MySQL/PostgreSQL/SQLite; supports dedicated schema/connection.
• Async Workers: Requires context propagation (e.g., correlation_id in job payloads).
• Monitoring: SIEM streaming and anomaly detection integrate with existing tools.

Compatibility Notes:

• Laravel 9–13: Tested on PHP 8.1+; no breaking changes expected.
• Non-Eloquent: Raw SQL/Query Builder updates need explicit AuditLog::record().
• Legacy Code: Minimal impact if using global listeners (no model changes).

Migration Path

1. Assessment Phase:
   • Audit current logging (e.g., Spatie, custom tables).
   • Identify critical workflows needing provenance (e.g., payments, user actions).
2. Pilot Deployment:
   • Install in staging with AUDIT_LOG_UI_ENABLED=false.
   • Test queue-heavy workflows (e.g., order processing).
3. Gradual Rollout:
   • Enable async writes (AUDIT_LOG_WRITE_ASYNC=true).
   • Configure sampling for high-churn models.
   • Roll out dashboard (audit-log:ui enable) post-validation.
4. Advanced Features:
   • Enable tamper-evidence (AUDIT_LOG_INTEGRITY=true) for critical data.
   • Integrate SIEM alerts for anomalies.

Rollback Plan:

• Disable via AUDIT_LOG_CAPTURE_MODE=none (configurable at runtime).
• No data loss; audit logs are append-only.

Sequencing

Compatibility Matrix

Operational Impact

Maintenance

• Low Overhead:
  • No model changes required (zero setup).
  • Auto-migrations handle schema updates.
• Configuration-Driven:
  • Retention, sampling, and async writes are runtime-configurable.
  • Dashboard settings editable without redeploy.
• Dependency Risk:
  • Single package with MIT license; no external services (except optional SIEM).

Maintenance Tasks:

Support

• Debugging:
  • Provenance chain simplifies incident analysis (e.g., "Who triggered this payment?").
  • Time machine reconstructs past states for debugging.
• Alerting:
  • Slack/webhook alerts for anomalies (e.g., unexpected model changes).
  • SIEM integration for centralized monitoring.
• User Queries:
  • Dashboard provides self-service access to audit data.
  • JSON API enables programmatic queries.

Common Support Scenarios:

1. Incident Response: "Why did Order #42 change status?" → Trace provenance chain.
2. Compliance Audits: "Provide GDPR subject data." → Use audit-log:gdrp command.
3. Performance Issues: "Audit logs are slowing writes." → Enable async mode.

Scaling

• Write Scaling:
  • Async writes decouple audit logging from