README

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).

Optional application performance monitoring automatically captures transactions and spans for inbound HTTP, SQL, queues, commands, scheduled tasks, outbound Laravel HTTP, Redis, cache, mail, and notifications. Searchable timings use a dedicated metrics index; sampled Excimer/XHProf call stacks use a separate profiles index. A built-in performance dashboard links transactions, traces, and profiles. The subsystem is disabled by default and excludes request bodies, SQL bindings, query strings, message content, cache keys, Redis arguments, and error messages.

Guides

Audit Logs Guide — third-party HTTP request/callback logging, redaction, sampling, dashboards, and Elasticsearch queries.
- Installation · Configuration reference · Logging outgoing requests · Logging incoming callbacks · Dashboard · Troubleshooting
Activity Logs Guide — actor/entity activity logging, automatic Eloquent change capture, and the activity dashboard.
- Configuration · Manual logging · Automatic model logging · Dashboard
Metrics Guide — transactions/spans, W3C propagation, Excimer-first profiling, performance dashboard, security, separate metrics/profile indices, queues, and retention.
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.

Quick Start

Install the stable v5 release from Packagist:

composer require tsitsishvili/elastic-audit:^5.0

Publish the config files and enum stubs (see Publish Configuration):
```
php artisan vendor:publish --tag=elastic-audit
```
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).

Install the lifecycle policy, then create the Elasticsearch indices and aliases (HTTP · Activity):

php artisan elastic-audit:lifecycle-policy
php artisan http-logs:create-index              # when HTTP logs are enabled
php artisan activity-logs:create-index          # when activity logs are enabled
php artisan elastic-audit:metrics:create-index  # when metrics are enabled
php artisan elastic-audit:profiles:create-index # when profiles are enabled

Run a queue worker for the configured logs queue (see Queues):
```
php artisan queue:work --queue=default
```

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 for activity auditing. Enabling application metrics does observe completed query timings, but those measurements are not an audit trail and do not infer model changes.

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 audit logs and enabled metrics are indexed through queued jobs

Continuous profiles additionally require ext-excimer (recommended) or ext-xhprof; metrics and tracing work without either profiling extension.

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.

Resource	Purpose
`resources/boost/guidelines/core.blade.php`	Always-on rules, injected by Boost
`resources/boost/skills/elastic-audit-development`	Agent Skill loaded on demand for integration work
`AGENTS.md`	Standalone guide for agents, no tooling required

With Laravel Boost

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

composer require laravel/boost --dev
php artisan boost:install

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:

php artisan boost:update --discover

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:

vendor/tsitsishvili/elastic-audit/AGENTS.md

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

php artisan vendor:publish --tag=elastic-audit-ai

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

Internal Versioning

Use Git tags as Composer versions.

git tag v1.0.0
git push origin v1.0.0

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:

{
  "require": {
    "tsitsishvili/elastic-audit": "^5.0"
  }
}

Avoid using dev-main in production applications.

tsitsishvili / elastic-audit

Package info

Security

Statistics