json.h File Reference

📝 JSON structured logging output More...

Go to the source code of this file.

Functions
void	log_json_write (int fd, log_level_t level, uint64_t time_nanoseconds, const char *file, int line, const char *func, const char *message)
	Write a log entry as a JSON object to the json output fd.
void	log_set_json_output (int fd)
	Set the JSON output file descriptor.
void	log_json_async_safe (int fd, log_level_t level, const char *file, int line, const char *func, const char *message)
	Async-safe JSON logging for signal handlers.

Detailed Description

📝 JSON structured logging output

Definition in file include/ascii-chat/log/json.h.

Function Documentation

log_json_async_safe()

void log_json_async_safe	(	int	fd,
		log_level_t	level,
		const char *	file,
		int	line,
		const char *	func,
		const char *	message )

Async-safe JSON logging for signal handlers.

This function formats and writes JSON logs using ONLY async-safe operations:

• snprintf for string formatting
• write() for output
• No allocations, no locks, no library calls

Suitable for calling from signal handlers (SIGTERM, SIGINT, etc.)

Parameters

fd	File descriptor to write to (typically STDOUT_FILENO or STDERR_FILENO)
level	Log level (DEBUG, INFO, WARN, ERROR, FATAL)
file	Source file name (can be NULL)
line	Source line number (can be 0)
func	Function name (can be NULL)
message	Log message (must not be NULL)

This function formats and writes JSON logs using ONLY async-safe operations:

• snprintf for string formatting
• write() for output
• No allocations, no locks, no library calls

Suitable for calling from signal handlers (SIGTERM, SIGINT, etc.)

Parameters

fd	File descriptor to write to (typically STDOUT_FILENO or STDERR_FILENO)
level	Log level
file	Source file name (may be NULL)
line	Source line number
func	Function name (may be NULL)
message	Log message (must not be NULL)

Definition at line 273 of file log/json.c.

                                                                                                                       {
  if (fd < 0 || !message) {
    return;
  }
 
  /* Format JSON manually on stack using only async-safe operations */
  char json_buffer[LOG_JSON_JSON_BUFFER_SIZE];
  char escaped_message[LOG_JSON_ESCAPED_MESSAGE_BUFFER_SIZE];
  char escaped_file[LOG_JSON_ESCAPED_FILE_BUFFER_SIZE];
  char escaped_func[LOG_JSON_ESCAPED_FUNC_BUFFER_SIZE];
  char timestamp_buf[LOG_TIMESTAMP_BUFFER_SIZE];
 
  /* Escape the strings (normalize file path to project-relative) */
  json_escape_async_safe(message, escaped_message, sizeof(escaped_message));
  if (file) {
    const char *rel_file = extract_project_relative_path(file, ASCIICHAT_OWNED_SOURCE_DIRS);
    json_escape_async_safe(rel_file, escaped_file, sizeof(escaped_file));
  } else {
    escaped_file[0] = '\0';
  }
  json_escape_async_safe(func ? func : "", escaped_func, sizeof(escaped_func));
 
  /* Format timestamp using only async-safe operations */
  uint64_t time_ns = time_get_realtime_ns();
  format_timestamp_microseconds(time_ns, timestamp_buf, sizeof(timestamp_buf));
 
  /* Get thread ID (note: thread_current_id is assumed to be async-safe) */
  uint64_t tid = (uint64_t)thread_current_id();
 
  /* Format complete JSON object with timestamp */
  int written = snprintf(json_buffer, sizeof(json_buffer),
                         "{\"header\":{\"timestamp\":\"%s\",\"level\":\"%s\",\"tid\":%lu,"
                         "\"file\":\"%s\",\"line\":%d,\"func\":\"%s\"},"
                         "\"body\":{\"message\":\"%s\"}}\n",
                         timestamp_buf, log_level_to_string(level), (unsigned long)tid, file ? escaped_file : "", line,
                         func ? escaped_func : "", escaped_message);
 
  /* Write to fd if successful */
  if (written > 0 && written < (int)sizeof(json_buffer)) {
    platform_write_all(fd, (const uint8_t *)json_buffer, (size_t)written);
  }
}

References extract_project_relative_path(), LOG_JSON_ESCAPED_FILE_BUFFER_SIZE, LOG_JSON_ESCAPED_FUNC_BUFFER_SIZE, LOG_JSON_ESCAPED_MESSAGE_BUFFER_SIZE, LOG_JSON_JSON_BUFFER_SIZE, LOG_TIMESTAMP_BUFFER_SIZE, and platform_write_all().

