English · 한국어

cliproxyapi-plugin-usage-audit

A native Go plugin for CLIProxyAPI that audits token usage and aggregates request logs, with a responsive bilingual (English/Korean) web dashboard.

Preview · Features · Getting Started · Routes · Language · Operations

---

Overview

cliproxyapi-plugin-usage-audit is a c-shared C ABI native Go plugin that the CLIProxyAPI host loads directly. It captures and persists, without loss and through an asynchronous ring buffer, the token usage of every LLM request passing through the proxy (input, cache, reasoning, output and total), plus latency, status codes and per-provider/model statistics, and visualizes them in an embedded responsive dashboard.

Preview

Desktop Dashboard	Mobile View

Features

• Asynchronous lossless capture: a non-blocking ring-buffer queue and a background worker persist usage logs without adding latency to proxied requests.
• Multi-dimensional token aggregation: live totals by provider, endpoint, model and status (success/failure), plus daily request counts and token consumption.
• Cursor-based request log: reverse-cursor pagination with a high-performance top-K selection algorithm.
• Modern responsive dashboard: React 19 and Radix UI date-range picker, filters and responsive table layout.
• Bilingual UI: English and Korean, switchable from the dashboard header (see Language).
• Resilient storage: quarantine of corrupt lines, atomic snapshot decoding and safe rotation.
• Sanitizer tool: a standalone CLI that non-destructively audits and cleans sensitive data such as keys and prompt bodies.

Tech Stack

Domain	Technology / Specification
Runtime & ABI	Go 1.26.9, cgo, C shared library (.so / .dylib / .dll)
Host Integration	CLIProxyAPI Plugin C ABI (v7.2.155 SDK dependency)
Embedded UI	React 19, Radix UI primitives, esbuild bundle
Persistence	Rotating JSONL log, in-memory snapshot cache
Bundled Typography	SUIT Regular/SemiBold, Manrope Variable (self-hosted WOFF2)
Verification	Go race/vet, Node contract, i18n and auth-gate tests, native C smoke test (dlopen / LoadLibrary) on every platform

Getting Started

The plugin is a CGO c-shared library, so build it natively on the platform you target (Linux, macOS or Windows; amd64 or arm64) with a C compiler (gcc or clang).

Bootstrap the local runtimes with mise:

# Managed runtimes
mise trust
mise install

# Native build tools: Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y build-essential
# macOS: xcode-select --install      Windows: 64-bit mingw-w64 gcc (e.g. MSYS2 UCRT64) and Git Bash

# Run tests and the native ABI smoke test (the script also works where make is missing)
make verify
scripts/build-native.sh

Build

make build

The build writes artifacts/usage-audit.so (.dylib on macOS, .dll on Windows) and the matching header.

Rebuilding the dashboard UI

Normal Go builds do not need frontend tooling because the generated dashboard is checked in. After changing ui/entry.tsx or the vendored components, regenerate it:

cd ui
npm ci
npm run build

This rewrites the marked regions of internal/plugin/dashboard.html. Do not edit those generated regions by hand. See ui/README.md.

Install

Once listed in the CLIProxyAPI Plugins Store, install usage-audit from the host's plugin page. To install manually, download usage-audit_<version>_<os>_<arch>.zip and checksums.txt from the latest release, verify with sha256sum -c checksums.txt (shasum -a 256 -c on macOS), and unzip the library into the host's plugin directory.

Every release publishes all five store platforms; the Release workflow refuses to publish unless all of them built and passed the native smoke test:

Platform	Asset	Library
Linux x64	usage-audit_<version>_linux_amd64.zip	usage-audit.so
Linux arm64	usage-audit_<version>_linux_arm64.zip	usage-audit.so
macOS Intel	usage-audit_<version>_darwin_amd64.zip	usage-audit.dylib
macOS Apple silicon	usage-audit_<version>_darwin_arm64.zip	usage-audit.dylib
Windows x64	usage-audit_<version>_windows_amd64.zip	usage-audit.dll

The Linux builds require glibc 2.36 or older (the official Debian bookworm image).

Data directory

