palz-connector 1.2.8 → 1.2.9

package/index.ts

@@ -7,6 +7,7 @@
  * - IM 通信协议保持不变（WebSocket 接收消息，HTTP POST 发送回复）
  */
 
+import { initTracing } from "./src/tracing.js";
 import { palzPlugin } from "./src/channel.js";
 import { setPalzRuntime } from "./src/runtime.js";
 
@@ -21,6 +22,7 @@ const plugin = {
   },
   register(api: any) {
     const log = typeof api.runtime?.log === "function" ? api.runtime.log : console.log;
+    initTracing();
     log("palz-connector: register() called, saving runtime and registering channel");
     setPalzRuntime(api.runtime);
     api.registerChannel({ plugin: palzPlugin });

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "palz-connector",
   "name": "Palz Connector Channel",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "description": "Palz IM 接入 OpenClaw",
   "channels": [
     "palz-connector"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "palz-connector",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "type": "module",
   "main": "index.ts",
   "description": "Palz IM 接入 OpenClaw — 模块化架构，基于 OpenClaw Runtime 消息管道",
@@ -16,6 +16,12 @@
     }
   },
   "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.214.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-node": "^0.214.0",
+    "@opentelemetry/sdk-trace-node": "^2.6.1",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
     "ali-oss": "^6.21.0",
     "ws": "^8.18.0"
   }

package/src/bot.ts

@@ -15,6 +15,7 @@ import { resolvePalzAccount } from "./config.js";
 import { tryClaimMessage } from "./dedup.js";
 import { createPalzReplyDispatcher } from "./reply-dispatcher.js";
 import { resolvePalzMediaList } from "./media.js";
+import { tracer, trace, context, SpanStatusCode } from "./tracing.js";
 import type { PalzMessageEvent, OpenAIContent, ContentPart, TextContentPart, PalzMediaInfo } from "./types.js";
 
 // ============ group_id 解析 ============
