Laravel Monitoring Configuration

After installation, Uplinkr’s configuration file is available at config/uplinkr.php. This guide explains all available configuration options.

Note

In most cases, the default configuration is already sufficient for correct operation. You only need to adjust this file if you want to customize alerting, notifications, or advanced behavior.

Tip

config/uplinkr.php contains package/runtime configuration. Global heartbeat state such as I'm alive enabled state, interval, channels, and timestamps is stored separately in storage/app/private/uplinkr/settings.json and managed via php artisan uplinkr:settings.

Storage Configuration

Configure where and how uplinkr stores probe results, project settings, and archive data.

Storage Disk

'storage' => [
    'disk' => env('UPLINKR_STORAGE_DISK', 'local'),
]

The Laravel filesystem disk where uplinkr stores all data. Must be a valid disk configured in config/filesystems.php. Common values: local, s3, public.

Storage Paths

'path' => env('UPLINKR_STORAGE_PATH', 'uplinkr'),
'probe_results' => env('UPLINKR_STORAGE_PROBE_RESULTS', 'probes'),
'probe_filename_separator' => env('UPLINKR_PROBE_FILENAME_SEPARATOR', '@'),

• path: Base directory where all uplinkr data is stored
• probe_results: Subdirectory within each project for probe result files
• probe_filename_separator: Character separating URL from date in filenames (e.g., example_com@2026-01-19.json)

File Extension

'file_extension' => env('UPLINKR_FILE_EXTENSION', 'json'),

The file extension used for all uplinkr data files. Using json allows for easy inspection and manipulation of stored data.

Pretty Print Probe Results

'pretty_print_probe_results' => (bool)env('UPLINKR_STORAGE_PRETTY_PRINT_PROBE_RESULTS', true),

