sapi_log.c

Go to the documentation of this file.

#include "safeapi/oal/log/sapi_log.h"
#include "safeapi/utils/lifecycle/sapi_lifecycle.h"
#include "safeapi_backend/log/sapi_log_backend.h"
#include "safeapi/utils/string/sapi_string.h"
#include "safeapi/oal/timer/sapi_timer.h"
 
#include <string.h>


typedef struct
{
    const char      *name;
    sapi_log_level_t level;
} sapi_log_level_name_t;

static const sapi_log_backend_t *s_backend = NULL;

static sapi_log_level_t s_min_level = SAPI_LOG_LEVEL_DEBUG;

static const sapi_log_level_name_t s_level_names[] = {
    { "DEBUG",   SAPI_LOG_LEVEL_DEBUG   },
    { "INFO",    SAPI_LOG_LEVEL_INFO    },
    { "WARNING", SAPI_LOG_LEVEL_WARNING },
    { "ERROR",   SAPI_LOG_LEVEL_ERROR   }
};


static void sapi_log_append_event_field(sapi_string_t *line, const char *key, const char *value);
static void sapi_log_append_event_field_u32(sapi_string_t *line, const char *key, uint32_t value);
 

sapi_status_t sapi_log_register_backend(const sapi_log_backend_t *backend)
{
    sapi_status_t lifecycle_status;
 
    if (backend == NULL)
    {
        return SAPI_STATUS_INVALID_PARAM;
    }
    /* REQ-LIFECYCLE-001 (ADR-026): registering a backend is a setup-only
     * action - refuse once the application's setup phase has been locked. */
    lifecycle_status = sapi_lifecycle_check_setup_allowed();
    if (lifecycle_status != SAPI_STATUS_OK)
    {
        return lifecycle_status;
    }
    s_backend = backend;
    return SAPI_STATUS_OK;
}
 
sapi_status_t sapi_log_init(void)
{
    if ((s_backend == NULL) || (s_backend->init == NULL))
    {
        return SAPI_STATUS_OK;
    }
    return s_backend->init();
}
 
void sapi_log_write(sapi_log_level_t level, const char *tag, const char *message)
{
    if ((s_backend == NULL) || (s_backend->write == NULL))
    {
        /* No backend registered: intentionally a silent no-op, not an
         * error - REQ-OAL-LOG-001 requires logging to never affect the
         * caller's control flow. */
        return;
    }
    if ((int)level < (int)s_min_level)
    {
        /* Below the runtime threshold (sapi_log_set_level()) - dropped. */
        return;
    }
    s_backend->write(level, tag, message);
}
 
sapi_status_t sapi_log_level_from_string(const char *name, sapi_log_level_t *out_level)
{
    sapi_status_t status = SAPI_STATUS_INVALID_PARAM;
 
    if ((name != NULL) && (out_level != NULL))
    {
        size_t i;
 
        for (i = 0U; i < (sizeof(s_level_names) / sizeof(s_level_names[0])); i++)
        {
            if (strcmp(name, s_level_names[i].name) == 0)
            {
                *out_level = s_level_names[i].level;
                status = SAPI_STATUS_OK;
                break;
            }
        }
    }
    return status;
}
 
void sapi_log_set_level(sapi_log_level_t min_level)
{
    /* Only an upper bound is checked: the enum's underlying type is
     * unsigned (values 0..3), so `>= SAPI_LOG_LEVEL_DEBUG` would be a
     * tautology. A wrapped/garbage value lands above ERROR and is ignored. */
    if ((int)min_level <= (int)SAPI_LOG_LEVEL_ERROR)
    {
        s_min_level = min_level;
    }
}
 
sapi_log_level_t sapi_log_get_level(void)
{
    return s_min_level;
}
 
const char *sapi_log_level_to_string(sapi_log_level_t level)
{
    const char *result;
 
    switch (level)
    {
        case SAPI_LOG_LEVEL_DEBUG:
            result = "DEBUG";
            break;
        case SAPI_LOG_LEVEL_INFO:
            result = "INFO";
            break;
        case SAPI_LOG_LEVEL_WARNING:
            result = "WARNING";
            break;
        case SAPI_LOG_LEVEL_ERROR:
            result = "ERROR";
            break;
        default:
            /* Defensive only - not reachable through the public enum. */
            result = "UNKNOWN";
            break;
    }
    return result;
}
 
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)
{
    char line_storage[SAPI_LOG_EVENT_LINE_MAX_LEN];
    char ts_storage[24];
    sapi_string_t line;
    sapi_string_t ts;
    sapi_timestamp_ms_t now_ms = 0U;
    const char *ts_cstr = NULL;
    const char *line_cstr = NULL;
 
    if ((s_backend == NULL) || (s_backend->write == NULL) || ((int)level < (int)s_min_level))
    {
        /* Same silent-no-op contract as sapi_log_write() above - and the
         * same runtime-threshold drop (sapi_log_set_level()). Bail before
         * the formatting work below when there is nowhere for it to go, or
         * when it would be dropped anyway. */
        return;
    }
 
    (void)sapi_string_init(&line, line_storage, sizeof(line_storage));
    (void)sapi_string_init(&ts, ts_storage, sizeof(ts_storage));
 
    /* Site: written directly (no leading space/key), first field. */
    (void)sapi_string_concat(&line, "Site=");
    (void)sapi_string_concat(&line, (site != NULL) ? site : "");
 
    /* TIMESTAMP: best-effort - stays 0 (its declared initializer) if no
     * sapi_timer backend is registered or the call otherwise fails; a
     * timer problem must never prevent this event from being logged
     * (REQ-OAL-LOG-001), so the field is degraded, not the whole call. */
    (void)sapi_timer_now(&now_ms);
    (void)sapi_string_from_u64(&ts, now_ms);
    (void)sapi_string_c_str(&ts, &ts_cstr);
    sapi_log_append_event_field(&line, "Timestamp", (ts_cstr != NULL) ? ts_cstr : "0");
 
    sapi_log_append_event_field(&line, "Level", sapi_log_level_to_string(level));
    sapi_log_append_event_field_u32(&line, "Cycle", cycle);
    sapi_log_append_event_field(&line, "Source", source);
    sapi_log_append_event_field(&line, "Destination", destination);
    sapi_log_append_event_field(&line, "Type", type);
    sapi_log_append_event_field(&line, "Info", info);
 
    if ((extra_fields != NULL) && (extra_fields[0] != '\0'))
    {
        /* extra_fields is already caller-formatted Key=Value text (see
         * this function's own doc) - appended verbatim behind a single
         * separating space, not wrapped in another key, so it reads as
         * more of the same space-separated Key=Value convention rather
         * than a nested field. An empty string is treated exactly like
         * NULL (no field, no trailing space) so an empty
         * sapi_log_fields_t builder round-trips cleanly. */
        (void)sapi_string_concat(&line, " ");
        (void)sapi_string_concat(&line, extra_fields);
    }
 
    (void)sapi_string_c_str(&line, &line_cstr);
    s_backend->write(level, source, (line_cstr != NULL) ? line_cstr : "");
}
 
