トレースユーティリティ (trace-util) 設計・実装ドキュメント

1 目的

• Linux / Windows の両環境で共通のインターフェースでトレース (ログ) を出力する。
• 出力先として OS トレース (Linux: syslog、Windows: ETW)、ファイル、stderr の 3 系統を独立したスレッショルドレベルで管理する。
• trace-util.h が唯一の公開インターフェースであり、呼び出し側は OS 固有の API を直接扱う必要がない。

2 アーキテクチャ

Application
      |
      v
trace-util.h  (共通 API ─ 唯一の公開インターフェース)
      |
+-----+-------+---------+
|             |         |
OS トレース   File   stderr
(Linux: syslog            (両OS)  (両OS)
 Windows: ETW)

OS トレース層の詳細は下位層ヘッダ (trace-etw-util.h, trace-syslog-util.h) に委ねており、利用者は意識する必要がありません。

3 トレースレベル

enum trace_level で定義される共通レベルです。重大度は上から下へ低下します。

各出力先はスレッショルドレベルを個別に設定でき、設定レベル以上の重大度のメッセージのみ出力されます。TRACE_LV_NONE を指定するとその出力先を完全に抑止します。

4 デフォルト設定

trace_init() 呼び出し直後の各出力先のデフォルトスレッショルドレベルは以下のとおりです。

ファイルトレースは trace_init() 直後はパス未指定のため無効です。trace_modify_filetrc() でパスを設定して初めて有効になります。

5 API 仕様

5.1 ライフサイクル

ハンドルは stopped と started の 2 状態を持ちます。

• stopped 状態: 初期状態。設定関数 (trace_modify_*) が使用可能。出力関数は -1 を返す。
• started 状態: trace_start() 後。出力関数が有効。設定関数は -1 を返す。

trace_init()
    ↓ (stopped)
trace_modify_name / trace_modify_ostrc / ...  ← stopped でのみ有効
    ↓
trace_start()
    ↓ (started)
trace_write / trace_writef / trace_hex_write / trace_hex_writef  ← started でのみ有効
    ↓
trace_stop()
    ↓ (stopped)
... 設定変更・再開が可能 ...
    ↓
trace_dispose()  ← started / stopped どちらからも呼び出し可能

5.2 trace_init

trace_provider_t *trace_init(void);

トレースプロバイダを初期化する。

5.3 trace_dispose

void trace_dispose(trace_provider_t *handle);

トレースプロバイダを終了し、リソースを解放する。

5.4 trace_start / trace_stop

int trace_start(trace_provider_t *handle);
int trace_stop(trace_provider_t *handle);

5.5 trace_write

int trace_write(trace_provider_t *handle, enum trace_level level, const char *message);

指定したトレースレベルでメッセージを書き込む。

5.6 trace_writef

int trace_writef(trace_provider_t *handle, enum trace_level level, const char *format, ...);

printf 形式でトレースメッセージを書き込む。内部で vsnprintf を使用し、TRACE_MESSAGE_MAX_BYTES のバッファにフォーマットする。バッファを超える部分は切り詰められる。

trace_writef(logger, TRACE_LV_INFO, "user=%s count=%d", username, count);

5.7 trace_hex_write

int trace_hex_write(trace_provider_t *handle, enum trace_level level,
                    const void *data, size_t size, const char *message);

バイナリデータを大文字スペース区切りの HEX テキスト形式で書き込む。

出力フォーマット:

// message 指定あり:
"Received data: 48 65 6C 6C 6F"

// message が NULL:
"48 65 6C 6C 6F"

// データが収まらない場合:
"Received data: 48 65 6C ..."

5.8 trace_hex_writef

int trace_hex_writef(trace_provider_t *handle, enum trace_level level,
                     const void *data, size_t size, const char *format, ...);

trace_hex_write と同等だが、ラベル文字列を printf 形式で指定できる。

trace_hex_writef(logger, TRACE_LV_VERBOSE, data, len, "packet[%d]", index);
// → "packet[3]: 48 65 6C 6C 6F"

5.9 trace_modify_name

int trace_modify_name(trace_provider_t *handle, const char *name, int64_t identifier);

