Diagnostics

CNA snapshot 009d40f5  ·  new since alpha.1  ·  opt-in: CNA_DIAGNOSTICS=OFF|STATS|FULL

What Diagnostics is

Diagnostics (modules/diagnostics, namespace CNA::Diagnostics) is a renderer-independent, in-process observation layer: counters, gauges, per-frame counters, a rolling frame history, resource metadata, and — in FULL mode — CPU timing zones, markers, an event history and bounded recording with trace export. It depends only on the C++ standard library. It owns no thread, no socket and no renderer dependency: everything it does happens on the calling thread, at a macro call site or at a frame boundary.

Modes and how to enable them

Select the maximum level at configure time with the cache option CNA_DIAGNOSTICS:

cmake -S . -B build -DCNA_DIAGNOSTICS=STATS     # OFF (default) | STATS | FULL

The value is case-normalized, and anything other than OFF, STATS or FULL is a configure-time FATAL_ERROR. CMake turns it into the compile definition CNA_DIAGNOSTICS_LEVEL (0, 1 or 2), which is a public compile definition of the CNA build configuration: the engine and your game are compiled with the same level as soon as you link CNA. If a translation unit sees no definition, the header defaults it to 0, and a value outside 0–2 is a #error.

Runtime switches

The build level is a ceiling. At run time you may lower the mode, never raise it above what the build compiled:

Instrumentation macros

Include CNA/Diagnostics/Instrumentation.hpp. Names are string literals registered once through function-local statics at the macro site, so use stable, slash-separated names ("Physics/Contacts").

Instead of the macros you can use the handle classes directly — CounterHandle, GaugeHandle, FrameCounterHandle (register a metric once, then Add/Set), NameHandle with BeginZone/EndZone/ZoneScope, and MarkEvent. Handles are cheap to keep; a registration beyond the metric cap, or a conflicting re-registration (different kind, unit or accuracy under an existing name), yields an inert handle that silently does nothing.

What the engine already measures

With STATS or FULL the engine itself is instrumented at a handful of common points, so a game gets useful numbers without writing any instrumentation. All names below are registered by engine code (not by any single renderer):

Not published anywhere at this snapshot: GPU timings, input metrics and total process or driver memory. No production code registers an IDiagnosticsSource. (CNA’s changelog mentions Vulkan GPU timing query pools, but they are not wired to Diagnostics.)

The public API

Two public headers: CNA/Diagnostics/Instrumentation.hpp (the macros) and CNA/Diagnostics/Diagnostics.hpp (types and functions).

A frame counter shows up in Snapshot::metrics with the value of the last completed frame; the same counter, per frame, is in each FrameSample::metrics in recentFrames (the rolling history keeps the newest 240 frames, and copies at most 64 frame counters into each).

Resource metadata

The graphics layer registers metadata (never contents) for Texture2D, Texture3D, texture cubes, RenderTarget2D, render-target cubes, VertexBuffer and IndexBuffer, and unregisters it when the object is disposed or dies. Every other GraphicsResource (a state object, an effect and so on) also registers a zero-byte ResourceKind::Unknown record when it is constructed, so Snapshot::resources lists those too. Each record carries a stable id, a ResourceKind, a label, a format string, width, height, depth, mip count, byte size and an Accuracy for that byte size. The format is currently the numeric SurfaceFormat value. Snapshot::registeredResourceBytes is a mixed aggregate of exact and estimated sizes, not a measurement of GPU memory: nothing is read back from the GPU. Your own code can register a ResourceKind::Custom resource with ResourceHandle.

Optional sources

A renderer or subsystem may register an IDiagnosticsSource with RegisterSource. At each frame boundary (from EndFrame, never from a background thread) every registered source’s Collect(FrameStatisticsSink&) is called synchronously. The contract is strict: return promptly and publish only data that is already available; never wait for the GPU or a queue. A source that throws is counted in sourceCollectionFailures, and a source that tries to end a frame from inside Collect is refused and counted as a malformed frame. No production code registers a source at this snapshot; the interface exists so renderers can publish asynchronous GPU statistics later.

