loongsuite-js

June 12, 2026 · View on GitHub

✨ 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/
├── 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.git
cd loongsuite-js

# 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:

Summary:

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

Please also read our Code of Conduct.

📄 License

Apache-2.0 — see LICENSE for details.

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