api-monitor

enufacas 的头像作者 enufacas

监控和分析来自 Google Cloud Run 的叙述性 API 日志。在以下情况下使用:(1) 调查 Cloud Run API 错误或故障,(2) 分析 API 使用成本并优化支出,(3) 衡量场景生成性能(持续时间、引用),(4) 查看自定义场景生成请求,(5) 了解用户/IP 访问模式,(6) 调试生产问题。请勿用于本地 Docker 调试(使用 docker 日志)、实时监控(云日志有 1-2 分钟延迟)或 Vite 开发服务器日志(使用浏览器控制台)。

📖 中文导读:监控和分析来自 Google Cloud Run 的叙述性 API 日志。在以下情况下使用:(1) 调查 Cloud Run API 错误或故障,(2) 分析 API 使用成本并优化支出,(3) 衡量场景生成性能(持续时间、引用),(4) 查看自定义场景生成请求,(5) 了解用户/IP 访问模式,(6) 调试生产问题。请勿用于本地 Docker 调试(使用 docker 日志)、实时监控(云日志有 1-2 分钟延迟)或 Vite 开发服务器日志(使用浏览器控制台)。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: api-monitor description: Monitor and analyze narrative API logs from Google Cloud Run. Use when (1) Investigating Cloud Run API errors or failures, (2) Analyzing API usage costs and optimizing spend, (3) Measuring scenario generation performance (duration, citations), (4) Reviewing custom scenario generation requests, (5) Understanding user/IP access patterns, (6) Debugging production issues. DO NOT use for local Docker debugging (use docker logs), real-time monitoring (Cloud Logging has 1-2min delay), or Vite dev server logs (use browser console). allowed-tools: Bash(node:), Bash(gcloud:), Bash(curl:*), Read, Grep, WebFetch

API Monitor Skill

Monitor and debug the narrative-api service running on Google Cloud Run using the API monitor server.

What the API Monitor Does

The API monitor server (C:\Users\enufa\hddl\.vscode\scripts\api-monitor-server.mjs):

  1. Fetches logs from Google Cloud Logging for the narrative-api Cloud Run service
  2. Processes logs to extract HTTP requests, narrative generation metrics, errors
  3. Provides analytics via REST API at http://localhost:3030
  4. Serves dashboard at http://localhost:3030/api-monitor-dashboard.html

Starting the API Monitor Server

Prerequisites

Verify authentication and project:

# Check gcloud authentication
gcloud auth list

# Check current GCP project
gcloud config get-value project

# Verify narrative-api service exists
gcloud run services list --filter="narrative-api"

If auth fails: gcloud auth login

Start the Server

cd .vscode/scripts
node api-monitor-server.mjs

Expected output:

🚀 API Monitor Dashboard Server running at http://localhost:3030
📊 Open http://localhost:3030/api-monitor-dashboard.html in your browser

Verify Server is Running

curl http://localhost:3030/api/logs

Should return JSON with requests and summary fields.

Basic Usage

Fetch Recent Logs

# Default: last 100 logs
curl http://localhost:3030/api/logs

# Custom limit: last 200 logs
curl http://localhost:3030/api/logs/200

# Save to file for analysis
curl http://localhost:3030/api/logs/500 > recent-api-logs.json

Response Structure

{
  "requests": [
    {
      "timestamp": "2025-01-05T10:30:00.000Z",
      "method": "POST",
      "url": "/generate-scenario?...",
      "endpoint": "/generate-scenario",
      "status": 200,
      "latency": "18.5s",
      "scenario": "insurance",
      "duration": 18500,
      "citations": 17,
      "cost": 0.009374,
      "error": null
    }
  ],
  "summary": {
    "totalRequests": 45,
    "totalCost": "0.4231",
    "avgDuration": 12500,
    "scenarios": ["insurance", "minimal"],
    "errorCount": 2,
    "errorRate": "4.4",
    "recentErrors": [...]
  }
}

Quick Analysis Commands

# Check error summary
curl http://localhost:3030/api/logs/200 | jq '.summary.recentErrors'

# Check total cost
curl http://localhost:3030/api/logs/500 | jq '.summary.totalCost'

# Check average duration
curl http://localhost:3030/api/logs/200 | jq '.summary.avgDuration'

# List custom scenario prompts
curl http://localhost:3030/api/logs/500 | jq '.summary.customScenarioPrompts'

# Check server health
curl http://localhost:3030/api/logs > /dev/null && echo "Server OK" || echo "Server DOWN"

Common Error Status Codes

Status Likely Cause Fix
401 Authentication failure Re-run gcloud auth login
403 Permission denied Check IAM roles for Cloud Run service
500 Internal server error Check .error field for stack traces
503 Service unavailable Cloud Run cold start or scaling issue
504 Timeout Request took >60s (Cloud Run default timeout)

Performance Targets

  • Good: <15s for scenario generation
  • Acceptable: 15-30s
  • Slow: >30s (investigate)

Advanced Workflows

For detailed debugging scenarios, troubleshooting guides, integration patterns, and example analysis workflows, see:

Dashboard Usage

The HTML dashboard provides visual interface at http://localhost:3030/api-monitor-dashboard.html:

  • Auto-refresh logs
  • Visual analytics (charts for costs, duration, errors)
  • Interactive filtering (by scenario, IP, status code)

Note: Claude Code cannot view the dashboard directly, but can fetch and analyze the underlying API data using curl.


Remember: This skill is for Cloud Run production API monitoring. For local Docker debugging, use docker logs instead.