File Consumer

The File consumer is a specialized transport implementation that logs analytics events to a local file instead of sending them directly to a data plane over the network. This approach is useful for high-throughput environments where minimizing request latency is critical, or for audit logging where a local persistent record of events is required before transmission.

Implementation Details

The File consumer is defined in lib/Consumer/File.php and extends the base Consumer class lib/Consumer/File.php7-8 Unlike other consumers in the SDK, it does not inherit from QueueConsumer, as it performs synchronous writes to the local filesystem for every event call lib/Consumer/File.php58-61

Data Flow and Storage

When an event (track, identify, etc.) is triggered, the File consumer converts the message array into a JSON string and appends it as a new line to the configured log file lib/Consumer/File.php68-78

Feature	Specification
Format	Line-delimited JSON (LDJSON) lib/Consumer/File.php74-75
Default Filename	sys_get_temp_dir() . '/analytics.log' lib/Consumer/File.php24-26
Default Permissions	0644 lib/Consumer/File.php38
Write Mode	Append Binary (ab) lib/Consumer/File.php30

File Lifecycle Diagram

The following diagram illustrates the lifecycle of the file handle within the File class.

File Handle Management

Sources: lib/Consumer/File.php22-50 lib/Consumer/File.php68-78

Configuration Options

The consumer accepts an $options array during initialization via Rudder::init() or the Client constructor lib/Client.php26-50

Option	Type	Description
filename	string	The absolute path to the log file. Defaults to the system temp directory.
filepermissions	int	Octal file permissions (e.g., 0664). Defaults to 0644.
debug	bool	If true, errors are logged to error_log lib/Consumer/Consumer.php109-112

Permission Handling

During instantiation, the consumer attempts to open the file handle. If successful, it applies permissions using chmod lib/Consumer/File.php35-39 If the file cannot be opened, it triggers the handleError method with code 13 lib/Consumer/File.php31-34

Sources: lib/Consumer/File.php22-40 lib/Consumer/Consumer.php92-103

Replaying Events: SendBatchFromFile.php

Because the File consumer only writes to disk, a separate process is required to transmit these logs to the RudderStack data plane. The SDK provides a utility script at examples/SendBatchFromFile.php for this purpose.

Execution Workflow

1. File Rotation: The script renames the active log file to a unique name (e.g., analytics-RANDOM.log) to prevent the SDK from writing to the file while it is being read examples/SendBatchFromFile.php40-52
2. Parsing: It reads the file line-by-line, decoding the JSON payloads examples/SendBatchFromFile.php84-89
3. Batching: It accumulates events into a batch, ensuring the total size does not exceed 512KB examples/SendBatchFromFile.php94-96
4. Transmission: It uses Rudder::flush() (defaulting to LibCurl) to send the batch to the data plane examples/SendBatchFromFile.php109-112
5. Cleanup: Once successfully sent, the temporary log file is deleted examples/SendBatchFromFile.php113

CLI Usage

Batch Processing Diagram

This diagram maps the CLI utility logic to the SDK's internal Rudder and Client entities.

Log Replay Data Flow

Sources: examples/SendBatchFromFile.php40-52 examples/SendBatchFromFile.php70-76 examples/SendBatchFromFile.php84-107

Key Functions

__construct(string $secret, array $options)

Initializes the file handle and sets permissions. It defaults the filename to analytics.log in the system's temporary directory if not provided lib/Consumer/File.php22-40

write(array $body)

The internal helper that performs the json_encode and fwrite. It appends a newline character \n to ensure the file follows the line-delimited JSON format lib/Consumer/File.php68-78

__destruct()

Ensures the file handle is safely closed when the consumer object is destroyed, preventing resource leaks lib/Consumer/File.php42-50

Sources: lib/Consumer/File.php1-134