Crate gwr_track 

gwr-track

gwr_track is the logging library used by the GWR engine and all components. It can be used to generate either text-based or Cap’n Proto-based binary log files.

Entities

gwr_track provides the Entity struct. It is designed to represent a unique simulation Entity/component which exists within the simulation hierarchy.

An Entity will have a unique location within the simulation hierarchy and are each assigned a unique Id. For example:

top::processor0::cpu102::memory

Tracing can be configured globally or enabled/disabled depending on regular expressions matching entity names.

EntitiyMonitor

The EntityMonitor allows the user to create helper structs that can monitor an Entity and emit useful statistics through track_value() calls.

Objects

For short-lived parts of the simulations (like an Ethernet frame or a memory access) the user can create a track object. These are given unique Ids like Entities and Entities so that their lifecycle can be tracked across the simulation.

IDs

Each Entity will have a unique 64-bit Id. This ID is used throughout the log/bin files in order to identify the originator of messages and to reduce the size of the files.

Ids are also assigned to track Objects. Objects do not contain an Entity because they flow through the simulation and so their location within the simulation changes. However, the logging of packets is controlled by the Entity that creates the object.

Macros

The library provides a number of macros that provide the logging functionlity with a minimal run-time overhead when not enabled.

There are the macros that map to log messages of the specified level:

• trace! - a message that will only be emitted if log level is Trace.
• debug! - a message that will only be emitted if log level is Debug or above.
• info! - a message that will only be emitted if log level is Info or above.
• warn! - a message that will only be emitted if log level is Warn or above.
• error! - a message that will only be emitted if log level is Error or above.

Note: the logging level is controlled globally with the ability to configure it at the level of any Entity within the simulation hierarchy.

Re-exports

pub use tracker::Track;

pub use tracker::Tracker;

pub use id::Id;

Modules

builder

Library functions to build trackers as defined by the user.

entity

A simulation entity.

gwr_track_capnp

Auto-generated Cap’n Proto module

id

Id

perfetto_trace_builder

Support for generating Perfetto traces.

test_helpers

This module provides helper functions for testing logging output

trace_visitor

This module provides helper functions for dealing with Cap’n Proto binary data.

tracker

Include the trackers. Define the Track trait a number of Trackers.

Macros

build_aka

Helper function for creating local Aka derived from incoming Aka

connect

Connect two entities

create_id

Create a unique ID for tracking.

debug

The debug macro provides a wrapper for the log macro at level log::Level::Debug

destroy

Add an entity destroy event

destroy_id

Destroy an ID

error

the error macro provides a wrapper for the log macro at level log::Level::Error

info

The info macro provides a wrapper for the log macro at level log::Level::Info

log_base

Base macro for log messages of all level.

set_time

Update the current time.

test_init

Initialise the logging system for tests

trace

The trace macro provides a wrapper for the log macro at level log::Level::Trace

track_create_object

Add an object creation event.

warn

The warn macro provides a wrapper for the log macro at level log::Level::Info

Constants

NO_ID

ID value which indicates where there is no valid ID

ROOT

The root ID from which all other IDs are derived

Functions

str_to_level

Take the command-line string and convert it to a Level

Type Aliases

Writer

A type alias for objects that receive log / trace events.