Node.js LLM 应用自定义埋点最佳实践

本文重点说明最容易影响接入结果的三件事：

1. 如何在"ARMS 探针自动采集"和"util 完全手动接入"之间选择。

2. 如何保证 ENTRY -> AGENT -> STEP -> LLM/TOOL 的调用链关系正确。

3. 如何在发布前验证属性、Token、消息内容和异常状态确实已上报。

1. 接入模式选择

@loongsuite/cms_node_sdk 探针和 @loongsuite/otel-util-genai 当前使用不同的 Trace/Context API。不要在同一进程中把二者当成同一套 Provider 组合使用，也不要初始化两套导出链路。

npm install \
  @loongsuite/cms_node_sdk@1.0.4 \
  openai@5.23.2

export ARMS_LICENSE="<ARMS License>"
export CMS_SERVICE_NAME="weather-agent"
export ARMS_REGION_ID="cn-hongkong"
# 默认 workspace 不需要设置；非默认 workspace 才设置
# export ARMS_WORKSPACE="<workspace>"

node -r @loongsuite/cms_node_sdk/register app.js

2. 前提条件

• 已开通并完成ARMS 应用监控接入。

• 使用 Node.js 20 或 22 LTS。

• 已从 ARMS 控制台取得当前应用和地域对应的 OTLP HTTP 接入地址及鉴权 Header。

• 已确认应用的 service.name 在同一环境中唯一且稳定。

• 埋点字段遵循LLM Trace 字段定义说明。

不要把 API Key、OTLP 鉴权 Header、完整用户输入或其他敏感数据写入源码和日志。

3. 安装依赖

为了保证示例可复现，本文固定安装已验证的正式版本，不使用裸包名。本文的验证基线是 @loongsuite/otel-util-genai@0.1.0；升级到后续版本后，必须按照第 17 节重新验证依赖安装、Span 树、属性和 OTLP 导出。所有预发布版本均不作为本文的生产接入基线。

npm install @loongsuite/otel-util-genai@0.1.0

手动接入还需安装已经验证的 OpenTelemetry 1.30.x SDK 和 OTLP HTTP Exporter：

npm install \
  @opentelemetry/api@1.9.1 \
  @opentelemetry/sdk-trace-node@1.30.1 \
  @opentelemetry/sdk-trace-base@1.30.1 \
  @opentelemetry/resources@1.30.1 \
  @opentelemetry/exporter-trace-otlp-http@0.57.2

@loongsuite/otel-util-genai 当前 peer dependency 位于 OpenTelemetry JS 1.x 版本线。不要在没有完整兼容性验证的情况下把本文示例直接替换为 OpenTelemetry SDK 2.x。

4. 配置 Resource 和内容采集策略

export OTEL_SERVICE_NAME="weather-agent"
export OTEL_RESOURCE_ATTRIBUTES="acs.arms.service.feature=genai_app,gen_ai.instrumentation.sdk.name=loongsuite-genai-utils"

export OTEL_SEMCONV_STABILITY_OPT_IN="gen_ai_latest_experimental"
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="SPAN_ONLY"

5. 完全手动接入时初始化 OpenTelemetry

以下初始化文件必须先于业务模块加载：

// telemetry.mjs
import { trace } from "@opentelemetry/api";
import { OTLPTraceExporter } from
  "@opentelemetry/exporter-trace-otlp-http";
import {
  Resource,
  detectResourcesSync,
  envDetectorSync,
} from "@opentelemetry/resources";
import {
  BatchSpanProcessor,
} from "@opentelemetry/sdk-trace-base";
import {
  NodeTracerProvider,
} from "@opentelemetry/sdk-trace-node";
import {
  ExtendedTelemetryHandler,
} from "@loongsuite/otel-util-genai";

const detected = detectResourcesSync({
  detectors: [envDetectorSync],
});
const resource = Resource.default()
  .merge(detected)
  .merge(new Resource({
    "service.name":
      process.env.OTEL_SERVICE_NAME ?? "weather-agent",
    "acs.arms.service.feature": "genai_app",
    "gen_ai.instrumentation.sdk.name":
      "loongsuite-genai-utils",
  }));

