Registry / ai-ml / llm-trace-phoenix-otlp

llm-trace-phoenix-otlp

library1.3.0jsnpmunverified

OpenClaw plugin for sending LLM input/output traces to Arize Phoenix via OpenTelemetry OTLP gRPC. Version 1.3.0. Hooks into llm_input and llm_output events, opens OTel spans, and batches export to Phoenix. Routes projects via resource attribute 'openinference.project.name' or gRPC metadata header 'x-phoenix-project-name'. Requires running Phoenix instance on port 4317. Inspired by a similar plugin, rewritten for better reliability.

ai-ml devops

npm install llm-trace-phoenix-otlp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LLM-TRACE-PHOENIX-

llm-trace-phoenix-otlp

ai-mljavascriptv1.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createLLMTracePhoenixPlugin

✓ import { createLLMTracePhoenixPlugin } from 'llm-trace-phoenix-otlp';

✗ const createLLMTracePhoenixPlugin = require('llm-trace-phoenix-otlp');

Default export function, but named import is correct. CommonJS require() does not work as expected; use ESM import or destructure.

LLMTracePhoenixPluginConfig

✓ import type { LLMTracePhoenixPluginConfig } from 'llm-trace-phoenix-otlp';

✗ import { LLMTracePhoenixPluginConfig } from 'llm-trace-phoenix-otlp';

This is a TypeScript type, not a runtime value. Use `import type` to avoid emitting in JS.

setupLLMTrace

✓ import { setupLLMTrace } from 'llm-trace-phoenix-otlp';

✗ import setupLLMTrace from 'llm-trace-phoenix-otlp';

setupLLMTrace is a named export, not default. Using default import will result in undefined.

Shows how to create the plugin with configuration and register with OpenClaw or use standalone setup function.

import { createLLMTracePhoenixPlugin } from 'llm-trace-phoenix-otlp'; const plugin = createLLMTracePhoenixPlugin({ phoenixGrpcUrl: process.env.PHOENIX_GRPC_URL ?? 'http://localhost:4317', projectName: process.env.PHOENIX_PROJECT_NAME ?? 'openclaw', }); // Register with OpenClaw (if using OpenClaw Gateway) // In openclaw.json: // { // "plugins": { // "allow": ["llm-trace-phoenix-otlp"], // "entries": { // "llm-trace-phoenix-otlp": { // "enabled": true, // "config": { // "phoenixGrpcUrl": "http://localhost:4317", // "projectName": "my-project" // } // } // } // } // } // Or use standalone with setupLLMTrace: import { setupLLMTrace } from 'llm-trace-phoenix-otlp'; setupLLMTrace({ phoenixGrpcUrl: 'http://localhost:4317', projectName: 'my-app', });

Debug

Known issues

gotchaPhoenix instance must be running and accessible on the configured gRPC endpoint; otherwise spans will be dropped silently.

fix

Ensure Phoenix is running on port 4317. Use Docker Compose as shown in README.

affects: >=0.1.0

deprecatedThe plugin version 1.0.0 had an incorrect span attribute name 'llm.token_count.total' as 'llm.token_count.total_tokens' which was fixed in 1.1.0.

fix

Update to version 1.1.0 or later.

affects: >=1.0.0 <1.1.0

gotchaProject routing uses 'openinference.project.name' resource attribute; if not set, falls back to 'x-phoenix-project-name' gRPC metadata header. If neither is set, spans may not be visible in Phoenix UI.

fix

Set the 'projectName' config option to ensure correct routing.

affects: >=0.1.0

gotchaTypeScript types are bundled but not exported individually; importing types from subpaths will fail.

fix

Import only from the package root: 'llm-trace-phoenix-otlp'.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module '@opentelemetry/exporter-trace-otlp-grpc'

Missing peer dependency @opentelemetry/exporter-trace-otlp-grpc.

fix

Install the missing dependency: npm install @opentelemetry/exporter-trace-otlp-grpc

TypeError: (0 , createLLMTracePhoenixPlugin) is not a function

Using CommonJS require() instead of ESM import.

fix

Use import statement: import { createLLMTracePhoenixPlugin } from 'llm-trace-phoenix-otlp';

Property 'llm.token_count.total' does not exist on type 'SpanAttributes'

Trying to set non-standard attribute not defined in types.

fix

Use the correct attribute names from package; or cast to any if necessary.

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

@opentelemetry/exporter-trace-otlp-grpcrequiredOTLP gRPC trace exporter for sending spans to Phoenix

@opentelemetry/resourcesrequiredResource creation for setting project name and other attributes

@opentelemetry/sdk-trace-baserequiredBasic trace SDK components like BatchSpanProcessor

@opentelemetry/apirequiredOpenTelemetry API for span creation and context propagation

@opentelemetry/semantic-conventionsrequiredSemantic convention constants for span attributes

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/ParinLL/llm-trace-phoenix-otlp ↗

packagellm-trace-phoenix-otlp ↗

homepagehttps://github.com/ParinLL/llm-trace-phoenix-otlp#readme ↗