🚨 Per-statement logging for crash debugging in C programs More...

Files
file	instrument_log.h
	🔍 Debug instrumentation logging runtime for ascii-chat line tracing

Macros
#define	ASCII_INSTR_SOURCE_PRINT_SIGNAL_HANDLER
	Attribute to mark signal handler functions.

Typedefs
typedef struct asciichat_instr_runtime	asciichat_instr_runtime_t
	Opaque runtime context for instrumentation logging.

Enumerations
enum	{ ASCII_INSTR_SOURCE_PRINT_MACRO_NONE = 0u , ASCII_INSTR_SOURCE_PRINT_MACRO_EXPANSION = 1u , ASCII_INSTR_SOURCE_PRINT_MACRO_INVOCATION = 2u }
	Macro expansion indicator values for asciichat_instr_log_line() More...

Functions
asciichat_instr_runtime_t *	asciichat_instr_runtime_get (void)
	Get or create the thread-local runtime context.

void	asciichat_instr_runtime_destroy (asciichat_instr_runtime_t *runtime)
	Destroy a runtime context and release resources.

void	asciichat_instr_runtime_global_destroy (void)
	Global shutdown of the instrumentation system.

void	asciichat_instr_log_line (const char file_path, uint32_t line_number, const char function_name, const char *snippet, uint8_t is_macro_expansion)
	Log a source line execution event.

bool	asciichat_instr_coverage_enabled (void)
	Check if coverage logging is enabled.

void	asciichat_instr_log_pc (uintptr_t program_counter)
	Log a program counter for coverage analysis.

Detailed Description

🚨 Per-statement logging for crash debugging in C programs

This module provides the runtime logging infrastructure for the source-print instrumentation system. When code is instrumented with ascii-instr-panic, calls to asciichat_instr_log_line() are inserted at each statement to trace execution flow.

Features

Per-Thread Logging: Each thread gets its own log file or runtime context
Configurable Filtering: Filter by file path, function name, thread ID, or using regex patterns
Rate Limiting: Sample every Nth log entry to reduce output volume
Coverage Mode: Log program counter addresses for coverage analysis
Environment Configuration: All settings controlled via environment variables

Environment Variables

ASCII_INSTR_SOURCE_PRINT_ENABLE: Enable/disable tracing (default: enabled)
ASCII_INSTR_SOURCE_PRINT_OUTPUT_DIR: Directory for log files
ASCII_INSTR_SOURCE_PRINT_INCLUDE: Substring filter for file paths (include)
ASCII_INSTR_SOURCE_PRINT_EXCLUDE: Substring filter for file paths (exclude)
ASCII_INSTR_SOURCE_PRINT_FUNCTION_INCLUDE: Substring filter for functions
ASCII_INSTR_SOURCE_PRINT_FUNCTION_EXCLUDE: Substring filter for functions
ASCII_INSTR_SOURCE_PRINT_THREAD: Filter by thread ID(s)
ASCII_INSTR_SOURCE_PRINT_RATE: Log every Nth entry (rate limiting)
ASCII_INSTR_SOURCE_PRINT_ONLY: Comma-separated selector filters
ASCII_INSTR_SOURCE_PRINT_ENABLE_COVERAGE: Enable PC logging for coverage

Regex variants (Unix only):

ASCII_INSTR_SOURCE_PRINT_INCLUDE_REGEX
ASCII_INSTR_SOURCE_PRINT_EXCLUDE_REGEX
ASCII_INSTR_SOURCE_PRINT_FUNCTION_INCLUDE_REGEX
ASCII_INSTR_SOURCE_PRINT_FUNCTION_EXCLUDE_REGEX

See also: docs/tooling/panic-instrumentation.md for full documentation

Panic Instrumentation

🚨 Overview

Panic instrumentation provides per-statement logging for debugging crashes in C programs. The core idea is simple: the last line printed before a crash is the crashing line (or the line immediately before it in most cases).

Implementation: src/tooling/panic/tool.cpp

Key Features:

Per-statement source code logging
Multi-threaded support with per-thread log files
Environment variable filtering (by file, function, thread, regex, glob patterns)
Signal-safe logging using atomic writes
Post-mortem analysis with ascii-panic-report tool
SanitizerCoverage integration for edge coverage

Background: The Core Idea

The Problem: C programs crash without error messages. When a segfault or other crash occurs, you get no information about which line of code caused it. Traditional debugging approaches have limitations:

