AgentLoop:Node.js LLM uygulamalarının özel olarak izlenmesi

Otomatik toplama için ARMS Node.js probunu kullanın

Yalnızca model SDK çağrılarının otomatik olarak toplanmasına ihtiyacınız varsa ARMS Node.js probunu kullanın. Aşağıdaki kombinasyon Node.js 20, gerçek DashScope istekleri ve ARMS sunucu tarafı verileri ile doğrulanmıştır:

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"
# No configuration required for the default workspace; set this only for non-default workspaces
# export ARMS_WORKSPACE="<workspace>"

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

ARMS_LICENSE bir kimlik bilgisidir ve kaynak koduna, görüntülere, günlüklere veya belgelere yazılmamalıdır. Hizmet adı aynı ortam içinde benzersiz ve kararlı olmalıdır.

@loongsuite/cms_node_sdk@1.0.4 şunun için OpenAI otomatik izleme desteği bildirir: openai >=4 <6. OpenAI 6 bu desteklenen aralıkta değildir. Bir model isteği başarılı olsa bile LLM Span'lerinin oluşturulduğunu varsayamazsınız. OpenAI veya probu yükselttikten sonra sunucu tarafı doğrulamasını yeniden yapmalısınız.

Bu probun ön yükleme giriş noktası uzun süre çalışan hizmetler için tasarlanmıştır. Yeni bir hizmet ilk kez başladığında probun yapılandırma el sıkışmasını tamamlaması gerekir. CLI betikleri, tek seferlik betikler ve son derece kısa Serverless işlemleri el sıkışma veya toplu dışa aktarma işlemi bitmeden önce sonlanabilir. Tam özel hiyerarşiye veya deterministik boşaltmaya ihtiyaç duyan kısa görevler için aşağıdaki bölümdeki manuel OTLP modunu kullanın.

Prob LLM Span'lerini otomatik olarak zaten oluşturuyorsa aynı istek için startLlm() işlevini tekrar çağırmayın. Giriş, Aracı, Adım ve Araç gibi iş Span'lerine de ihtiyacınız varsa aşağıdaki manuel modu seçin ve tüm izlemeyi tek bir standart OpenTelemetry Provider ile tamamlayın.

Tam manuel izleme için yardımcı programı kullanın

Uygulama standart bir OpenTelemetry JS TracerProvider, SpanProcessor ve OTLP Exporter başlatır ve provider'ı açıkça ExtendedTelemetryHandler öğesine iletir.

Bu modda uygulama gerekli GenAI Span'lerini manuel olarak oluşturur ve çıkmadan önce forceFlush() ve shutdown() işlevlerinin tamamlanmasını bekler. Bu belgenin geri kalanı bu modu kullanır. Aşağıdaki adımları tamamlayacaksınız:

1. Bağımlılıkları yükleyin

2. Kaynak ve içerik toplama ilkesini yapılandırın

3. OpenTelemetry'yi başlatın

4. GenAI Span'leri oluşturun (Giriş, Aracı, Adım, LLM, Araç ve diğerleri)

5. Hataları yönetin ve Span'leri kapatın

6. ARMS konsolunda izleme sonuçlarını doğrulayın

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

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

Kaynak

En azından kararlı bir hizmet adı ayarlayın ve ARMS için GenAI uygulamasını ve izleme kaynağını işaretleyin:

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

acs.arms.service.feature ve gen_ai.instrumentation.sdk.name düzenli Span Öznitelikleri değil, Kaynak Öznitelikleridir. OTEL_RESOURCE_ATTRIBUTES zaten ayarlanmışsa virgülle ekleyin. service.namespace ve deployment.environment.name gibi mevcut özniteliklerin üzerine yazmayın.

Mesaj içeriği toplama

Bu bölümdeki ortam değişkenleri yalnızca yardımcı program tarafından mesaj kaydını kontrol eder. Uygulama ortam değişkenlerini ayarlamadan yardımcı programı doğrudan kullandığında mesajlar NO_CONTENT modunda işlenir; bu mod tam mesaj içeriğini toplamaz. Süreci başlatmadan önce istenen modu açıkça ayarlayın:

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

