Download the PHP package tsitsishvili/elastic-audit without Composer

Elastic Audit

Laravel package that logs third-party HTTP traffic and actor/model activity to a dedicated Elasticsearch cluster.

Elastic Audit is intended for internal applications that need a consistent audit/debug trail for provider calls, callbacks, latency, status codes, entity context, sanitized payload previews, and domain activity. The package has two independent subsystems that share one Elasticsearch connection:

• Audit logs / HTTP logs — outgoing third-party requests and incoming callbacks through the HttpLog facade and HTTP middleware.
• Activity logs — actor actions and Eloquent model changes through the ActivityLog facade and ActivityLoggable trait.

Each subsystem has its own config, Elasticsearch index/aliases, queue, console commands, and optional dashboard, so an application can enable only what it needs. Both document types include the configured application identity and a snapshotted execution origin (HTTP route/controller, queue job, Artisan command, or an explicit manual origin).

Guides

• Audit Logs Guide — third-party HTTP request/callback logging, redaction, sampling, dashboards, and Elasticsearch queries.
  • Configuration reference · Logging outgoing requests · Dashboard · Troubleshooting
• Activity Logs Guide — actor/entity activity logging, automatic Eloquent change capture, and the activity dashboard.
  • Manual logging · Automatic model logging · Dashboard
• Agent Guide — condensed rules, examples, and safety invariants for AI coding agents integrating the package. See AI Agents for how to deliver it to an agent.

Screenshots

Quick Start

1. Install the stable v4 release from Packagist:

2. Publish the config files and enum stubs (see Publish Configuration):

3. Give every application a stable, unique APP_NAME, configure Elasticsearch, and enable the subsystem you need in .env (see Environment Variables and Register Application Enums).

4. Install the lifecycle policy, then create the Elasticsearch indices and aliases (Activity):

5. Run a queue worker for the configured logs queue (see Queues):

For usage, see logging outgoing requests, logging incoming callbacks, and recording activity.

ActivityLoggable observes Eloquent lifecycle events only. Raw SQL and query-builder writes must call ActivityLog::record() explicitly with their meaningful before/after values; the package does not install a database query listener.

Permanent retention is supported independently for documents and indexes. Use a subsystem's retain_forever setting or a context's retainForever: true for documents, and disable log_elasticsearch.lifecycle.delete_enabled to keep rolled-over indexes. See Lifecycle, Rollover, and Health.

HTTP capture is bounded to 1 MB by default; larger bodies are headers-only, and bodies that cannot be key-redacted (such as XML or plain text) default to hash-only metadata. Successful incoming callbacks are queued after the response is sent, while activity jobs wait for the surrounding database transaction to commit. Review the upgrade guide before moving an existing installation to this release line.

Requirements

• PHP ^8.2
• Laravel ^12.0 || ^13.0
• Elasticsearch PHP client ^8.5 || ^9.0
• A queue worker, because logs are indexed through queued jobs

AI Agents

Elastic Audit ships package-owned agent resources that teach coding agents how to configure the package, use its HTTP and activity APIs, preserve trusted audit metadata, apply redaction, and verify queued logging without a live Elasticsearch cluster. They work with or without Laravel Boost.

With Laravel Boost

Boost is optional and is not a runtime dependency. In a consuming Laravel application, install it normally:

Boost discovers the package's guidelines and skill automatically and writes them to the application's configured coding-agent files. If Boost was installed before Elastic Audit, pick up the newly available resources with:

Select tsitsishvili/elastic-audit (guidelines, skills) when prompted.

Discovery requires tsitsishvili/elastic-audit to be a direct entry in the application's composer.json. Boost does not scan transitive dependencies.

Without Laravel Boost

Every agent resource is plain Markdown, so no tooling is required. Either point the agent at the guide in place:

…or copy the resources into the application so they sit alongside its own agent configuration:

This publishes:

• .ai/skills/elastic-audit-development/ — the Agent Skill, ready to move to .claude/skills/, .cursor/skills/, .github/skills/, or wherever the application's agent reads skills from.
• AGENTS.elastic-audit.md — the standalone guide, to reference from or paste into the application's root AGENTS.md or CLAUDE.md.

Published files are copies. Re-run the command with --force after upgrading the package to refresh them.

If the application later adopts Laravel Boost, Boost treats .ai/skills/elastic-audit-development as a user-owned skill and prefers it over the package's own copy. Either keep the published copy refreshed with --force, or delete it and let Boost read the skill straight from the package.

Project Documents

• Changelog
• Upgrade Guide
• Security Policy and Threat Model
• Contributing
• Coding Standards

Internal Versioning

Use Git tags as Composer versions.

Recommended policy:

• Patch: bug fixes only, for example v1.0.1
• Minor: backward-compatible features, for example v1.1.0
• Major: breaking config, contract, class, or behavior changes, for example v2.0.0

Applications should depend on stable tags:

Avoid using dev-main in production applications.