void sapi_log_fields_reset(sapi_log_fields_t *fields)
{
    if (fields != NULL)
    {
        (void)sapi_string_init(&fields->str, fields->storage, sizeof(fields->storage));
    }
}

static bool sapi_log_fields_begin_pair(sapi_log_fields_t *fields, const char *key)
{
    bool ok = (fields != NULL) && (key != NULL);
 
    if (ok)
    {
        if (sapi_string_length(&fields->str) > 0U)
        {
            (void)sapi_string_concat(&fields->str, " ");
        }
        (void)sapi_string_concat(&fields->str, key);
        (void)sapi_string_concat(&fields->str, "=");
    }
    return ok;
}
 
sapi_log_fields_t *sapi_log_fields_add_str(sapi_log_fields_t *fields, const char *key, const char *value)
{
    if (sapi_log_fields_begin_pair(fields, key))
    {
        (void)sapi_string_concat(&fields->str, (value != NULL) ? value : "");
    }
    return fields;
}
 
sapi_log_fields_t *sapi_log_fields_add_u32(sapi_log_fields_t *fields, const char *key, uint32_t value)
{
    if (sapi_log_fields_begin_pair(fields, key))
    {
        (void)sapi_string_append_u32(&fields->str, value);
    }
    return fields;
}
 
sapi_log_fields_t *sapi_log_fields_add_i32(sapi_log_fields_t *fields, const char *key, int32_t value)
{
    if (sapi_log_fields_begin_pair(fields, key))
    {
        (void)sapi_string_append_i32(&fields->str, value);
    }
    return fields;
}
 
sapi_log_fields_t *sapi_log_fields_add_u64(sapi_log_fields_t *fields, const char *key, uint64_t value)
{
    if (sapi_log_fields_begin_pair(fields, key))
    {
        (void)sapi_string_append_u64(&fields->str, value);
    }
    return fields;
}
 
sapi_log_fields_t *sapi_log_fields_add_i64(sapi_log_fields_t *fields, const char *key, int64_t value)
{
    if (sapi_log_fields_begin_pair(fields, key))
    {
        (void)sapi_string_append_i64(&fields->str, value);
    }
    return fields;
}
 
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)
{
    if (sapi_log_fields_begin_pair(fields, key))
    {
        (void)sapi_string_concat(&fields->str, "0x");
        (void)sapi_string_append_hex_u32(&fields->str, value, min_digits);
    }
    return fields;
}
 
sapi_log_fields_t *sapi_log_fields_add_bool(sapi_log_fields_t *fields, const char *key, bool value)
{
    if (sapi_log_fields_begin_pair(fields, key))
    {
        (void)sapi_string_concat(&fields->str, value ? "true" : "false");
    }
    return fields;
}
 
const char *sapi_log_fields_c_str(sapi_log_fields_t *fields)
{
    const char *out = "";
 
    if (fields != NULL)
    {
        const char *tmp = NULL;
 
        if (sapi_string_c_str(&fields->str, &tmp) == SAPI_STATUS_OK)
        {
            out = tmp;
        }
    }
    return out;
}
 
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)
{
    /* c_str() yields "" for a NULL/empty builder; sapi_log_write_event()
     * now treats "" exactly like NULL, so no special-casing needed. */
    sapi_log_write_event(level, site, cycle, source, destination, type, info,
                          sapi_log_fields_c_str(fields));
}
 
 
/****Local functions ****/
 
static void sapi_log_append_event_field(sapi_string_t *line, const char *key, const char *value)
{
    (void)sapi_string_concat(line, " ");
    (void)sapi_string_concat(line, key);
    (void)sapi_string_concat(line, "=");
    (void)sapi_string_concat(line, (value != NULL) ? value : "");
}
 
static void sapi_log_append_event_field_u32(sapi_string_t *line, const char *key, uint32_t value)
{
    char num_storage[16];
    sapi_string_t num;
    const char *num_cstr = NULL;
 
    (void)sapi_string_init(&num, num_storage, sizeof(num_storage));
    (void)sapi_string_from_u32(&num, value);
    (void)sapi_string_c_str(&num, &num_cstr);
    sapi_log_append_event_field(line, key, num_cstr);
}