groundcover

Investigate incidents with groundcover logs and traces, queried with gcQL (groundcover Query Language) over groundcover’s public, read-only MCP endpoint. This is the initial integration: configuration, verification, and three read-only tools (logs, traces, and the gcQL reference). More signals (metrics, APM, Kubernetes events/entities, monitors, monitor issues) and alert-source routing land in follow-up releases. v1 is read-only — no monitor creation, silencing, or other mutating actions.

Commands

Command	What it does
`opensre integrations setup groundcover`	Store a groundcover service-account token and routing settings
`opensre integrations verify groundcover`	Connect to the MCP endpoint, list tools, and check workspace routing

1. Create a read-only service-account token

In groundcover: Settings → Access → Service Accounts → create a service account with a read-only policy → create an API key and copy it (shown once). OpenSRE never performs write actions.

2. Configure

Run the interactive setup:

opensre integrations setup groundcover

…or set environment variables:

export GROUNDCOVER_API_KEY="<service-account-token>"   # alias: GROUNDCOVER_MCP_TOKEN
# Optional — defaults shown:
export GROUNDCOVER_MCP_URL="https://mcp.groundcover.com/api/mcp"
export GROUNDCOVER_TIMEZONE="UTC"
# Only for multi-workspace / multi-backend accounts:
export GROUNDCOVER_TENANT_UUID="<tenant-uuid>"
export GROUNDCOVER_BACKEND_ID="<backend-id>"

Single-workspace accounts need only the token. If your account has multiple workspaces or backends, verification tells you exactly which value to set. Multiple instances:

export GROUNDCOVER_INSTANCES='[
  {"name":"prod","api_key":"...","tenant_uuid":"...","backend_id":"prod"},
  {"name":"staging","api_key":"...","tenant_uuid":"...","backend_id":"staging"}
]'

opensre integrations list shows integrations saved to the local store (via setup); environment-variable configuration is still picked up by verify and at runtime.

3. Verify

opensre integrations verify groundcover

Verification connects to the MCP endpoint, confirms the expected read-only tool surface is present, and lists your workspaces. It returns passed, missing (token not configured), or failed with an actionable message — for example, naming the missing or mistyped GROUNDCOVER_TENANT_UUID / GROUNDCOVER_BACKEND_ID when the account is ambiguous. Tokens are never printed.

Tools

Tool	Use it for
`get_groundcover_query_reference`	The gcQL syntax reference — call once before writing queries
`query_groundcover_logs`	Application errors, exceptions, and log events
`query_groundcover_traces`	Slow/failing spans and request correlations

Writing efficient gcQL

gcQL is a pipe-based language: a query starts with a filter (or *) and pipes through operators. These rules keep queries fast and valid:

Lead with the filter directly — level:error | …, not * | filter level:error. The | filter pipe is for post-aggregation conditions on computed aliases.
Project or aggregate — don’t pull raw rows blindly. Use | fields a, b, … to select columns, or | stats … to aggregate. A bare select-all (<filter> | limit N) can be rejected by the backend.
Keep the time window narrow. The default is the last 1 hour; widen only after an empty or inconclusive result.
Always include | limit N — it caps rows returned (not data scanned), so for wide ranges prefer stats/aggregations.
Discover fields with * | field_names (or get_groundcover_query_reference).

Examples:

# Recent error logs for a workload (projected)
level:error workload:checkout | fields _time, instance, content | limit 50

# Error count per workload in one query
level:error | stats by (env, cluster, namespace, workload) count() as errors
  | sort by (errors desc) | limit 20

# Slowest spans for a service (projected)
duration_seconds>0.5 workload:checkout
  | fields _time, span_name, duration_seconds, status_code | limit 50

# 5xx rate per workload (HTTP spans use status_code; status:error is universal)
status_code>=500 | stats by (workload) count() as errors | sort by (errors desc) | limit 20

Troubleshooting

Symptom	Fix
`missing` on verify	Set `GROUNDCOVER_API_KEY` (or `GROUNDCOVER_MCP_TOKEN`).
`401 Unauthorized`	Regenerate the service-account token; ensure it has read access.
`Account has N workspaces…`	Set `GROUNDCOVER_TENANT_UUID` to the listed tenant.
`…has N backends…`	Set `GROUNDCOVER_BACKEND_ID` to the listed backend.
`failed to query …`	Project with `	fields …`or aggregate with`	stats …`; narrow the time window; avoid a bare raw select-all.
Empty results	Run `*	field_names` to find real field names; avoid leading-wildcard globs.
Not shown in `integrations list`	`list` shows the local store — run `opensre integrations setup groundcover` (env vars still work for `verify`/runtime).

Overview

LLM providers

Observability and incidents

Cloud, code, and collaboration

Messaging

Data and workflow systems

Commands

1. Create a read-only service-account token

2. Configure

3. Verify

Tools

Writing efficient gcQL

Troubleshooting

​Commands

​1. Create a read-only service-account token

​2. Configure

​3. Verify

​Tools

​Writing efficient gcQL

​Troubleshooting

Commands

1. Create a read-only service-account token

2. Configure

3. Verify

Tools

Writing efficient gcQL

Troubleshooting