@grafana/sigil-sdk-js

中文文档
0.8.2发布于 2026/07/16Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 9085

Sigil records normalized LLM generation and tool-execution telemetry using your OpenTelemetry tracer/meter setup.

此软件包已被标记为弃用

Renamed to @grafana/agento11y. See https://grafana.com/docs/grafana-cloud/machine-learning/agent-observability/guides/migrate-sigil-sdk-to-agento11y/

原始使用文档
文档目录20 节
  1. Installation
  2. Validation
  3. Quick Start
  4. Content Capture
  5. Pre-Ingest Redaction
  6. Configuring redaction via environment variables
  7. Hooks and Guards
  8. Core API
  9. Manual try/finally style
  10. Embedding Observability
  11. Tool Execution Example
  12. Provider Helpers
  13. Framework Handlers
  14. Behavior
  15. Instrumentation-only mode (no generation send)
  16. SDK metrics
  17. Generation export auth modes
  18. Grafana Cloud auth (basic)
  19. Wiring custom env vars
  20. Conversation Ratings

Grafana Sigil TypeScript/JavaScript SDK

Sigil records normalized LLM generation and tool-execution telemetry using your OpenTelemetry tracer/meter setup.

Installation

pnpm add @grafana/sigil-sdk-js

For low-dependency runtimes that only need the core SigilClient and generation export APIs, use the slim core package:

pnpm add @grafana/sigil-sdk-js-core

For a Grafana Cloud setup walkthrough (where to find the endpoint URL, instance ID, and API token), refer to the Grafana Cloud setup guide.

Validation

Run the shared core conformance suite for the JavaScript SDK from the repo root:

mise run test:ts:sdk-conformance

Run the cross-language aggregate core conformance suite from the repo root:

mise run sdk:conformance

Quick Start

The snippet below configures the SDK explicitly. As an alternative, set SIGIL_* environment variables and call new SigilClient() with no arguments — refer to the Grafana Cloud setup guide for the variable names.

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

Content Capture

contentCapture controls what content the SDK includes in exported generation payloads and OTel span attributes. See Content Capture Modes for the canonical mode matrix and defaults; the snippets below show how to wire it up in TypeScript.

Client-level default:

import { SigilClient } from "@grafana/sigil-sdk-js";

const client = new SigilClient({
  contentCapture: "metadata_only",
});

The core SDK client treats "default" as "no_tool_content": generation content is captured but tool-execution arguments and results stay out of spans.

Per-generation override:

await client.startGeneration(
  {
    model: { provider: "openai", name: "gpt-5" },
    contentCapture: "full",
  },
  async (recorder) => {
    recorder.setResult({ output: [{ role: "assistant", content: "hi" }] });
  }
);

Per-tool-execution override (here "full" opts into capturing tool arguments and results in the span):

await client.startToolExecution(
  { toolName: "search", contentCapture: "full" },
  async (recorder) => {
    recorder.setResult({ arguments: { q: "weather" }, result: { tempC: 18 } });
  }
);

Dynamic resolution via contentCaptureResolver:

const client = new SigilClient({
  contentCaptureResolver: (metadata) => {
    if (metadata?.["sigil.tenant"] === "healthcare") {
      return "metadata_only";
    }
    return "default"; // defer to `contentCapture`
  },
});

The resolver receives the recording's metadata (or undefined for recording types that have no metadata, like tool executions). Thrown errors are caught and treated as "metadata_only" (fail-closed).

Resolution precedence (highest to lowest):

  1. Per-recording contentCapture on GenerationStart / ToolExecutionStart
  2. contentCaptureResolver return value
  3. Client-level contentCapture (defaults to "no_tool_content")

Unlike the Go, Python, Java, and .NET SDKs, the JS SDK does not propagate the resolved capture mode through async context, so tool executions started inside a generation block do not automatically inherit the generation's mode. Set contentCapture on each ToolExecutionStart when you need a tool to follow a non-default policy.

User-provided metadata and tags are not stripped by any capture mode. SDK-internal metadata keys that carry content (e.g. call_error, sigil.conversation.title) are stripped along with the matching content. See Tags and Metadata for where client tags, per-generation tags, metadata, and userId each show up (export vs spans vs metrics).

Pre-Ingest Redaction

Use generationSanitizer when you want to redact substrings from normalized generations before validation, span sync, debug snapshots, and export.

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

The built-in sanitizer:

  • redacts high-confidence secret formats in assistant text and thinking
  • redacts secret formats plus env-style secret values in tool call inputs and tool results
  • redacts email addresses by default
  • leaves user input unchanged unless input redaction is enabled

To preserve email addresses, opt out explicitly:

const client = new SigilClient({
  generationSanitizer: createSecretRedactionSanitizer({
    redactEmailAddresses: false,
  }),
});

Configuring redaction via environment variables

createSecretRedactionSanitizer() reads SIGIL_REDACT_INPUT_MESSAGES (accepts 1/0, true/false, yes/no, on/off) when redactInputMessages is omitted. Precedence is explicit option > env var > false. An unrecognised env value is warned and falls back to the next layer, so a typo cannot silently flip redaction.