Manual printf debugging: You have to guess where to add logs, and you might not even be in the right function yet. Hours can be wasted adding printf() calls to the wrong places.
Debuggers (gdb/lldb): Great for reproducible crashes, but timing-sensitive bugs (race conditions) may not reproduce under a debugger.
Sanitizers (ASan/UBSan): Excellent for memory bugs, but don't help with logic errors or silent hangs.

The Solution: What if we automatically insert a log before every line of code? When the program crashes, the last line printed tells you exactly where it crashed.

If your program crashes without logs:
  ??? → ??? → ??? → CRASH
 
With panic instrumentation:
  log(line 10) → log(line 11) → log(line 12) → CRASH
                                      ↑
                          Last printed line = crash location!

Why This Works:

We log BEFORE each statement executes
The logging uses atomic writes (survives crashes)
Whatever printed last was the last thing that ran
Therefore, the crash is at or after that line

Why Hasn't This Been Done Before?

Tools like this exist in various forms (SanitizerCoverage, -finstrument-functions, dynamic binary instrumentation), but they typically:

Log addresses/PCs that need symbolization, not actual source text
Work at function granularity, not per-statement
Require post-processing to map back to source

This approach is deliberately simple: print the actual source code text, so the crash location is immediately readable. No symbolization, no post-processing.

Multi-Threaded Programs

With multiple threads, the "last printed line globally" might be from a different thread than the one that crashed. The solution:

Each thread writes to its own log file (ascii-instr-<pid>-<tid>.log)
Each log line includes the thread ID
Use ascii-panic-report to find the last line from each thread
Identify the crashing thread from the crash report, then check its log

When to Use

Use panic instrumentation when:

You have a crash that's difficult to reproduce
Traditional debuggers don't work (e.g., timing-sensitive bugs)
You need to know exactly which statement crashed
You're debugging multi-threaded code

How It Works

The panic instrumentation tool transforms your C source code to print each statement before executing it:

Original code:          Instrumented code:
---------------         -------------------------------------------
int x = 5;              log("lib/foo.c:10: int x = 5;");
                        int x = 5;
 
int y = x / 0;          log("lib/foo.c:11: int y = x / 0;");  // Last printed!
                        int y = x / 0;                         // CRASH!
 
return y;               log("lib/foo.c:12: return y;");       // Never reached
                        return y;

Single-Threaded Programs: The last log line is the crash location.

Multi-Threaded Programs: Each thread writes to its own log file (ascii-instr-<pid>-<tid>.log). Use ascii-panic-report to summarize the last statement executed by each thread.

Usage

Building with Panic Instrumentation

# Build with panic instrumentation
cmake -B build -DASCIICHAT_BUILD_WITH_PANIC=ON
cmake --build build

Debugging Workflow

# 1. Build with panic instrumentation
cmake -B build -DASCIICHAT_BUILD_WITH_PANIC=ON
cmake --build build
 
# 2. Run the crashing program
export ASCII_PANIC_OUTPUT_DIR=/tmp/crash-logs
./build/bin/ascii-chat server
# ... program crashes ...
 
# 3. Find the crash location
# Single-threaded: just look at the last line
tail -n1 /tmp/crash-logs/ascii-instr-*.log
 
# Multi-threaded: use the report tool
./build/bin/ascii-panic-report --log-dir /tmp/crash-logs

The ascii-panic-report Tool

For multi-threaded programs, ascii-panic-report parses all log files and shows the last executed statement per thread:

# Build the report tool
cmake --build build --target ascii-panic-report
 
# Run it
./build/bin/ascii-panic-report --log-dir /tmp/crash-logs
 
# Output:
# Latest instrumentation record per thread (3 threads)
# ======================================================================
# tid=1234 seq=42891 pid=5678
#   timestamp : 2025-11-07T18:32:01.123456789Z
#   elapsed   : 12.3ms
#   location  : lib/network.c:512
#   function  : socket_send
#   macro     : none (0)
#   snippet   : send_packet(queue, payload)
# ----------------------------------------------------------------------
# tid=1235 seq=8901 pid=5678
#   location  : lib/mixer.c:234
#   function  : mix_audio_frames
#   snippet   : buffer[i] = left + right

Report Tool Options

# Filter to specific thread
./build/bin/ascii-panic-report --thread 1234
 
# Filter by file path
./build/bin/ascii-panic-report --include network.c
 
