etl-file

Parses Windows ETL (Event Trace Log) files and retrieves event trace records. Supports MOF-based system trace records and ETW (Event Tracing for Windows) records, enabling analysis of system events such as processes, threads, and disk I/O.

Command properties

Item	Description
Command type	Driver query
Required permission	None
License usage	Counted
Parallel execution	Not supported
Distributed execution	Runs on Data Node (mapper)

Syntax

etl-file [zippath=STR] [zipcharset=STR] FILE_PATH

Options

zippath=STR: Path to the ZIP file containing the ETL file. Use this to query ETL files directly inside a ZIP archive.
zipcharset=STR: Character set for ZIP file entries (default: utf-8)

Target

FILE_PATH: Path to the ETL file to query. You can use a wildcard (*) to specify multiple files.

Output fields

ETL files contain three types of records: System Trace, Trace, and Event. Output fields differ depending on the record type.

Common fields:

Field	Type	Description
`_file`	string	Original ETL file name
`_time`	timestamp	Event occurrence time
`entry_type`	string	Record type. One of `System Trace`, `Trace`, or `Event`
`thread_id`	long	Thread identifier
`process_id`	long	Process identifier

Additional fields for System Trace records:

Field	Type	Description
`opcode`	integer	Event operation code
`event_trace_group`	string	Event trace group. One of `HEADER`, `PROCESS`, `THREAD`, `DISKIO`, `NETWORK`, etc.
`version`	integer	Record version
`kernel_time`	timestamp	Kernel time
`user_time`	timestamp	User time

Additional fields for Trace records:

Field	Type	Description
`guid`	string	Event provider GUID
`processor_time`	timestamp	Processor timestamp
`user_data`	binary	Event user data

Additional fields for Event records:

Field	Type	Description
`provider_id`	string	Event provider GUID
`activity_id`	string	Event activity GUID
`processor_time`	long	Processor timestamp

Error codes

Parse errors

N/A

Runtime errors

Error code	Message	Description	Post-processing
-	cannot load etl file	Unable to read or parse the ETL file	Stops query execution

Description

The etl-file command parses Windows ETL files and retrieves event trace records. ETL files store system events recorded by the Windows Event Tracing (ETW) system in binary format.

A file can contain three types of records: System Trace, Trace, and Event. System Trace records are kernel events using the MOF (Managed Object Format) schema. Trace records are MOF-based user-mode events. Event records are ETW manifest-based events.

The command extracts a reference timestamp from the first System Trace record in the HEADER group and uses it to calculate timestamps for subsequent records. ETW events can generate additional output fields by parsing fields with the built-in ETW schema.

Examples

Query an ETL file
```
etl-file /opt/logpresso/evidence/Logfile.etl
```
Retrieves all event trace records from the ETL file at the specified path.

Filter only process events

etl-file /opt/logpresso/evidence/Logfile.etl
| search event_trace_group == "PROCESS"

Retrieves only process creation and termination events.

Query an ETL file inside a ZIP archive
```
etl-file zippath=/opt/logpresso/evidence/artifacts.zip Logfile.etl
```
Retrieves event trace records from an ETL file inside a ZIP archive.