loongsuite-js-plugins

---

✨ Introduction

LoongSuite JS Plugins is a key component of LoongSuite, Alibaba's unified observability data collection suite, providing OpenTelemetry instrumentation plugins for JavaScript-based AI coding agents. Collect traces, tool calls, and LLM metrics from Claude Code and OpenClaw — zero code changes required.

LoongSuite includes the following key components:

• LoongCollector: universal node agent, which provides log collection, Prometheus metric collection, and network and security collection capabilities based on eBPF.
• LoongSuite Python Agent: a process agent providing instrumentation for Python applications.
• LoongSuite Go Agent: a process agent for Golang with compile time instrumentation.
• LoongSuite Java Agent: a process agent for Java applications.
• LoongSuite JS Plugins: OpenTelemetry instrumentation plugins for JavaScript-based AI coding agents.
• Other upcoming language agents.

---

📦 Plugins

Plugin	Platform	Description
opentelemetry-instrumentation-claude	Claude Code	Hook-based session tracing + in-process LLM call capture via intercept.js
opentelemetry-instrumentation-openclaw	OpenClaw	Native gateway plugin: Traces + Metrics to any OTLP backend

Both plugins follow the OpenTelemetry GenAI semantic conventions and work with any OTLP-compatible backend (Jaeger, Honeycomb, Alibaba Sunfire, Grafana Tempo, Alibaba Cloud ARMS, etc.).

---

⚡ Quick Start

Claude Code — 5 minutes to first trace

One-line install (with OTLP backend):

curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/agenttrack/remote-install.sh | bash -s -- \
  --endpoint "https://your-otlp-endpoint:4318" \
  --service-name "my-claude-agent"

The script automatically installs hooks, sets up the claude alias, and writes the OTLP config to your shell profile. Traces appear in your backend automatically. The Span tree looks like:

🤖 Claude Session: "Analyze this codebase..."
├── 👤 Turn 1: Analyze this codebase...
│   ├── 🔧 Read: /src/index.js             gen_ai.span.kind=TOOL
│   ├── 🔧 Bash: npm test                  gen_ai.span.kind=TOOL
│   └── 🧠 LLM call (claude-sonnet-4-5)   gen_ai.span.kind=LLM
│       ├── input_tokens:  2048
│       └── output_tokens: 512
└── 👤 Turn 2: ...

📖 Full documentation → opentelemetry-instrumentation-claude

---

OpenClaw — one-line install

curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/install.sh | bash -s -- \
  --endpoint "https://your-otlp-endpoint:4318" \
  --serviceName "my-openclaw-agent"

📖 Full documentation → opentelemetry-instrumentation-openclaw

---

🏗️ Repository Structure

loongsuite-js-plugins/
├── opentelemetry-instrumentation-claude/   # Claude Code plugin (JavaScript)
│   ├── src/                                # Core source files
│   ├── test/                               # Jest test suite (101 tests)
│   ├── scripts/                            # Install / uninstall / pack scripts
│   ├── bin/otel-claude-hook                # CLI entry point
│   └── README.md
└── opentelemetry-instrumentation-openclaw/ # OpenClaw platform plugin (TypeScript)
    ├── src/                                # TypeScript source files
    ├── scripts/                            # Install / uninstall scripts
    └── README.md

---

🛠️ Development

Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0

Clone and set up

git clone https://github.com/alibaba/loongsuite-js-plugins.git
cd loongsuite-js-plugins

# Claude plugin
cd opentelemetry-instrumentation-claude
npm install
npm test

# OpenClaw plugin (TypeScript, requires build)
cd ../opentelemetry-instrumentation-openclaw
npm install
npm run build

Run tests

cd opentelemetry-instrumentation-claude
npm test                   # run tests
npm test -- --coverage     # with coverage report

Commit style

Follow Conventional Commits:

feat:     new feature
fix:      bug fix
docs:     documentation changes
test:     test additions or fixes
refactor: code refactoring
perf:     performance improvements
chore:    build / toolchain

---

🔧 Environment Variables

Common OTel variables

Variable	Description	Example
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP export endpoint	https://your-backend:4318
OTEL_EXPORTER_OTLP_HEADERS	Request headers (comma-separated)	x-api-key=your-key
OTEL_SERVICE_NAME	Service name for traces	my-claude-agent
OTEL_RESOURCE_ATTRIBUTES	Additional resource attributes	env=prod,team=infra

Claude plugin specific

Variable	Description
CLAUDE_TELEMETRY_DEBUG	Set to 1 for console output (no backend needed)
OTEL_CLAUDE_DEBUG	Set to 1 for verbose intercept.js logging
OTEL_CLAUDE_LANG	Force language: zh or en (default: auto-detect)
OTEL_CLAUDE_HOOK_CMD	Override hook command name

---

🤝 Contributing

Contributions are welcome! Please read the contributing guide for the plugin you're working on:

• opentelemetry-instrumentation-claude/CONTRIBUTING.md
• opentelemetry-instrumentation-openclaw/CONTRIBUTING.md

Summary:

1. Fork the repo and create a feature branch from main
2. Make your changes (follow Conventional Commits)
3. Ensure tests pass: npm test
4. Open a Pull Request

Please also read our Code of Conduct.

---

📄 License

Apache-2.0 — see LICENSE for details.

---

🔗 Related

• OpenTelemetry
• OpenTelemetry GenAI Semantic Conventions
• Claude Code
• OpenClaw

Community

We are looking forward to your feedback and suggestions. You can join our DingTalk group or scan the QR code below to engage with us.

LoongSuite JS SIG	LoongCollector SIG	LoongSuite Python SIG

LoongCollector Go SIG	LoongSuite Java SIG