# Exclude files
./build/bin/ascii-panic-report --exclude video
 
# Show raw log lines
./build/bin/ascii-panic-report --raw

Log Record Format

Each log line contains:

pid=12345 tid=678 seq=42 ts=2025-11-07T18:32:01.123456789Z elapsed=12.3ms file=lib/network.c line=512 func=socket_send macro=0 snippet=send_packet(queue, payload)

pid: Process ID
tid: Thread ID
seq: Sequence number for this thread
ts: Timestamp (ISO 8601 format)
elapsed: Time since runtime initialization
file: Source file path
line: Line number
func: Function name
macro: Macro flag (0=normal, 1=from macro expansion, 2=macro invocation)
snippet: The source code being executed

Environment Variable Filtering

Reduce log volume by filtering what gets logged. Filters are checked before formatting to minimize overhead.

Basic Filters

Variable	Purpose
`ASCII_INSTR_SOURCE_PRINT_INCLUDE`	Only log files matching substring
`ASCII_INSTR_SOURCE_PRINT_EXCLUDE`	Skip files matching substring
`ASCII_INSTR_SOURCE_PRINT_THREAD`	Comma-separated thread IDs to log
`ASCII_INSTR_SOURCE_PRINT_FUNCTION_INCLUDE`	Only log functions matching substring
`ASCII_INSTR_SOURCE_PRINT_FUNCTION_EXCLUDE`	Skip functions matching substring
`ASCII_INSTR_SOURCE_PRINT_OUTPUT_DIR`	Directory for log files
`ASCII_INSTR_SOURCE_PRINT_RATE`	Log every Nth statement (throttle)
`ASCII_INSTR_SOURCE_PRINT_ENABLE`	Set to "0" to disable at runtime

Regex Filters (POSIX platforms only)

Variable	Purpose
`ASCII_INSTR_SOURCE_PRINT_INCLUDE_REGEX`	POSIX regex include filter on file path
`ASCII_INSTR_SOURCE_PRINT_EXCLUDE_REGEX`	POSIX regex exclude filter on file path
`ASCII_INSTR_SOURCE_PRINT_FUNCTION_INCLUDE_REGEX`	POSIX regex include filter on function name
`ASCII_INSTR_SOURCE_PRINT_FUNCTION_EXCLUDE_REGEX`	POSIX regex exclude filter on function name

ONLY Selectors (Advanced)

The ASCII_INSTR_SOURCE_PRINT_ONLY variable supports sophisticated allow-list filtering using comma-separated selectors:

Syntax	Description
`file=<glob>`	Match files by glob pattern
`func=<glob>`	Match functions by glob pattern
`module=<name>`	Match files under `/name/` directory
`module=<name>:<glob>`	Match files under `/name/` with basename matching glob
`<name>:<glob>`	Shorthand for `module=<name>:<glob>`
`<substring>`	Match files containing substring

Examples:

# Only log network-related files
export ASCII_INSTR_SOURCE_PRINT_INCLUDE=network.c
 
# Skip video processing (too noisy)
export ASCII_INSTR_SOURCE_PRINT_EXCLUDE=video
 
# Only log specific threads
export ASCII_INSTR_SOURCE_PRINT_THREAD=1234,5678
 
# Log every 100th statement (reduce volume)
export ASCII_INSTR_SOURCE_PRINT_RATE=100
 
# Custom output directory
export ASCII_INSTR_SOURCE_PRINT_OUTPUT_DIR=/tmp/crash-logs
 
# Advanced: Only log server render code
export ASCII_INSTR_SOURCE_PRINT_ONLY="server:render_*"
 
# Advanced: Multiple selectors
export ASCII_INSTR_SOURCE_PRINT_ONLY="file=lib/network/*,func=socket_*"
 
# Advanced: Module with glob pattern
export ASCII_INSTR_SOURCE_PRINT_ONLY="module=crypto:handshake*"
 
# Disable instrumentation at runtime (binary still instrumented)
export ASCII_INSTR_SOURCE_PRINT_ENABLE=0

Custom Log File

For debugging specific issues, you can direct all output to a single file:

# Write to a specific file (allows appending across runs)
export ASCII_CHAT_DEBUG_SELF_SOURCE_CODE_LOG_FILE=/tmp/trace.log
 
# Also echo to stderr for live viewing
export ASCII_CHAT_DEBUG_SELF_SOURCE_CODE_LOG_STDERR=1

Signal Handler Annotations

