TLS Observer for Pi

Pi Coding Agent plugin that converts Pi lifecycle events into GenAI OTEL traces and exports them to Volcengine TLS.

Trace shape

agent.turn (server)
  llm.request (client)
  tool.call (client)

The plugin listens to Pi public lifecycle hooks, groups them by session and turn in memory, and exports one agent.turn trace when the turn or agent run finishes.

Configuration

Environment variables:

• PI_TLS_EXPORT=0 disables export.
• PI_TLS_ENV_FILE optionally points to an env file. Defaults to ~/.pi/agent/tls-observer-pi.env.
• PI_TLS_DATA_ROOT overrides local send-log and retry state.
• PI_TLS_CAPTURE_CONTENT=0 disables prompt/response/tool content capture.
• PI_TLS_ENDPOINT or TRACE_TLS_ENDPOINT or TLS_ENDPOINT
• PI_TLS_REGION or TRACE_TLS_REGION or TLS_REGION
• PI_TLS_TRACE_TOPIC_ID or PI_TLS_TOPIC_ID or TRACE_TLS_TRACE_TOPIC_ID or TLS_TRACE_TOPIC_ID
• PI_TLS_API_KEY or TRACE_TLS_API_KEY or TLS_API_KEY
• PI_TLS_AK / PI_TLS_SK or TRACE_TLS_AK / TRACE_TLS_SK or TLS_AK / TLS_SK

Default data root:

~/.pi/agent/tls-observer-pi

Pi plugin loading

Install with the dedicated installer:

npm exec -y --package=@volcengine/tls-observer-pi-install -- tls-observer-pi-install

If pi is not on PATH, pass PI_TLS_PI_BIN=/absolute/path/to/pi or --pi-bin /absolute/path/to/pi.

For local installs, build the runtime package first and point the installer at the package source. The installer uses Pi CLI install semantics: pi install npm:<package> for registry installs and pi install <local-path> for local runtime packages.

cd packages/pi
rslib build
node scripts/build-package.mjs
cd ../pi-install
PI_PLUGIN_SOURCE=../pi/dist-package npm exec -y -- tls-observer-pi-install
cd -

Design notes

This implementation uses a clean-room Pi adapter. It borrows the event-aggregation idea from existing Pi tracing integrations, but the code, names, state model, and TLS span mapping are independently implemented for this repository.