Recording and trace export (FULL)

StartRecording(maximumEvents) returns an active RecordingSession only when the build and the current runtime mode are FULL (and maximumEvents is non-zero); otherwise it returns an inactive session, and StopRecording on it returns an empty trace. The event count is clamped to the size of the process history (32,768) and StopRecording copies at most that many of the newest events.

Limits

Overhead

What the code guarantees, independent of any benchmark:

• OFF: macros compile out and evaluate nothing; no diagnostics state, thread or lock is reachable from them. CNA’s benchmark note reports that a symbol check of the objects for Game.cpp, GraphicsDevice.cpp, SpriteBatch.cpp and TextureCollection.cpp finds no CNA::Diagnostics reference.
• STATS: a counter or gauge update is one relaxed atomic operation after a relaxed load of the runtime mode. Frame completion iterates only the registered metrics and calls registered sources synchronously. No mode creates a profiler thread or does periodic work.
• FULL: a zone or marker writes into a thread-local ring; the first event on a thread allocates that thread’s context; merging into the process history happens at frame boundaries or on an explicit provider read.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCNA_DIAGNOSTICS=STATS -DCNA_BUILD_BENCHMARKS=ON
cmake --build build --target cna_diagnostics_benchmark
build/modules/diagnostics/cna_diagnostics_benchmark

Repeat for OFF and FULL (a fresh build directory or a reconfigure each time, because the level is a compile-time definition), and compare medians of several runs.

Tests and CI

DiagnosticsTests.cpp holds 40 test definitions; the graphics module adds 6 (GraphicsDiagnosticsTests.cpp) and the audio module 1 (AudioDiagnosticsTests.cpp). They are part of the ordinary CnaTests glob, with a focused target CnaDiagnosticsTests; the counts are static TEST definitions, not pass results. No CI workflow configures CNA_DIAGNOSTICS above OFF, so the STATS and FULL paths are exercised only where a developer builds them.

End-to-end recipe

Every call in the following was checked to compile against the snapshot’s headers at all three levels (the second half needs to sit inside a function body); the CMake step is the option the build defines. Tutorial 155 walks through the same idea in a complete project. First configure, then instrument, then read.

cmake -S . -B build -DCNA_DIAGNOSTICS=FULL          # or STATS

#include "CNA/Diagnostics/Instrumentation.hpp"
#include <fstream>

void Simulate() {
    CNA_PROFILE_SCOPE_CATEGORY("Physics/Simulate", CNA::Diagnostics::Category::Update);  // FULL
    CNA_DIAGNOSTICS_FRAME_COUNTER_ADD("Physics/Contacts", 12);                            // STATS and FULL
    CNA_DIAGNOSTICS_GAUGE_SET("Physics/ActiveBodies", 340);
}

// After some frames have run:
auto snapshot = CNA::Diagnostics::GetProvider().CaptureSnapshot();   // metrics, recentFrames, resources
auto recording = CNA::Diagnostics::StartRecording(4096);             // FULL only; otherwise inactive
/* ... run frames ... */
auto trace = CNA::Diagnostics::StopRecording(recording);
std::ofstream out("trace.json");
(void) trace.WriteChromeTrace(out);                                   // open in a Chrome/Perfetto trace viewer

Your game gets the level for free by linking CNA, which carries CNA_DIAGNOSTICS_LEVEL. To look at the same data from a browser while the game runs, add the Inspector.

Known limitations

• No GPU timings, input metrics or process/driver memory totals are published; resource byte counts are declared, partly estimated sizes, not measurements.
• No renderer or subsystem registers an IDiagnosticsSource yet.
• The level is a compile-time property of every target that links CNA; mixing translation units built with different levels is not supported.
• There is no C ABI and no environment-variable control.
• No CI lane builds or runs STATS or FULL; the timing figures are CNA’s own, from one machine.
• A macro site registers its name the first time it runs, so pass a string literal, not a runtime string: a later, different value at the same site is ignored.