Diag Log

Overview

Provide a reusable logger script for recording skill or MCP error/conflict/warning/info events to ~/.codex/diag-events.ndjson with concurrency-safe appends.

Quick Start

Call the logger in any skill or MCP wrapper when an error, conflict, warning, or informational event occurs.

~/.codex/skills/diag-log/scripts/log_diag_event.sh \
  --event-type "error" \
  --source "skill" \
  --name "frontend-design" \
  --message "command failed" \
  --meta '{"exitCode":1}'

Logger Script

• Path: ~/.codex/skills/diag-log/scripts/log_diag_event.sh
• Required args:
  • --event-type <error|conflict|warning|info>
• Required when --event-type conflict:
  • --conflict-type <lock_timeout|lock_contention|resource_busy|concurrent_run>
• Optional args:
  • --source <skill|mcp|system|other>
  • --name <skill_or_mcp_name>
  • --message <string>
  • --meta <json_string> (must be valid JSON)
  • --lock-timeout <seconds> (default: 10)

Output Format (NDJSON)

Each call appends one line with at least:

{ "ts": "<ISO8601>", "event_type": "error|conflict|warning|info" }

When provided, conflict_type, source, name, message, and meta are included.

Concurrency Behavior

• Prefer flock when available.
• If flock is not available, use an O_EXCL lockfile fallback.
• If lock acquisition exceeds --lock-timeout, append a conflict event with:
  • event_type: "conflict"
  • conflict_type: "lock_timeout"
  • message: "lock timeout after <seconds>s"
  • then exit non-zero.

Examples

Conflict: lock contention

~/.codex/skills/diag-log/scripts/log_diag_event.sh \
  --event-type "conflict" \
  --conflict-type "lock_contention" \
  --source "mcp" \
  --name "figma" \
  --message "lock busy; retrying" \
  --meta '{"retry":2}'

Warning: fallback path

~/.codex/skills/diag-log/scripts/log_diag_event.sh \
  --event-type "warning" \
  --source "skill" \
  --name "context7-latest-usage" \
  --message "fallback to cached docs" \
  --meta '{"cacheAgeDays":3}'

Resources

scripts/

• log_diag_event.sh: NDJSON logger with concurrency-safe appends and lock timeout handling.