README

The official Laravel telemetry collector for Tyto. It captures application signals and sends buffered batches to your self-hosted Tyto instance.

Supported signals

HTTP requests and authenticated users
exceptions and source context
database queries
queued jobs and scheduled tasks
Artisan commands
cache, mail and notifications
outgoing HTTP requests
application logs and security audits
scheduler and custom process heartbeats

Requirements

PHP 8.2+
Laravel 10, 11, 12 or 13

Installation

composer require tyto/agent
php artisan tyto:install

The installer publishes config/tyto.php and writes the connection values to your .env:

TYTO_SERVER_URL=https://tyto.example.com
TYTO_TOKEN=your-project-token

Telemetry is sent to /api/v1/ingest with X-Tyto-Token. Every batch carries an idempotency key so the server can reject duplicate delivery safely.

Application logs

The agent registers a Laravel logging channel named tyto automatically. To send application logs to Tyto, the channel must also be part of Laravel's active logging stack.

For Laravel applications whose config/logging.php reads LOG_STACK, configure:

LOG_CHANNEL=stack
LOG_STACK=single,tyto

If the application uses a fixed stack definition, add tyto to the channels array in config/logging.php:

'stack' => [
    'driver' => 'stack',
    'channels' => ['single', 'tyto'],
    'ignore_exceptions' => false,
],

The active default channel must be stack. Merely defining the tyto channel without using it in the active stack does not forward calls such as Log::info().

Clear cached configuration after changing .env or config/logging.php:

php artisan optimize:clear

Verify the effective configuration:

php artisan tinker --execute="dump(config('logging.default'), config('logging.channels.stack.channels'), array_key_exists('tyto', config('logging.channels')));"

The expected result is stack, an array containing tyto, and true. Then send a test entry:

php artisan tinker --execute="Log::info('Tyto logging integration test', ['source' => 'production']);"

Configuration

TYTO_ENABLED=true
TYTO_INGEST_TIMEOUT=2
TYTO_INGEST_BUFFER=500
TYTO_INGEST_ATTEMPTS=3
TYTO_INGEST_BACKOFF_MS=100

TYTO_HEARTBEAT_ENABLED=true
TYTO_HEARTBEAT_SLUG=scheduler
TYTO_HEARTBEAT_NAME="Laravel scheduler"
TYTO_HEARTBEAT_INTERVAL=1

TYTO_CAPTURE_SOURCE_CODE=true
TYTO_CAPTURE_PAYLOAD=false
TYTO_REDACT_FIELDS=_token,password,password_confirmation
TYTO_REDACT_HEADERS=Authorization,Cookie,Proxy-Authorization,X-XSRF-TOKEN

TYTO_SAMPLE_REQUESTS=1.0
TYTO_SAMPLE_COMMANDS=1.0
TYTO_SAMPLE_EXCEPTIONS=1.0
TYTO_SAMPLE_TASKS=1.0

The agent schedules a heartbeat automatically, which lets Tyto detect when Laravel's scheduler stops running. Keep php artisan schedule:run configured every minute in production.

Report custom recurring processes from application code:

TytoAgent::heartbeat('nightly-import', 'Nightly customer import', 1440);

Or from cron and deployment scripts:

php artisan tyto:heartbeat nightly-import --name="Nightly customer import" --interval=1440

Privacy defaults

Request payload capture is disabled by default. Authentication headers, cookies, CSRF tokens and common password fields are redacted before transmission. Review config/tyto.php before enabling additional payload collection.

License

MIT. See LICENSE.md.

tyto / agent

Maintainers

Package info

Statistics

Security