Kullanılabilir değerler:

Mesaj içeriği kişisel bilgileri, ticari sırları, ipuçlarını ve araç parametrelerini içerebilir. Bunu üretim ortamlarında etkinleştirmeden önce sansürleme, izin ve saklama süresi değerlendirmelerini tamamlayın.

@loongsuite/cms_node_sdk@1.0.4 OpenAI otomatik izlemesi probun kendi içerik toplama yapılandırmasını kullanır. Yukarıdaki yardımcı program ortam değişkenlerini kullanarak davranışını tahmin edemezsiniz. Bu sürüm varsayılan olarak OpenAI istek ve yanıt içeriğini kaydeder. İş içeriğin izlere girmesine izin vermiyorsa ve prob tarafında içerik toplamanın kapalı olduğunu onaylayamıyorsanız manuel moda geçin ve NO_CONTENT kullanın.

// 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();
}

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="<traces endpoint provided by the console>"
export OTEL_EXPORTER_OTLP_HEADERS="<authentication header provided by the console>"

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

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

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

Bağlam otomatik olarak etkinleştirilmez

startXxx() yeni Span'e karşılık gelen OTel Bağlamını invocation.contextToken içine kaydeder ancak bunu otomatik olarak context.active() olarak ayarlamaz.

Manuel alt Span'ler oluştururken üst çağrının contextToken değerini ikinci bağımsız değişken olarak iletmeniz gerekir:

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

Otomatik izlemeye sahip olabilecek bir model SDK'sını, HTTP istemcisini veya veritabanını çağırırken ilgili bağlamı etkinleştirmek için context.with() kullanmanız gerekir:

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

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

Aksi takdirde otomatik olarak oluşturulan SDK/HTTP Span'leri LLM Span'inin kardeş düğümleri haline gelebilir veya hatta ayrı bir iz oluşturabilir.

Genel öznitelikler Baggage aracılığıyla devralınır

Girişteki sessionId ve userId ile Aracıdaki agentName OTel Baggage'e yazılır. Bunların contextToken değerini üst bağlam olarak kullanarak oluşturulan sonraki GenAI Span'leri şunları devralabilir:

• gen_ai.session.id

• gen_ai.user.id

• gen_ai.agent.name

Devralma doğru üst Bağlama bağlıdır. Üst-alt ilişkisi bozulduğunda bu genel öznitelikler de eksik olabilir.

Bu belgenin neden açık başlat/durdur kullandığı

Handler ayrıca entry(), invokeAgent() ve llm() gibi geri arama tarzı arabirimler sağlar ancak bu geri arama tarzı arabirimler geri aramaları otomatik olarak yeni çağrının Bağlamı ile yürütmez.

Geri arama otomatik olarak izlenen SDK'ları çağırdığında veya çok düzeyli GenAI Span'leri oluşturması gerektiğinde bağlam sınırlarının net olması için açık startXxx(), context.with(), stopXxx()/failXxx() kalıbını kullanın.

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: "Query the weather tool first, then answer the user's question.",
  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);

Aynı OpenTelemetry Provider tarafından toplanan model SDK'sı

Bu bölüm yalnızca otomatik izleme ve yardımcı programın açıkça aynı @opentelemetry/api TracerProvider'ını paylaştığı durumlar için geçerlidir. Prob bölümünde anlatılan @loongsuite/cms_node_sdk@1.0.4 senaryosu için geçerli değildir.

Manuel bir LLM Span'i oluşturmayın. Model çağrısını yalnızca Adımın Bağlamı içinde yürütün:

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

Yayınlamadan önce tek bir model isteğinin yalnızca bir LLM Span'i ürettiğini ve otomatik LLM Span'inin parentSpanId değerinin ilgili Adımı gösterdiğini onaylayın.

LLM Span'ini manuel olarak oluşturun

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;
}

İsteği göndermeden önce LLM Span'ini durdurmayın. Aksi takdirde gecikme süresi, otomatik alt Span'ler ve hata durumu yanlış olur.

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 ?? {},
  }));
}

Model returns choice.finish_reason = "tool_calls"

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

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

