@grafana/sigil-pi

Pi agent extension that sends LLM generations to Grafana AI Observability.

By default only metadata is sent (token counts, cost, model, tool names, durations). Set SIGIL_CONTENT_CAPTURE_MODE to full, no_tool_content, metadata_only, or full_with_metadata_spans to control what is sent. default is accepted as an alias for metadata_only. See Content Capture Modes for the full reference.

1. Install and launch

brew install grafana/grafana/sigil
sigil pi

sigil pi installs the @grafana/sigil-pi extension on first run, prompts for missing Grafana Cloud credentials, writes ~/.config/sigil/config.env, and then launches pi.

pi install npm:@grafana/sigil-pi
sigil login

The extension reads the same ~/.config/sigil/config.env file whether you start pi with sigil pi or plain pi.

2. Credentials

When sigil pi or sigil login prompts, copy values from https://<your-grafana>.grafana.net/plugins/grafana-sigil-app. Make sure AI Observability is enabled on your stack — an administrator opens Observability → AI Observability once and accepts the terms.

You need values from three Grafana Cloud pages:

1. AI Observability → Configuration

   • API URL → SIGIL_ENDPOINT
   • Instance ID → SIGIL_AUTH_TENANT_ID

2. Administration → Users and access → Cloud access policies

   • Create a policy with scopes sigil:write, metrics:write, traces:write.
   • Add a token. The glc_… value is shown once → SIGIL_AUTH_TOKEN.

3. Grafana Cloud Portal → your stack → OpenTelemetry card

   • OTLP endpoint URL → SIGIL_OTEL_EXPORTER_OTLP_ENDPOINT

Run sigil login later to update saved credentials.

Create or update ~/.config/sigil/config.env:

SIGIL_ENDPOINT=https://sigil-prod-<region>.grafana.net
SIGIL_AUTH_TENANT_ID=<instance-id>
SIGIL_AUTH_TOKEN=glc_...
SIGIL_OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-<region>.grafana.net/otlp

When SIGIL_AUTH_TENANT_ID and SIGIL_AUTH_TOKEN are set, the extension uses them for Sigil and OTLP auth. If the OpenTelemetry card shows a different Instance ID, set OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic <base64(otlp-id:glc_token)>.

To include conversation text (with automatic secret redaction), add this to ~/.config/sigil/config.env:

SIGIL_CONTENT_CAPTURE_MODE=full

3. Verify

Run one pi turn, then open AI Observability → Conversations in Grafana Cloud. A new generation should appear within a few seconds.

If nothing shows up, set SIGIL_DEBUG=true in ~/.config/sigil/config.env, run another turn, and check the debug log at ~/.local/state/sigil/logs/sigil.log (honors XDG_STATE_HOME).

Redaction

Before any generation leaves the process, the SDK scrubs known token formats, PEM private keys, database URLs, KEY=value pairs, bearer tokens, and email addresses. Matches become [REDACTED:<id>]. User input messages are redacted by default; set SIGIL_REDACT_INPUT_MESSAGES=false to leave them unchanged.

Guards

Guards block tool calls before they execute (e.g. refuse a bash invocation matching a deny rule). They're off by default:

SIGIL_GUARDS_ENABLED=true sigil pi

By default, transport errors and timeouts let the tool through. Set SIGIL_GUARDS_FAIL_OPEN=false to block on errors instead. Raise or lower SIGIL_GUARDS_TIMEOUT_MS (default 1500) to trade latency against tolerance for slow evaluators.

The same three variables are honored by the Claude Code plugin; both plugins read them from ~/.config/sigil/config.env.

All options

~/.config/sigil/config.env is the only configuration file. Every option is set via env var.

Variable	Default	Description
SIGIL_ENDPOINT	—	Sigil URL (find it at /plugins/grafana-sigil-app)
SIGIL_AUTH_TENANT_ID	—	Grafana Cloud instance ID. Combined with SIGIL_AUTH_TOKEN becomes Basic auth for Sigil and OTLP.
SIGIL_AUTH_TOKEN	—	Cloud access policy token (glc_…).
SIGIL_AGENT_NAME	pi	Agent name reported to Sigil.
SIGIL_AGENT_VERSION	—	Optional version string reported with the agent.
SIGIL_CONTENT_CAPTURE_MODE	metadata_only	One of full, no_tool_content, metadata_only, or full_with_metadata_spans. default is accepted as an alias for metadata_only.
SIGIL_DEBUG	false	Write lifecycle events to ~/.local/state/sigil/logs/sigil.log (honors XDG_STATE_HOME). Never written to the terminal, to avoid corrupting pi's TUI.
SIGIL_REDACT_INPUT_MESSAGES	true	Redact known secret patterns in user input messages before export.
SIGIL_OTEL_EXPORTER_OTLP_ENDPOINT	—	OTLP HTTP endpoint. Falls back to OTEL_EXPORTER_OTLP_ENDPOINT.
SIGIL_OTEL_AUTH_TOKEN	SIGIL_AUTH_TOKEN	Override the OTLP password.
SIGIL_GUARDS_ENABLED	false	Evaluate tool_call requests against Sigil policy.
SIGIL_GUARDS_TIMEOUT_MS	1500	Per-call timeout for guard requests, in milliseconds.
SIGIL_GUARDS_FAIL_OPEN	true	Allow tools through when the guard call fails. Set false for strict mode.

File format: one KEY=value per line, # line comments, optional export prefix, optional matching single or double quotes around the value. Only the following keys are honoured — anything else (including stray PATH=… lines) is ignored: any SIGIL_* key plus OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_INSECURE, and OTEL_SERVICE_NAME.

A non-empty OS env value always wins over the file; an empty or whitespace-only OS value is treated as unset and gets filled from config.env. Missing files are silent.