Usage records are stored in usage.jsonl (rotated to .1, .2, ...) in the directory given by the USAGE_AUDIT_DATA_DIR environment variable of the host process. When it is unset the plugin uses a per-user default, <user-config-dir>/cliproxyapi/usage-audit (~/.config/cliproxyapi/usage-audit on Linux, ~/Library/Application Support/cliproxyapi/usage-audit on macOS, %AppData%\cliproxyapi\usage-audit on Windows). If neither is available the plugin runs without storage and logs a message. Earlier builds defaulted to a fixed /var/lib/homelab/... path; set USAGE_AUDIT_DATA_DIR to keep using an existing directory.

Releasing

Bump pluginVersion in internal/plugin/plugin.go, merge, then push a matching tag:

git tag v0.2.0 && git push origin v0.2.0

The tag must match pluginVersion and be a dotted numeric version (vX.Y.Z); the workflow builds each platform on a native runner, packages <id>_<version>_<os>_<arch>.zip, writes checksums.txt and creates the GitHub release.

Language

The dashboard ships in English and Korean. A single translate icon button in the filter area switches between Korean and English; its tooltip names the language it switches to.

• Selection order: saved choice, then browser language (Korean selects Korean, anything else selects English), then Korean.
• Shared setting: the choice is stored in the browser under cpa_plugin_lang, the same key used by the quota-monitor dashboard. Changing it in one open dashboard updates the other. This only applies when both dashboards are served from the same origin.
• Privacy: the language key is the only thing the page writes to localStorage. The management key is held in sessionStorage for the current tab only and is never written to localStorage, cookies or a URL.
• Not translated: the plugin name shown in the host menu is registered once at load time, so it stays Korean ("토큰 사용량").

Routes

Once the CLIProxyAPI host has loaded the plugin, these routes are available. Only the static shell is unauthenticated; all usage data requires the management key:

Method	Route	Description
GET	/v0/resource/plugins/usage-audit/dashboard	Responsive usage audit dashboard (static shell, no data)
GET	/v0/management/plugins/usage-audit/data/summary	Aggregated summary for a period and filters (dashboard)
GET	/v0/management/plugins/usage-audit/data/records	Cursor-based request log (dashboard)
GET	/v0/management/plugins/usage-audit/dashboard	Dashboard on the management path
GET	/v0/management/plugins/usage-audit/summary	Aggregated summary (management API)
GET	/v0/management/plugins/usage-audit/records	Request log (management API)
DELETE	/v0/management/plugins/usage-audit/records	Clear stored records

Operations & Tooling

Tools to audit or sanitize log files for sensitive data without modifying them in place:

# Dry-run audit against the sample data
make audit-dry-run

# Audit an operational log (read-only)
make audit-dry-run USAGE_LOG_PATH=/path/to/usage.jsonl

# Safe sanitize dry-run based on a service-stop boundary
make boundary-sanitize-dry-run USAGE_LOG_PATH=/path/to/usage.jsonl

See the Sanitization Runbook for the full procedure.

Project Structure

cliproxyapi-plugin-usage-audit/
├── main.go                     # c-shared C ABI entry point (usage.handle, management routes)
├── cmd/
│   └── usage-audit-sanitize/   # Standalone log audit and sanitizer CLI
├── internal/
│   ├── plugin/                 # Plugin lifecycle, dashboard serving, top-K queries
│   │                           #   dashboard.html (generated UI regions), style.css, app.js
│   ├── queue/                  # Non-blocking ring-buffer queue
│   └── store/                  # JSONL file store, rotation, snapshot decoder
├── ui/                         # React dashboard sources and build pipeline
├── docs/                       # Dashboard design, structural hardening, sanitization runbook
├── scripts/                    # Release packaging, native build, audit/sanitize scripts and UI regression tests
├── testdata/                   # Synthetic usage sample data
├── verification/               # Cross-platform native C ABI smoke test (dlopen / LoadLibrary)
├── Makefile                    # Build, verify and smoke-test targets
└── THIRD_PARTY_NOTICES.md      # SDK and bundled font license notices

Documentation

• Dashboard Design: dashboard UI/UX architecture and state flow
• Structural Hardening: storage fault isolation and queue recovery guide
• Sanitization Runbook: procedure for sanitizing operational logs

License

MIT. You may use, modify, distribute and sell this software, including commercially, as long as the copyright and license notice are kept.

The CLIProxyAPI SDK this plugin depends on is a separate project under its own license; see THIRD_PARTY_NOTICES.md.

Security & Attribution

• Real usage logs, account keys and prompt bodies are never committed to this repository.
• CLIProxyAPI SDK and bundled font licenses are listed in THIRD_PARTY_NOTICES.md.