convez.ai
AgenteDevOps & InfraestruturaIntermediário
alibaba

LoongSuite JS - Instrumentação OpenTelemetry para Agentes de IA

alibaba/loongsuite-js

Observabilidade zero-code para agentes de IA em JavaScript

Ver no GitHub
BomPluginScore · de 0 a 100

Suite de plugins OpenTelemetry que instrumenta agentes de IA baseados em JavaScript (Claude Code e OpenClaw) para coletar traces, chamadas de ferramentas e métricas de LLM sem alterações de código. Integra-se com qualquer backend OTLP compatível como Jaeger, Honeycomb e Grafana Tempo.

Instalação

$npx convez-ai alibaba/loongsuite-js

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
26
Forks
16
Acompanhando
0
Saúde
75%
Último commit
há 3 meses
Versão
opentelemetry-instrumentation-openclaw/v0.1.5-beta
Issues abertas
13
Contribuidores
3

Casos de uso

  • Monitorar execução de agentes Claude Code em produção
  • Rastrear chamadas de ferramentas e métricas de LLM
  • Integrar observabilidade com backends OTLP existentes

Veredito

Solução madura da Alibaba para observabilidade de agentes de IA, com instalação simplificada e integração profunda em Claude Code. Essencial para times que precisam monitorar comportamento de agentes em produção com observabilidade distribuída.

README

A tradução para o português deste README ainda está na fila.

loongsuite-js


loongsuite

✨ Introduction

CI License Node.js OpenTelemetry

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

PluginPlatformDescription
opentelemetry-instrumentation-claudeClaude CodeHook-based session tracing + in-process LLM call capture via intercept.js
opentelemetry-instrumentation-openclawOpenClawNative 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

VariableDescriptionExample
OTEL_EXPORTER_OTLP_ENDPOINTOTLP export endpointhttps://your-backend:4318
OTEL_EXPORTER_OTLP_HEADERSRequest headers (comma-separated)x-api-key=your-key
OTEL_SERVICE_NAMEService name for tracesmy-claude-agent
OTEL_RESOURCE_ATTRIBUTESAdditional resource attributesenv=prod,team=infra

Claude plugin specific

VariableDescription
CLAUDE_TELEMETRY_DEBUGSet to 1 for console output (no backend needed)
OTEL_CLAUDE_DEBUGSet to 1 for verbose intercept.js logging
OTEL_CLAUDE_LANGForce language: zh or en (default: auto-detect)
OTEL_CLAUDE_HOOK_CMDOverride hook command name

🤝 Contributing

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

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

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 SIGLoongCollector SIGLoongSuite Python SIG
LoongCollector Go SIGLoongSuite Java SIG
Ver o original no GitHub

Bom para

Relacionados