sapi_log.h File Reference

OS Abstraction Layer - Logging/diagnostics service. More...

#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/utils/types/sapi_types.h"
#include "safeapi/utils/string/sapi_string.h"
#include <stdbool.h>

Include dependency graph for sapi_log.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	sapi_log_fields_t
	Bounded builder for sapi_log_write_event()'s extra_fields (or info) argument: accumulates space-separated key=value pairs, each typed at the call site, so a caller adding a couple of variable values does not hand-roll a sapi_string_concat()/sapi_string_append_u32() chain every time (MISRA C:2012 Rule 17.1 rules out a printf-style variadic here). More...

Macros
#define	SAPI_LOG_EVENT_LINE_MAX_LEN   256U
	Max length, in bytes and not counting the NUL terminator, of one sapi_log_write_event() line - fields are truncated, not rejected, if the formatted line would exceed this (REQ-OAL-LOG-001: a formatting limit must never turn into a blocked/failed caller). Sized generously for the 8 mandatory fields plus a typical extra_fields value; a longer extra_fields is where truncation would first show up in practice.

Enumerations
enum	sapi_log_level_t { SAPI_LOG_LEVEL_DEBUG = 0 , SAPI_LOG_LEVEL_INFO = 1 , SAPI_LOG_LEVEL_WARNING = 2 , SAPI_LOG_LEVEL_ERROR = 3 }
	Log message severity, passed to sapi_log_write(). More...

Functions
sapi_status_t	sapi_log_init (void)
	Initializes the logging backend. Safe to call once at startup.
void	sapi_log_write (sapi_log_level_t level, const char *tag, const char *message)
	Emits one log message. Non-blocking; never fails the caller's control flow even if the message is dropped.
const char *	sapi_log_level_to_string (sapi_log_level_t level)
	Renders a sapi_log_level_t as a fixed, human-readable tag - "DEBUG"/"INFO"/"WARNING"/"ERROR" - used as the LEVEL field of sapi_log_write_event()'s structured line and available to any backend/integrator wanting the same canonical spelling.
sapi_status_t	sapi_log_level_from_string (const char *name, sapi_log_level_t *out_level)
	Parses one of the canonical level spellings ("DEBUG", "INFO", "WARNING", "ERROR" - exactly as sapi_log_level_to_string() renders them, case-sensitive) into a sapi_log_level_t.
void	sapi_log_set_level (sapi_log_level_t min_level)
	Sets the minimum severity that sapi_log_write() and sapi_log_write_event() forward to the backend - a call whose level is below min_level is dropped before dispatch (and before any formatting work). Default is SAPI_LOG_LEVEL_DEBUG: nothing is filtered until this is called.
sapi_log_level_t	sapi_log_get_level (void)
	Returns the current minimum severity (see sapi_log_set_level()). REQ-OAL-LOG-015.
void	sapi_log_write_event (sapi_log_level_t level, const char *site, uint32_t cycle, const char *source, const char *destination, const char *type, const char *info, const char *extra_fields)
	Emits one structured inter-channel event/message-trail log line - for a message actually sent/received/decided between channels or nodes (e.g. an AB_SAMPLE frame, an M136 report, a checkpoint REQUEST/REPLY, a cross-compare AGREE/DISAGREE) - distinct from sapi_log_write()'s free-text diagnostic logging, which remains the right call for an event with no natural cycle/source/destination (e.g. an NVM write failure).
void	sapi_log_fields_reset (sapi_log_fields_t *fields)
	(Re)initialises a builder to empty. MUST be called before the first sapi_log_fields_add_*(); safe to call again to reuse the same builder for another line.
const char *	sapi_log_fields_c_str (sapi_log_fields_t *fields)
	NUL-terminated view of the accumulated pairs.
void	sapi_log_write_event_fields (sapi_log_level_t level, const char *site, uint32_t cycle, const char *source, const char *destination, const char *type, const char *info, sapi_log_fields_t *fields)
	sapi_log_write_event() with a builder passed directly as the extra fields - no sapi_log_fields_c_str() at the call site.
sapi_log_fields_t *	sapi_log_fields_add_str (sapi_log_fields_t *fields, const char *key, const char *value)
	Appends one key=value pair (preceded by a single separating space only when the builder is already non-empty).
sapi_log_fields_t *	sapi_log_fields_add_u32 (sapi_log_fields_t *fields, const char *key, uint32_t value)
sapi_log_fields_t *	sapi_log_fields_add_i32 (sapi_log_fields_t *fields, const char *key, int32_t value)
sapi_log_fields_t *	sapi_log_fields_add_u64 (sapi_log_fields_t *fields, const char *key, uint64_t value)
sapi_log_fields_t *	sapi_log_fields_add_i64 (sapi_log_fields_t *fields, const char *key, int64_t value)
sapi_log_fields_t *	sapi_log_fields_add_hex_u32 (sapi_log_fields_t *fields, const char *key, uint32_t value, uint8_t min_digits)
sapi_log_fields_t *	sapi_log_fields_add_bool (sapi_log_fields_t *fields, const char *key, bool value)

Detailed Description

OS Abstraction Layer - Logging/diagnostics service.

NON-SAFETY-RELATED. Black-box/event-recorder style diagnostic logging. This service must never sit on a safety execution path: it must not block callers, must not be able to cause a safety function to miss a deadline, and its failure shall never affect safety behavior. See ADR-001, section 4 (item 6).

REQ-OAL-LOG-001: log calls are best-effort and non-blocking; a full backend buffer silently drops the newest entries rather than blocking or erroring the caller's control flow.

Definition in file sapi_log.h.