const provider = new NodeTracerProvider({ resource });
provider.addSpanProcessor(
  new BatchSpanProcessor(new OTLPTraceExporter()),
);
provider.register();

export const handler = new ExtendedTelemetryHandler({
  tracerProvider: provider,
});
export const tracer = trace.getTracer("weather-agent", "1.0.0");

export async function shutdownTelemetry() {
  await provider.forceFlush();
  await provider.shutdown();
}

从 ARMS 控制台复制接入参数。变量名称和 URL 形式以控制台给出的示例为准，不要自行拼接地域、路径或鉴权参数。

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="<控制台提供的 traces endpoint>"
export OTEL_EXPORTER_OTLP_HEADERS="<控制台提供的鉴权 Header>"

如果控制台给出的是通用 OTEL_EXPORTER_OTLP_ENDPOINT，应按控制台示例使用该变量。

应用入口必须先加载 telemetry.mjs，并在进程退出前刷新数据：

import {
  handler,
  shutdownTelemetry,
} from "./telemetry.mjs";
import { runRequest } from "./agent.mjs";

try {
  await runRequest({ handler });
} finally {
  await shutdownTelemetry();
}

ConsoleSpanExporter 只能用于本地观察，不能把数据发送到 ARMS。

6. Span 类型与命名

Span 名称和 gen_ai.operation.name 是两个不同字段，不应混用。

典型 Agent 请求的链路应为：

ENTRY enter_ai_application_system
  AGENT invoke_agent WeatherAgent
    STEP react step
      LLM chat qwen-plus
      TOOL execute_tool get_weather
    STEP react step
      LLM chat qwen-plus

Tool 是否与 LLM 同属一个 Step，取决于应用的实际执行模型。不要为了得到固定截图而伪造父子关系。

7. Node.js 上下文传播规则

这是 Node.js 接入中最重要的规则。

handler.startInvokeAgent(agentInv, entryInv.contextToken);
handler.startReactStep(stepInv, agentInv.contextToken);
handler.startLlm(llmInv, stepInv.contextToken);
handler.startExecuteTool(toolInv, stepInv.contextToken);

import { context } from "@opentelemetry/api";

const response = await context.with(
  llmInv.contextToken,
  () => modelClient.chat.completions.create(request),
);

8. 创建 Entry、Agent 和 ReAct Step

import {
  createEntryInvocation,
  createInvokeAgentInvocation,
  createReactStepInvocation,
} from "@loongsuite/otel-util-genai";

const entryInv = createEntryInvocation({
  sessionId,
  userId,
  agentName: "WeatherAgent",
  inputMessages: [{
    role: "user",
    parts: [{ type: "text", content: userMessage }],
  }],
});
handler.startEntry(entryInv);

const agentInv = createInvokeAgentInvocation("dashscope", {
  agentName: "WeatherAgent",
  agentDescription: "先查询天气工具，再回答用户问题。",
  requestModel: "qwen-plus",
});
handler.startInvokeAgent(agentInv, entryInv.contextToken);

const stepInv = createReactStepInvocation({ round: 1 });
handler.startReactStep(stepInv, agentInv.contextToken);

完成时从内向外结束：

stepInv.finishReason = "stop";
handler.stopReactStep(stepInv);

agentInv.inputTokens = totalInputTokens;
agentInv.outputTokens = totalOutputTokens;
agentInv.outputMessages = finalOutputMessages;
handler.stopInvokeAgent(agentInv);

entryInv.outputMessages = finalOutputMessages;
handler.stopEntry(entryInv);

如果上游返回可靠的 total_tokens，可以显式设置 totalTokens。未设置时，工具会根据 input 和 output Token 计算总量。

9. LLM Span：自动采集和手工采集二选一

const response = await context.with(
  stepInv.contextToken,
  () => modelClient.chat.completions.create(request),
);

import {
  createLLMInvocation,
} from "@loongsuite/otel-util-genai";