Mark functions that must remain async-signal-safe:

ASCII_PANIC_SIGNAL_HANDLER
void handle_sigint(int signum) {
    // ... signal handler code ...
}

The panic instrumentation tool skips any function carrying that annotation, ensuring inserted logging calls never appear inside signal handlers.

Safety Guarantees

Original sources remain untouched: The tool writes only to new files under build/instrumented/
Atomic writes: Each log line is emitted with a single write() call, so concurrent threads cannot interleave records
Signal tolerance: Once initialized, the runtime avoids non-signal-safe functions inside the hot path
Thread isolation: Separate files per thread prevent interleaving

Limitations and Best Practices

Performance cost: Logging every statement carries significant overhead. Use filters to narrow the scope when possible.
Timing changes: Heavy I/O can mask race conditions (Heisenbugs). After localizing the failure, confirm with sanitizers or record/replay tools.
Binary size: Expect larger binaries because every statement introduces a logging call and associated string literal.
Thread IDs differ by platform: Always copy the numeric ID from log headers when using ASCII_PANIC_THREAD.

Build System Details

File Locations

Tool source: src/tooling/panic/tool.cpp (Clang libTooling rewriter)
Runtime library: lib/tooling/panic/instrument_log.c and .h
Coverage runtime: lib/tooling/panic/instrument_cov.c
CMake integration: cmake/tooling/Panic.cmake
Helper script: cmake/tooling/run_panic_instrumentation.sh
Report tool: src/tooling/panic/report.c
Instrumented output: build/instrumented/

CMake Options

Option	Default	Description
`ASCIICHAT_BUILD_WITH_PANIC`	OFF	Enable panic instrumentation
`ASCIICHAT_PANIC_TOOL`	""	Path to pre-built tool (faster rebuilds)

SanitizerCoverage Mode

For lightweight edge coverage without full statement logging:

# Build with coverage instrumentation
cmake -B build -DCMAKE_C_FLAGS="-fsanitize-coverage=trace-pc-guard"
 
# Enable coverage logging at runtime
export ASCII_INSTR_SOURCE_PRINT_ENABLE_COVERAGE=1
./build/bin/ascii-chat server

Coverage mode logs compact pc=0x... entries that can be symbolized with llvm-symbolizer or addr2line to map back to source locations.

Tool Command-Line Options

The ascii-instr-panic tool supports:

Option	Description
`--output-dir <path>`	Where to write instrumented sources
`--input-root <path>`	Root for computing relative paths
`--log-macro-expansions`	Instrument statements from macro expansions
`--log-macro-invocations`	Emit synthetic log for macro call sites
`--filter-file <substring>`	Only instrument files matching substring
`--filter-function <substring>`	Only instrument functions matching substring
`--signal-handler-annotation <name>`	Annotation to skip (default: ASCII_INSTR_PANIC_SIGNAL_HANDLER)

Troubleshooting

No logs emitted:

Check the output directory exists and is writable
Verify filters aren't over-restrictive (unset ASCII_INSTR_SOURCE_PRINT_INCLUDE)
Check ASCII_INSTR_SOURCE_PRINT_ENABLE isn't set to "0"

**"Refusing to overwrite" errors**:

Remove existing build/instrumented/ directory
Or specify a fresh output directory

Partial log files:

Ensure disk isn't full
Check runtime didn't hit a fatal error before logging

Thread IDs don't match:

Thread IDs are platform-specific (pthread vs system TID)
Always copy the exact numeric ID from log headers

Related Tools and Alternatives

Tool	Approach	Pros	Cons
Panic instrumentation	Source rewriting	Readable output, no symbolization	High overhead
SanitizerCoverage	Edge callbacks	Lower overhead	Needs symbolization
-finstrument-functions	Function entry/exit	Very low overhead	Function granularity only
rr (record/replay)	Deterministic replay	Perfect reproduction	Linux only, heavyweight
ASan/UBSan	Memory/UB detection	Catches specific bugs	Not for all crash types
gdb/lldb	Debugger	Full control	May perturb timing

Panic instrumentation is best when you need:

Immediate, readable crash location without post-processing
To debug timing-sensitive code that doesn't reproduce under debuggers
Per-statement granularity for complex control flow

References

Defer Statements - Related tooling for automatic cleanup
Build System - CMake build options including panic instrumentation
Clang libTooling: https://clang.llvm.org/docs/LibTooling.html
SanitizerCoverage: https://clang.llvm.org/docs/SanitizerCoverage.html

