gcloud-usage — скилл для Claude Code: разбор логов GCP
Скилл gcloud-usage помогает разбирать логи, метрики и трассировки Google Cloud, а также настраивать фильтры и алерты. Пригодится при отладке проблем в GCP.
Apache-2.0 ★ 1 216 обновлён 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install gcloud-tools@claude-settingsЧто делает gcloud-usage
Скилл описывает работу с наблюдаемостью в Google Cloud: как фильтровать логи по уровню серьёзности, ресурсу, времени и полям JSON, а также как выбирать между метриками, логами и трассировками. Есть примеры запросов для Cloud Logging и сценарий поиска причины сбоя: начать с метрик, затем сопоставить логи и проверить трассировки.
В рекомендациях по алертам разобраны условия для частоты ошибок, задержки и нехватки ресурсов. Также описаны способы сократить расходы на логи: фильтры исключения, семплирование и уменьшение срока хранения. Окна алертов для большинства метрик предлагается выбирать в диапазоне 5–15 минут; это нужно учитывать при настройке порогов под свой сервис.
Скилл предназначен для запросов о логах GCloud, метриках Google Cloud, трассировках и отладке GCP. В примерах встречаются cloud_run_revision, jsonPayload.user_id и textPayload; они пригодятся при составлении фильтров для конкретного сервиса.
Какие задачи решает
- найти ошибки в логах по уровню серьёзности и сервису
- отфильтровать события Cloud Logging по времени и полям JSON
- сопоставить метрики, логи и трассировки при сбое
- настроить алерты на рост ошибок или задержки
- сократить объём логов с помощью фильтров исключения
Примеры запросов агенту
- Найди ошибки сервиса
apiв Cloud Logging и отфильтруй их по уровню серьёзности. - Помоги сопоставить метрики, логи и трассировки для запроса, который завершился с ошибкой.
- Предложи фильтр Cloud Logging, чтобы исключить проверки
/health.
Как установить gcloud-usage
1Через маркетплейс плагинов
/plugin marketplace add fcakyon/claude-codex-settings/plugin install gcloud-tools@claude-settingsКоманда ставит плагин gcloud-tools целиком, со всеми его скиллами
2Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill gcloud-usage -a claude-code3Вручную: положить файлы
~/.claude/skills/gcloud-usage/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/gcloud-usage/
1Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill gcloud-usage -a codex2Вручную: положить файлы
.agents/skills/gcloud-usage/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill gcloud-usage -a cursor2Вручную: положить файлы
.cursor/skills/gcloud-usage/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install fcakyon/claude-codex-settings plugins/gcloud-tools/skills/gcloud-usage2Вручную: положить файлы
.github/skills/gcloud-usage/SKILL.md1Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill gcloud-usage -a gemini-cli2Командой платформы
gemini skills install https://github.com/fcakyon/claude-codex-settings --path plugins/gcloud-tools/skills/gcloud-usageВручную: положить файлы
.devin/skills/gcloud-usage/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о gcloud-usage
Как установить gcloud-usage в Claude Code?
В Claude Code добавьте маркетплейс командой /plugin marketplace add fcakyon/claude-codex-settings, затем установите плагин командой /plugin install gcloud-tools@claude-settings.
Что делает gcloud-usage?
Скилл подсказывает, как искать события в Cloud Logging, анализировать метрики и трассировки, проектировать алерты и снижать расходы на хранение логов.
Какие данные использовать для отладки проблем в GCP?
Скилл предлагает начать с метрик, чтобы определить время начала проблемы, затем отфильтровать логи за этот период и проследить запрос по трассировкам. Также рекомендуется проверить логи ресурсов.
Исходный текст
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