Controls whether files in <project>/probes/*.json are written in pretty-printed JSON format.

• true: Easier to read manually, larger files
• false: Compact JSON, smaller files, and less I/O overhead (recommended for production/high-frequency probes)

Archive Folder

'archive_folder' => env('UPLINKR_ARCHIVE_FOLDER', 'archived'),

Name of the subdirectory where archived projects are stored. Archived projects are moved here instead of being deleted, allowing for later retrieval if needed.

Allow Complete Wipe

'allow_complete_wipe' => env('UPLINKR_ALLOW_COMPLETE_WIPE', false),

Destructive Operation

When enabled, allows complete deletion of all uplinkr data including all projects, probe results, and settings. This is a destructive operation that cannot be undone. Keep disabled in production environments.

Probe Results Grouping

'probe_results_grouping' => env('UPLINKR_PROBE_RESULTS_GROUPING', 'daily'),

Controls how probe results are grouped into files:

• hourly: example_com@2026-01-19-14.json (high-frequency monitoring)
• daily: example_com@2026-01-19.json (default, balanced)
• monthly: example_com@2026-01.json (long-term storage)

Probe Configuration

Settings that control how uplinkr performs HTTP probes to monitor your endpoints.

Probe Execution Mode

'execution_mode' => env('UPLINKR_PROBES_EXECUTION_MODE', 'direct'),

Defines how probes are executed:

• direct: Execute synchronously in the current process (default)
• job: Dispatch probes as Laravel queue jobs (recommended for high-frequency or large setups)

Probe Queue Connection

'queue_connection' => env('UPLINKR_PROBES_QUEUE_CONNECTION', 'sync'),

Queue connection used when execution_mode is set to job (for example: sync, redis, database, sqs).

Standard Latency Threshold

'probes' => [
    'standard_latency' => (int)env('UPLINKR_PROBES_STANDARD_LATENCY', 1500),
]

Maximum acceptable response time in milliseconds. Probes that exceed this threshold are marked as slow/unreachable, even if they return a successful HTTP status code.

Default: 1500ms (1.5 seconds)

User-Agent Header

'user_agent' => env('UPLINKR_PROBES_USER_AGENT', 'uplinkr-monitor'),

The User-Agent string sent with each probe request. Helps identify uplinkr probes in server logs.

Project Configuration

Settings for project management. Projects are used to organize and group related probes together.

'projects' => [
    'standard_project' => env('UPLINKR_STANDARD_PROJECT', 'standard_project'),
    'standard_project_status' => env('UPLINKR_STANDARD_PROJECT_STATUS', 'enabled'),
]

• standard_project: Fallback project name when no project is specified
• standard_project_status: Default status for newly created projects (common values: enabled, disabled, archived)

Notifications

Define how uplinkr sends alerts when probe results indicate problems. Channels can be enabled/disabled and configured independently.

Enabled Channels

'notifications' => [
    'enabled' => array_filter(explode(',', (string)env('UPLINKR_NOTIFY_CHANNELS', 'log'))),
]

Optional convenience list of enabled notification channels in your .env file:

UPLINKR_NOTIFY_CHANNELS=log,mail,webhook

In practice, the per-channel enabled flags under notifications.channels.* remain the decisive switches.

Log Channel

'channels' => [
    'log' => [
        'enabled' => (bool)env('UPLINKR_NOTIFY_LOG_ENABLED', true),
        'channel' => env('UPLINKR_NOTIFY_LOG_CHANNEL', 'uplinkr'),
        'level' => env('UPLINKR_NOTIFY_LOG_LEVEL', 'warning'),
    ],
]

Logs alerts to your application’s logging system.

• enabled: Enable/disable log notifications
• channel: Laravel log channel to use (maps to config/logging.php)
• level: Log level for alert entries (debug, info, warning, error, etc.)

Mail Channel

'mail' => [
    'enabled' => (bool)env('UPLINKR_NOTIFY_MAIL_ENABLED', false),
    'mailer' => env('UPLINKR_NOTIFY_MAIL_MAILER', null),
    'to' => array_filter(explode(',', (string)env('UPLINKR_NOTIFY_MAIL_TO', ''))),
    'from' => [
        'address' => env('UPLINKR_NOTIFY_MAIL_FROM_ADDRESS', null),
        'name' => env('UPLINKR_NOTIFY_MAIL_FROM_NAME', null),
    ],
    'subject_prefix' => env('UPLINKR_NOTIFY_MAIL_SUBJECT_PREFIX', '[Uplinkr]'),
]

Send email notifications when alerts are triggered.

Example .env configuration:

UPLINKR_NOTIFY_MAIL_ENABLED=true
UPLINKR_NOTIFY_MAIL_TO=admin@example.com,ops@example.com
UPLINKR_NOTIFY_MAIL_FROM_ADDRESS=uplinkr@example.com
UPLINKR_NOTIFY_MAIL_FROM_NAME="Uplinkr Monitor"

Webhook Channel

'webhook' => [
    'enabled' => (bool)env('UPLINKR_NOTIFY_WEBHOOK_ENABLED', false),
    'url' => env('UPLINKR_NOTIFY_WEBHOOK_URL', null),
    'method' => env('UPLINKR_NOTIFY_WEBHOOK_METHOD', 'POST'),
    'timeout_seconds' => (int)env('UPLINKR_NOTIFY_WEBHOOK_TIMEOUT', 10),
    'connect_timeout_seconds' => (int)env('UPLINKR_NOTIFY_WEBHOOK_CONNECT_TIMEOUT', 5),
    'verify_tls' => (bool)env('UPLINKR_NOTIFY_WEBHOOK_VERIFY_TLS', true),
    'headers' => [
        'Content-Type' => 'application/json',
    ],
]

Send alert data to any external application or endpoint. This is the “bring your own integration” channel.

Retry Strategy:

'retry' => [
    'max_attempts' => (int)env('UPLINKR_NOTIFY_WEBHOOK_RETRY_MAX', 3),
    'backoff_ms' => [0, 2000, 10000],
]

Defines retry behavior with configurable backoff delays between attempts.

Optional HMAC Signing:

'signing' => [
    'enabled' => (bool)env('UPLINKR_NOTIFY_WEBHOOK_SIGNING', false),
    'secret' => env('UPLINKR_NOTIFY_WEBHOOK_SECRET', null),
    'header' => env('UPLINKR_NOTIFY_WEBHOOK_SIGNATURE_HEADER', 'X-Uplinkr-Signature'),
    'algo' => env('UPLINKR_NOTIFY_WEBHOOK_SIGNATURE_ALGO', 'sha256'),
]

Enable webhook signing so the receiver can verify the request originates from uplinkr.

Payload Format

'payload' => [
    'version' => env('UPLINKR_NOTIFY_PAYLOAD_VERSION', 'uplinkr.v1'),
]

Version identifier for the notification payload structure, allowing for stable integrations over time.

Alert payloads include probe_tls_expiration_date (when available), and pass it through Mail, Webhook, and Log channels.

When multiple probes fail in a project, alert notifications are aggregated and contain a probes[] list for compact delivery.

Logging Configuration

Configure how uplinkr writes log messages. Uplinkr uses its own dedicated log channel to keep probe-related logs separate from your application logs.

The package defaults currently expose these values through environment variables:

• UPLINKR_LOG_CHANNEL: Name of the log channel Uplinkr should use
• UPLINKR_LOG_DRIVER: Log driver (daily, single, stack, syslog, errorlog)
• UPLINKR_LOG_PATH: Full path to the log file
• UPLINKR_LOG_LEVEL: Minimum log level (debug, info, notice, warning, error, critical, alert, emergency)
• UPLINKR_LOG_DAYS: Number of days to retain daily log files

Default behavior:

'log_channel' => env('UPLINKR_LOG_CHANNEL', 'uplinkr'),
'log' => [
    'driver' => env('UPLINKR_LOG_DRIVER', 'daily'),
    'path' => env('UPLINKR_LOG_PATH', storage_path('logs/uplinkr.log')),
    'level' => env('UPLINKR_LOG_LEVEL', 'info'),
    'days' => (int)env('UPLINKR_LOG_DAYS', 14),
]

Auto-Registration

This channel is registered automatically if it doesn’t exist in your config/logging.php.

Scheduler

Configure the automatic execution of uplinkr probes. When enabled, uplinkr integrates with Laravel’s task scheduler to run your monitoring probes at the specified interval.

'scheduler' => [
    'enabled' => false,
    'cron' => '* * * * *',
    'alert_cron' => '*/2 * * * *',
]