import {
  createSecretRedactionSanitizer,
  SigilClient,
} from "@grafana/sigil-sdk-js";

// Omit redactInputMessages so SIGIL_REDACT_INPUT_MESSAGES decides.
const client = new SigilClient({
  generationSanitizer: createSecretRedactionSanitizer(),
});

Hooks and Guards

Use hooks when you want Sigil guard rules to run before an LLM call. The SDK evaluates the hook on your request path; guard rules configured in Grafana Cloud decide whether to allow, deny, or transform the input.

Hooks are disabled by default. Enable them on the client and call evaluateHook(...) before the provider request:

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;

With failOpen: true, hook transport errors resolve to allow so an unavailable evaluator does not block production traffic. Set failOpen: false for strict paths that should fail closed.

If you use transformed input, pass the transformed messages/system prompt to the provider and record those same values in startGeneration(...). If you use the Vercel AI SDK adapter, see docs/frameworks/vercel-ai-sdk.md for automatic preflight hook wiring.

Configure OTEL exporters (traces/metrics) in your application OTEL SDK setup. You can optionally pass tracer and meter directly to SigilClient.

Quick OTEL setup pattern before creating the Sigil client:

import { NodeSDK } from "@opentelemetry/sdk-node";

const otel = new NodeSDK();
await otel.start();

Core API

  • startGeneration(...) and startStreamingGeneration(...)
  • startToolExecution(...)
  • Recorder methods: setResult(...), setCallError(...), end(), getError()
  • Lifecycle: flush(), shutdown()

Manual try/finally style

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

Embedding Observability

Use startEmbedding(...) for embedding API calls. Embedding recording creates OTel spans and SDK metrics only, and does not enqueue generation exports.

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

Input text capture is opt-in:

const client = new SigilClient({
  embeddingCapture: {
    captureInput: true,
    maxInputItems: 20,
    maxTextLength: 1024,
  },
});

embeddingCapture.captureInput may expose PII/document content in spans. Keep it disabled by default and enable it only for scoped debugging.

TraceQL examples:

  • 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!=""}

Tool Execution Example

await client.startToolExecution(
  {
    toolName: "weather",
    includeContent: true,
  },
  async (recorder) => {
    recorder.setResult({
      arguments: { city: "Paris" },
      result: { temp_c: 18 },
    });
  }
);

Provider Helpers

  • OpenAI: docs/providers/openai.md
  • Anthropic: docs/providers/anthropic.md
  • Gemini: docs/providers/gemini.md

Framework Handlers

Use module subpath exports for framework callback integrations:

  • LangChain: @grafana/sigil-sdk-js/langchain
  • LangGraph: @grafana/sigil-sdk-js/langgraph
  • OpenAI Agents: @grafana/sigil-sdk-js/openai-agents
  • LlamaIndex: @grafana/sigil-sdk-js/llamaindex
  • Google ADK: @grafana/sigil-sdk-js/google-adk
  • Vercel AI SDK: @grafana/sigil-sdk-js/vercel-ai-sdk
  • Strands Agents: @grafana/sigil-sdk-js/strands
  • LangChain guide: docs/frameworks/langchain.md
  • LangGraph guide: docs/frameworks/langgraph.md
  • OpenAI Agents guide: docs/frameworks/openai-agents.md
  • LlamaIndex guide: docs/frameworks/llamaindex.md
  • Google ADK guide: docs/frameworks/google-adk.md
  • Vercel AI SDK guide: docs/frameworks/vercel-ai-sdk.md
  • Strands Agents guide: 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" });

Framework handlers use the SigilClient instance you pass in. If that client is configured with generationSanitizer, the same redaction policy applies automatically to generations recorded through LangChain, LangGraph, OpenAI Agents, LlamaIndex, Google ADK, and Vercel AI SDK integrations. The same redaction policy also applies to Strands Agents generations.

Each framework handler injects:

  • sigil.framework.name (langchain, langgraph, openai-agents, llamaindex, google-adk, vercel-ai-sdk, or strands)
  • sigil.framework.source (handler for existing callback handlers, framework for Vercel AI SDK hooks, hooks for Strands)
  • sigil.framework.language (javascript for existing callback handlers, typescript for Vercel AI SDK and Strands hooks)
  • metadata["sigil.framework.run_id"]
  • metadata["sigil.framework.thread_id"] (when present)
  • metadata["sigil.framework.parent_run_id"] (when available)
  • metadata["sigil.framework.component_name"]
  • metadata["sigil.framework.run_type"]
  • metadata["sigil.framework.tags"]
  • metadata["sigil.framework.retry_attempt"] (when available)
  • metadata["sigil.framework.event_id"] (when available)
  • metadata["sigil.framework.langgraph.node"] (LangGraph when available)

Conversation mapping is conversation-first:

  • conversation_id / session_id / group_id from framework context first
  • then thread_id
  • deterministic fallback sigil:framework:<framework_name>:<run_id>

When present in generation metadata, low-cardinality framework keys are copied onto generation span attributes.

For LangGraph persistence, pass configurable.thread_id and reuse it across invocations:

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

