module Lapis::Docs::B_LAPIS_CLI_AND_TOOLCHAIN::K_LOGGING_AND_TELEMETRY

Overview

Logging Framework & Telemetry

Comprehensive guide to the Lapis logging and telemetry apparatus, covering runtime severity levels, the metaprogrammed define_log_filters DSL, compile-time zero-cost log elision, and the lapis log CLI tool.

Executive Summary & Key Topics

Topic	Method / Anchor	Description
Core Logging Capabilities	`.topic_00_logging_features`	High-performance features of the Lapis diagnostic logging system.
Godot.log & Severity Levels	`.topic_01_godot_log_dsl`	Writing structured log messages across standard severity levels.
Custom Domain Filters & Tags	`.topic_02_custom_filters_and_tags`	Declaring project-specific log categories using define_log_filters and log_filter.
Compile-Time Log Elision & Optimization	`.topic_03_compile_time_elision`	Stripping low-priority logs at compile time to eliminate string allocations.
CLI Log Streaming with lapis log	`.topic_04_lapis_log_cli`	Inspecting, streaming, and filtering game logs from the terminal.

Related Guides & Source References

Logging Implementation: src/libgodot/logging/
Log CLI Command: tools/lapis/src/commands/log.cr
Specifications: spec/logging_spec.cr

Defined in:

libgodot/docs/b_lapis_cli_and_toolchain/k_logging_and_telemetry.cr

Class Method Summary

.topic_00_logging_features : Nil
Core Logging Capabilities: High-performance features of the Lapis diagnostic logging system.
.topic_01_godot_log_dsl : Nil
Godotlog & Severity Levels: Writing structured log messages across standard severity levels.
.topic_02_custom_filters_and_tags : Nil
Custom Domain Filters & Tags: Declaring project-specific log categories using define_log_filters and log_filter.
.topic_03_compile_time_elision : Nil
Compile-Time Log Elision & Optimization: Stripping low-priority logs at compile time to eliminate string allocations.
.topic_04_lapis_log_cli : Nil
CLI Log Streaming with lapis log: Inspecting, streaming, and filtering game logs from the terminal.

Class Method Detail

def self.topic_00_logging_features : Nil #

Core Logging Capabilities: High-performance features of the Lapis diagnostic logging system.

Key Topics & Information

Zero-Cost Compile-Time Elision: Unused logs produce 0 bytes in output binaries
Metaprogrammed Filter DSL: define_log_filters creates typed enum values and dispatchers
BBCode Console Formatting: Rich color highlights for Godot editor output dock
Structured Records: Captures timestamp, severity, tag, channel, callsite file and line
CLI Streaming & Inspection: lapis log tails, filters, and formats logs with ANSI colors

def self.topic_01_godot_log_dsl : Nil #

Godotlog & Severity Levels: Writing structured log messages across standard severity levels.

Lapis provides built-in logging methods on Godot:

require "libgodot"

# Standard logging methods:
Godot.error("Failed to load map data", "LevelLoader")
Godot.warn("High frame time detected: #{delta * 1000} ms")
Godot.info("Player spawned at #{position}")
Godot.debug("Velocity: #{velocity}")
Godot.trace("Sub-frame physics iteration")

Or via Godot.log with a level symbol or enum:

Godot.log :info, "Audio bus initialized"
Godot.log Godot::LogLevel::Warn, "Texture cache nearing limit"

def self.topic_02_custom_filters_and_tags : Nil #

Custom Domain Filters & Tags: Declaring project-specific log categories using define_log_filters and log_filter.

Use define_log_filters to register domain-specific categories with custom BBCode hex colors and tags:

define_log_filters do
  filter :combat,    tag: "{combat}",    name_tag: "COMBAT",    color: "#ff5555"
  filter :ai,        tag: "{ai}",        name_tag: "AI",        color: "#50fa7b"
  filter :dialogue,  tag: "{dialogue}",  name_tag: "DIALOGUE",  color: "#bd93f9"
  filter :net,       tag: "{net}",       name_tag: "NETWORK",   color: "#8be9fd"
end

# In your gameplay nodes:
Godot.log :combat, "Fireball dealt 45 damage to #{target.name}"
Godot.log :dialogue, "NPC greeting started: 'Welcome stranger!'"

Or declare a single filter directly at the top of a file:

log_filter :inventory, tag: "{inv}", name_tag: "INVENTORY", color: "#f1fa8c"

def self.topic_03_compile_time_elision : Nil #

Compile-Time Log Elision & Optimization: Stripping low-priority logs at compile time to eliminate string allocations.

In production builds or performance-sensitive loops, log formatting overhead must not impact frame rate. Lapis evaluates log statements through Crystal macros:

In --release builds, debug and trace logs are completely removed from the abstract syntax tree.
Expressions passed to Godot.log (such as string interpolations "Value: #{expensive_calc}") are never executed if the log level is disabled.
You can specify a custom compile-time log threshold via compiler flag:
```
crystal build src/main.cr -Dlog_level=warn
```

def self.topic_04_lapis_log_cli : Nil #

CLI Log Streaming with lapis log: Inspecting, streaming, and filtering game logs from the terminal.

Use the lapis log CLI command to monitor game execution:

# Follow live game log output in real time
lapis log --tail

# Filter by minimum severity level
lapis log --level=WARN

# Filter by custom tag or channel
lapis log --filter=combat

# Output formatted with ANSI terminal escape colors
lapis log --ansi

# View the last 50 log records
lapis log --lines=50