@@ -173,6 +174,28 @@ export interface HandlePalzMessageParams {
 }
 
 export async function handlePalzMessage(params: HandlePalzMessageParams): Promise<void> {
+  const { msg } = params;
+
+  // 在当前 trace context（由 monitor.ts ws_recv span 建立）下创建子 span
+  return tracer.startActiveSpan("palz.handleMessage", async (span) => {
+    span.setAttribute("msg_id", msg.msg_id);
+    span.setAttribute("sender_id", msg.sender_id);
+    span.setAttribute("conversation_type", msg.conversation_type);
+    span.setAttribute("agent_id", msg.agent_id || "main");
+    span.setAttribute("is_group", msg.conversation_type === "group");
+
+    try {
+      await _handlePalzMessageInner(params);
+    } catch (e) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: String(e) });
+      throw e;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+async function _handlePalzMessageInner(params: HandlePalzMessageParams): Promise<void> {
   const { cfg, msg, runtime, accountId } = params;
   const log = typeof runtime?.log === "function" ? runtime.log : console.log;
   const error = typeof runtime?.error === "function" ? runtime.error : console.error;
@@ -181,11 +204,16 @@ export async function handlePalzMessage(params: HandlePalzMessageParams): Promis
   const isGroup = msg.conversation_type === "group";
   const effectiveAgentId = msg.agent_id || "main";
 
-  log(`${tag}: [STEP 1/6 入站过滤] msg_id=${msg.msg_id} sender=${msg.sender_id} conv=${msg.conversation_id} type=${msg.conversation_type} agent=${effectiveAgentId}`);
+  const step1Filter = `[STEP 1/6 入站过滤] msg_id=${msg.msg_id} sender=${msg.sender_id} conv=${msg.conversation_id} type=${msg.conversation_type} agent=${effectiveAgentId}`;
+  log(`${tag}: ${step1Filter}`);
+  const span = trace.getActiveSpan();
+  span?.addEvent(step1Filter);
 
   const content = msg.content;
   if (!content) {
-    log(`${tag}: [STEP 1 跳过] 原因=content为空`);
+    const skip = `[STEP 1 跳过] 原因=content为空`;
+    log(`${tag}: ${skip}`);
+    span?.addEvent(skip);
     return;
   }
 
@@ -197,10 +225,14 @@ export async function handlePalzMessage(params: HandlePalzMessageParams): Promis
     ? content.filter((p: ContentPart) => p.type === "file").length
     : 0;
 
-  log(`${tag}: [STEP 1 解析] plainText="${plainText}" (len=${plainText.length}) hasMedia=${hasMedia} mediaCount=${mediaCount}`);
+  const step1Parse = `[STEP 1 解析] plainText="${plainText}" (len=${plainText.length}) hasMedia=${hasMedia} mediaCount=${mediaCount}`;
+  log(`${tag}: ${step1Parse}`);
+  span?.addEvent(step1Parse);
 
   if (!plainText && !hasMedia) {
-    log(`${tag}: [STEP 1 跳过] 原因=无文本且无媒体`);
+    const skip = `[STEP 1 跳过] 原因=无文本且无媒体`;
+    log(`${tag}: ${skip}`);
+    span?.addEvent(skip);
     return;
   }
 
@@ -215,9 +247,11 @@ export async function handlePalzMessage(params: HandlePalzMessageParams): Promis
     const historyKey = `${effectiveAgentId}:${msg.conversation_id}`;
     const senderName = msg.sender_name || msg.sender_id;
     log(`${tag}: [STEP 1 群聊历史] 未@机器人, 准备记录历史 historyKey=${historyKey} mentioned_bot=${msg.mentioned_bot} conversation_type=${msg.conversation_type}`);
+    span?.addEvent(`[STEP 1 群聊历史] 未@机器人, 准备记录历史 historyKey=${historyKey} mentioned_bot=${msg.mentioned_bot} conversation_type=${msg.conversation_type}`);
     // 解析媒体文件（图片/文档等），缓存到本地
     const historyMediaList = await resolvePalzMediaList(msg.content, log);
     log(`${tag}: [STEP 1 群聊历史] 媒体解析完成: mediaCount=${historyMediaList.length}`);
+    span?.addEvent(`[STEP 1 群聊历史] 媒体解析完成: mediaCount=${historyMediaList.length}`);
     const bodyWithPlaceholder = historyMediaList.length > 0
       ? `${senderName}: ${plainText} ${historyMediaList.map(m => m.placeholder).join(' ')}`
       : `${senderName}: ${plainText}`;
@@ -233,36 +267,82 @@ export async function handlePalzMessage(params: HandlePalzMessageParams): Promis
       limit: DEFAULT_GROUP_HISTORY_LIMIT,
       log,
     });
-    log(`${tag}: [STEP 1 跳过] 原因=群聊中未@机器人, 已记录到历史 historyKey=${historyKey} mediaCount=${historyMediaList.length}`);
+    const skipHistory = `[STEP 1 跳过] 原因=群聊中未@机器人, 已记录到历史 historyKey=${historyKey} mediaCount=${historyMediaList.length}`;
+    log(`${tag}: ${skipHistory}`);
+    span?.addEvent(skipHistory);
     return;
   }
   if (isGroup && !wasMentioned && !groupContextCacheEnabled) {
-    log(`${tag}: [STEP 1 群聊直通] groupContextCache=false, 未@消息也将发送给AI mentioned_bot=${msg.mentioned_bot}`);
+    const passThrough = `[STEP 1 群聊直通] groupContextCache=false, 未@消息也将发送给AI mentioned_bot=${msg.mentioned_bot}`;
+    log(`${tag}: ${passThrough}`);
+    span?.addEvent(passThrough);
   }
 
   // 去重（按 agentId + conversationId 隔离，同群多 bot 场景）
   const claimed = tryClaimMessage(msg.msg_id, effectiveAgentId, msg.conversation_id);
