feat(Opencode): add OpenTelemetry instrumentation plugin for Opencode

[whoIam0987]

feat(opencode): add OpenTelemetry instrumentation plugin for OpenCode

Summary

Add an OpenTelemetry observability plugin for OpenCode, enabling session-level Trace, Metrics, and Logs collection. Follows the same observability architecture as the existing Claude Code and OpenClaw plugins, but integrates as a native OpenCode Plugin (no hooks or shell aliases required).

---

What's included

• Plugin-driven event capture: Registers as an OpenCode plugin in ~/.config/opencode/plugins/, zero-intrusion integration with no code changes required
• Complete trace hierarchy: Entry → Agent → Step → LLM / Tool full parent-child span tree following the ReAct pattern (Permission recorded as an event on TOOL Span, not an independent Span)
• Metrics: Session count, token usage (by type), cost (USD), lines of code, git commits, tool duration, cache activity, session duration, model usage, retries
• Structured OTel Logs: User prompts, session lifecycle events, API requests/errors, tool decisions exported via OTLP Logs
• JSONL event logging: Outputs event_t schema records (consumed by loongsuite-pilot), with daily rotation
• Full OTLP export: Traces, Metrics, and Logs exported to any OTLP-compatible backend (Jaeger, Grafana Tempo, Alibaba Cloud ARMS, etc.)
• Per-signal endpoints: Traces, Metrics, and Logs can each be configured with independent OTLP endpoints
• Semconv dialect auto-detection: Automatically switches to ALIBABA_GROUP dialect (gen_ai.span_kind_name) when Sunfire endpoint detected
• One-line install: curl -fsSL <url>/remote-install.sh | bash with --endpoint and --service-name options
• Install/uninstall/pack scripts: Full lifecycle management
• Process exit safety: Intercepts process.exit(), SIGTERM, SIGINT, and beforeExit to guarantee final span flush
• Endpoint probing: TCP connectivity check before SDK initialization with clear diagnostic output

---

Key differences from existing plugins

Aspect	Claude Code	OpenClaw	OpenCode (this PR)
Integration method	Shell alias + NODE_OPTIONS injection	Native gateway plugin	Native OpenCode Plugin (file in ~/.config/opencode/plugins/)
Config format	JSON (settings.json)	JSON (openclaw.plugin.json)	Environment variables only (zero config files)
HTTP interception	intercept.js via NODE_OPTIONS	Not needed	Not needed (plugin receives events directly)
Shell alias	Required for NODE_OPTIONS injection	Not needed	Not needed
Build	JavaScript (no build step)	TypeScript → tsc	TypeScript (source-loaded by Bun runtime, no build step)
Test runner	Jest	Vitest	Bun test
Trace export	Optional OTLP	OTLP (traces + metrics)	OTLP (traces + metrics + logs, per-signal endpoints)
Span hierarchy	Session → Turn → Tool/LLM	Invocation-based	Entry → Agent → Step → LLM / Tool
JSONL logging	Yes	No	Yes (daily-rotated, event_t schema)
Metrics	Basic (session, token, cost)	Traces + metrics only	13+ instruments (histograms, counters, gauges)
Graceful shutdown	Hook-based flush	N/A	process.exit interception + signal handlers

---

Event flow

OpenCode runtime
  → plugin event bus (session.*, message.*, permission.*, command.*)
    → OtelPlugin (src/index.ts)
      → HandlerContext (shared state across all handlers)
        → OTel TracerProvider → OTLP Traces export
        → OTel MeterProvider  → OTLP Metrics export (periodic)
        → OTel LoggerProvider  → OTLP Logs export (batched)
        → JSONL log writer     → ~/.loongsuite-pilot/logs/opencode/ (daily rotation)

---

Trace hierarchy

🚪 enter (ENTRY)
└── 🤖 invoke_agent <agent-name> (AGENT)
    └── 📋 react step (STEP)
        ├── 🧠 chat <model> (LLM)
        │     gen_ai.input.messages, gen_ai.output.messages
        │     gen_ai.usage.input_tokens, gen_ai.usage.output_tokens
        │     gen_ai.response.time_to_first_token, gen_ai.response.reasoning_time
        └── 🔧 execute_tool <tool-name> (TOOL)
              gen_ai.tool.name, gen_ai.tool.call.arguments, gen_ai.tool.call.result

---

Test plan

Unit tests (bun test)

Run all tests via bun test in the plugin directory, covering the following modules:

• Config parsing and environment variable fallback
• OTel SDK initialization and metric instrument creation
• Endpoint connectivity probing
• Utility functions (truncate, bounded map, span attribute builders)
• Session lifecycle (counters, duration, error cleanup)
• Message/LLM Span (token metrics, TTFT, ReAct step)
• Permission decision events
• Activity metrics (lines of code, git commit detection)
• Metric disabling logic

End-to-end tests

• bash scripts/install.sh --endpoint <url> correctly writes plugin entry + env config block
• bash scripts/uninstall.sh cleanly removes all artifacts
• End-to-end: OpenCode session → spans appear in OTLP backend with correct hierarchy
• JSONL log file generates paired llm.request/llm.response + tool.call/tool.result events
• Token data captured correctly (input/output/reasoning/cache non-zero)
• process.exit interception ensures final span batch is flushed
• Resource attributes include acs.arms.service.feature: "genai_app"

---

Configuration

All configuration via environment variables (no config files required):

Variable	Description	Default
OTEL_EXPORTER_OTLP_ENDPOINT	Base OTLP endpoint (auto-enables telemetry when set)	http://localhost:4318
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	Per-signal traces endpoint (full URL)	—
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	Per-signal metrics endpoint (full URL)	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	Per-signal logs endpoint (full URL)	—
OTEL_EXPORTER_OTLP_HEADERS	Auth headers, comma-separated key=value	—
OTEL_SERVICE_NAME	Service name in resource	opencode
OTEL_RESOURCE_ATTRIBUTES	Additional resource attributes	—
OTEL_TRACES_EXPORTER	Set to none to disable traces	—
OTEL_LOGS_EXPORTER	Set to otlp to enable, none to disable	disabled
OTEL_METRIC_EXPORT_INTERVAL	Metrics export interval (ms)	60000
OTEL_METRIC_PREFIX	Metric name prefix	opencode.
OTEL_DISABLE_METRICS	Comma-separated metric names to disable	—
OTEL_TRACE_MAX_CONTENT_SIZE	Max chars per message content (0 = unlimited)	2048
OTEL_BLRP_SCHEDULE_DELAY	Log batch export delay (ms)	5000
LOONGSUITE_SEMCONV_DIALECT_NAME	Set to ALIBABA_GROUP for ARMS compatibility	auto-detected

---

Checklist

• 13+ metric instruments with correct units and descriptions
• Complete trace hierarchy (Entry → Agent → Step → LLM/Tool)
• JSONL event logging (llm.request/response, tool.call/result)
• Install/uninstall/pack/remote-install scripts
• Unit tests covering all handlers, config, and utility functions
• README with full documentation (Chinese)
• CHANGELOG with version history