Macro Definition Documentation

◆ ASCII_INSTR_SOURCE_PRINT_SIGNAL_HANDLER

#define ASCII_INSTR_SOURCE_PRINT_SIGNAL_HANDLER

#include <instrument_log.h>

Attribute to mark signal handler functions.

Functions marked with this attribute are recognized by the instrumentation tool and may receive special handling to avoid signal-unsafe operations.

Definition at line 76 of file instrument_log.h.

Typedef Documentation

◆ asciichat_instr_runtime_t

typedef struct asciichat_instr_runtime asciichat_instr_runtime_t

#include <instrument_log.h>

Opaque runtime context for instrumentation logging.

Each thread has its own runtime context that tracks:

File descriptor for the log file
Sequence numbers and call counters
Filter configuration (compiled regexes, substring patterns)
Rate limiting state

Definition at line 88 of file instrument_log.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

#include <instrument_log.h>

Macro expansion indicator values for asciichat_instr_log_line()

These values indicate whether a logged line originates from a macro expansion, the macro invocation site, or regular code.

Enumerator
ASCII_INSTR_SOURCE_PRINT_MACRO_NONE	Regular code, not from a macro
ASCII_INSTR_SOURCE_PRINT_MACRO_EXPANSION	Inside macro expansion
ASCII_INSTR_SOURCE_PRINT_MACRO_INVOCATION	At macro invocation site

Definition at line 61 of file instrument_log.h.

     {
  ASCII_INSTR_SOURCE_PRINT_MACRO_NONE = 0u,      
  ASCII_INSTR_SOURCE_PRINT_MACRO_EXPANSION = 1u, 
  ASCII_INSTR_SOURCE_PRINT_MACRO_INVOCATION = 2u 
};

Function Documentation

◆ asciichat_instr_coverage_enabled()

bool asciichat_instr_coverage_enabled ( void )

#include <instrument_log.h>

Check if coverage logging is enabled.

Coverage mode logs program counter addresses instead of full source info, useful for generating coverage reports with lower overhead.

Returns: true if ASCII_INSTR_SOURCE_PRINT_ENABLE_COVERAGE is set

Definition at line 431 of file instrument_log.c.

                                            {
  if (g_disable_write) {
    return false;
  }
 
  // Initialize runtime once using lock-free lifecycle API
  if (!lifecycle_is_initialized(&g_runtime_lc)) {
    if (lifecycle_init_once(&g_runtime_lc)) {
      asciichat_instr_runtime_init_once();
      lifecycle_init_commit(&g_runtime_lc);
    }
  }
 
  return g_coverage_enabled;
}

References lifecycle_init_commit(), lifecycle_init_once(), and lifecycle_is_initialized().

Referenced by asciichat_instr_log_pc().

◆ asciichat_instr_log_line()

void asciichat_instr_log_line	(	const char *	file_path,
		uint32_t	line_number,
		const char *	function_name,
		const char *	snippet,
		uint8_t	is_macro_expansion
	)

#include <instrument_log.h>

Log a source line execution event.

Called by instrumented code at each statement to record execution trace. The log entry includes timestamp, thread ID, sequence number, file location, function name, and source code snippet.

Parameters

file_path	Source file path (typically from FILE)
line_number	Line number in the source file
function_name	Name of the containing function
snippet	Source code snippet for this line
is_macro_expansion	One of ASCII_INSTR_SOURCE_PRINT_MACRO_* values

Note: Filters are applied before logging; entry may be skipped; Thread-safe: uses per-thread runtime context; Reentrant-safe: nested calls are detected and skipped