-  log(`${tag}: [STEP 2/6 去重] msg_id=${msg.msg_id} agent=${effectiveAgentId} conv=${msg.conversation_id} claimed=${claimed}`);
-  if (!claimed) return;
+  const step2 = `[STEP 2/6 去重] msg_id=${msg.msg_id} agent=${effectiveAgentId} conv=${msg.conversation_id} claimed=${claimed}`;
+  log(`${tag}: ${step2}`);
+  span?.addEvent(step2);
+  if (!claimed) {
+    span?.addEvent(`[STEP 2 跳过] 原因=消息已被处理(去重)`);
+    return;
+  }
 
   // 入队（按 agentId 隔离，不同 agent 并行处理）
   const queueKey = isGroup
     ? `${effectiveAgentId}:${msg.conversation_id}`
     : `${effectiveAgentId}:${msg.sender_id}:${msg.conversation_id}`;
-  log(`${tag}: [STEP 3/6 入队] queueKey="${queueKey}" isGroup=${isGroup}`);
+  const step3 = `[STEP 3/6 入队] queueKey="${queueKey}" isGroup=${isGroup}`;
+  log(`${tag}: ${step3}`);
+  span?.addEvent(step3);
 
+  // 捕获当前 trace context，enqueue 异步回调中恢复
+  const capturedCtx = context.active();
+
+  const enqueuedAt = Date.now();
   enqueue(queueKey, async () => {
     const startMs = Date.now();
+    const queueWaitMs = startMs - enqueuedAt;
+    if (queueWaitMs > 100) {
+      const waitLog = `[队列等待] msg_id=${msg.msg_id} queueKey=${queueKey} waitMs=${queueWaitMs}`;
+      log(`${tag}: ${waitLog}`);
+      span?.addEvent(waitLog);
+    }
     try {
-      await dispatchPalzMessage({ cfg, msg, runtime, accountId });
-      log(`${tag}: [完成] msg_id=${msg.msg_id} 总耗时=${Date.now() - startMs}ms`);
+      await context.with(capturedCtx, () =>
+        dispatchPalzMessage({ cfg, msg, runtime, accountId }),
+      );
+      const doneLog = `[完成] msg_id=${msg.msg_id} 总耗时=${Date.now() - startMs}ms queueWait=${queueWaitMs}ms`;
+      log(`${tag}: ${doneLog}`);
+      span?.addEvent(doneLog);
     } catch (err) {
-      error(`${tag}: [失败] msg_id=${msg.msg_id} 总耗时=${Date.now() - startMs}ms error=${String(err)}`);
+      const failLog = `[失败] msg_id=${msg.msg_id} 总耗时=${Date.now() - startMs}ms queueWait=${queueWaitMs}ms error=${String(err)}`;
+      error(`${tag}: ${failLog}`);
+      span?.addEvent(failLog);
     }
   });
 }
 
 async function dispatchPalzMessage(params: HandlePalzMessageParams): Promise<void> {
+  const { msg, runtime } = params;
+  const log = typeof runtime?.log === "function" ? runtime.log : console.log;
+
+  return tracer.startActiveSpan("palz.dispatch", async (span) => {
+    try {
+      span.setAttribute("msg_id", msg.msg_id);
+      span.setAttribute("conversation_id", msg.conversation_id);
+      await _dispatchPalzMessageInner(params);
+    } catch (e) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: String(e) });
+      log(`palz: [dispatch span error] ${String(e)}`);
+      throw e;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+async function _dispatchPalzMessageInner(params: HandlePalzMessageParams): Promise<void> {
   const { cfg, msg, runtime, accountId } = params;
   const log = typeof runtime?.log === "function" ? runtime.log : console.log;
   const tag = `palz[${accountId}]`;
@@ -287,15 +367,22 @@ async function dispatchPalzMessage(params: HandlePalzMessageParams): Promise<voi
   const mediaCount = Array.isArray(msg.content)
     ? msg.content.filter((p: ContentPart) => p.type === "file").length
     : 0;
-  log(`${tag}: [STEP 4/6 媒体解析] 输入: contentType=${typeof msg.content === "string" ? "string" : "array"} mediaCount=${mediaCount}`);
+  const span = trace.getActiveSpan();
+  const step4Input = `[STEP 4/6 媒体解析] 输入: contentType=${typeof msg.content === "string" ? "string" : "array"} mediaCount=${mediaCount}`;
+  log(`${tag}: ${step4Input}`);
+  span?.addEvent(step4Input);
   const mediaList = await resolvePalzMediaList(msg.content, log);
   let mediaPayload = buildMediaPayload(mediaList);
-  log(`${tag}: [STEP 4 输出] mediaList=${JSON.stringify(mediaList.map((m) => ({ path: m.path, contentType: m.contentType })))} mediaPayload=${JSON.stringify(mediaPayload)}`);
+  const step4Output = `[STEP 4 输出] mediaList=${JSON.stringify(mediaList.map((m) => ({ path: m.path, contentType: m.contentType })))} mediaPayload=${JSON.stringify(mediaPayload)}`;
+  log(`${tag}: ${step4Output}`);
+  span?.addEvent(step4Output);
 
   // STEP 5: 解析路由
   const peerKind = isGroup ? "group" : "direct";
   const routeInput = { cfg: "(cfg)", channel: "palz-connector", accountId, peer: { kind: peerKind, id: peerId } };
-  log(`${tag}: [STEP 5/6 路由解析] 输入: ${JSON.stringify(routeInput)} agent_id=${msg.agent_id ?? "(auto)"}`);
+  const step5Input = `[STEP 5/6 路由解析] 输入: ${JSON.stringify(routeInput)} agent_id=${msg.agent_id ?? "(auto)"}`;
+  log(`${tag}: ${step5Input}`);
+  span?.addEvent(step5Input);
   const route = core.channel.routing.resolveAgentRoute({
     cfg,
     channel: "palz-connector",
@@ -309,17 +396,23 @@ async function dispatchPalzMessage(params: HandlePalzMessageParams): Promise<voi
     const oldAgentId = route.agentId;
     route.agentId = effectiveAgentId;
     route.sessionKey = route.sessionKey.replace(`agent:${oldAgentId}:`, `agent:${effectiveAgentId}:`);
-    log(`${tag}: [STEP 5 覆盖] agentId: ${oldAgentId} -> ${effectiveAgentId}, sessionKey=${route.sessionKey} (${msg.agent_id ? "IM指定" : "默认main"})`);
+    const step5Override = `[STEP 5 覆盖] agentId: ${oldAgentId} -> ${effectiveAgentId}, sessionKey=${route.sessionKey} (${msg.agent_id ? "IM指定" : "默认main"})`;
+    log(`${tag}: ${step5Override}`);
+    span?.addEvent(step5Override);
   }
 
-  log(`${tag}: [STEP 5 输出] agentId=${route.agentId} sessionKey=${route.sessionKey} accountId=${route.accountId} matchedBy=${route.matchedBy}`);
+  const step5Output = `[STEP 5 输出] agentId=${route.agentId} sessionKey=${route.sessionKey} accountId=${route.accountId} matchedBy=${route.matchedBy}`;
+  log(`${tag}: ${step5Output}`);
+  span?.addEvent(step5Output);
 
   // STEP 6a: 构建 envelope body
   const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
   const messageBody = `${senderName}: ${plainText}`;
   // 群聊 from 带上 conversation_id 以区分不同用户
   const envelopeFrom = isGroup ? `${msg.conversation_id}:${msg.sender_id}` : msg.sender_id;
-  log(`${tag}: [STEP 6a/6 envelope构建] 输入: channel=Palz from=${envelopeFrom} messageBody="${messageBody.slice(0, 120)}" envelopeOptions=${JSON.stringify(envelopeOptions)}`);
+  const step6aInput = `[STEP 6a/6 envelope构建] 输入: channel=Palz from=${envelopeFrom} messageBody="${messageBody.slice(0, 120)}" envelopeOptions=${JSON.stringify(envelopeOptions)}`;
+  log(`${tag}: ${step6aInput}`);
+  span?.addEvent(step6aInput);
   const body = core.channel.reply.formatAgentEnvelope({
     channel: "Palz",
     from: envelopeFrom,
@@ -327,7 +420,9 @@ async function dispatchPalzMessage(params: HandlePalzMessageParams): Promise<voi
     body: messageBody,
     envelope: envelopeOptions,
   });
-  log(`${tag}: [STEP 6a 输出] envelope body (len=${body.length}): "${body.slice(0, 200)}"`);
+  const step6aOutput = `[STEP 6a 输出] envelope body (len=${body.length}): "${body.slice(0, 200)}"`;
+  log(`${tag}: ${step6aOutput}`);
+  span?.addEvent(step6aOutput);
 
   // STEP 6b: 构建 inbound context
   const palzFrom = `palz:${msg.sender_id}`;
@@ -343,7 +438,9 @@ async function dispatchPalzMessage(params: HandlePalzMessageParams): Promise<voi
         authorizers: [{ configured: false, allowed: true }],
       })
     : undefined;
-  log(`${tag}: [STEP 6b 命令授权] needsCommandAuth=${needsCommandAuth} commandAuthorized=${commandAuthorized}`);
+  const step6bAuth = `[STEP 6b 命令授权] needsCommandAuth=${needsCommandAuth} commandAuthorized=${commandAuthorized}`;
+  log(`${tag}: ${step6bAuth}`);
+  span?.addEvent(step6bAuth);
 
   const chatType = isGroup ? "group" : "direct";
 
@@ -388,7 +485,9 @@ async function dispatchPalzMessage(params: HandlePalzMessageParams): Promise<voi
           timestamp: entry.timestamp,
         }))
       : undefined;