Behavior

  • Generation modes are explicit: SYNC and STREAM.
  • Generation export supports HTTP, gRPC, and none (instrumentation-only).
  • Traces/metrics use config.tracer/config.meter when provided, otherwise OTEL globals.
  • Exports are asynchronous with bounded queueing and retry/backoff.
  • flush() drains queued generations; shutdown() flushes and closes generation exporters.
  • Empty tool names produce a no-op tool recorder.
  • Generation/tool spans always include SDK identity attributes:
    • sigil.sdk.name=sdk-js
  • Normalized generation metadata always includes the same SDK identity key; conflicting caller values are overwritten.
  • Raw provider artifacts are opt-in (rawArtifacts: true).

Instrumentation-only mode (no generation send)

Set generationExport.protocol to "none" to keep generation/tool instrumentation and spans while disabling generation transport.

const client = new SigilClient({
  generationExport: {
    protocol: "none",
  },
});

SDK metrics

The SDK emits these OTel histograms through your configured OTEL meter provider:

  • gen_ai.client.operation.duration
  • gen_ai.client.token.usage
  • gen_ai.client.time_to_first_token
  • gen_ai.client.tool_calls_per_operation

Generation export auth modes

Auth is configured for generationExport.

  • mode: "none"
  • mode: "tenant" (requires tenantId, injects X-Scope-OrgID)
  • mode: "bearer" (requires bearerToken, injects Authorization: Bearer <token>)
  • mode: "basic" (requires basicPassword + basicUser or tenantId, injects Authorization: Basic <base64(user:password)>; also injects X-Scope-OrgID when tenantId is set — for multi-tenant deployments only, not needed for Grafana Cloud)

Invalid mode/field combinations throw during client config resolution.

If explicit headers already contain Authorization or X-Scope-OrgID, explicit headers take precedence.

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)

For Grafana Cloud, use basic auth mode. The username is your Grafana Cloud instance/tenant ID and the password is your Grafana Cloud API key. See the Grafana Cloud AI Observability getting started docs for full setup steps; for this SDK endpoint, copy the API URL from Observability → AI Observability → Configuration. It looks like 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,
    },
  },
});

If your deployment requires a distinct username, set basicUser explicitly:

auth: {
  mode: "basic",
  tenantId: process.env.SIGIL_AUTH_TENANT_ID,
  basicUser: process.env.SIGIL_AUTH_TENANT_ID,
  basicPassword: process.env.SIGIL_AUTH_TOKEN,
},

Wiring custom env vars

The SDK only auto-loads SIGIL_* env vars (SIGIL_ENDPOINT, SIGIL_PROTOCOL, SIGIL_AUTH_MODE, SIGIL_AUTH_TOKEN, etc.) when you call new SigilClient(). For any other env var (for example one your secret manager exposes under a different name), read it in your app and pass the value into the config:

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

Common topology:

  • Grafana Cloud: generation basic mode with instance ID and API key.
  • Self-hosted direct to Sigil: generation tenant mode.
  • Traces/metrics via OTEL Collector/Alloy: configure exporters in your app OTEL SDK setup.
  • Enterprise proxy: generation bearer mode to proxy; proxy authenticates and forwards tenant header upstream.

Conversation Ratings

Use the SDK helper to submit user-facing ratings:

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 sends requests to api.endpoint, which should be the Grafana Cloud Sigil API URL from AI Observability configuration, and uses the same generation-export auth headers already configured on the SDK client.

版本与发布记录

@grafana/sigil-sdk-js 共发布 13 个版本,首次发布于 2026/04/23;过去 12 个月发布了 13 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.8.2latest2026/07/164 个月前
0.8.12026/07/134 个月前
0.8.02026/06/135 个月前
0.7.02026/06/025 个月前
0.6.02026/05/285 个月前
0.5.02026/05/176 个月前

关于 @grafana/sigil-sdk-js 的常见问题

@grafana/sigil-sdk-js 是什么?

Sigil records normalized LLM generation and tool-execution telemetry using your OpenTelemetry tracer/meter setup.注意:该包已被作者标记为弃用——Renamed to @grafana/agento11y. See https://grafana.com/docs/grafana-cloud/machine-learning/agent-observability/guides/migrate-sigil-sdk-to-agento11y/

如何安装 @grafana/sigil-sdk-js?

在项目目录运行 npm install @grafana/sigil-sdk-js,或使用 pnpm add / yarn add / bun add。

@grafana/sigil-sdk-js 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@grafana/sigil-sdk-js 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@grafana/sigil-sdk-js 可以商用吗?

@grafana/sigil-sdk-js 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@grafana/sigil-sdk-js 的下载量有多少?

根据 npm 官方下载统计,@grafana/sigil-sdk-js 在 2026/10/17 – 2026/11/15 这 30 天内被下载 9,085 次,日均约 303 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@grafana/sigil-sdk-js 还在维护吗?

最新版本 0.8.2 发布于 2026/07/16(4 个月前);至今共发布 13 个版本,其中过去 12 个月发布了 13 个;首次发布于 2026/04/23。作者已将其标记为弃用,新项目建议寻找替代方案。