APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

Logging

Centralized, application-aware logging with context-specific files, custom channels, safe message normalization and optional DebugBar integration.

Overview

The shared Core\Log service writes persistent runtime logs for APPNETOS applications. By default, entries are separated by application and runtime context. Developers can optionally select a custom log filename without changing the active application directory.

Logging does not require debug mode. If the debug controller exposes log collection, entries are also forwarded to it for request-level inspection.

APPNETOS logging flow from application to persistent files and optional DebugBar

File locations and naming

Log files are stored below APPNETOS_VAR/log. The application name selects the directory; the current runtime context selects the default filename.

APPNETOS_VAR/log/
├── appnetos-dns-control/
│   ├── admin.log
│   ├── worker.log
│   ├── deployment.log
│   └── monitoring.log
└── appnetos-cms/
    └── app.log

For example, a log entry in the admin context of appnetos-dns-control is written to APPNETOS_VAR/log/appnetos-dns-control/admin.log. Passing deployment as the custom name writes to deployment.log in the same application directory.

Application, context and custom log names are normalized to lowercase; characters other than letters a-z, digits, underscores and hyphens are replaced with hyphens. Missing application names fall back to appnetos; missing contexts or empty sanitized names fall back to runtime.

Writing log entries

Resolve the shared log controller from the APPNETOS registry, then use a convenience method or add().

use Core\Log;
use Core\Registry;

$log = Registry::get(Log::class);

$log->info('Application initialized');
$log->warning('Deployment pending');
$log->error('Remote service unavailable');
$log->critical('Deployment failed');

Custom log files

$log->info('Deployment started', 'deployment');
$log->warning('Zone requires synchronization', 'monitoring');
$log->error('Deployment failed', 'deployment');

Custom types

$log->add('Scheduled job completed', 'audit', 'scheduler');
$log->add('Default type is info');

Custom types are lowercased for normalization and rendered in uppercase in the file. An omitted or empty type defaults to info.

Structured data and exceptions

$log->info([
    'job_id' => $jobId,
    'status' => 'finished',
], 'worker');

try {
    // Application operation
} catch (\Throwable $exception) {
    $log->error($exception, 'worker');
}

Strings are written directly. A Throwable is represented by its message, file and line number. Other values are JSON-encoded with unescaped Unicode and slashes; print_r() is used if encoding fails.

Log entry format

[2026-11-06 08:30:00] INFO: Deployment started
[2026-11-06 08:30:01] WARNING: Zone requires synchronization
[2026-11-06 08:30:02] AUDIT: Scheduled job completed

Each line includes the server-local timestamp, uppercase type and normalized message. The logger appends to existing files instead of replacing their contents.

Filesystem behavior and failure handling

Automatic directories

Missing application log directories are created recursively with requested mode 0775 (subject to the process umask).

Concurrent writes

FILE_APPEND | LOCK_EX appends each entry while requesting an exclusive filesystem lock.

Fallback reporting

Directory and file write failures are reported through native PHP error_log() rather than recursively logging through APPNETOS.

Ensure the PHP process can write to APPNETOS_VAR/log. Native error-log fallback does not guarantee that the original APPNETOS entry was persisted.

DebugBar integration

During initialization, the shared logger resolves Core\Debug through the registry. After writing an entry, it calls addLog($message, $type) when that method is available. This allows the DebugBar's Log collector to show messages associated with the current request.

The persistent log file remains the primary destination. DebugBar collection is optional and depends on the active debug implementation.

Public API Reference

Core\Log

Class & Registry

Class: Core\Log

Extends: Core\Log\Base

use Core\Log;
use Core\Registry;

$log = Registry::get(Log::class);
Method Description
init(): void Initialize the logger and resolve the shared debug controller; subsequent calls are idempotent.
add(mixed $message, string|null $type = null, string|null $name = null): void Write a normalized message with a default or custom type and optional custom log filename.
info(mixed $message, string|null $name = null): void Write an INFO entry.
warning(mixed $message, string|null $name = null): void Write a WARNING entry.
error(mixed $message, string|null $name = null): void Write an ERROR entry.
critical(mixed $message, string|null $name = null): void Write a CRITICAL entry.

These methods are defined on the shared Core\Log\Base class. File path resolution, formatting and normalization are protected implementation details.

Practical recommendations

  • Use the default context log for general runtime messages and a custom filename for operational domains such as deployments or monitoring.
  • Prefer structured arrays for machine-readable context, but avoid secrets and sensitive payloads.
  • Log exceptions at the point where they can be meaningfully handled; logging alone does not recover an operation.
  • Configure log rotation and retention externally for long-running production deployments.
  • Check filesystem permissions and the PHP error log if expected entries do not appear.

Next Steps

Previous

Debug

Explore Debug

Next

Shutdown

Explore Shutdown