=== Honeylog ===
Contributors: secondbreakfastio
Tags: analytics, logging, ingestion
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Honeylog batches frontend requests into a JSON queue and flushes them to Honeylog.

== Description ==

# Honeylog WordPress Plugin

Multi-file WordPress plugin that batches frontend requests into a JSON queue and flushes to Honeylog.

This client targets self-hosted and conventional managed WordPress. It is not
the complete integration for WordPress VIP, where edge cache hits do not execute
PHP and the uploads filesystem is not a durable local queue. Use
`clients/wordpress-vip-s3` for VIP.

## Behavior

- Tracks HTML/XHTML frontend responses regardless of the request `Accept` header, plus `.xml` and `.txt` URLs (excludes wp-admin pages).
- Keeps frontend responses without an explicit Content-Type, including redirects.
- Writes each event to a local NDJSON queue file.
- Serializes queue writes and rotation using a blocking filesystem lock on local storage.
- Schedules a flush every 60 seconds through WP-Cron; actual execution depends on the cron runner.
- Sends queued events in batches of up to 100.
- Warns administrators when automatic WP-Cron execution is disabled.

## Plugin Files

- `honeylog-ingestion.php`: bootstrap and WordPress hooks
- `includes/honeylog-constants.php`: constants + option sanitizers
- `includes/honeylog-batching-utils.php`: queue file lock, enqueue/snapshot/requeue/flush
- `includes/honeylog-request-utils.php`: request capture + HTTP batch sender
- `includes/honeylog-settings.php`: admin settings page
- `includes/honeylog-debug.php`: persistent debug log + last status/error helpers

## Settings

Go to `Settings -> Honeylog`:

- `Token`
- `Site Domain` (optional)

The ingestion endpoint is fixed to `https://api.honeylog.io/events`.

## Debugging

Debug log is written to:

- `wp-content/uploads/honeylog-ingestion/debug.log` when available
- fallback: `wp-content/honeylog-ingestion-debug.log`

## Reliable scheduling and cache coverage

On low-traffic or cached sites, configure a system cron to run due WordPress
cron events every minute. The 60-second schedule is not a delivery deadline.
See `docs/clients/wordpress-installation.md` for a WP-CLI example.
Requests served entirely by a page cache or CDN without loading the plugin
cannot be captured; use server/CDN log ingestion for those visits.
The queue requires a writable local filesystem with working `flock` support.

== Changelog ==

= 1.0.2 =

- Use response Content-Type at shutdown instead of request Accept to capture crawler page visits.
- Wait for concurrent queue mutations using a filesystem lock instead of dropping events after option-lock retries.
- Clarify cron scheduling and cache coverage requirements.

= 1.0.1 =

- Warn administrators when `DISABLE_WP_CRON` is enabled and queued events require an external cron runner.
- Track `.xml` and `.txt` visits, including requests with non-HTML `Accept` headers.
