Documentation Grafana Cloud AI and machine learning Grafana AI Observability Guides Coding agents

Instrument coding agents

Coding-agent plugins forward sessions from the coding agent you already use into AI Observability. Each session shows up there as generations, tool calls, and metrics.

Supported coding agents

For the full list of supported coding agents and per-plugin install instructions, refer to grafana/sigil-sdk/plugins.

Before you begin

• AI Observability is enabled on a Grafana Cloud stack. Refer to Use AI Observability on Grafana Cloud to enable the plugin and collect credentials.

• The sigil CLI is installed and on your PATH:

  • On Linux and macOS, use the install script:

    Bash Copy

    curl -fsSL https://raw.githubusercontent.com/grafana/sigil-sdk/main/plugins/sigil/scripts/install.sh | sh

    The script downloads the latest release for your OS and architecture, verifies its SHA-256 checksum, and installs the binary to ~/.local/bin. Make sure that directory is on your PATH.

  • On macOS, you can also use Homebrew:

    Bash Copy

    brew install grafana/grafana/sigil

  • On Windows, download the windows_amd64 or windows_arm64 zip from the releases page, extract sigil.exe, and put it on your PATH.

  • On any platform with Go 1.25 or later, you can use go install:

    Bash Copy

    go install github.com/grafana/sigil-sdk/plugins/sigil/cmd/sigil@latest

    go install puts the binary in go env GOPATH/bin (or GOBIN). Make sure that directory is on your PATH.

Configure credentials

Run sigil login, or run the launcher for your coding agent (such as sigil pi, sigil claude, or sigil codex). On the first launch, the launcher runs the same login flow automatically. Both write to ~/.config/sigil/config.env, the shared configuration file that every coding-agent plugin reads. Later launches reuse it, and you can re-run sigil login any time to change a value.

The interactive prompt has two steps:

1. Connection details: your Grafana Cloud endpoint (the plugin’s API URL), tenant ID (the Instance ID), token, and OTLP endpoint. Find these in Grafana Cloud at https://<your-stack>.grafana.net/plugins/grafana-sigil-app.
2. Preferences: content capture mode, session tags, and guards. Every field defaults to the plugin’s current behavior, so press Enter through this step to keep the defaults.

If you can’t run an interactive prompt (for example, in CI, a container, or a scripted setup), write the configuration file directly instead. Refer to Configure without the prompt.

Content capture

By default, plugins send only metadata: model, token usage, tool names, and timing. Prompts, responses, and tool I/O stay on your machine. To also send prompts and responses, with automatic secret redaction, set the Content capture field to Full when you run sigil login.

The modes are metadata_only (default) and full. You can also set SIGIL_CONTENT_CAPTURE_MODE directly. Refer to Configure without the prompt.

Enable guards

Guards run synchronous checks on tool calls before they execute. When guards are enabled, tool calls that fail evaluation are blocked. Refer to Set up guards for guard rule configuration.

Guards are off by default. To turn them on, set the Guards field in sigil login:

• Enabled, fail-open: transport errors and timeouts let the tool call through. This is the safer choice when you first turn guards on.
• Enabled, fail-closed: a guard error or timeout blocks the tool call.

The Guard timeout field sets how long to wait for a guard before applying the fail mode (default 1500 ms). Raise it to tolerate slow evaluators, or lower it to cap per-call latency. The timeout applies only when guards are enabled.

Configure without the prompt

sigil login is interactive and needs a terminal. For non-interactive setups, such as CI, containers, or dotfiles, write ~/.config/sigil/config.env directly. Each prompt maps to an environment variable:

dotenv Copy

# Connection (required)
SIGIL_ENDPOINT=https://sigil-prod-<region>.grafana.net
SIGIL_AUTH_TENANT_ID=<instance-id>
SIGIL_AUTH_TOKEN=glc_<token>
# OTLP endpoint for SDK traces and metrics (optional)
SIGIL_OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-<region>.grafana.net/otlp

# Preferences (optional; defaults shown)
# Modes: metadata_only | full
SIGIL_CONTENT_CAPTURE_MODE=metadata_only
SIGIL_TAGS=team=ai,project=demo            # applied to every generation
SIGIL_GUARDS_ENABLED=false
SIGIL_GUARDS_FAIL_OPEN=true                # only used when guards are enabled
SIGIL_GUARDS_TIMEOUT_MS=1500               # only used when guards are enabled

Find the connection values in Grafana Cloud at https://<your-stack>.grafana.net/plugins/grafana-sigil-app.

Verify

Run a turn in your coding agent, then open Conversations in the AI Observability plugin. The generation appears within a few seconds.

If nothing appears, enable debug logging and tail the log. For example, for Pi:

Bash Copy

SIGIL_DEBUG=true sigil pi
tail -f ~/.local/state/sigil/logs/sigil.log

Check the following:

• sigil --version resolves on your PATH.
• SIGIL_ENDPOINT, SIGIL_AUTH_TENANT_ID, and SIGIL_AUTH_TOKEN are set in ~/.config/sigil/config.env.
• The access policy token has the sigil:write scope.

Next steps

• Browse conversations
• Set up guards
• Use the agent catalog
• Use built-in dashboards