Buccaneer

Buccaneer is a solution for the Unreal Engine that logs a variety of performance metrics and semantic events by pushing the collected data to an accompanying part of Go servers. From here, the Prometheus software scrapes the endpoints exposed by the Go server, storing the scraped metrics as it goes. Through the use of a Grafana dashboard, the scraped metrics can be seen in an easily interpretable manner, with the semantic events being overlayed as annotations.

NOTE: The Buccaneer4PixelStreaming plugin only works in Unreal Engine 5 and is dependent on both the Buccaneer base plugin and the Pixel Streaming plugin.

Requirements

Architecture

The Buccaneer plugin consists of two primary components:

Time-Series Data Emitter

The time-series data emitter collects real-time performance data and exports it for consumption by Prometheus where the per-instance data can then be aggregated in order to examine the performance of an entire multi-instance simulation.
Semantic Event Emitter

The semantic event emitter facilitates emitting arbitrary and user-defined discrete event information for consumption by Promtail. The consumed logs are then displayed as annotations on the Grafana dashboard through the use of Loki.

Using Buccaneer

How do I use these custom plugins in my Unreal Project?

Adding to your project
- Navigate to your project folder which contains [ProjectName].uproject
- Copy the Plugins folder to this directory

Using the Semantic Event Emitter

Interacting with the semantic event emitter can be done with the Emit Semantic Event blueprint node

or with the EmitSemanticEvent(FString Level, FString Event) function. In order to use this function, you must add the SemanticEventEmitter to your module dependencies and include SemanticEventEmitter.h

Configuration

The majority of the configurations provided can be left as-is. However, Line 19 of promtail-local-config.yaml requires you to configure the path to the log file of the events server.

Starting the Buccaneer Server

The Buccaneer server can be started by running its executable located under /Build or by running go run ./main.go from the Server/BuccaneerServer directory.

By default, the server listens for metric and event pushes on 127.0.0.1:8000

Required Launch Arguments

The following launch arguments must be specified when launching an Unreal Engine application that uses Buccaneer:	Command Line Argument	Description
-BuccaneerURL=\	Specifies the URL used to push performance metrics and semantic events to

Optional Launch Arguments

The following launch arguments aren't required. However, many applications using Buccaneer may find them useful:	Command Line Argument	Description
-BuccaneerID=\	Specifies the ID of the instance. This is used in distinguishing which metrics came from which instance. If the argument is left empty, the ID is generated by the stats server
-BuccaneerMetadata=\	Specifies additional metadata for use in distinguishing instances in multi-instance deployments. This is a semi-colon separated list of key:value pairs. eg "-BuccaneerMetadata=KeyX:ValueX;KeyY:ValueY"

Buccaneer Plugin Configuration

The following launch arguments must be specified when launching an Unreal Engine application that uses Buccaneer:	Command Line Argument	Default Value
-BuccaneerEnableStats=\<true/false>	true	Whether the pushing of performance stats is enabled
-BuccaneerEnableEvents=\<true/false>	true	Whether the pushing of semantic events is enabled
-Buccaneer4PixelStreamingEnableStats=\<true/false>	true	Whether the pushing of stats collected from pixel streaming is enabled

Buccaneer Runtime Configuration

The following CVars can be used to toggle on and off aspects of Buccaneer at runtime:	Command Line Argument	Default Value	Description
Buccaneer.EnableStats=\<1/0>	1	Whether the pushing of performance stats is enabled
Buccaneer.EnableEvents=\<1/0>	1	Whether the pushing of semantic events is enabled

A typical application launch is as follows:

MyBuccaneerApplication.exe -BuccaneerURL="http://127.0.0.1:8000"

Running the Docker Compose demo

To try Buccaneer with a demo project, you can use the Docker Compose demo located in the Examples subdirectory. The demo has the following requirements:

One of the Linux distributions that is supported by the NVIDIA Container Toolkit
The proprietary NVIDIA GPU drivers
Docker
NVIDIA Container Toolkit

To start the demo, simply run the command docker compose up in the Examples/Compose subdirectory. Docker Compose will automatically download all of the required container images and start the containers for each component of the stack. Once everything is running, open two web browser tabs:

http://127.0.0.1 - This is a demo Unreal Engine application that uses Pixel Streaming to allow streaming via a browser.
http://127.0.0.1:3000/dashboards - This is the Grafana dashboard that displays metrics collected from the Unreal Engine application. Log in using the username admin and the password admin, and select "Unreal Engine Metrics" from the list of available dashboards.

TensorWorks / Buccaneer

readme