Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow AI and machine learningbreadcrumb arrow Grafana AI Observabilitybreadcrumb arrow Get startedbreadcrumb arrow Instrument Go
Grafana Cloud

Instrument Go agents

This guide shows you how to install the AI Observability Go SDK, instrument an LLM call, and verify that generation data reaches AI Observability.

Note

AI Observability is referred to as “Sigil” in SDKs, package names, and configuration. For example, the Go module is github.com/grafana/sigil-sdk/go.

Before you begin

  • A running AI Observability instance or Grafana Cloud stack with AI Observability enabled.
  • Go 1.23 or later.
  • Your AI Observability generation export endpoint URL.

Install the SDK

Bash 
go get github.com/grafana/sigil-sdk/go

Capture a generation

Go 
package main

import (
	"context"

	"github.com/grafana/sigil-sdk/go/sigil"
)

func main() {
	cfg := sigil.DefaultConfig()
	cfg.GenerationExport.Protocol = sigil.GenerationExportProtocolHTTP
	cfg.GenerationExport.Endpoint = "<SIGIL_ENDPOINT>/api/v1/generations:export"
	cfg.GenerationExport.Auth = sigil.AuthConfig{
		Mode:     sigil.ExportAuthModeTenant,
		TenantID: "<TENANT_ID>",
	}

	client := sigil.NewClient(cfg)
	defer func() { _ = client.Shutdown(context.Background()) }()

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

	_ = ctx // pass ctx to downstream calls for trace propagation

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

Replace SIGIL_ENDPOINT and TENANT_ID with your values.

Use a provider helper

Provider helpers wrap LLM client calls to capture generations automatically. Helpers are available for OpenAI, Anthropic, and Gemini:

Bash 
go get github.com/grafana/sigil-sdk/go-providers/openai
go get github.com/grafana/sigil-sdk/go-providers/anthropic
go get github.com/grafana/sigil-sdk/go-providers/gemini

Use a framework integration

A Google ADK framework integration is available:

Bash 
go get github.com/grafana/sigil-sdk/go-frameworks/google-adk

Configure authentication

For Grafana Cloud, use basic auth:

Go 
cfg.GenerationExport.Auth = sigil.AuthConfig{
	Mode:          sigil.ExportAuthModeBasic,
	TenantID:      "<INSTANCE_ID>",
	BasicPassword: "<API_KEY>",
}

Verify data

Open the AI Observability plugin in Grafana and navigate to Conversations. Your generation should appear within a few seconds.

Next steps