識別名と識別番号を変更する。

trace_modify_name(logger, "worker", 2);
// → 識別名 "worker-2"

5.10 trace_modify_ostrc

int trace_modify_ostrc(trace_provider_t *handle, enum trace_level level);

OS トレース (syslog / ETW) のスレッショルドレベルを設定する。

5.11 trace_modify_filetrc

int trace_modify_filetrc(trace_provider_t *handle, const char *path,
                         enum trace_level level, size_t max_bytes, int generations);

ファイルトレースの出力先と設定を変更する。

5.12 trace_modify_stderrtrc

int trace_modify_stderrtrc(trace_provider_t *handle, enum trace_level level);

stderr トレースのスレッショルドレベルを設定する。

stderr 出力フォーマット例:

2026-04-02 12:34:56.789 I application started
2026-04-02 12:34:56.790 E connection failed

5.13 trace_get_ostrc / trace_get_filetrc / trace_get_stderrtrc

enum trace_level trace_get_ostrc(trace_provider_t *handle);
enum trace_level trace_get_filetrc(trace_provider_t *handle);
enum trace_level trace_get_stderrtrc(trace_provider_t *handle);

各出力先の現在のスレッショルドレベルを取得する。

6 DLL エクスポート / インポート制御マクロ

TRACE_UTIL_EXPORT の展開ルール:

7 内部設計

7.1 trace_provider 構造体

内部状態として以下のフィールドを保持します。

7.2 スレッド安全機構

• 設定変更 (trace_modify_*, trace_start, trace_stop): 排他ロック (write lock) で保護。
• 出力 (trace_write 等) / レベル参照 (trace_get_*): 共有ロック (read lock) を最大 100ms のタイムアウト付きで取得し、複数スレッドからの並行実行を許容する。
• trace_dispose: ロック取得後に running を 0 にしてから解放処理を行い、進行中の書き込みと競合しない。

7.3 Windows: ETW プロバイダ共有

同一プロセス内で複数の trace_provider_t ハンドルが存在する場合、ETW プロバイダ登録 (TraceLogging) は参照カウント機構で共有されます。最後のハンドルが trace_dispose() されたときに登録が解除されます。

8 使用例

8.1 基本的な使い方

#include <trace-util.h>

trace_provider_t *logger = trace_init();
trace_modify_name(logger, "myapp", 0);
trace_start(logger);

trace_write(logger, TRACE_LV_INFO, "application started");
trace_writef(logger, TRACE_LV_WARNING, "retry count=%d", count);

trace_stop(logger);
trace_dispose(logger);

8.2 ファイルトレースを有効にする

trace_provider_t *logger = trace_init();
trace_modify_name(logger, "myapp", 0);
trace_modify_ostrc(logger, TRACE_LV_WARNING);          /* OS トレースは WARNING 以上 */
trace_modify_filetrc(logger, "/var/log/myapp.log",
                     TRACE_LV_INFO, 0, 0);             /* ファイルに INFO 以上を記録 */
trace_modify_stderrtrc(logger, TRACE_LV_CRITICAL);     /* stderr に CRITICAL のみ */
trace_start(logger);

trace_writef(logger, TRACE_LV_INFO, "pid=%d started", getpid());

trace_stop(logger);
trace_dispose(logger);

8.3 識別番号付きの使い方 (複数インスタンス管理)

trace_provider_t *logger = trace_init();
trace_modify_name(logger, "worker", 2);  /* 識別名 "worker-2" */
trace_start(logger);
trace_write(logger, TRACE_LV_INFO, "worker-2 running");
trace_dispose(logger);                   /* started 状態でも解放可能 */

8.4 バイナリデータの HEX ダンプ

uint8_t buf[16] = { 0x48, 0x65, 0x6C, 0x6C, 0x6F };

trace_hex_write(logger, TRACE_LV_VERBOSE, buf, 5, "Received");
/* → "Received: 48 65 6C 6C 6F" */

trace_hex_writef(logger, TRACE_LV_VERBOSE, buf, 5, "packet[%d]", idx);
/* → "packet[0]: 48 65 6C 6C 6F" */

9 実装ファイル一覧