Definition at line 281 of file instrument_log.c.

                                                                               {
  // Instrumentation is enabled by default when the binary is built with Source Print.
  // Set ASCII_INSTR_SOURCE_PRINT_ENABLE=0 to disable tracing at runtime.
  if (!g_instrumentation_enabled_checked) {
    const char *enable_env = SAFE_GETENV("ASCII_INSTR_SOURCE_PRINT_ENABLE");
    // Default to enabled (true) - only disable if explicitly set to "0", "false", "off", or "no"
    if (enable_env != NULL && enable_env[0] != '\0') {
      g_instrumentation_enabled = asciichat_instr_env_is_enabled(enable_env);
    } else {
      g_instrumentation_enabled = true; // Default to enabled when instrumented
    }
    g_instrumentation_enabled_checked = true;
  }
 
  if (!g_instrumentation_enabled) {
    return;
  }
 
  if (g_disable_write) {
    return;
  }
 
  if (g_logging_reentry_guard) {
    return;
  }
 
  g_logging_reentry_guard = true;
 
  asciichat_instr_runtime_t *runtime = asciichat_instr_runtime_get();
  if (runtime == NULL) {
    goto cleanup;
  }
 
  if (!asciichat_instr_should_log(runtime, file_path, line_number, function_name)) {
    goto cleanup;
  }
 
  runtime->call_counter++;
  if (runtime->rate_enabled) {
    const uint64_t counter = runtime->call_counter;
    if (((counter - 1U) % runtime->rate) != 0U) {
      goto cleanup;
    }
  }
 
  if (runtime->fd < 0) {
    if (asciichat_instr_open_log_file(runtime) != 0) {
      runtime->stderr_fallback = true;
    }
  }
 
  const int fd = runtime->stderr_fallback ? STDERR_FILENO : runtime->fd;
  char buffer[ASCII_INSTR_SOURCE_PRINT_MAX_LINE];
  size_t pos = 0;
 
  uint64_t realtime_ns = time_get_realtime_ns();
  time_t sec = (time_t)(realtime_ns / NS_PER_SEC_INT);
  long nsec = (long)(realtime_ns % NS_PER_SEC_INT);
  struct tm tm_now;
  memset(&tm_now, 0, sizeof(tm_now));
  if (platform_gtime(&sec, &tm_now) != ASCIICHAT_OK) {
    memset(&tm_now, 0, sizeof(tm_now));
  }
 
  char timestamp[32];
  size_t ts_len = strftime(timestamp, sizeof(timestamp), "%Y-%m-%dT%H:%M:%S", &tm_now);
  if (ts_len == 0) {
    SAFE_STRNCPY(timestamp, "1970-01-01T00:00:00", sizeof(timestamp));
    ts_len = strlen(timestamp);
  }
 
  char elapsed_buf[32];
  elapsed_buf[0] = '\0';
  if (g_ticks_initialized) {
    uint64_t now_ns = time_get_ns();
    uint64_t elapsed_ns = time_elapsed_ns(g_start_ns, now_ns);
    if (time_pretty((uint64_t)elapsed_ns, -1, elapsed_buf, sizeof(elapsed_buf)) < 0) {
      elapsed_buf[0] = '\0';
    }
  }
 
  runtime->sequence++;
 
  const char *elapsed_field = (elapsed_buf[0] != '\0') ? elapsed_buf : "-";
 
  const char *safe_file_path = (file_path != NULL) ? file_path : "<unknown>";
  pos += safe_snprintf(buffer + pos, sizeof(buffer) - pos,
                       "pid=%d tid=%llu seq=%llu ts=%.*s.%09ldZ elapsed=%s file=%s line=%u func=%s macro=%u snippet=",
                       runtime->pid, (unsigned long long)runtime->thread_id, (unsigned long long)runtime->sequence,
                       (int)ts_len, timestamp, nsec, elapsed_field, safe_file_path, line_number,
                       function_name ? function_name : "<unknown>", (unsigned)is_macro_expansion);
 
  if (snippet != NULL) {
    size_t snippet_len = strnlen(snippet, ASCII_INSTR_SOURCE_PRINT_MAX_SNIPPET);
    for (size_t i = 0; i < snippet_len && pos < sizeof(buffer) - 2; ++i) {
      const char ch = snippet[i];
      switch (ch) {
      case '\n':
        buffer[pos++] = '\\';
        buffer[pos++] = 'n';
        break;
      case '\r':
        buffer[pos++] = '\\';
        buffer[pos++] = 'r';
        break;
      case '\t':
        buffer[pos++] = '\\';
        buffer[pos++] = 't';
        break;
      default:
        buffer[pos++] = ch;
        break;
      }
    }
  }
 
  if (pos >= sizeof(buffer) - 1) {
    pos = sizeof(buffer) - 2;
  }
 
  buffer[pos++] = '\n';
  buffer[pos] = '\0';
 
  asciichat_instr_write_full(fd, buffer, pos);
 
  // Also echo to stderr if requested via environment variable
  if (!g_echo_to_stderr_initialized) {
    const char *echo_env = SAFE_GETENV("ASCII_CHAT_DEBUG_SELF_SOURCE_CODE_LOG_STDERR");
    g_echo_to_stderr = asciichat_instr_env_is_enabled(echo_env);
    g_echo_to_stderr_initialized = true;
  }
 
  if (g_echo_to_stderr && !runtime->stderr_fallback) {
    // Write to stderr in addition to the log file
    // Suppress Windows deprecation warning for POSIX write function
#ifdef _WIN32
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wdeprecated-declarations"
#endif
    (void)posix_write(STDERR_FILENO, buffer, pos);
#ifdef _WIN32
#pragma clang diagnostic pop
#endif
  }
 
cleanup:
  g_logging_reentry_guard = false;
}

