Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/*
* log.h — Structured key-value logging to stderr.
*
* Design:
* - All output goes to stderr (stdout is reserved for MCP JSON-RPC)
* - Structured text format: "level=info msg=pass.timing pass=defs elapsed_ms=42"
* - Optional JSON format for local structured parsing
* - Levels: DEBUG, INFO, WARN, ERROR
* - Level filtering at runtime via cbm_log_set_level() or the
* CBM_LOG_LEVEL env var (see cbm_log_init_from_env)
* - Thread-safe (each fprintf is atomic on POSIX for lines < PIPE_BUF)
*/
#ifndef CBM_LOG_H
#define CBM_LOG_H
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
typedef enum {
CBM_LOG_DEBUG = 0,
CBM_LOG_INFO = 1,
CBM_LOG_WARN = 2,
CBM_LOG_ERROR = 3,
CBM_LOG_NONE = 4 /* disable all logging */
} CBMLogLevel;
typedef enum {
CBM_LOG_FORMAT_TEXT = 0,
CBM_LOG_FORMAT_JSON = 1,
} CBMLogFormat;
typedef enum {
CBM_LOG_SINK_REPLACE = 0,
CBM_LOG_SINK_TEE = 1,
} CBMLogSinkMode;
/* Apply the CBM_LOG_LEVEL environment variable to the runtime log level.
* Accepts (case-insensitive) "debug", "info", "warn", "error", "none", or
* the numeric equivalents 0..4 matching CBMLogLevel. Unknown, empty, or
* unset values leave the level unchanged (fail-open).
*
* Also applies CBM_LOG_FORMAT=text|json. If unset, the current format is left
* unchanged. Call once at startup before any threads or log lines. */
void cbm_log_init_from_env(void);
/* Apply a role-aware startup policy, then the environment override. Thin
* frontends pass quiet_by_default=true; detached daemons pass false. Physical
* workers also pass require_info_liveness=true because their private log is
* the supervisor's no-progress heartbeat, so WARN/NONE cannot suppress INFO
* lifecycle records and turn a healthy long index into a false hang. */
void cbm_log_init_for_process(bool quiet_by_default, bool require_info_liveness);
/* Set minimum log level (library default: INFO; process startup policy is role-aware). */
void cbm_log_set_level(CBMLogLevel level);
/* Get current log level. */
CBMLogLevel cbm_log_get_level(void);
/* Set/get output format. Default is text. */
void cbm_log_set_format(CBMLogFormat format);
CBMLogFormat cbm_log_get_format(void);
/* Core logging function. msg is a short semantic tag.
* Variadic args are key-value pairs: (const char *key, const char *value)...
* Terminated by NULL key.
*
* Example:
* cbm_log(CBM_LOG_INFO, "pass.timing",
* "pass", "defs", "elapsed_ms", "42", NULL);
*
* Output:
* level=info msg=pass.timing pass=defs elapsed_ms=42
*/
void cbm_log(CBMLogLevel level, const char *msg, ...);
/* Convenience macros. */
#define cbm_log_debug(msg, ...) cbm_log(CBM_LOG_DEBUG, msg, ##__VA_ARGS__, NULL)
#define cbm_log_info(msg, ...) cbm_log(CBM_LOG_INFO, msg, ##__VA_ARGS__, NULL)
/* Always-delivered internal control/discovery record. It bypasses the level
* threshold and always uses the JSON encoding, so exact values (paths with
* spaces or control bytes) survive unambiguously; it flows through the
* configured sink like every other record. Reserve it for the rare
* discovery/control events that ordinary log filtering must never suppress
* (e.g. diagnostics.start path announcement). */
void cbm_log_control_record(const char *msg, ...);
#define cbm_log_control(msg, ...) cbm_log_control_record(msg, ##__VA_ARGS__, NULL)
#define cbm_log_warn(msg, ...) cbm_log(CBM_LOG_WARN, msg, ##__VA_ARGS__, NULL)
#define cbm_log_error(msg, ...) cbm_log(CBM_LOG_ERROR, msg, ##__VA_ARGS__, NULL)
/* Log with integer value (avoids sprintf for common case). */
void cbm_log_int(CBMLogLevel level, const char *msg, const char *key, int64_t value);
/* Operational event helpers. They deliberately avoid request bodies, headers,
* arguments, and query strings. */
void cbm_log_mcp_request(const char *method, const char *tool_name, bool is_error,
int64_t duration_us, int64_t handler_duration_us,
int64_t response_serialization_us, bool cancelled, bool timed_out);
void cbm_log_http_request(const char *component, const char *method, const char *path, int status,
int64_t duration_ms, size_t request_bytes, size_t response_bytes);
/* Crash-durable log stream.
*
* Enable in a process whose stderr is redirected to a FILE that has to survive
* the process dying abnormally — today that is the supervised index worker,
* whose `.worker-*.log` is the only post-mortem evidence a contained crash,
* SIGKILL or hang leaves behind. Default stdio buffering loses exactly that
* evidence: the C standard only promises stderr is "not fully buffered", and
* the Windows CRT gives a redirected stderr FULL buffering, so a worker that
* aborts or is killed takes its whole diagnostic with it and the user is left
* holding a 0-byte log (#1070, #1130, #1132, #1133, #1145, #1450).
*
* Two mechanisms, deliberately both: setvbuf(_IONBF) covers EVERY writer to
* the stream (including the plain fprintf(stderr, …) startup errors that
* explain a worker which never got as far as logging), and a per-line flush
* covers the case where setvbuf is refused because the stream was already
* written to — it is only guaranteed before a stream's first operation.
*
* Also the process-wide answer to "is this log post-mortem evidence?", which
* is what makes the per-file breadcrumb worth its volume in a worker and not
* anywhere else. Cost is ~0: flushing an unbuffered stream writes nothing. */
void cbm_log_set_crash_durable(bool enabled);
bool cbm_log_crash_durable(void);
/* Optional log sink callback — called with the formatted log line. */
typedef void (*cbm_log_sink_fn)(const char *line);
void cbm_log_set_sink(cbm_log_sink_fn fn);
void cbm_log_set_sink_ex(cbm_log_sink_fn fn, CBMLogSinkMode mode);
#endif /* CBM_LOG_H */