const toolInv = createExecuteToolInvocation(
  toolCall.function.name,
  {
    toolCallId: toolCall.id ?? null,
    toolDescription: "Query the weather for a specified city",
    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;
}

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

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

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

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();
}

const embeddingInv = createEmbeddingInvocation(
  "text-embedding-v3",
  { provider: "dashscope" },
);
handler.startEmbedding(embeddingInv, stepInv.contextToken);
// Call the 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);

Görüntü URL girdisi

Uygulama tarafından modele gönderilen istek nesnesi ile GenAI Span'lerine yazılan mesaj nesnesi iki farklı şema kullanır. Bunları ayrı ayrı oluşturun. Aşağıdaki örnek model tarafından gerçekten alınan görüntü URL'sini kullanır, bu nedenle GenAI mesajlarında bir Uri Parçasına eşlenir:

const prompt = "Describe this image in one sentence.";
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 genel API'si mimeType kullanır. SPAN_ONLY veya SPAN_AND_EVENT modunda 0.1.0 otomatik olarak şunları oluşturur:

gen_ai.input.messages
gen_ai.input.multimodal_metadata

Her iki öznitelik de URI verileri için Şema alanı mime_type kullanır:

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

Çok modlu meta veriler yalnızca son mesajlardaki Uri Parçalarını özetler. Metin, BLOB, Base64Blob veya Dosya içermez. Araç yalnızca telemetri verilerini kaydeder; medya yüklemekten, modelleri çağırmaktan veya sağlayıcı dosya nesnelerini URI'lere dönüştürmekten sorumlu değildir.

Dosya Parçası destek sınırları

TypeScript'teki Dosya Parçası şunu kullanır:

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

Mesaj JSON'a yazıldığında fileId file_id olarak ve mimeType mime_type olarak dönüştürülür. Ancak farklı model sağlayıcılarının dosya yükleme ve dosya kimliği referans alma arayüzleri önemli ölçüde farklıdır. Bu belge Dosya Parçasını gerçek model uçtan uca doğrulaması tamamlanmış bir örnek olarak ele almaz. Uygulama bir model isteği göndermek için sağlayıcı tarafından döndürülen bir dosya kimliğini gerçekten kullandığında yalnızca Dosya Parçasını eşleyin. Alanı göstermek için sahte dosya kimlikleri oluşturmayın.