Referenced by asciichat_instr_log_pc().

◆ asciichat_instr_log_pc()

void asciichat_instr_log_pc ( uintptr_t program_counter )

#include <instrument_log.h>

Log a program counter for coverage analysis.

Records just the PC address with minimal metadata, intended for post-processing into coverage reports.

Parameters

program_counter The instruction address to log

Note: Only logs if coverage mode is enabled

Definition at line 447 of file instrument_log.c.

                                                       {
  if (!asciichat_instr_coverage_enabled()) {
    return;
  }
 
  char snippet[64];
  safe_snprintf(snippet, sizeof(snippet), "pc=0x%zx", (size_t)program_counter);
  asciichat_instr_log_line("__coverage__", 0, "<coverage>", snippet, ASCII_INSTR_SOURCE_PRINT_MACRO_NONE);
}

References ASCII_INSTR_SOURCE_PRINT_MACRO_NONE, asciichat_instr_coverage_enabled(), asciichat_instr_log_line(), and safe_snprintf().

Referenced by __sanitizer_cov_trace_pc_guard().

◆ asciichat_instr_runtime_destroy()

void asciichat_instr_runtime_destroy ( asciichat_instr_runtime_t * runtime )

#include <instrument_log.h>

Destroy a runtime context and release resources.

Closes the log file descriptor, frees compiled regexes, and deallocates the runtime structure. Called automatically by TLS destructor on thread exit.

Parameters

runtime Context to destroy (safe to pass NULL)

Definition at line 224 of file instrument_log.c.

                                                                         {
  if (runtime == NULL) {
    return;
  }
 
  if (runtime->fd >= 0) {
    platform_close(runtime->fd);
    runtime->fd = -1;
  }
 
#if ASCII_INSTR_SOURCE_PRINT_HAVE_REGEX
  if (runtime->include_regex_valid) {
    regfree(&runtime->include_regex);
    runtime->include_regex_valid = false;
  }
  if (runtime->exclude_regex_valid) {
    regfree(&runtime->exclude_regex);
    runtime->exclude_regex_valid = false;
  }
  if (runtime->function_include_regex_valid) {
    regfree(&runtime->function_include_regex);
    runtime->function_include_regex_valid = false;
  }
  if (runtime->function_exclude_regex_valid) {
    regfree(&runtime->function_exclude_regex);
    runtime->function_exclude_regex_valid = false;
  }
#endif
 
  asciichat_instr_only_list_destroy(&runtime->only_selectors);
  SAFE_FREE(runtime);
}

References asciichat_instr_runtime::exclude_regex, asciichat_instr_runtime::exclude_regex_valid, asciichat_instr_runtime::fd, asciichat_instr_runtime::function_exclude_regex, asciichat_instr_runtime::function_exclude_regex_valid, asciichat_instr_runtime::function_include_regex, asciichat_instr_runtime::function_include_regex_valid, asciichat_instr_runtime::include_regex, asciichat_instr_runtime::include_regex_valid, asciichat_instr_runtime::only_selectors, platform_close(), and SAFE_FREE.

Referenced by asciichat_instr_runtime_global_destroy().

◆ asciichat_instr_runtime_get()

asciichat_instr_runtime_t * asciichat_instr_runtime_get ( void )

#include <instrument_log.h>

Get or create the thread-local runtime context.

Returns the instrumentation runtime for the current thread, creating one if it doesn't exist. The runtime is stored in thread-local storage and cleaned up automatically when the thread exits.

Returns: Runtime context, or NULL if disabled or initialization fails

Note: Thread-safe: each thread gets its own context; Returns NULL if ASCII_INSTR_SOURCE_PRINT_ENABLE=0