const llmInv = createLLMInvocation({
  provider: "dashscope",
  operationName: "chat",
  requestModel: "qwen-plus",
  inputMessages: toGenAIInputMessages(messages),
  toolDefinitions: toGenAIToolDefinitions(tools),
});
handler.startLlm(llmInv, stepInv.contextToken);

try {
  const response = await context.with(
    llmInv.contextToken,
    () => modelClient.chat.completions.create({
      model: "qwen-plus",
      messages,
      tools,
    }),
  );

  const choice = response.choices?.[0];
  if (!choice?.message) {
    throw new Error("The model response has no first choice");
  }

  llmInv.responseId = response.id ?? null;
  llmInv.responseModelName = response.model ?? "qwen-plus";
  llmInv.finishReasons = [
    choice.finish_reason ?? "stop",
  ];
  llmInv.outputMessages = [
    toGenAIOutputMessage(
      choice.message,
      choice.finish_reason,
    ),
  ];

  if (response.usage) {
    llmInv.inputTokens =
      response.usage.prompt_tokens ?? null;
    llmInv.outputTokens =
      response.usage.completion_tokens ?? null;
    llmInv.totalTokens =
      response.usage.total_tokens ?? null;
  }

  handler.stopLlm(llmInv);
} catch (error) {
  handler.failLlm(
    llmInv,
    toSafeGenAIError(
      error,
      "LLMError",
      "LLM request failed",
    ),
  );
  throw error;
}

10. 正确转换 OpenAI 兼容消息

不能只转换 { role, content }。Agent 的第二轮模型输入还包含 assistant tool_calls 和 role 为 tool 的工具结果；丢失这些字段会导致 ARMS 无法还原一次完整工具调用。

export function toGenAIMessageFinishReason(reason) {
  return reason === "tool_calls" ? "tool_call" : reason || "stop";
}

function textPart(content) {
  return { type: "text", content };
}

function toolCallPart(toolCall) {
  return {
    type: "tool_call",
    id: toolCall.id ?? null,
    name: toolCall.function.name,
    arguments: toolCall.function.arguments,
  };
}

export function toGenAIInputMessages(messages) {
  return messages.map((message) => {
    if (message.role === "tool") {
      return {
        role: "tool",
        parts: [{
          type: "tool_call_response",
          id: message.tool_call_id ?? null,
          response: message.content ?? "",
        }],
      };
    }

    if (
      message.content != null &&
      typeof message.content !== "string"
    ) {
      throw new TypeError(
        "This example only accepts string message content.",
      );
    }

    const parts = [];

    if (message.content) {
      parts.push(textPart(message.content));
    }

    for (const toolCall of message.tool_calls ?? []) {
      parts.push(toolCallPart(toolCall));
    }
    return { role: message.role, parts };
  });
}

export function toGenAIOutputMessage(message, finishReason) {
  const parts = [];

  if (message.content) {
    parts.push(textPart(message.content));
  }

  for (const toolCall of message.tool_calls ?? []) {
    parts.push(toolCallPart(toolCall));
  }
  return {
    role: "assistant",
    parts,
    finishReason: toGenAIMessageFinishReason(finishReason),
  };
}

export function toGenAIToolDefinitions(tools) {
  return tools.map((tool) => ({
    type: "function",
    name: tool.function.name,
    description: tool.function.description ?? null,
    parameters: tool.function.parameters ?? {},
  }));
}

Span 属性和消息 JSON 使用不同的 finish reason 取值。不要对两者应用同一转换：

模型返回 choice.finish_reason = "tool_calls"

gen_ai.response.finish_reasons = ["tool_calls"]
output message.finish_reason    = "tool_call"

gen_ai.response.finish_reasons 应保留模型提供商返回的原始值；只有写入 output message Schema 时，才把复数 tool_calls 转成单数 tool_call。

toolCall.function.arguments 通常是 JSON 字符串。除非业务已经成功解析并希望按对象记录，否则应保留模型的原始值，避免埋点数据与实际请求不一致。

11. 创建 Tool Span

import {
  createExecuteToolInvocation,
} from "@loongsuite/otel-util-genai";