Referenced by log_console_impl().

log_json_write()

void log_json_write	(	int	fd,
		log_level_t	level,
		uint64_t	time_nanoseconds,
		const char *	file,
		int	line,
		const char *	func,
		const char *	message )

Write a log entry as a JSON object to the json output fd.

Outputs a newline-delimited JSON (NDJSON) format log entry with the following structure:

{
  "header": {
    "timestamp": "14:30:45.123456",
    "level": "INFO",
    "tid": 12345,
    "file": "lib/network/server.c",
    "line": 42,
    "func": "handle_client"
  },
  "body": {
    "message": "Client connected"
  }
}

The file, line, and func fields are omitted from the output when they are NULL/0 (which typically occurs in release builds).

Parameters

fd	File descriptor to write JSON to (-1 = disabled)
level	Log level (DEBUG, INFO, WARN, ERROR, FATAL)
time_nanoseconds	Current time in nanoseconds (used to format timestamp)
file	Source file name (can be NULL)
line	Line number (can be 0)
func	Function name (can be NULL)
message	Formatted log message

See also

log_set_json_output() - Set the JSON output file descriptor

Definition at line 104 of file log/json.c.

                                         {
  if (fd < 0 || !message) {
    return;
  }
 
  /* Create root object */
  yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
  if (!doc) {
    return;
  }
 
  yyjson_mut_val *root = yyjson_mut_obj(doc);
  if (!root) {
    yyjson_mut_doc_free(doc);
    return;
  }
  yyjson_mut_doc_set_root(doc, root);
 
  /* Create "header" object */
  yyjson_mut_val *header = yyjson_mut_obj(doc);
  if (header) {
    yyjson_mut_obj_add_val(doc, root, "header", header);
 
    /* Add timestamp (HH:MM:SS.microseconds) */
    char timestamp_buf[LOG_TIMESTAMP_BUFFER_SIZE];
    size_t ts_len = format_timestamp_microseconds(time_nanoseconds, timestamp_buf, sizeof(timestamp_buf));
    if (ts_len > 0) {
      yyjson_mut_obj_add_strncpy(doc, header, "timestamp", timestamp_buf, ts_len);
    }
 
    /* Add level */
    yyjson_mut_obj_add_str(doc, header, "level", log_level_to_string(level));
 
    /* Add thread ID */
    uint64_t tid = (uint64_t)thread_current_id();
    yyjson_mut_obj_add_uint(doc, header, "tid", tid);
 
    /* Add file (if not NULL) - normalize to project-relative path */
    if (file) {
      const char *rel_file = extract_project_relative_path(file, ASCIICHAT_OWNED_SOURCE_DIRS);
      yyjson_mut_obj_add_str(doc, header, "file", rel_file);
    }
 
    /* Add line (if > 0) */
    if (line > 0) {
      yyjson_mut_obj_add_int(doc, header, "line", line);
    }
 
    /* Add func (if not NULL) */
    if (func) {
      yyjson_mut_obj_add_str(doc, header, "func", func);
    }
  }
 
  /* Create "body" object with message */
  yyjson_mut_val *body = yyjson_mut_obj(doc);
  if (body) {
    yyjson_mut_obj_add_val(doc, root, "body", body);
    yyjson_mut_obj_add_str(doc, body, "message", message);
  }
 
  /* Serialize to compact JSON (single line, no pretty-printing) */
  size_t json_len = 0;
  char *json_str = yyjson_mut_write(doc, 0, &json_len);
 
  if (json_str && json_len > 0) {
    // Include the delimiter in the same write so concurrent records stay on separate lines.
    json_str[json_len] = '\n';
    platform_write_all(fd, (const uint8_t *)json_str, json_len + 1);
 
    /* Free serialized JSON string */
    free(json_str);
  }
 
  /* Free document */
  yyjson_mut_doc_free(doc);
}

References extract_project_relative_path(), LOG_TIMESTAMP_BUFFER_SIZE, and platform_write_all().

Referenced by log_msg(), and log_plain_msg().

log_set_json_output()

void log_set_json_output

(

int

fd

)

Set the JSON output file descriptor.

Sets which file descriptor should receive JSON-formatted logs. Pass -1 to disable JSON output.

Parameters

fd	File descriptor (typically STDERR_FILENO for terminal, or an open log file)

Note

This function is thread-safe (uses atomic operations)

Definition at line 775 of file log.c.

                                 {
  atomic_store_int(&g_log.json_file, fd);
}

Referenced by main().