Definition at line 177 of file instrument_log.c.

                                                             {
  if (g_disable_write) {
    return NULL;
  }
 
  // Initialize runtime once using lock-free lifecycle API
  if (!lifecycle_is_initialized(&g_runtime_lc)) {
    if (lifecycle_init_once(&g_runtime_lc)) {
      asciichat_instr_runtime_init_once();
      lifecycle_init_commit(&g_runtime_lc);
    }
  }
 
  asciichat_instr_runtime_t *runtime = ascii_tls_get(g_runtime_key);
  if (runtime != NULL) {
    return runtime;
  }
 
  runtime = SAFE_CALLOC(1, sizeof(*runtime), asciichat_instr_runtime_t *);
  if (runtime == NULL) {
    return NULL;
  }
 
  runtime->pid = platform_get_pid();
  runtime->thread_id = asciichat_thread_current_id();
  runtime->sequence = 0;
  runtime->call_counter = 0;
  runtime->fd = -1;
  runtime->filter_include = SAFE_GETENV("ASCII_INSTR_SOURCE_PRINT_INCLUDE");
  runtime->filter_exclude = SAFE_GETENV("ASCII_INSTR_SOURCE_PRINT_EXCLUDE");
  runtime->filter_thread = SAFE_GETENV("ASCII_INSTR_SOURCE_PRINT_THREAD");
  runtime->filter_function_include = NULL;
  runtime->filter_function_exclude = NULL;
  runtime->filters_enabled = false;
  runtime->rate = 1;
  runtime->rate_enabled = false;
 
  asciichat_instr_runtime_configure(runtime);
 
  if (ascii_tls_set(g_runtime_key, runtime) != 0) {
    SAFE_FREE(runtime);
    return NULL;
  }
 
  return runtime;
}

Referenced by asciichat_instr_log_line().

◆ asciichat_instr_runtime_global_destroy()

void asciichat_instr_runtime_global_destroy ( void )

#include <instrument_log.h>

Global shutdown of the instrumentation system.

Disables all logging, cleans up the TLS key, and resets global state. Should be called at program exit to ensure clean shutdown.

Note: After calling this, logging can be re-enabled by resetting env vars; Thread-safe: acquires global mutex during shutdown

Definition at line 257 of file instrument_log.c.

                                                  {
  if (lifecycle_shutdown(&g_runtime_lc)) {
    g_disable_write = true;
    asciichat_instr_runtime_t *runtime = ascii_tls_get(g_runtime_key);
    if (runtime != NULL) {
      ascii_tls_set(g_runtime_key, NULL);
      asciichat_instr_runtime_destroy(runtime);
    }
    ascii_tls_key_delete(g_runtime_key);
    g_ticks_initialized = false;
    g_start_ns = 0;
    g_coverage_enabled = false;
    g_output_dir_set = false;
    g_output_dir[0] = '\0';
    g_instrumentation_enabled_checked = false;
    g_instrumentation_enabled = false;
    g_echo_to_stderr_initialized = false;
    g_echo_to_stderr = false;
  }
 
  // Reset g_disable_write so instrumentation can be re-enabled in subsequent tests
  g_disable_write = false;
}

References ascii_tls_get(), ascii_tls_key_delete(), ascii_tls_set(), asciichat_instr_runtime_destroy(), and lifecycle_shutdown().

Files

Macros

Typedefs

Enumerations

Functions

Detailed Description

Features

Environment Variables

Panic Instrumentation

🚨 Overview

Background: The Core Idea

Multi-Threaded Programs

When to Use

How It Works

Usage

Building with Panic Instrumentation

Debugging Workflow

The ascii-panic-report Tool

Report Tool Options

Log Record Format

Environment Variable Filtering

Basic Filters

Regex Filters (POSIX platforms only)

ONLY Selectors (Advanced)

Custom Log File

Signal Handler Annotations

Safety Guarantees

Limitations and Best Practices

Build System Details

File Locations

CMake Options

SanitizerCoverage Mode

Tool Command-Line Options

Troubleshooting

Related Tools and Alternatives

References

Macro Definition Documentation

◆ ASCII_INSTR_SOURCE_PRINT_SIGNAL_HANDLER

Typedef Documentation

◆ asciichat_instr_runtime_t

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ asciichat_instr_coverage_enabled()

◆ asciichat_instr_log_line()

◆ asciichat_instr_log_pc()

◆ asciichat_instr_runtime_destroy()

◆ asciichat_instr_runtime_get()

◆ asciichat_instr_runtime_global_destroy()