const toolInv = createExecuteToolInvocation(
  toolCall.function.name,
  {
    toolCallId: toolCall.id ?? null,
    toolDescription: "查询指定城市的天气",
    toolType: "function",
    toolCallArguments: toolCall.function.arguments,
  },
);
handler.startExecuteTool(toolInv, stepInv.contextToken);

try {
  const result = await context.with(
    toolInv.contextToken,
    () => dispatchTool(
      toolCall.function.name,
      toolCall.function.arguments,
    ),
  );
  toolInv.toolCallResult = result;
  handler.stopExecuteTool(toolInv);
} catch (error) {
  handler.failExecuteTool(
    toolInv,
    toSafeGenAIError(
      error,
      "ToolError",
      "Tool execution failed",
    ),
  );
  throw error;
}

工具调用完成后，还应把结果以 OpenAI 兼容格式追加到下一轮输入：

messages.push({
  role: "tool",
  tool_call_id: toolCall.id,
  content: result,
});

toolCallId 必须在 assistant tool call、Tool Span 和 tool response 三处保持一致。

toolCallArguments 和 toolCallResult 会直接写入 Tool Span，不受消息内容采集开关控制。设置这两个字段前必须完成脱敏；不允许上报的内容应省略，而不是寄希望于 NO_CONTENT 自动过滤。

12. 异常处理必须逐层收口

每个已经开始且仍在 recording 的 invocation 都必须调用一次对应的 stopXxx() 或 failXxx()。

原始异常消息可能包含模型响应体、请求参数、文件路径或凭证。failXxx() 会把传入的 message 写入 Span Status，因此不能直接传入 error.message 或 String(error)。应使用固定的安全消息，并只保留经过约束的错误类型：

const SAFE_ERROR_TYPE_PATTERN =
  /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;

function toSafeGenAIError(error, fallbackType, safeMessage) {
  const candidateType =
    error instanceof Error
      ? error.constructor?.name
      : null;
  const type =
    typeof candidateType === "string" &&
    SAFE_ERROR_TYPE_PATTERN.test(candidateType)
      ? candidateType
      : fallbackType;

  return { type, message: safeMessage };
}

嵌套调用失败时，应从内向外标记：

failLlm / failExecuteTool
  -> failReactStep
    -> failInvokeAgent
      -> failEntry

推荐在外层 catch 中先检查：

if (stepInv.span?.isRecording()) {
  handler.failReactStep(
    stepInv,
    toSafeGenAIError(
      error,
      "StepError",
      "Agent step failed",
    ),
  );
}

这样可以避免已经结束的 Span 被重复结束。failXxx() 会记录错误状态和 error.type，调用后仍需重新抛出原始异常，不能吞掉业务错误。应用如需记录日志，也应使用固定安全消息或经过审核的脱敏字段，不能直接输出原始异常。

13. 创建普通业务 Span

不属于 GenAI 语义的内部操作使用原生 OTel Span。例如在 Tool 内记录参数校验：

import {
  context,
  SpanStatusCode,
  trace,
} from "@opentelemetry/api";

const validationSpan = tracer.startSpan(
  "validate_weather_arguments",
  { attributes: { "app.validation.type": "json-schema" } },
  toolInv.contextToken,
);
const validationContext = trace.setSpan(
  toolInv.contextToken,
  validationSpan,
);

try {
  await context.with(
    validationContext,
    () => validateArguments(argumentsJson),
  );
} catch (error) {
  const safeError = toSafeGenAIError(
    error,
    "ValidationError",
    "Argument validation failed",
  );
  validationSpan.recordException({
    name: safeError.type,
    message: safeError.message,
  });
  validationSpan.setAttribute(
    "error.type",
    safeError.type,
  );
  validationSpan.setStatus({
    code: SpanStatusCode.ERROR,
    message: safeError.message,
  });
  throw error;
} finally {
  validationSpan.end();
}

自定义属性应使用业务命名空间，例如 app.*。不要用自定义值覆盖 gen_ai.*、server.*、error.type 等由工具维护的字段。

14. 其他 GenAI Span 类型