• enabled: Enable/disable automatic scheduler integration
• cron: Cron expression defining when probes should run (default: every minute)
• alert_cron: Cron expression for uplinkr:project:alert:decision (default: every 2 minutes). Set to null to reuse cron.

When scheduler integration is enabled, Uplinkr currently registers:

• uplinkr:project:run-probes --force
• uplinkr:project:alert:decision
• uplinkr:iam-alive --scheduled if I'm alive is enabled in global settings

Heartbeat cadence is not configured in config/uplinkr.php. The scheduler only activates the command; the effective heartbeat interval comes from uplinkr/settings.json.

Async Queue Mode Recommendation

When probes.execution_mode = job, probe commands may dispatch queue jobs and exit before workers finish updating state.json. Use scheduler.alert_cron to run alert decisions on a delayed schedule (for example every 2 minutes) to reduce stale-state alert evaluations.

Enable via Install Command

You can enable the scheduler during installation with:

php artisan uplinkr:install --scheduler

You can inspect the current package configuration at runtime with:

php artisan uplinkr:config

Common cron expressions:

• * * * * * - Every minute
• */5 * * * * - Every 5 minutes
• 0 * * * * - Every hour
• 0 */6 * * * - Every 6 hours

Laravel Scheduler Requirement

Remember to add Laravel’s scheduler to your crontab for automatic execution:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1