gcloud-usage — Claude Code skill for GCP logs
gcloud-usage is a Claude Code skill that guides Google Cloud log queries and analysis of metrics, traces, and alerts. It supports production debugging and GCP observability work.
Apache-2.0 ★ 1,216 updated 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install gcloud-tools@claude-settingsWhat gcloud-usage does
The skill covers Google Cloud observability workflows: filtering Cloud Logging entries by severity, resource, time, and JSON fields, then choosing whether metrics, logs, or traces are the right evidence. Its debugging sequence starts with metrics, moves to logs around the incident, and follows requests through traces.
Alert guidance covers error rates, latency, and resource pressure. The skill also discusses reducing log costs through exclusion filters, sampling, shorter retention, and routing logs to cheaper storage. For most metrics, it recommends alert windows of 5–15 minutes, so thresholds and windows need to match the service being monitored.
It is meant for questions about GCloud logs, Google Cloud metrics, trace analysis, and GCP production debugging. Examples use fields such as jsonPayload.user_id and resources such as cloud_run_revision, which can help shape queries for a specific service.
What it helps with
- filter Cloud Logging entries by severity and service
- search logs by timestamp or JSON field
- trace a production issue across metrics, logs, and traces
- set alerts for elevated errors or latency
- cut log volume with exclusion filters
Example prompts for the agent
- Find high-severity Cloud Logging entries for the
apiservice. - Help me compare metrics, logs, and traces for a failed request.
- Draft a Cloud Logging filter that excludes
/healthchecks.
How to install gcloud-usage
1Plugin marketplace
/plugin marketplace add fcakyon/claude-codex-settings/plugin install gcloud-tools@claude-settingsThis installs the whole gcloud-tools plugin with all its skills
2Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill gcloud-usage -a claude-code3Manually: put the files in place
~/.claude/skills/gcloud-usage/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gcloud-usage/
1Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill gcloud-usage -a codex2Manually: put the files in place
.agents/skills/gcloud-usage/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill gcloud-usage -a cursor2Manually: put the files in place
.cursor/skills/gcloud-usage/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install fcakyon/claude-codex-settings plugins/gcloud-tools/skills/gcloud-usage2Manually: put the files in place
.github/skills/gcloud-usage/SKILL.md1Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill gcloud-usage -a gemini-cli2Platform CLI
gemini skills install https://github.com/fcakyon/claude-codex-settings --path plugins/gcloud-tools/skills/gcloud-usageManually: put the files in place
.devin/skills/gcloud-usage/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about gcloud-usage
How do I install gcloud-usage in Claude Code?
In Claude Code, add the marketplace with /plugin marketplace add fcakyon/claude-codex-settings, then install the plugin with /plugin install gcloud-tools@claude-settings.
What does gcloud-usage do?
It provides guidance for querying Cloud Logging, interpreting metrics and traces, designing alerts, and managing log costs.
How does the skill suggest debugging a GCP incident?
Start with metrics to locate when the issue began, inspect logs from that period, then follow requests in traces. It also recommends checking resource logs.
Source text
SKILL.md · Apache-2.0
---
name: gcloud-usage
description: This skill should be used when user asks about "GCloud logs", "Cloud Logging queries", "Google Cloud metrics", "GCP observability", "trace analysis", or "debugging production issues on GCP".
---
# GCP Observability Best Practices
## Structured Logging
### JSON Log Format
Use structured JSON logging for better queryability:
```json
{
"severity": "ERROR",
"message": "Payment failed",
"httpRequest": { "requestMethod": "POST", "requestUrl": "/api/payment" },
"labels": { "user_id": "123", "transaction_id": "abc" },
"timestamp": "2025-01-15T10:30:00Z"
}
```
### Severity Levels
Use appropriate severity for filtering:
- **DEBUG:** Detailed diagnostic info
- **INFO:** Normal operations, milestones
- **NOTICE:** Normal but significant events
- **WARNING:** Potential issues, degraded performance
- **ERROR:** Failures that don't stop the service
- **CRITICAL:** Failures requiring immediate action
- **ALERT:** Person must take action immediately
- **EMERGENCY:** System is unusable
## Log Filtering Queries
### Common Filters
```
# By severity
severity >= WARNING
# By resource
resource.type="cloud_run_revision"
resource.labels.service_name="my-service"
# By time
timestamp >= "2025-01-15T00:00:00Z"
# By text content
textPayload =~ "error.*timeout"
# By JSON field
jsonPayload.user_id = "123"
# Combined
severity >= ERROR AND resource.labels.service_name="api"
```
### Advanced Queries
```
# Regex matching
textPayload =~ "status=[45][0-9]{2}"
# Substring search
textPayload : "connection refused"
# Multiple values
severity = (ERROR OR CRITICAL)
```
## Metrics vs Logs vs Traces
### When to Use Each
**Metrics:** Aggregated numeric data over time
- Request counts, latency percentiles
- Resource utilization (CPU, memory)
- Business KPIs (orders/minute)
**Logs:** Detailed event records
- Error details and stack traces
- Audit trails
- Debugging specific requests
**Traces:** Request flow across services
- Latency breakdown by service
- Identifying bottlenecks
- Distributed system debugging
## Alert Policy Design
### Alert Best Practices
- **Avoid alert fatigue:** Only alert on actionable issues
- **Use multi-condition alerts:** Reduce noise from transient spikes
- **Set appropriate windows:** 5-15 min for most metrics
- **Include runbook links:** Help responders act quickly
### Common Alert Patterns
**Error rate:**
- Condition: Error rate > 1% for 5 minutes
- Good for: Service health monitoring
**Latency:**
- Condition: P99 latency > 2s for 10 minutes
- Good for: Performance degradation detection
**Resource exhaustion:**
- Condition: Memory > 90% for 5 minutes
- Good for: Capacity planning triggers
## Cost Optimization
### Reducing Log Costs
- **Exclusion filters:** Drop verbose logs at ingestion
- **Sampling:** Log only percentage of high-volume events
- **Shorter retention:** Reduce default 30-day retention
- **Downgrade logs:** Route to cheaper storage buckets
### Exclusion Filter Examples
```
# Exclude health checks
resource.type="cloud_run_revision" AND httpRequest.requestUrl="/health"
# Exclude debug logs in production
severity = DEBUG
```
## Debugging Workflow
1. **Start with metrics:** Identify when issues started
2. **Correlate with logs:** Filter logs around problem time
3. **Use traces:** Follow specific requests across services
4. **Check resource logs:** Look for infrastructure issues
5. **Compare baselines:** Check against known-good periods
© Fatih C. Akyon · Apache-2.0 · fcakyon/claude-codex-settings