Grafana AI observability is a product from Grafana for teams running agents in production. This repo holds the open-source SDKs and the coding-agent plugins that send telemetry to it.

Drop llms.txt into your repo and ask your agent what you want. It handles either case, depending on what your repo is:

• Instrument this codebase with Grafana AI observability: the agent wires the SDK into your app or agent code.
• Set up Grafana AI observability for my coding agent: the agent installs one of the plugins/ launchers to capture sessions from popular coding agents.

Or open the AI Observability plugin in your Grafana Cloud stack and use the onboarding wizard.

Set the SIGIL_* env vars and construct the client. To configure it explicitly instead, see the per-SDK READMEs linked under SDKs.

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

const client = new SigilClient(); // reads SIGIL_* env vars

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

await client.shutdown();

from sigil_sdk import Client, GenerationStart, ModelRef, assistant_text_message

client = Client()  # reads SIGIL_* env vars

with client.start_generation(
    GenerationStart(
        conversation_id="conv-1",
        model=ModelRef(provider="openai", name="gpt-5"),
    )
) as rec:
    rec.set_result(output=[assistant_text_message("Hello")])

client.shutdown()

client := sigil.NewClient(sigil.Config{}) // reads SIGIL_* env vars
defer func() { _ = client.Shutdown(context.Background()) }()

ctx, rec := client.StartGeneration(context.Background(), sigil.GenerationStart{
    ConversationID: "conv-1",
    Model:          sigil.ModelRef{Provider: "openai", Name: "gpt-5"},
})
defer rec.End()

rec.SetResult(sigil.Generation{
    Output: []sigil.Message{sigil.AssistantTextMessage("Hello from Grafana AI observability")},
}, nil)

Minimal, self-contained examples that make a real LLM call and record the generation to Grafana AI observability.

Application SDK hooks evaluate Sigil guard rules on your request path before a provider call. A guard can allow the request, deny it, or return transformed input such as redacted messages. See the Go, Python, and TypeScript SDK READMEs for manual hook evaluation, and the runnable examples/getting-started/go-hooks/ and examples/getting-started/python-hooks/ examples for preflight guard setups.

The SDKs default to no_tool_content: full generation messages ship to Sigil, but tool-execution arguments and results stay out of spans. The coding-agent plugins default to metadata_only. See Content Capture Modes for the mode matrix, defaults per surface, and the generation, tool-execution, and embedding resolution rules.

All four connection values (API URL, Instance ID, API token, and OTLP endpoint) live on the Connection tab of the AI Observability plugin in your stack:

https://<your-stack>.grafana.net/plugins/grafana-sigil-app

Follow Create a token in Cloud Access Policies on the Connection page and create one token scoped with sigil:write, metrics:write, traces:write, and logs:write. The same token then covers both SIGIL_AUTH_TOKEN (Sigil ingest) and OTEL_EXPORTER_OTLP_HEADERS (OTel traces and metrics).

See the Grafana Cloud AI observability getting started docs for the full setup flow.

Plugins can record sessions from Claude Code, Codex, Copilot CLI, Cursor, OpenCode, and Pi without changing application code. See plugins/README.md for install and config per agent.

• The SDK emits traces and metrics as standard OTLP, so they can use existing OTel pipelines. Conversations and generations go through Sigil ingest so Grafana can join them with traces, costs, and scores.
• It uses OTel GenAI semantic conventions where they exist. Sigil-specific fields cover agent versions, generation IDs, and tool executions.
• Prompt and tool changes create agent versions when the producer does not send a version string.
• Evaluators can score live traffic, so teams can find regressions without reviewing every conversation manually.

Contributor notes (proto regeneration, mise tasks, conformance suites) live in docs/development.md. Agent context for working in this repo is in CLAUDE.md.

Apache License 2.0