Skip to main content

AdGuardHome-LogSync

A Python tool to synchronize AdGuard Home query logs between multiple instances with automatic log rotation.

Description

AdGuardHome-LogSync allows you to merge and synchronize query logs from multiple AdGuard Home instances while automatically managing log retention. This is useful when you're running multiple AdGuard Home instances and want to maintain a unified query log with configurable retention policies.

Features

  • Backup existing query logs
  • Merge multiple query log files
  • Automatic log rotation with configurable retention time
  • Safe atomic replacement of original logs
  • Asynchronous processing for better performance
  • Memory-efficient streaming for large log files
  • Command-line interface for easy automation

Installation

Install from PyPI:

pipx install adguardhome-logsync

Install from Git repository:

pipx install git+https://github.com/xz-dev/AdGuardHomeLogSync.git

Using pip

Install from PyPI:

pip install adguardhome-logsync

Install from Git repository:

pip install git+https://github.com/xz-dev/AdGuardHomeLogSync.git

Usage

adguardhome-logsync --name <instance-name> --path <querylog-path> --backup <backup-directory> [--retention <seconds>]

Parameters

  • --name: Current instance nickname (required)
  • --path: Path to the query log file (required)
  • --backup: Path to backup directory (required)
  • --retention: Log retention time in seconds (optional, default: 604800 = 7 days)

Examples

Basic usage with default 24-hour retention

adguardhome-logsync --name genx --path ~/adg/workdir/data/querylog.json --backup ~/adg/workdir/data/backup

Keep logs for 7 days (604800 seconds)

adguardhome-logsync --name genx --path ~/adg/workdir/data/querylog.json --backup ~/adg/workdir/data/backup --retention 604800

Keep logs for 12 hours (43200 seconds)

adguardhome-logsync --name genx --path ~/adg/workdir/data/querylog.json --backup ~/adg/workdir/data/backup --retention 43200

Keep logs for 1 hour only (3600 seconds)

adguardhome-logsync --name genx --path ~/adg/workdir/data/querylog.json --backup ~/adg/workdir/data/backup --retention 3600

Common Retention Values

Period Seconds Example Usage
1 hour 3600 --retention 3600
6 hours 21600 --retention 21600
12 hours 43200 --retention 43200
1 day 86400 --retention 86400
3 days 259200 --retention 259200
1 week 604800 --retention 604800 (default)
1 month 2592000 --retention 2592000

Example Output

Starting log synchronization for instance: genx
Log retention: 604800 seconds (168.0 hours)
Logs older than 2025-01-09 22:41:58 will be removed
Backing up querylog...
Searching for querylog files...
Found 3 querylog files
Merging querylogs...
Writing merged querylog...
Moving to updated querylog at /tmp/tmp2eqv7rdc.json...
Log synchronization completed successfully

Automation

Take care! it's from AI (If you have a tested version, please new PR for that, thanks a lot!)

Systemd Timer (Linux)

Create a systemd service file /etc/systemd/system/adguard-logsync.service:

[Unit]
Description=AdGuard Home Log Sync
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/adguardhome-logsync --name server1 --path /opt/adguard/querylog.json --backup /opt/adguard/backup --retention 604800
User=adguard
Group=adguard

Create a timer file /etc/systemd/system/adguard-logsync.timer:

[Unit]
Description=Run AdGuard Home Log Sync every 5 minutes
Requires=adguard-logsync.service

[Timer]
OnCalendar=*:0/5
Persistent=true

[Install]
WantedBy=timers.target

Enable and start:

sudo systemctl enable adguard-logsync.timer
sudo systemctl start adguard-logsync.timer

Cron Job

# Run every 5 minutes, keep logs for 1 week
*/5 * * * * /usr/local/bin/adguardhome-logsync --name server1 --path /opt/adguard/querylog.json --backup /opt/adguard/backup --retention 604800

# Run every hour, keep logs for 1 day
0 * * * * /usr/local/bin/adguardhome-logsync --name server1 --path /opt/adguard/querylog.json --backup /opt/adguard/backup --retention 86400

Development

Prerequisites

  • Python 3.9+
  • uv (for development)

Running from Source

Clone the repository:

git clone https://github.com/xz-dev/AdGuardHomeLogSync.git
cd AdGuardHomeLogSync

Run with uv:

uv run main.py --name genx --path ~/adg/workdir/data/querylog.json --backup ~/adg/workdir/data/backup --retention 604800

Project Structure

AdGuardHomeLogSync/
├── main.py                 # Main entry point
├── utils/
│   ├── querylog_copy.py   # Backup and file operations
│   └── querylog_merge.py  # Asynchronous log merging with retention
├── pyproject.toml         # Project configuration
└── README.md             # This file

How It Works

  1. Backup: Creates a backup of the current query log with instance name
  2. Discovery: Searches for all query log files in the backup directory
  3. Merge: Combines all found query logs into a single unified log
  4. Filter: Removes logs older than the specified retention time
  5. Replace: Safely replaces the original query log with the merged and filtered version

Performance Features

  • Asynchronous Processing: Multiple log files are processed concurrently
  • Streaming: Large files are processed in chunks to minimize memory usage
  • Efficient Sorting: Uses SortedList for optimal insertion performance
  • Memory Management: Configurable chunk sizes prevent memory spikes

Requirements

  • AdGuard Home instances with JSON format query logs
  • Write access to query log files and backup directory
  • Python 3.8 or higher

License

BSD-3-Clause

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Issues

Please report issues at: https://github.com/xz-dev/AdGuardHomeLogSync/issues

Metadata

Release files for adguardhome-logsync 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for adguardhome-logsync 0.1.3
File Size Uploaded Provenance Actions
adguardhome_logsync-0.1.3.tar.gz 7.9 kB Without provenance Details for adguardhome_logsync-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for adguardhome-logsync 0.1.3
File Interpreter ABI Platform Actions
adguardhome_logsync-0.1.3-py3-none-any.whl Python 3 none any Details for adguardhome_logsync-0.1.3-py3-none-any.whl

Total release size: 16.7 kB

Release files / adguardhome_logsync-0.1.3.tar.gz

Download URL adguardhome_logsync-0.1.3.tar.gz
Size 7.9 kB
Tags Source
SHA-256 checksum
How to use checksums
d8280dcc873cce462b715f0bfdd9bbd4613a38488362e0865dbf0786a21d12b9
BLAKE2b-256 checksum
How to use checksums
25ecd278219904c2eaf7f1ced5f77476d0add1bba46ad755161ba1e805af93cd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.13

Release files / adguardhome_logsync-0.1.3-py3-none-any.whl

Download URL adguardhome_logsync-0.1.3-py3-none-any.whl
Size 8.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1d4a014133676edc946cf423acd214d0e4e4f24409e5f61f9c217259ad9be3d3
BLAKE2b-256 checksum
How to use checksums
c95398511504e49583aab7584bd1912c46e4b3b3f5c4bf49df1deaeffffb684f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.13

Security for adguardhome-logsync 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page