-  log(`${tag}: [STEP 6b InboundHistory] count=${inboundHistory?.length ?? 0}`);
+  const step6bHistory = `[STEP 6b InboundHistory] count=${inboundHistory?.length ?? 0}`;
+  log(`${tag}: ${step6bHistory}`);
+  span?.addEvent(step6bHistory);
 
   // 构建 UntrustedContext：将 IM 消息的关键字段注入到 AI agent 的上下文中
   const untrustedContext: string[] = [
@@ -407,7 +506,9 @@ async function dispatchPalzMessage(params: HandlePalzMessageParams): Promise<voi
   if (msg.owner_name) {
     untrustedContext.push(`owner_name: ${msg.owner_name}`);
   }
-  log(`${tag}: [STEP 6b UntrustedContext] entries=${untrustedContext.length} values=${JSON.stringify(untrustedContext)}`);
+  const step6bCtx = `[STEP 6b UntrustedContext] entries=${untrustedContext.length} values=${JSON.stringify(untrustedContext)}`;
+  log(`${tag}: ${step6bCtx}`);
+  span?.addEvent(step6bCtx);
 
   const ctx = core.channel.reply.finalizeInboundContext({
     Body: combinedBody,
@@ -434,7 +535,9 @@ async function dispatchPalzMessage(params: HandlePalzMessageParams): Promise<voi
     OriginatingTo: palzTo,
     ...mediaPayload,
   });
-  log(`${tag}: [STEP 6b 输出] finalized context keys=[${Object.keys(ctx).join(",")}] CommandAuthorized=${ctx.CommandAuthorized}`);
+  const step6bOutput = `[STEP 6b 输出] finalized context keys=[${Object.keys(ctx).join(",")}] CommandAuthorized=${ctx.CommandAuthorized}`;
+  log(`${tag}: ${step6bOutput}`);
+  span?.addEvent(step6bOutput);
   ctx.metadata = {
     ...ctx.metadata,
     traceId: msg.msg_id, 
@@ -449,7 +552,9 @@ async function dispatchPalzMessage(params: HandlePalzMessageParams): Promise<voi
     enableStreaming: useStream,
     msgId: msg.msg_id,
   };
-  log(`${tag}: [STEP 6c 创建dispatcher] 输入: ${JSON.stringify(dispatcherParams)}`);
+  const step6c = `[STEP 6c 创建dispatcher] 输入: ${JSON.stringify(dispatcherParams)}`;
+  log(`${tag}: ${step6c}`);
+  span?.addEvent(step6c);
 
   const { dispatcher, replyOptions, markDispatchIdle } = createPalzReplyDispatcher({
     cfg,
@@ -468,7 +573,9 @@ async function dispatchPalzMessage(params: HandlePalzMessageParams): Promise<voi
   // STEP 6d: 分发消息给 AI
   // channel registry 守卫已在 index.ts 中通过 defineProperty 安装，
   // 每次读取 state.registry 时会自动注入 palz-connector channel。
-  log(`${tag}: [STEP 6d AI分发] 开始 session=${route.sessionKey} stream=${useStream}`);
+  const step6dStart = `[STEP 6d AI分发] 开始 session=${route.sessionKey} stream=${useStream}`;
+  log(`${tag}: ${step6dStart}`);
+  span?.addEvent(step6dStart);
   const dispatchStartMs = Date.now();
 
   const { queuedFinal, counts } = await core.channel.reply.withReplyDispatcher({
@@ -489,7 +596,31 @@ async function dispatchPalzMessage(params: HandlePalzMessageParams): Promise<voi
   }
 
   const dispatchElapsedMs = Date.now() - dispatchStartMs;
-  log(
-    `${tag}: [STEP 6d 输出] queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)} 耗时=${dispatchElapsedMs}ms`,
-  );
+  const step6dOutput = `[STEP 6d 输出] queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)} 耗时=${dispatchElapsedMs}ms`;
+  log(`${tag}: ${step6dOutput}`);
+  span?.addEvent(step6dOutput);
+  span?.setAttribute("dispatch_elapsed_ms", dispatchElapsedMs);
+  if (!queuedFinal && (!counts || Object.keys(counts).length === 0)) {
+    const noReply = `[STEP 6d 警告] AI 未产生回复 session=${route.sessionKey}`;
+    log(`${tag}: ${noReply}`);
+    span?.addEvent(noReply);
+  }
+
+  // 解析 sessionFile 路径，写入 trace
+  try {
+    const agentId = route.agentId;
+    const storePath = core.agent.session.resolveStorePath(undefined, { agentId });
+    const store = core.agent.session.loadSessionStore(storePath, { skipCache: true });
+    const normalizedKey = route.sessionKey.trim().toLowerCase();
+    const entry = store[normalizedKey] ?? store[route.sessionKey];
+    if (entry?.sessionId) {
+      const sessionFile = core.agent.session.resolveSessionFilePath(entry.sessionId, entry, { agentId });
+      const traceLog = `[TRACE] sessionFile=${sessionFile} sessionKey=${route.sessionKey} agentId=${agentId}`;
+      log(`${tag}: ${traceLog}`);
+      span?.setAttribute("session_file", sessionFile);
+      span?.addEvent(traceLog);
+    }
+  } catch (err) {
+    log(`${tag}: [TRACE] 解析 sessionFile 失败: ${String(err)}`);
+  }
 }

package/src/monitor.ts

@@ -7,6 +7,7 @@
 
 import WebSocket from "ws";
 import { handlePalzMessage } from "./bot.js";
+import { tracer, extractTraceparentContext, SpanStatusCode } from "./tracing.js";
 import type { PalzConfig, PalzMessageEvent } from "./types.js";
 
 export interface MonitorPalzParams {
@@ -97,8 +98,26 @@ export async function monitorPalzProvider(params: MonitorPalzParams): Promise<vo
             return;
           }
           messageCount++;
-          log(`palz[${accountId}]: [WS_RECV] #${messageCount} full_message=${raw.slice(0, 1000)}`);
-          handlePalzMessage({ cfg, msg, runtime, accountId });
+
+          // 从 IM 上游的 traceparent 恢复 trace context
+          const parentCtx = extractTraceparentContext(msg.traceparent);
+
+          tracer.startActiveSpan("palz.ws_recv", {}, parentCtx, (span) => {
+            try {
+              span.setAttribute("raw_message", raw);
+
+              log(`palz[${accountId}]: [WS_RECV] #${messageCount} full_message=${raw.slice(0, 1000)} traceId=${span.spanContext().traceId}`);
+
+              handlePalzMessage({ cfg, msg, runtime, accountId }).catch((err: any) => {
+                error(`palz[${accountId}]: [WS_RECV] handlePalzMessage unhandled error: ${err.message ?? err}`);
+              });
+            } catch (e) {
+              span.setStatus({ code: SpanStatusCode.ERROR, message: String(e) });
+              throw e;
+            } finally {
+              span.end();
+            }
+          });
         } catch (err: any) {
           error(`palz[${accountId}]: [WS_RECV] parse error: ${err.message}, raw=${raw.slice(0, 500)}`);
         }

package/src/send.ts

@@ -5,6 +5,7 @@
  * 支持一次性发送和流式发送两种模式。
  */
 
+import { tracer, trace, SpanStatusCode, buildTraceparentHeader } from "./tracing.js";
 import type { SendToIMParams, OpenAIContent } from "./types.js";
 
 let msgSeq = 0;
@@ -14,9 +15,24 @@ function nextMsgId(): string {
 }
 
 export async function sendToPalzIM(params: SendToIMParams): Promise<any> {
+  return tracer.startActiveSpan("palz.sendToIM", async (span) => {
+    try {
+      const result = await _sendToPalzIMInner(params);
+      return result;
+    } catch (e) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: String(e) });
+      throw e;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+async function _sendToPalzIMInner(params: SendToIMParams): Promise<any> {
   const { config, conversationId, content, conversationType, msgId, senderId, stream, msgType, groupId } = params;
   const url = `${config.apiBaseUrl}/bot/send`;
   const resolvedMsgId = msgId || nextMsgId();
+  const span = trace.getActiveSpan();
 
   const reqBody: Record<string, unknown> = {
     bot_id: config.botId,
@@ -46,14 +62,21 @@ export async function sendToPalzIM(params: SendToIMParams): Promise<any> {
   }
 
   const reqBodyStr = JSON.stringify(reqBody);
-  console.log(
-    `palz-send: [HTTP_REQ] POST ${url} body_length=${reqBodyStr.length}\n  request_body=${reqBodyStr}`,
-  );
+  const reqLog = `[HTTP_REQ] POST ${url} body_length=${reqBodyStr.length}\n  request_body=${reqBodyStr}`;
+  console.log(`palz-send: ${reqLog}`);
+  span?.addEvent(reqLog);
+
+  // 构建请求 headers，注入 Traceparent
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  const traceparent = buildTraceparentHeader();
+  if (traceparent) {
+    headers["Traceparent"] = traceparent;
+  }
 
   const startMs = Date.now();
   const response = await fetch(url, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers,
     body: reqBodyStr,
   });
   const elapsedMs = Date.now() - startMs;
@@ -65,15 +88,15 @@ export async function sendToPalzIM(params: SendToIMParams): Promise<any> {
   } catch {}
 
   if (!response.ok) {
-    console.error(
-      `palz-send: [HTTP_RES] FAILED status=${response.status} elapsed=${elapsedMs}ms\n  response_headers=${JSON.stringify(Object.fromEntries(response.headers.entries()))}\n  response_body=${rawText.slice(0, 500)}`,
-    );
+    const failLog = `[HTTP_RES] FAILED status=${response.status} elapsed=${elapsedMs}ms\n  response_headers=${JSON.stringify(Object.fromEntries(response.headers.entries()))}\n  response_body=${rawText.slice(0, 500)}`;
+    console.error(`palz-send: ${failLog}`);
+    span?.addEvent(failLog);
     throw new Error(`Palz send failed: ${response.status} ${rawText}`);
   }
 
-  console.log(
-    `palz-send: [HTTP_RES] OK status=${response.status} elapsed=${elapsedMs}ms msg_id=${resolvedMsgId}\n  response_body=${rawText.slice(0, 500)}`,
-  );
+  const okLog = `[HTTP_RES] OK status=${response.status} elapsed=${elapsedMs}ms msg_id=${resolvedMsgId}${traceparent ? ` Traceparent=${traceparent}` : ""}\n  response_body=${rawText.slice(0, 500)}`;
+  console.log(`palz-send: ${okLog}`);
+  span?.addEvent(okLog);
   return body;
 }
 

package/src/tracing.ts

@@ -0,0 +1,101 @@
+/**
+ * OpenTelemetry Tracing 初始化 + 工具函数
+ *
+ * 接入阿里云 ARMS 分布式链路追踪。
+ * - initTracing(): 初始化 SDK，在 index.ts register() 最前面调用
+ * - tracer: 全局 tracer 实例
+ * - extractTraceparentContext(): 从 W3C traceparent 字符串恢复上游 context
+ * - buildTraceparentHeader(): 构建当前 span 的 W3C traceparent 字符串
+ */
+
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import {
+  trace,
+  context,
+  SpanContext,
+  TraceFlags,
+  ROOT_CONTEXT,
+  SpanStatusCode,
+} from "@opentelemetry/api";
+
+export { trace, context, SpanStatusCode, ROOT_CONTEXT };
+export type { SpanContext };
+
+// 阿里云 ARMS 接入点
+const ARMS_ENDPOINT =
+  "http://tracing-analysis-dc-bj.aliyuncs.com/adapt_cd5l20bzv2@591056c1ce22f09_cd5l20bzv2@53df7ad2afe8301/api/otlp/traces";
+
+const helmEnv = process.env.HELM_ENV || "local";
+const serviceName = `palz-connector-${helmEnv}`;
+
+let sdk: NodeSDK | null = null;
+
+export function initTracing(): void {
+  if (sdk) return;
+
+  sdk = new NodeSDK({
+    resource: resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: serviceName,
+    }),
+    traceExporter: new OTLPTraceExporter({
+      url: ARMS_ENDPOINT,
+    }),
+  });
+
+  sdk.start();
+  console.log(
+    `[tracing] initialized: service=${serviceName} endpoint=${ARMS_ENDPOINT}`,
+  );
+}
+
+export const tracer = trace.getTracer("palz-connector");
+
+/**
+ * 解析 W3C traceparent 字符串，返回携带上游 span context 的 OTel Context。
+ *
+ * traceparent 格式: {version}-{traceId}-{spanId}-{traceFlags}
+ * 例: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+ */
+const TRACEPARENT_RE =
+  /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+export function extractTraceparentContext(
+  traceparent: string | undefined,
+): typeof ROOT_CONTEXT {
+  if (!traceparent) return ROOT_CONTEXT;
+
+  const match = TRACEPARENT_RE.exec(traceparent.trim());
+  if (!match) {
+    console.warn(`[tracing] invalid traceparent: ${traceparent}`);
+    return ROOT_CONTEXT;
+  }
+
+  const spanContext: SpanContext = {
+    traceId: match[2],
+    spanId: match[3],
+    traceFlags: parseInt(match[4], 16) as TraceFlags,
+    isRemote: true,
+  };
+
+  return trace.setSpanContext(ROOT_CONTEXT, spanContext);
+}
+
+/**
+ * 构建当前活跃 span 的 W3C traceparent 字符串。
+ * 用于在 HTTP 回复 header 中注入 Traceparent。
+ */
+export function buildTraceparentHeader(): string | undefined {
+  const span = trace.getActiveSpan();
+  if (!span) return undefined;
+
+  const ctx = span.spanContext();
+  if (!ctx.traceId || ctx.traceId === "00000000000000000000000000000000") {
+    return undefined;
+  }
+
+  const flags = ctx.traceFlags.toString(16).padStart(2, "0");
+  return `00-${ctx.traceId}-${ctx.spanId}-${flags}`;
+}

package/src/types.ts

@@ -37,6 +37,8 @@ export interface PalzMessageEvent {
   owner_name?: string;
   /** 群组 ID，群聊时 IM 可直接下发；若未提供则从 conversation_id 中解析 */
   group_id?: string;
+  /** W3C Trace Context traceparent，由 IM 上游传递 */
+  traceparent?: string;
 }
 
 // ============ 配置 ============