microsoft / ue4telemetryvisualizer

Telemetry emitter and in-editor visualization plugins for use in games and other projects built on Unreal Engine.

UE4 Telemetry Visualizer

This is a plugin for adding telemetry to your UE4 game and visualizing that telemetry in the UE4 editor. It is featured in the Azure Gaming Reference Architectures. There is also a Unity version of this plugin.

Summary

Game telemetry itself is nothing new, but the number of "out of the box" solutions for games to leverage while in development are next to none. Historically, developers would use log files to debug issues, which worked fine for local debugging. Today's games more closely resemble distributed systems, interacting with other clients, servers, and various cloud services regularly.

This project was inspired by developers needing to answer questions for which their own development systems could not provide all the answers, and who were tired of asking people to email them log files!

Goals

• Make it as simple as possible for anyone on a development team to add and view telemetry - No dedicated engineers required!
• Iterative development model - You won't know what you'll need up front, so make it as easy as possible to add things along the way!
• Low cost of operation

Features

• Telemetry generation API and asynchronous upload with configurable buffers and send intervals,
  • Optimized for a large volume of telemetry (10's to 100's per second) from a small number of clients (10-30)
  • Batching and compression out of the box, common fields denormalized server side to reduce bandwidth requirements
• Simple UI to build queries in editor, wraps a JSON defined query language usable by external tools
  • Customizable colors and shapes, as well as heatmaps

Example use cases for telemetry during development

Programmers

• Code Correctness: Asserts, non-critical errors, unlikely code paths taken
• Profiling: Tracking system counters over thresholds (RAM, CPU, frame render time)

Artists and Game Designers

• Game asset tracking (missing assets, over-budget assets, hitches)
• Playtesting analytics in realtime (focus groups, friends and family alpha builds)
• Game mechanics validation (AI, balancing)

Testing and Quality

• Testing test coverage per build
• Bug correlation, reproduction, regression

Setup Instructions

This plugin requires a server component to send telemetry to, which can be found here: https://github.com/Azure-Samples/gaming-in-editor-telemetry.

Plugin setup instructions can be found here.

If you find issues, please add them to the issue tracker.

Contributing

Microsoft Open Source Code of Conduct

We welcome contributions to this project. This project Please read the contributing information before submitting a pull request. If you need inspiration, please check the issue tracker. We are using the GitHub Flow development model.

ue4telemetryvisualizer's Issues

Heatmap Colors Scaling Issue

When changing the Maximum value in the Type Range to a value below the actual maximum, Heatmap "cell" colors that have actual values above the new maximum will not scale correctly.

To Reproduce
Steps to reproduce the behavior:

1. Select an Event type to heatmap
2. Generate the heatmap
3. change the maximum range value to something (significantly) less that the generated value
4. Observe cells with colors that look incorrect as though the color scaling goes "over" the maximum color

Expected behavior
Every cell in a heatmap will have colors that fall between the min and max color values

From the code it looks as though the values to select color range can go over 1.0 because of the way they are clamped. The code in question is from TelemetryVisualizerTab.cpp (around lines 1090 thru 1150) where the tempColorValue is being clamped (there are 4 instances of this clamping):
tempColorValue = FMath::Max(tempColorValue, 0.f);
tempColorValue = FMath::Min(tempColorValue, (float)m_heatmapMaxValue);

The incoming tempColorValue can (and will when max range is smaller than actual) be above 1.0. Clamping clamping to 1.0 should fix the problem as such:
tempColorValue = FMath::Max(tempColorValue, 0.f);
tempColorValue = FMath::Min(tempColorValue, 1.f);

If the value is properly clamped between 0.0 and 1.0 then the scaling of the color will be proper and modified max values will show as actual max color from this call:
tempActor->AddEvent(parts[i].GetCenter(), orientation[i], m_heatmapColor.GetColorFromRange(tempColorValue), m_heatmapShapeType, scaledHeatmapSize, tempValue);

Heatmap cell Value is incorrect

Describe the bug
When using value or value-bar to generate heatmap, the cell values get added up when they should use the average value of all the events within that cell. The effect of this is cells with multiple events will have the wrong and potentially way out of range value. for example, using FPS events, if I'm at a steady 30 fps and I have 3 events in a cell all with value of 30 fps, the actual cell value will be calculated as 90, not 30.

To Reproduce
Steps to reproduce the behavior:

1. create a heatmap with cells that have multiple events in them
2. generate and note the max value reported will be higher than the highest individual event value in the event set

Expected behavior
When the heatmap calculates the value for a cell it should be the average of all the values of the events in that cell. EG. if I'm using event values of frames per second and I have a steady 30fps, in a cell with multiple events I should have a cell value of 30, not the value of all the events added up.

The solution to this is to simply average the values within a cell. Take the current added up value and divide by the number of events in the cell.

Heatmap Colors Scaliing Issue #2

Describe the bug
There is an issue with how the heatmap colors are scaling between low and high value colors due to an unsigned value error in calculating the range between colors.

To Reproduce
Steps to reproduce the behavior:

1. Create a heatmap
2. Change the low and high colors
3. depending on the colors selected, the newly generated heatmap colors may seem off

Expected behavior
The heatmap colors scale between high and low linearly in the R, G, B, and Alpha values

The range values that are being calculated between the low and high colors are only ever positive values because the ColorRange struct uses uint8 values for the ranges:
struct ColorRange
{
uint8 A;
uint8 B;
uint8 G;
uint8 R;
};

The range is created be subtracting the low color value members from the high color value members, but that value could be a negative value. eg. if my high color is r:255, g:0, b:0, a:128 (default) and low color is r:0, g:255, b:0, a:128 (default), the resulting range values are r:255, g:1, b:0, a:0 when the should be r:255, g:-255, b:0, a:0

So when the range is used to scale between low and high the colors right now are not as intended.

Crash when using TelemetryBuilder without Initialize

Describe the bug
Attempting to use TelemetryBuilder without first calling its Initialize function will result a crash

Expected behavior
Errors/asserts should be present to stop these issues from happening

Build failed with linker errors

Describe the bug
Building a Blank C++ UE4 project after adding the GameTelemetry plugin fails with linker errors.

To Reproduce
Steps to reproduce the behavior:

1. Create a new Blank C++ project using Unreal Editor 4.23.0
2. Follow the steps mentioned in the Instructions doc
3. When performing Step 7. Build the game from Visual Studio 2017, the linker errors are encountered.

1>LINK : error LNK2001: unresolved external symbol IMPLEMENT_MODULE_GameTelemetry
1>E:\Projects\Unreal\TelemetryTest\Plugins\GameTelemetry\Binaries\Win64\UE4Editor-GameTelemetry.dll : fatal error LNK1120: 1 unresolved externals


1>LINK : error LNK2001: unresolved external symbol IMPLEMENT_MODULE_GameTelemetryVisualizer
1>E:\Projects\Unreal\TelemetryTest\Plugins\GameTelemetry\Binaries\Win64\UE4Editor-GameTelemetryVisualizer.dll : fatal error LNK1120: 1 unresolved externals

Expected behavior
Build should succeed.

Screenshots
Build :

Rebuild :

Desktop (please complete the following information):

• OS: Microsoft Windows 10 Pro
• Version : 10.0.17763 Build 17763
• Visual Studio 2017 version : 15.9.16
• UE4 Engine version: 4.23.0

Additional context
Please find attached the build output and rebuild output in text format as well.

telemetry-build-failure.txt
telemetry-rebuild-failure.txt