C / C++ / 系统课时

加入结构化日志与运行信息

加入结构化日志与运行信息

结构化日志的目标不是“多打印几行”,而是让一次异常可以按字段检索、关联到具体进程或线程,并在高负载时仍保持可控成本。本节建立一个最小日志契约:统一级别、时间、事件名、进程与线程标识,以及少量关键状态,同时把级别判断放在格式化之前。

学习目标

  • 设计稳定、可检索的结构化日志字段,而不是依赖自由文本。
  • 记录 pid、tid、事件名和关键状态,支持并发程序定位问题。
  • 通过日志级别门控和热点路径节流,避免日志反过来成为性能瓶颈。

先定义日志契约

日志字段应优先回答“何时、什么级别、哪个执行单元、发生了什么、关键状态是什么”。示例采用 JSON Lines,每条日志占一行,固定包含 time、level、pid、tid、event、state 和 value。

字段名一旦进入采集与告警规则,就应尽量保持稳定。自由文本适合补充人类可读信息,但不能替代 event 这类可聚合字段。真实业务字符串写入 JSON 前必须做转义;本例只输出代码内的固定字面量,因此不演示通用 JSON 编码器。

用级别门控减少无效开销

下面的程序从 LOG_LEVEL 读取最低日志级别。should_log 的判断直接放在 log_event() 入口,因此被过滤掉的 DEBUG 日志不会获取时间、线程 ID 或执行 JSON 格式化。flockfile() 则减少多线程同时写 stderr 时的行内容交叉。

c
#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/syscall.h>
#include <time.h>
#include <unistd.h>

enum log_level { LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR };

static enum log_level min_level = LOG_INFO;

static const char *level_name(enum log_level level) {
    static const char *names[] = {"DEBUG", "INFO", "WARN", "ERROR"};
    return names[level];
}

static void init_log_level(void) {
    const char *value = getenv("LOG_LEVEL");
    if (value == NULL) {
        return;
    }
    if (strcmp(value, "DEBUG") == 0) min_level = LOG_DEBUG;
    else if (strcmp(value, "INFO") == 0) min_level = LOG_INFO;
    else if (strcmp(value, "WARN") == 0) min_level = LOG_WARN;
    else if (strcmp(value, "ERROR") == 0) min_level = LOG_ERROR;
}

static void log_event(enum log_level level,
                      const char *event,
                      const char *state,
                      long value) {
    if (level < min_level) {
        return;  // 先过滤,再获取运行信息和格式化字符串
    }

    struct timespec ts;
    struct tm tm;
    char timebuf[32];

    clock_gettime(CLOCK_REALTIME, &ts);
    gmtime_r(&ts.tv_sec, &tm);
    strftime(timebuf, sizeof timebuf, "%Y-%m-%dT%H:%M:%S", &tm);

    long tid = syscall(SYS_gettid);
    flockfile(stderr);
    fprintf(stderr,
            "{\"time\":\"%sZ\",\"level\":\"%s\","
            "\"pid\":%ld,\"tid\":%ld,\"event\":\"%s\","
            "\"state\":\"%s\",\"value\":%ld}\n",
            timebuf, level_name(level), (long)getpid(), tid,
            event, state, value);
    funlockfile(stderr);
}

int main(void) {
    init_log_level();

    log_event(LOG_DEBUG, "worker.poll", "idle", 0);
    log_event(LOG_INFO, "service.start", "ready", 1);
    log_event(LOG_WARN, "queue.depth", "high", 87);
    return 0;
}

预期结果:保存为 log_demo.c 后应能在 Linux 上编译运行;默认最低级别为 INFO,因此 DEBUG 事件被过滤,而 INFO 与 WARN 各输出一条 JSON 日志。

pid 用于区分进程,Linux 的 tid 用于定位具体线程。生产代码若需要跨平台,不应直接依赖 SYS_gettid,可以改成线程库提供的标识或由日志框架统一生成。

运行并核对字段

编译并按默认 INFO 级别运行:

bash
gcc -std=c11 -Wall -Wextra -Wpedantic log_demo.c -o log_demo
LOG_LEVEL=INFO ./log_demo 2>&1

预期输出如下;<TIME>、<PID> 和 <TID> 是动态值,实际运行时会不同:

text
{"time":"<TIME>","level":"INFO","pid":<PID>,"tid":<TID>,"event":"service.start","state":"ready","value":1}
{"time":"<TIME>","level":"WARN","pid":<PID>,"tid":<TID>,"event":"queue.depth","state":"high","value":87}

把最低级别提高到 WARN 可以验证门控行为:

bash
LOG_LEVEL=WARN ./log_demo 2>&1

预期输出:

text
{"time":"<TIME>","level":"WARN","pid":<PID>,"tid":<TID>,"event":"queue.depth","state":"high","value":87}

热点路径要控制日志预算

高频循环、每包处理和每次系统调用都属于热点路径,不能无条件打印。优先记录状态变化、错误边界和聚合结果;确实需要观察高频事件时,应使用采样、速率限制或周期汇总,而不是把每一次迭代写入磁盘。

日志还要避免泄露密码、令牌、密钥和完整用户数据。工程上可把“字段契约、敏感字段规则、默认级别、采样策略”作为统一约束。这样日志既能提供故障现场,又不会因字段漂移、I/O 放大或敏感信息泄露制造新的问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

加入结构化日志与运行信息

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通