Embedding、Retrieval、Rerank、Memory 等扩展 Span 类型遵循同一生命周期：创建 invocation、传入父 Context、在真实操作完成后补充结果、正常或异常结束。异常处理模式与第 12 节一致（try/catch + failXxx()），以下示例省略异常路径以突出核心字段。

const embeddingInv = createEmbeddingInvocation(
  "text-embedding-v3",
  { provider: "dashscope" },
);
handler.startEmbedding(embeddingInv, stepInv.contextToken);
// 调用 embedding API
embeddingInv.inputTokens = usage.prompt_tokens;
embeddingInv.dimensionCount = vectors[0].length;
handler.stopEmbedding(embeddingInv);

const retrievalInv = createRetrievalInvocation({
  dataSourceId: "product-docs",
  query,
  topK: 5,
});
handler.startRetrieval(retrievalInv, stepInv.contextToken);
retrievalInv.documents = documents.map((document) => ({
  id: document.id,
  score: document.score,
  content: document.content,
  metadata: document.metadata,
}));
handler.stopRetrieval(retrievalInv);

14.1 多模态输入（图片 URL）

应用发送给模型的请求对象和写入 GenAI Span 的消息对象是两套 Schema，应分别构造。以下示例使用模型实际接收的图片 URL，因此在 GenAI 消息中映射为 Uri Part：

const prompt = "请用一句话描述这张图片。";
const imageUrl = "https://example.com/image.jpg";

const inputMessages = [{
  role: "user",
  parts: [
    { type: "text", content: prompt },
    {
      type: "uri",
      mimeType: "image/jpeg",
      modality: "image",
      uri: imageUrl,
    },
  ],
}];

const llmInv = createLLMInvocation({
  provider: "dashscope",
  operationName: "chat",
  requestModel: "qwen3-vl-plus",
  inputMessages,
  outputType: "text",
});
handler.startLlm(llmInv, entryInv.contextToken);

try {
  const response = await context.with(
    llmInv.contextToken,
    () => modelClient.chat.completions.create({
      model: "qwen3-vl-plus",
      messages: [{
        role: "user",
        content: [
          { type: "text", text: prompt },
          {
            type: "image_url",
            image_url: { url: imageUrl },
          },
        ],
      }],
    }),
  );

  const choice = response.choices?.[0];
  if (!choice?.message) {
    throw new Error("The model response has no first choice");
  }
  llmInv.responseId = response.id ?? null;
  llmInv.responseModelName =
    response.model ?? "qwen3-vl-plus";
  llmInv.finishReasons = [
    choice.finish_reason ?? "stop",
  ];
  llmInv.inputTokens =
    response.usage?.prompt_tokens ?? null;
  llmInv.outputTokens =
    response.usage?.completion_tokens ?? null;
  llmInv.totalTokens =
    response.usage?.total_tokens ?? null;
  llmInv.outputMessages = [{
    role: "assistant",
    parts: [{
      type: "text",
      content: choice.message.content ?? "",
    }],
    finishReason: choice.finish_reason ?? "stop",
  }];
  handler.stopLlm(llmInv);
} catch (error) {
  handler.failLlm(
    llmInv,
    toSafeGenAIError(
      error,
      "LLMError",
      "Multimodal LLM request failed",
    ),
  );
  throw error;
}

TypeScript 公共 API 使用 mimeType。在 SPAN_ONLY 或 SPAN_AND_EVENT 模式下，0.1.0 会自动生成：

gen_ai.input.messages
gen_ai.input.multimodal_metadata

两个属性中的 URI 数据都使用 Schema 字段 mime_type：

[
  {
    "type": "uri",
    "mime_type": "image/jpeg",
    "uri": "https://example.com/image.jpg",
    "modality": "image"
  }
]

multimodal metadata 只汇总最终消息中的 Uri Part，不包含 Text、Blob、Base64Blob 或 File。该工具只记录遥测数据，不负责上传媒体、调用模型或把 provider 文件对象转换成 URI。

{
  type: "file",
  mimeType: "application/pdf",
  modality: "document",
  fileId: "file-123",
}

