Grafana Sigil 类型脚本/ JavaScript SDK
Sigil 记录 正常 LLM 生成和工具执行 遥测 使用您的 OpenTelemetrime tracker/ meter 设置 .
安装
pnpm add @grafana/sigil-sdk-js
对于只需要核心的低依赖性运行时间 SigilClient 生成导出 API,使用瘦芯包 :
pnpm add @grafana/sigil-sdk-js-core
对于Grafana Cloud 设置的走过(在哪里找到端点 URL, 例如 ID, 和 API 令牌), 指的是 Grafana 云设置指南。 。 。 .
验证
从 repo 根运行 JavaScript SDK 共享核心兼容套件 :
mise run test:ts:sdk-conformance
从 repo 根运行跨语言集合核心相容套件 :
mise run sdk:conformance
快速启动
下面的片段明确配置了SDK. 作为替代方案,设置 SIGIL_* 环境变量和呼叫 new SigilClient() 没有任何论据——参见: Grafana 云设置指南 用于变量名称.
import { SigilClient } from "@grafana/sigil-sdk-js";
const client = new SigilClient({
generationExport: {
protocol: "http",
endpoint: "https://sigil-prod-<region>.grafana.net",
auth: {
mode: "basic",
tenantId: process.env.SIGIL_AUTH_TENANT_ID,
basicPassword: process.env.SIGIL_AUTH_TOKEN,
},
},
api: {
endpoint: "https://sigil-prod-<region>.grafana.net",
},
});
await client.startGeneration(
{
conversationId: "conv-1",
model: { provider: "openai", name: "gpt-5" },
},
async (recorder) => {
const outputText = "Hello from model";
recorder.setResult({
output: [{ role: "assistant", content: outputText }],
});
}
);
await client.shutdown();
内容抓取
contentCapture 控制SDK在输出的生成有效载荷和OTel的属性中包含的内容。 见 内容抓取模式 用于 Cononical 模式矩阵和默认; 下面的片段显示如何在 TypeScript 中将其接线.
客户端级别默认 :
import { SigilClient } from "@grafana/sigil-sdk-js";
const client = new SigilClient({
contentCapture: "metadata_only",
});
SDK 核心客户端处理 "default" 作为 "no_tool_content":生成内容被捕获,但工具执行参数和结果不超出范围.
每代覆盖 :
await client.startGeneration(
{
model: { provider: "openai", name: "gpt-5" },
contentCapture: "full",
},
async (recorder) => {
recorder.setResult({ output: [{ role: "assistant", content: "hi" }] });
}
);
每个工具执行覆盖( 这里) "full" 选择获取工具参数和跨度结果 :
await client.startToolExecution(
{ toolName: "search", contentCapture: "full" },
async (recorder) => {
recorder.setResult({ arguments: { q: "weather" }, result: { tempC: 18 } });
}
);
动态分辨率通过 contentCaptureResolver数字 :
const client = new SigilClient({
contentCaptureResolver: (metadata) => {
if (metadata?.["sigil.tenant"] === "healthcare") {
return "metadata_only";
}
return "default"; // defer to `contentCapture`
},
});
解析器接收录制的元数据(或 undefined 用于记录没有元数据的类型,如工具执行)。 丢出的错误被抓住并当作 "metadata_only" (失闭.
分辨率优先( 最高至最低) :
- 每集记录
contentCapture打开GenerationStart编号 :ToolExecutionStart contentCaptureResolver返回值- 客户一级
contentCapture(违约)"no_tool_content"(中文(简体) )
与"去","Python","Java"和"NET SDK"不同,JS SDK没有通过Async上下文来传播解析的捕捉模式,因此在一代块内开始的工具执行不会自动地继承一代模式. 设定 contentCapture 每个 ToolExecutionStart 当您需要工具来遵循非违约政策时.
用户提供 metadata 财务报告和审定财务报表 tags 不被任何捕获模式剥离。 SDK-内部元数据密钥,包含内容(例如. call_error, (中文(简体) ), sigil.conversation.title)与匹配内容一起剥去。 见 标记和元数据 用于客户端标签、每代标签、元数据以及 userId 每个显示( export vs 跨度 vs 度量衡) .
提醒前编辑
使用 generationSanitizer 当您想要编辑以前正常世代的子字符串时
验证、 跨度同步、 调试快照和导出 .
import {
SigilClient,
createSecretRedactionSanitizer,
} from "@grafana/sigil-sdk-js";
const client = new SigilClient({
generationSanitizer: createSecretRedactionSanitizer({
redactInputMessages: false, // omit to fall back to SIGIL_REDACT_INPUT_MESSAGES, then false
redactEmailAddresses: true,
}),
});
内置消毒器:
- 编辑助理文本和思维中的高度自信秘密格式
- 编辑工具调用输入和工具结果中的秘密格式外加 env 风格的秘密值
- 默认编辑电子邮件地址
- 除非启用输入编辑,否则用户输入保持不变
要保存电子邮件地址, 请明确选择退出 :
const client = new SigilClient({
generationSanitizer: createSecretRedactionSanitizer({
redactEmailAddresses: false,
}),
});
通过环境变量配置编辑
createSecretRedactionSanitizer() 读取 SIGIL_REDACT_INPUT_MESSAGES 联合国
1/0, (中文(简体) ), true/false, (中文(简体) ), yes/no, (中文(简体) ), on/off当 redactInputMessages 省略.
优先是明确的选项 > env var > false未识别的嵌入值是
警告并倒回下一层, 所以打字不能静地翻转
编辑.
import {
createSecretRedactionSanitizer,
SigilClient,
} from "@grafana/sigil-sdk-js";
// Omit redactInputMessages so SIGIL_REDACT_INPUT_MESSAGES decides.
const client = new SigilClient({
generationSanitizer: createSecretRedactionSanitizer(),
});
虎克和卫兵
在LLM呼叫前要用钩子来操作西吉尔守卫规则. SDK评估您请求路径上的钩子; Grafana Cloud 配置的守护规则决定是允许,拒绝,还是转换输入.
虎克默认被禁用. 启用客户端并拨打 evaluateHook(...) 在提供者提出请求之前:
import { HookDeniedError, SigilClient } from "@grafana/sigil-sdk-js";
const client = new SigilClient({
hooks: { enabled: true, phases: ["preflight"], timeoutMs: 15_000, failOpen: true },
});
let messages = [{ role: "user" as const, content: "Summarize this customer note..." }];
const response = await client.evaluateHook({
phase: "preflight",
context: {
agentName: "support-agent",
agentVersion: "1.0.0",
model: { provider: "openai", name: "gpt-5" },
},
input: {
messages,
systemPrompt: "You are a helpful support agent.",
conversationPreview: "Summarize this customer note...",
},
});
if (response.action === "deny") {
throw new HookDeniedError(response.reason ?? "", response.ruleId, response.evaluations);
}
messages = response.transformedInput?.messages ?? messages;
与 failOpen: true,钩子运输错误的解决 允许一个没有评估者不会阻断生产流量。 设定 failOpen: false 用于关闭的严格路径.
如果您使用已转换的输入, 请将已转换的信件/系统提示传递给提供者, 并将相同的值记录在 startGeneration(...)。如果您使用 Vercel AI SDK 适配器,请参见 docs/frameworks/vercel-ai-sdk.md 用于自动飞行前接线.
在您的应用程序 OTEL SDK 设置中配置 OTEL 导出器( 追踪/ 测量) 。 你可以选择通过 tracer 财务报告和审定财务报表 meter 直接转到 SigilClient。 。 。 .
在创建 Sigil 客户端前快速 OTEL 设置模式 :
import { NodeSDK } from "@opentelemetry/sdk-node";
const otel = new NodeSDK();
await otel.start();
核心 API
startGeneration(...)财务报告和审定财务报表startStreamingGeneration(...)startToolExecution(...)- 记录方法 :
setResult(...), (中文(简体) ),setCallError(...), (中文(简体) ),end(), (中文(简体) ),getError() - 生命周期 :
flush(), (中文(简体) ),shutdown()
手动 try/finally 样式
const recorder = client.startGeneration({
model: { provider: "anthropic", name: "claude-sonnet-4-5" },
});
try {
recorder.setResult({
output: [{ role: "assistant", content: "Done" }],
});
} catch (error) {
recorder.setCallError(error);
throw error;
} finally {
recorder.end();
}
嵌入可观察性
使用 startEmbedding(...) 用于嵌入 API 调用。 嵌入式记录只创建OTel跨度和SDK度量衡,不为生成输出定序.
await client.startEmbedding(
{
agentName: "retrieval-worker",
agentVersion: "1.0.0",
model: { provider: "openai", name: "text-embedding-3-small" },
},
async (recorder) => {
const response = await openai.embeddings.create(request);
recorder.setResult({
inputCount: request.input.length,
inputTokens: response.usage?.prompt_tokens ?? 0,
inputTexts: request.input,
responseModel: response.model,
});
}
);
输入文本抓取为选入 :
const client = new SigilClient({
embeddingCapture: {
captureInput: true,
maxInputItems: 20,
maxTextLength: 1024,
},
});
embeddingCapture.captureInput 可能以跨度显示PII/文件内容。 默认情况下保留其禁用并仅允许用于范围调试.
TrackQL 示例 :
traces{gen_ai.operation.name="embeddings"}traces{gen_ai.operation.name="embeddings" && gen_ai.request.model="text-embedding-3-small"}traces{gen_ai.operation.name="embeddings" && error.type!=""}
工具执行示例
await client.startToolExecution(
{
toolName: "weather",
includeContent: true,
},
async (recorder) => {
recorder.setResult({
arguments: { city: "Paris" },
result: { temp_c: 18 },
});
}
);
提供者助手
- 打开AI :
docs/providers/openai.md - 安东尼:
docs/providers/anthropic.md - 双子座:
docs/providers/gemini.md
框架处理器
使用模块子路径导出用于框架召回集成 :
- 兰彩:
@grafana/sigil-sdk-js/langchain - 兰格:
@grafana/sigil-sdk-js/langgraph - OpenAI 代理 :
@grafana/sigil-sdk-js/openai-agents - 拉玛因德克斯:
@grafana/sigil-sdk-js/llamaindex - Google ADK: (英语)
@grafana/sigil-sdk-js/google-adk - Vercel AI SDK: (中文(简体) )
@grafana/sigil-sdk-js/vercel-ai-sdk - 特工队:
@grafana/sigil-sdk-js/strands - 兰彩指南:
docs/frameworks/langchain.md - LangGraph 向导 :
docs/frameworks/langgraph.md - OpenAI 代理指南 :
docs/frameworks/openai-agents.md - LlamaIndex 指南 :
docs/frameworks/llamaindex.md - 谷歌 ADK 指南 :
docs/frameworks/google-adk.md - Vercel AI SDK指南:
docs/frameworks/vercel-ai-sdk.md - Strands 代理指南 :
docs/frameworks/strands.md
import { SigilClient } from "@grafana/sigil-sdk-js";
import { withSigilLangChainCallbacks } from "@grafana/sigil-sdk-js/langchain";
import { withSigilLangGraphCallbacks } from "@grafana/sigil-sdk-js/langgraph";
import { withSigilOpenAIAgentsHooks } from "@grafana/sigil-sdk-js/openai-agents";
import { withSigilLlamaIndexCallbacks } from "@grafana/sigil-sdk-js/llamaindex";
import { withSigilGoogleAdkPlugins } from "@grafana/sigil-sdk-js/google-adk";
import { createSigilVercelAiSdk } from "@grafana/sigil-sdk-js/vercel-ai-sdk";
import { withSigilStrandsHooks } from "@grafana/sigil-sdk-js/strands";
import { Runner } from "@openai/agents";
import { CallbackManager } from "llamaindex";
const client = new SigilClient();
const langChainConfig = withSigilLangChainCallbacks(undefined, client, { providerResolver: "auto" });
const langGraphConfig = withSigilLangGraphCallbacks(undefined, client, { providerResolver: "auto" });
const runner = new Runner();
const openAIAgentsHooks = withSigilOpenAIAgentsHooks(runner, client, { providerResolver: "auto" });
const callbackManager = new CallbackManager();
const llamaIndexConfig = withSigilLlamaIndexCallbacks({ callbackManager }, client, { providerResolver: "auto" });
const googleAdkRunnerConfig = withSigilGoogleAdkPlugins(undefined, client, { providerResolver: "auto" });
const vercelAiSdk = createSigilVercelAiSdk(client, { agentName: "vercel-agent" });
const strandsConfig = withSigilStrandsHooks(undefined, client, { conversationId: "chat-123" });
框架处理器使用 SigilClient 假设你通过。 如果客户端配置为
generationSanitizer,同样的编辑政策自动适用于记录的世代
通过LangChain,LangGraph,OpenAI Agents,LlamaIndex,Google ADK,和Vercel AI SDK集成.
同样的编辑政策也适用于斯特兰德斯代理世代.
每个框架处理器注入:
sigil.framework.name(单位:千美元)langchain, (中文(简体) ),langgraph, (中文(简体) ),openai-agents, (中文(简体) ),llamaindex, (中文(简体) ),google-adk, (中文(简体) ),vercel-ai-sdk,或strands(中文(简体) )sigil.framework.source(单位:千美元)handler对于现有的召回处理器,framework对于Vercel AI SDK钩,hooks用于 Strands )sigil.framework.language(单位:千美元)javascript对于现有的召回处理器,typescript为 Vercel AI SDK 和 Strands 钩)metadata["sigil.framework.run_id"]metadata["sigil.framework.thread_id"](当有)metadata["sigil.framework.parent_run_id"](如有)metadata["sigil.framework.component_name"]metadata["sigil.framework.run_type"]metadata["sigil.framework.tags"]metadata["sigil.framework.retry_attempt"](如有)metadata["sigil.framework.event_id"](如有)metadata["sigil.framework.langgraph.node"](可用时 LangGraph)
对话绘图是对话的第一:
conversation_id编号 :session_id编号 :group_id从框架上下文- 接下来
thread_id - 决定性倒计时
sigil:framework:<framework_name>:<run_id>
当生成元数据中存在时,低心力框架密钥被复制到生成跨属性上.
对LangGraph的坚持,通过 configurable.thread_id 并反复使用它
const threadConfig = {
...withSigilLangGraphCallbacks(undefined, client, { providerResolver: "auto" }),
configurable: { thread_id: 'customer-42' },
};
await graph.invoke({ prompt: 'Remember my timezone is UTC+1.', answer: '' }, threadConfig);
await graph.invoke({ prompt: 'What timezone did I give you?', answer: '' }, threadConfig);
行为
- 生成模式是明确的:
SYNC财务报告和审定财务报表STREAM。 。 。 . - 生成导出支持 HTTP, gRPC, 以及
none(仅以文书为主. - 追踪/测量使用
config.tracer编号 :config.meter提供,否则 OTEL 全球. - 导出与被限制的队列和重试/后退同步 .
flush()排出排队的世代;shutdown()冲洗并关闭世代出口商.- 空工具名会生成一个禁用工具记录器.
- 生成/工具跨度总是包括 SDK 身份属性:
sigil.sdk.name=sdk-js
- 常态化生成元数据总是包括相同的SDK身份密钥;相冲突的调用器值被覆盖.
- 原始提供者的文物选入(
rawArtifacts: true) (中文(简体) ).
只使用仪器模式( 没有生成发送)
设定 generationExport.protocol 改为 "none" 保持生成/工具的仪器和跨度,同时使生成运输失效.
const client = new SigilClient({
generationExport: {
protocol: "none",
},
});
SDK 度量衡
SDK通过您配置的 OTL 测量器提供商 来发布这些 OTel 直方图 :
gen_ai.client.operation.durationgen_ai.client.token.usagegen_ai.client.time_to_first_tokengen_ai.client.tool_calls_per_operation
生成导出认证模式
Auth 配置为 generationExport。 。 。 .
mode: "none"mode: "tenant"(所需经费)tenantId输入X-Scope-OrgID(中文(简体) )mode: "bearer"(所需经费)bearerToken输入Authorization: Bearer <token>(中文(简体) )mode: "basic"(所需经费)basicPassword+ 键basicUser或者说tenantId输入Authorization: Basic <base64(user:password)>; 还注入X-Scope-OrgID何时tenantId设定——仅用于多租户部署,格拉法纳云不需要)
在客户端配置解析时丢出无效的模式/字段组合 .
如果已包含明确的信头 Authorization 或者说 X-Scope-OrgID,明确标题优先.
const client = new SigilClient({
generationExport: {
protocol: "http",
endpoint: "https://sigil-prod-<region>.grafana.net",
auth: {
mode: "basic",
tenantId: process.env.SIGIL_AUTH_TENANT_ID,
basicPassword: process.env.SIGIL_AUTH_TOKEN,
},
},
api: {
endpoint: "https://sigil-prod-<region>.grafana.net",
},
});
Grafana Cloud auth( 基础) :
对于格拉法纳云,使用 basic 认证模式 。 用户名是您的 Grafana Cloud 实例/租户 ID 密码是您的 Grafana Cloud API 密钥 。 见 Grafana Cloud AI 开始观察文件 用于完整的设置步骤; 对于 SDK 端点, 复制 API 網址 从 Observation → AI observation → 配置看起来像 https://sigil-prod-<region>.grafana.net。 。 。 .
const client = new SigilClient({
generationExport: {
protocol: "http",
endpoint: "https://sigil-prod-<region>.grafana.net",
auth: {
mode: "basic",
tenantId: process.env.SIGIL_AUTH_TENANT_ID,
basicPassword: process.env.SIGIL_AUTH_TOKEN,
},
},
});
如果您的部署需要不同的用户名, 设置 basicUser 明确:
auth: {
mode: "basic",
tenantId: process.env.SIGIL_AUTH_TENANT_ID,
basicUser: process.env.SIGIL_AUTH_TENANT_ID,
basicPassword: process.env.SIGIL_AUTH_TOKEN,
},
连接自定义环境 vars
SDK 只自动装入 SIGIL_* (原始内容存档于2013-10-12) (中文(简体) ). env vars (nSIGIL_ENDPOINT, (中文(简体) ), SIGIL_PROTOCOL, (中文(简体) ), SIGIL_AUTH_MODE, (中文(简体) ), SIGIL_AUTH_TOKEN当您打电话时 new SigilClient()。对于任何其他的 env var(例如您的秘密管理者以不同名称曝光的),请在您的应用程序中读取,并将值传递到配置中:
const generationBearerToken = (process.env.MY_APP_SIGIL_TOKEN ?? "").trim();
const client = new SigilClient({
generationExport: {
protocol: "http",
endpoint: "https://sigil-prod-<region>.grafana.net",
auth:
generationBearerToken.length > 0
? { mode: "bearer", bearerToken: generationBearerToken }
: {
mode: "basic",
tenantId: process.env.SIGIL_AUTH_TENANT_ID,
basicPassword: process.env.SIGIL_AUTH_TOKEN,
},
},
api: {
endpoint: "https://sigil-prod-<region>.grafana.net",
},
});
共同地貌学:
- 格拉法纳云:一代人
basic模式,带有实例 ID 和 API 密钥. - 自办直通西吉尔:一代
tenant模式. - 通过 OTEL 收集器/合金进行追踪/测量:在您的应用程序 OTEL SDK 设置中配置出口商.
- 企业代理: 生成
bearer模式到代理;代理认证和向上转发租户头.
对话评分
使用 SDK 帮助提交用户化的收视率 :
const result = await client.submitConversationRating("conv-123", {
ratingId: "rat-123",
rating: "CONVERSATION_RATING_VALUE_BAD",
comment: "Answer ignored user context",
metadata: { channel: "assistant-ui" },
source: "sdk-js",
});
console.log(result.rating.rating, result.summary.hasBadRating);
submitConversationRating 向 api.endpoint,它应该是来自AI可观察性配置的Grafana Cloud Sigil API URL,并使用SDK客户端已经配置的同一代导出认证头.