Skip to main content
Version: 1.2.0

Example: Log Collection with Agents

Synopsis​

Learn how to deploy Agent endpoints for collecting Windows Event logs from remote computers and sending them to a centralized Director for processing. This example demonstrates basic Agent-Director coordination using websocket communication.

What You'll Learn:

  • Deploy Agent on a Windows client machine
  • Configure Director to receive Agent connections
  • Collect Windows Event logs remotely
  • Verify log collection is working

Scenario​

You have a Windows server running Director and want to collect Windows Event logs from multiple Windows client machines across your network. Rather than installing Director on every machine, you deploy lightweight Agent endpoints that collect logs locally and send them to the centralized Director.

Architecture:

  • Director: Server-side telemetry processor (receives and processes logs)
  • Agent: Client-side log collector (collects Windows Events, sends to Director)
  • Communication: Websocket connection from Agent to Director

The Agent uses a WebSocket connection because it provides reliable, persistent communication that can handle network interruptions gracefully. When the Agent starts, it identifies itself using a device ID, and the Director sends back the appropriate configuration for that specific endpoint.

Setup​

Configure the Director for Agent connections​

Create a device configuration on your Director server that defines what your Agent should collect.

<vm_root>/Director/config/windows-log-collector.yml
devices:
  - id: 2
    name: "Windows Server"
    type: windows
    status: true
    properties:
      type: agent
      debug:
        level: 4
        console:
          status: true
    definitions: 
      - name: windows_main_log_collector
      - name: windows_security_log_collector

This configuration tells the Agent windows_main_log_collector to enable event log collection and with windows_security_log_collector definition to collect all following logs events.

"Microsoft-Windows-AppLocker/EXE and DLL" "Microsoft-Windows-AppLocker/MSI and Script" "Security"

Debug level 4 provides detailed logging to help monitor the collection process.

Configure the Agent on the Windows client​

Deploy Agent on the Windows client machine, and create a simple configuration that connects to Director.

<vm_root>/Agent/config/vmetric.yml
device:
    id: 2
director:
    address: 192.168.1.100

This simple configuration goes in the Agent's vmetric.yml file and tells it two things: its device ID (2) and where to find the Director server (192.168.1.100). The Agent connects to the Director using websocket communication and receives its collection instructions, which are then stored in a vmf file with vmetric.vmf binary file name in config folder automatically.

The Agent will automatically start collecting Windows Security events according to the windows_security_log_collector definition, which includes essential events like successful logons (4624), failed logons (4625), account changes (4720-4740), and system events (1102, 4688, 4719).

note

Replace 192.168.1.100 with the actual IP address of your Director server. The device ID (2) must match exactly what you configured in the Director's device configuration. The Agent gets all collection details from the Director - no local event configuration needed.

Install the services​

On Director's machine:

vmetric-director.exe -service install

On the client machine:

vmetric-agent.exe -service install

Start the services​

On Director's machine:

vmetric-director.exe -service start

On the client machine:

vmetric-agent.exe -service start

Trial​

Verify the Agent connection​

Check Director logs for Agent connection:

On Director's machine:

Get-Content -Path <vm_root>\Director\storage\logs\director.log -Tail 10 -Wait

You should see output similar to this in the Director logs:

[2025-08-26 10:07:17] [Information] [vmetric-director] Received logs from Device:Windows Server (2). Number of logs 73

Device name Windows Server and Device ID 2 and the number of logs collected from the agent device 73.

These messages confirm that your Agent has successfully connected to the Director and is receiving configuration. The websocket connection is established and the Agent is actively collecting Windows Security events using the predefined definition.

warning

If you don't see these messages, check that:

  • The Director is actually running
  • The IP address in your Agent configuration matches the Director's IP
  • The device ID (2) matches in both configurations
  • Windows Firewall isn't blocking the websocket connection
  • The Agent has permissions to read Windows Security logs

Verify the event collection​

Now let's test the setup by generating some Windows login events on the client machine. You can simply lock and unlock your screen, or log out and log back in. Then check if these events appear in the Director's processing queue:

On Director's machine:

Get-ChildItem <vm_root>\Director\storage\queue\

You should see queue files containing collected Windows Event logs. These files have names like eventlog.queue.001.vmfl or similar in the <vm_root>/Director/storage/queue/eventlog/ directory. The presence of these files means your Agent is successfully collecting Windows Security events and sending them to the Director.

note

VMFL (VirtualMetric File Format) is DataStream's efficient binary format for storing telemetry data. The files are organized by log type - Windows Events go to the eventlog queue directory. These files are processed by the Director automatically.

Monitoring​

Your Agent setup is working correctly if:

  • Director logs show Agent connection messages in <vm_root>/Director/storage/logs/director.log
  • Queue files appear in <vm_root>/Director/storage/queue/eventlog/ directory

Generate test events by locking/unlocking your Windows screen, then check for new queue files. If you see new .vmfl files appearing, the Agent is successfully collecting Windows Security events and sending them to the Director for processing.