{ type: "uri", mimeType: "image/png", modality: "image", uri }
{ type: "file", mimeType: "application/pdf", modality: "document", fileId }

{
  "type": "uri",
  "mime_type": "image/png",
  "modality": "image",
  "uri": "https://example.com/input.png"
}

{
  "type": "file",
  "mime_type": "application/pdf",
  "modality": "document",
  "file_id": "file-123"
}

gen_ai.input.multimodal_metadata
gen_ai.output.multimodal_metadata

15. 本地测试和端到端验证

cd nodejs-genai-util-demo
npm ci
npm test
npm run demo

export DASHSCOPE_API_KEY="<your-api-key>"
npm run demo:dashscope

export OTEL_SERVICE_NAME="weather-agent-validation"
export OTEL_RESOURCE_ATTRIBUTES="service.name=weather-agent-validation"
export OTEL_EXPORTER_OTLP_ENDPOINT="<ARMS endpoint>"
export OTEL_EXPORTER_OTLP_HEADERS="<ARMS auth header>"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export GENAI_DEMO_ALLOW_CONTENT_EXPORT="true"
npm run demo:e2e

export completed traceId=<trace-id>

export DASHSCOPE_API_KEY="<your-api-key>"
export OTEL_SERVICE_NAME="multimodal-agent-validation"
export OTEL_RESOURCE_ATTRIBUTES="service.name=multimodal-agent-validation"
export OTEL_EXPORTER_OTLP_ENDPOINT="<ARMS endpoint>"
export OTEL_EXPORTER_OTLP_HEADERS="<ARMS auth header>"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export GENAI_DEMO_ALLOW_CONTENT_EXPORT="true"
npm run demo:multimodal-e2e

export OTEL_SERVICE_NAME="event-log-validation"
export OTEL_RESOURCE_ATTRIBUTES="service.name=event-log-validation"
export OTEL_EXPORTER_OTLP_ENDPOINT="<ARMS endpoint>"
export OTEL_EXPORTER_OTLP_HEADERS="<ARMS auth header>"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export GENAI_DEMO_ALLOW_CONTENT_EXPORT="true"
npm run demo:event-log-e2e

cd nodejs-genai-util-demo/arms-probe-demo
npm ci

export DASHSCOPE_API_KEY="<your-api-key>"
export ARMS_LICENSE="<ARMS License>"
export CMS_SERVICE_NAME="probe-openai-validation"
export ARMS_REGION_ID="cn-hongkong"
# 默认 workspace 不需要设置
# export ARMS_WORKSPACE="<workspace>"

node -r @loongsuite/cms_node_sdk/register app.js

16. 常见问题

OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY

17. 相关资料

• ARMS 应用监控接入

• ARMS LLM Trace 字段定义说明

• OpenTelemetry GenAI 语义规范

• OpenTelemetry JS 文档

• OpenTelemetry JS W3C Baggage 安全公告（CVE-2026-54285）

• OpenTelemetry JS Jaeger Propagator 安全公告（CVE-2026-59892）

18. 配套 Demo

nodejs-genai-util-demo 包含：

• 离线模型和内存 Exporter。

• 真实 DashScope OpenAI 兼容接口调用。

• 真实 DashScope Tool Calling 到 OTLP 的组合验证。

• 真实 Qwen-VL 图片 URL 到 OTLP 的组合验证。

• Event Log input/output 多模态 metadata 到 OTLP 的组合验证。

• 独立的 ARMS Node.js 探针 + OpenAI 5 自动埋点验证。

• OTLP HTTP 导出。

• Tool 消息转换。

• 多模态 URI、mime_type 和自动 metadata 验证。

• 正常链路和异常链路单元测试。

• context.with() 对自动子 Span 父子关系的验证。

本文使用固定 commit 引用已经验收的 Demo，避免仓库后续变更导致文档代码和 npm 包行为漂移。更新本文验证基线时，应同步更新 Demo 的固定 tag 或 commit，并重新完成第 17 节的验证。Demo 中不得包含 API Key、OTLP 鉴权 Header、内部 Project、CLI profile 或历史 traceId。