{ 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

Çevrimdışı birim testi

Testler yalnızca Span'lerin oluşturulduğunu iddia etmekle kalmamalı, ayrıca şunları da kontrol etmelidir:

• Tüm Span'ler aynı traceId'yi paylaşır.

• Aracının parentSpanId'si Girişi gösterir.

• Adımın parentSpanId'si Aracıyı gösterir.

• LLM ve Araç parentSpanId değerleri ilgili Adımı gösterir.

• Otomatik olarak oluşturulan SDK/HTTP Span'leri manuel LLM veya Araç Span'inin altındadır.

• gen_ai.session.id, gen_ai.user.id ve gen_ai.agent.name devralınır.

• LLM ve Aracı token değerleri doğrudur.

• Hem asistan araç çağrısı hem de araç yanıtı korunur.

• Çok modlu alanlar mime_type / file_id kullanır, camelCase kalıntısı yoktur.

• Çok modlu meta veriler yalnızca URI Parçalarını içerir.

• Hata zincirindeki tüm Span'ler Hata olarak işaretlenir.

Eşlik eden Demoyu indirdikten sonra şunu çalıştırın:

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

Demonun package.json dosyası bu belgede doğrulanan npm sürümlerini sabitlemelidir. Müşteriye yönelik Demolar file:../... yerel kaynak kodu yollarına bağlı olmamalıdır.

Gerçek model doğrulaması

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

Bu adım modelin, araç çağrısının ve mesaj dönüşümünün doğru olduğunu ayrı ayrı onaylamak için bellek içi bir Exporter kullanır. Modelin araç çağrısını gerçekten tamamladığını kontrol edin ve program çıktısından traceId'yi kaydedin. API anahtarlarını günlüklerde yazdırmayın.

Araç çağrısından OTLP'ye birleşik doğrulama

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

GENAI_DEMO_ALLOW_CONTENT_EXPORT=true eşlik eden Demonun güvenlik onay anahtarıdır; operatörün örnekteki tam girdi ve çıktının yapılandırılan OTLP arka ucuna gönderilebileceğini onayladığını belirtir. Verileri otomatik olarak sansürlemez. Yalnızca herkese açık, kurgusal veya zaten sansürlenmiş veriler kullanın.

Yalnızca hem forceFlush() hem de shutdown() başarılı olduğunda Demo şunu çıkarır:

export completed traceId=<trace-id>

Exporter'dan başarılı bir dışa aktarma isteği yalnızca istemcinin dışa aktarma isteğini tamamladığını kanıtlar. ARMS konsolu doğrulamasının yerine geçemez.

Konsol OTEL_EXPORTER_OTLP_TRACES_ENDPOINT sağlarsa konsol örneğinde gösterildiği gibi bu değişkeni kullanın. URL'yi kendiniz yeniden yazmayın.

Görüntü URL'sinden OTLP'ye birleşik doğrulama

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

Görüntü hassas içerik içermeyen genel bir HTTPS URL'si olmalı ve kullanıcı adları, parolalar, sorgu parametreleri, parçalar veya geçici imzalama parametreleri içermemelidir. Tam URI hem gen_ai.input.messages hem de gen_ai.input.multimodal_metadata içine yazılır.

Program gerçek model yanıtını, util.version, model adını, yanıt kimliğini, bitiş nedenini, tokenları ve traceId'yi çıkarmalıdır. Model yanıtı görüntü içeriğini yansıtmalıdır. Yalnızca HTTP 200 almak modelin görüntüyü işlediğini kanıtlamaz.

Olay Günlüğünden OTLP'ye birleşik doğrulama

Bu kullanım durumu bir modeli çağırmaz. Yalnızca Olay Günlüğü dönüşümünü, girdi/çıktı çok modlu alanlarını ve OTLP raporlamasını doğrular:

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

Program span.count=4, input.mime_type=image/png, output.mime_type=image/webp ve traceId'yi çıkarmalıdır. Sunucu ENTRY -> AGENT -> STEP -> LLM yapısını almalı ve hem gen_ai.input.multimodal_metadata hem de gen_ai.output.multimodal_metadata mevcut olmalıdır.

ARMS Node.js probu otomatik toplama doğrulaması

Bu kullanım durumu ikinci bir Provider'ın karışmasını önlemek için manuel yardımcı program Demosundan ayrı olarak yüklenir:

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"
# No configuration required for the default workspace
# export ARMS_WORKSPACE="<workspace>"

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

Eşlik eden doğrulama programı @loongsuite/cms_node_sdk@1.0.4 ve openai@5.23.2 sürümlerini sabitler. Varsayılan olarak yeni bir hizmetin ilk yapılandırma el sıkışması için 65 saniye bekler ve ardından gerçek DashScope çağrıları yapar. Zaten kayıtlı olan hizmetler için doğrulamayı kısaltmak amacıyla PROBE_WARMUP_MS=0 ayarlayın.

Sunucu en azından HTTP SERVER -> openai.chat LLM -> model HTTP CLIENT üst-alt ilişkisini göstermelidir. openai.chat Span'i şunları içermelidir:

• gen_ai.span.kind=LLM ve gen_ai.operation.name=chat

• İstek/yanıt modeli, yanıt kimliği ve bitiş nedeni

• Girdi/çıktı/toplam tokenlar

• Girdi ve çıktı mesajları (yalnızca iş içerik kaydına izin verdiğinde)

• otel.scope.name=openai, otel.scope.version=1.0.4

• telemetry.sdk.name=cms_node_sdk ve doğru service.name içeren Kaynak

Günlükler BatchSpanProcessor: span export failed, HTTP 404/403 gösteriyorsa veya hizmet ARMS'te bulunamıyorsa model 200 döndürdüğü için izlemenin başarılı olduğunu varsaymayın. Lisans, bölge, çalışma alanı ve hizmet yapılandırmasının tutarlı olduğunu onaylayın. Yeni hizmetler için ilk yapılandırma el sıkışma süresine izin verin. Kısa görevler için manuel OTLP moduna geçin.

İzleme sonuçlarını doğrulayın

ARMS konsolundaki İz Gezgini altında bulunan LLM Uygulama İzleme sayfasındaki her öğeyi çıktı traceId'sini kullanarak doğrulayın:

1. İz doğru bölge, doğru uygulama ve doğru service.name altında alınabilir.

2. Çağrı zinciri ağacı iş yürütme sırasıyla eşleşir.

3. Tek bir model isteğinde yalnızca bir LLM Span'i vardır.

4. Her GenAI Span'i doğru gen_ai.span.kind ve gen_ai.operation.name değerine sahiptir.

5. LLM gen_ai.request.model, girdi/çıktı/toplam tokenları içerir.

6. Aracı tokenları içerdiği model çağrılarının toplamına eşittir.

7. Araç ad, çağrı kimliği, bağımsız değişkenler ve sonuç içerir.

8. İçerik toplama etkinleştirildiğinde ikinci tur LLM girdisi hem araç çağrısını hem de araç yanıtını içerir.

9. Giriş, Aracı, Adım, LLM ve Araç oturum/kullanıcı/aracı genel özniteliklerine sahiptir.

10. Başarısızlık durumunda açık kalan tüm Span'ler Hata olarak işaretlenir.

11. Görüntü doğrulamasında gen_ai.input.messages type=uri, mime_type, modality ve gerçek bir URL içerir.

12. gen_ai.input.multimodal_metadata bir JSON dizisidir ve yalnızca URI Parçalarını özetler.

13. Olay Günlüğü doğrulamasında gen_ai.output.messages ve gen_ai.output.multimodal_metadata çıktı URI'lerini içerir ve mime_type kullanır.

14. Mesaj JSON'ında ve meta verilerde kalan mimeType / fileId yoktur.

15. otel.scope.version gerçekten yüklenen npm sürümüyle eşleşir.

16. Kaynak service.name, acs.arms.service.feature=genai_app ve gen_ai.instrumentation.sdk.name=loongsuite-genai-utils içerir.

Web sitesi örnek bakıcısı ayrıca aynı npm sürümleriyle Node.js 20 ve 22 üzerinde temiz dizinlerde ayrı ayrı doğrulama yapmalıdır. Sunucu tarafı sorgulama tamamlanmadığında, yerel kaynak kodu hala kullanıldığında veya sürümler tutarsız olduğunda örnekler doğrulanmış olarak işaretlenmemelidir.

ARMS'te hiç veri yok

• Uç noktanın, bölgenin ve kimlik doğrulama üstbilgisinin aynı uygulamadan olduğunu doğrulayın.

• service.name değerini doğrulayın.

• ConsoleSpanExporter yerine bir OTLP Exporter kullandığınızı onaylayın.

• Süreç çıkmadan önce forceFlush() ve shutdown() çağrıldığını onaylayın.

• Exporter hata günlüğünü ve ağ gidiş trafiğini kontrol edin.

ARMS Node.js probu kullanırken ayrıca ARMS_LICENSE, ARMS_REGION_ID, ARMS_WORKSPACE ve CMS_SERVICE_NAME değerlerini kontrol edin. Yeni bir hizmetin ilk başlatılması için yapılandırma el sıkışma süresine izin verin. Model çağrısı başarılı olsa bile exporter 404/403 hatası alınıyorsa bu yine de bir raporlama hatasıdır.

ARMS probu altında LLM Span'i yok

• Node.js başlatma bağımsız değişkenlerinin -r @loongsuite/cms_node_sdk/register içerdiğini ve probun openai öncesinde yüklendiğini onaylayın.

• @loongsuite/cms_node_sdk@1.0.4 yalnızca openai >=4 <6 desteğini bildirir. OpenAI 6 doğrulanan aralıkta değildir.

• Başlatma günlüğünün openai izlemesini listeleyip listelemediğini kontrol edin.

• Yalnızca model yanıtına bakarak değil ARMS sunucu tarafı verileriyle onaylayın.

Yardımcı program Span'leri dışa aktarmıyor

@loongsuite/cms_node_sdk@1.0.4 standart @opentelemetry/api Provider'ını kaydetmez ve varsayılan Handler tarafından doğrudan yeniden kullanılamaz. İki yaklaşımı karıştırmayın. Yardımcı programa ihtiyacınız olduğunda başlatma bölümüne göre standart bir OpenTelemetry Provider ve OTLP Exporter başlatın.

Aynı model çağrısı için iki LLM Span'i

Bu genellikle model SDK'sının otomatik izleme tarafından zaten toplandığını ve işin ayrıca startLlm() çağırdığını gösterir. Aynı Provider içinde yalnızca bir tür LLM izlemesi tutun. @loongsuite/cms_node_sdk@1.0.4 ve yardımcı program izleme modu bölümüne göre tamamen ayrılmalıdır.

Span'ler aynı izdedir ancak hiyerarşi yanlıştır

• Manuel alt Span'lerin açıkça üst contextToken geçirip geçirmedığını kontrol edin.

• Otomatik olarak izlenen işlemlerin context.with() içinde yürütülüp yürütülmediğini kontrol edin.

• Kodun AsyncLocalStorage Bağlamını doğru şekilde yaymayan özel eşzamansız sınırları aşıp aşmadığını kontrol edin.

Alt Span'lerde oturum, kullanıcı veya aracı eksik

Giriş/Aracının ilgili alanları ayarlayıp ayarlamadığını kontrol edin ve alt Span'lerin üst çağrının contextToken değerini kullandığını onaylayın.

Girdi ve çıktı mesajları görünmüyor

Ortam değişkenlerinin Node.js süreci başlamadan önce ayarlandığını onaylayın:

OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY

Ardından mesaj dönüşüm sonucunun { role, parts } yapısına uyup uymadığını kontrol edin.

Görüntü mesajları mevcut ancak çok modlu meta veri yok

• Yüklenen sürümün bu belgeden doğrulanmış sürüm 0.1.0 olduğunu onaylayın. Sonraki sürümleri kullanırken tam doğrulamayı yeniden çalıştırın.

• İçerik toplama modunun SPAN_ONLY veya SPAN_AND_EVENT olduğunu onaylayın.

• Meta veriler yalnızca type: "uri" Parçalarını özetler, BLOB, Base64Blob veya Dosya içermez.

• TypeScript API'sini doğrudan çağırırken mimeType, modality ve uri değerlerini kontrol edin.

• Olay Günlüğü girdisi için Şema alanları mime_type, modality ve uri değerlerini kontrol edin.

• invocation.attributes değerinin otomatik olarak oluşturulan özniteliklerin üzerine açıkça yazıp yazmadığını kontrol edin.

Dosya Parçası çok modlu meta verilerde görünmüyor

Bu beklenen bir davranıştır. Dosya Parçası mesaj JSON'da korunur ve fileId değerini file_id olarak serileştirir ancak URI meta verileri yalnızca Uri Parçalarını özetler. Sağlayıcının gerçek isteği bir dosya kimliği kullandığında yalnızca Dosya Parçasını kaydedin.

Yükleme sırasında eş bağımlılık hataları

Projenin OpenTelemetry SDK 1.x ve 2.x'i karıştırıp karıştırmadığını kontrol edin. Bu belgedeki doğrulanan kombinasyon API 1.9.1, trace/resources 1.30.1 ve OTLP exporter 0.57.2'dir.

Kısa görevlerde aralıklı Span kaybı

Manuel OTLP modunda doğal süreç çıkışına güvenmeyin. CLI betikleri, Serverless işleyicileri ve test programları açıkça forceFlush()/shutdown() beklemelidir.

@loongsuite/cms_node_sdk/register sinyal işleme SIGINT/SIGTERM'de kapatmayı yürütür ancak yeni hizmetler yine de ilk yapılandırma el sıkışmasına ihtiyaç duyar. Son derece kısa görevler için yaşam döngüsünü açıkça kontrol edebileceğiniz manuel OTLP modunu tercih edin.