Skip to content

secondsky/claude-skills / plugins/cloudflare-workers/skills/cloudflare-workers-observability

cloudflare-workers-observability

Verified

Cloudflare Workers observability with logging, Analytics Engine, Tail Workers, metrics, and alerting. Use for monitoring, debugging, tracing, or encountering log parsing, metric aggregation, alert configuration errors.

scripts/setup-logging.sh

View on GitHub
#!/bin/bash
# Setup Logging and Observability for Cloudflare Workers
#
# Features:
# - Enables observability in wrangler.jsonc
# - Configures Analytics Engine dataset
# - Creates Tail Worker scaffold
# - Sets up KV namespace for rate limiting
#
# Usage:
#   ./setup-logging.sh
#   ./setup-logging.sh --with-tail-worker
#   ./setup-logging.sh --analytics-only

set -euo pipefail

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

# Configuration
WORKER_NAME=""
WITH_TAIL_WORKER=false
ANALYTICS_ONLY=false
TAIL_WORKER_NAME="log-aggregator"

# Parse arguments
while [[ $# -gt 0 ]]; do
  case $1 in
    --with-tail-worker)
      WITH_TAIL_WORKER=true
      shift
      ;;
    --analytics-only)
      ANALYTICS_ONLY=true
      shift
      ;;
    --tail-worker-name)
      TAIL_WORKER_NAME="$2"
      shift 2
      ;;
    --help|-h)
      echo "Usage: $0 [options]"
      echo ""
      echo "Options:"
      echo "  --with-tail-worker     Create a Tail Worker for log aggregation"
      echo "  --analytics-only       Only set up Analytics Engine"
      echo "  --tail-worker-name     Name for the Tail Worker (default: log-aggregator)"
      echo "  --help, -h             Show this help"
      exit 0
      ;;
    *)
      echo "Unknown option: $1"
      exit 1
      ;;
  esac
done

# D-010: validate tail worker name against a safe charset to prevent path
# traversal (../) and other shell/path metacharacter issues.
if [ -n "$TAIL_WORKER_NAME" ]; then
  if ! [[ "$TAIL_WORKER_NAME" =~ ^[A-Za-z0-9_-]+$ ]]; then
    echo -e "${RED}Error: invalid tail worker name '$TAIL_WORKER_NAME' (must match ^[A-Za-z0-9_-]+\$/)${NC}"
    exit 2
  fi
fi

# D-004 helper: heuristic JSONC-comment detection. jq is JSONC-blind, so when
# the target wrangler file contains // comments we refuse to overwrite in place.
wrangler_has_comments() {
  grep -Eq '(^|[^:])//' "$WRANGLER_FILE"
}

# D-004 helper: emit a comment-stripped copy of $WRANGLER_FILE on stdout for jq.
stripped_wrangler() {
  grep -v '^\s*//' "$WRANGLER_FILE"
}

# D-004 helper: write the jq-produced content safely. If the file has comments,
# emit to $WRANGLER_FILE.new and instruct the user; otherwise take a timestamped
# backup (D-021) and overwrite.
safe_write_wrangler() {
  local tmp_file="$1"
  local backup_file="${WRANGLER_FILE}.bak.$(date +%Y%m%d%H%M%S)"

  if wrangler_has_comments; then
    cp "$WRANGLER_FILE" "$backup_file"
    cp "$tmp_file" "${WRANGLER_FILE}.new"
    echo -e "  ${YELLOW}Warning: $WRANGLER_FILE contains JSONC comments.${NC}"
    echo -e "  ${YELLOW}Refusing to overwrite in place β€” wrote modified version to ${WRANGLER_FILE}.new${NC}"
    echo -e "  ${YELLOW}Backup of original (with comments) at: $backup_file${NC}"
    echo -e "  ${YELLOW}Review and replace $WRANGLER_FILE manually.${NC}"
    return 0
  fi

  cp "$WRANGLER_FILE" "$backup_file"
  mv "$tmp_file" "$WRANGLER_FILE"
  echo -e "  ${GREEN}(backup at $backup_file)${NC}"
}

# D-010 helper: back up an existing file to .bak.<timestamp> before overwriting.
backup_if_exists() {
  local target="$1"
  if [ -f "$target" ]; then
    local backup_file="${target}.bak.$(date +%Y%m%d%H%M%S)"
    cp "$target" "$backup_file"
    echo -e "  ${YELLOW}Backed up existing $target to $backup_file${NC}"
  fi
}

echo -e "${BLUE}========================================"
echo "Cloudflare Workers Logging Setup"
echo -e "========================================${NC}"
echo ""

# Check for wrangler.jsonc
if [ ! -f "wrangler.jsonc" ] && [ ! -f "wrangler.json" ]; then
  echo -e "${RED}Error: No wrangler.jsonc found in current directory${NC}"
  exit 1
fi

WRANGLER_FILE="wrangler.jsonc"
[ -f "wrangler.json" ] && WRANGLER_FILE="wrangler.json"

# Get worker name from config
WORKER_NAME=$(grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' "$WRANGLER_FILE" | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
echo -e "${GREEN}Worker name:${NC} $WORKER_NAME"
echo ""

# Step 1: Enable observability
echo -e "${YELLOW}Step 1: Enabling observability...${NC}"

if grep -q '"observability"' "$WRANGLER_FILE"; then
  echo "  Observability already configured"
else
  echo "  Adding observability config..."
  # Add observability after compatibility_date line
  if command -v jq &> /dev/null; then
    # Use jq if available. Feed jq a comment-stripped view so it parses even
    # when the file is JSONC; safe_write_wrangler decides where the result goes.
    TMP_FILE=$(mktemp)
    stripped_wrangler | jq '. + {"observability": {"enabled": true, "head_sampling_rate": 1}}' > "$TMP_FILE"
    safe_write_wrangler "$TMP_FILE"
    echo -e "  ${GREEN}βœ“ Observability enabled${NC}"
  else
    echo -e "  ${YELLOW}Warning: jq not found. Please manually add to $WRANGLER_FILE:${NC}"
    echo '    "observability": {'
    echo '      "enabled": true,'
    echo '      "head_sampling_rate": 1'
    echo '    }'
  fi
fi

# Step 2: Set up Analytics Engine
if [ "$ANALYTICS_ONLY" = true ] || [ "$WITH_TAIL_WORKER" = false ]; then
  echo ""
  echo -e "${YELLOW}Step 2: Setting up Analytics Engine...${NC}"

  if grep -q '"analytics_engine_datasets"' "$WRANGLER_FILE"; then
    echo "  Analytics Engine already configured"
  else
    DATASET_NAME="${WORKER_NAME//-/_}_metrics"
    echo "  Dataset name: $DATASET_NAME"

    if command -v jq &> /dev/null; then
      TMP_FILE=$(mktemp)
      stripped_wrangler | jq --arg dataset "$DATASET_NAME" '. + {"analytics_engine_datasets": [{"binding": "ANALYTICS", "dataset": $dataset}]}' > "$TMP_FILE"
      safe_write_wrangler "$TMP_FILE"
      echo -e "  ${GREEN}βœ“ Analytics Engine configured${NC}"
    else
      echo -e "  ${YELLOW}Warning: jq not found. Please manually add to $WRANGLER_FILE:${NC}"
      echo '    "analytics_engine_datasets": ['
      echo '      {'
      echo '        "binding": "ANALYTICS",'
      echo "        \"dataset\": \"$DATASET_NAME\""
      echo '      }'
      echo '    ]'
    fi
  fi
fi

# Step 3: Create Tail Worker (if requested)
if [ "$WITH_TAIL_WORKER" = true ]; then
  echo ""
  echo -e "${YELLOW}Step 3: Creating Tail Worker...${NC}"

  # Create tail worker directory
  TAIL_WORKER_DIR="workers/$TAIL_WORKER_NAME"
  mkdir -p "$TAIL_WORKER_DIR/src"

  # D-010: back up existing files before overwriting (only if they exist).
  backup_if_exists "$TAIL_WORKER_DIR/wrangler.jsonc"
  backup_if_exists "$TAIL_WORKER_DIR/src/index.ts"

  # Create tail worker wrangler.jsonc
  cat > "$TAIL_WORKER_DIR/wrangler.jsonc" << EOF
{
  "name": "$TAIL_WORKER_NAME",
  "main": "src/index.ts",
  "compatibility_date": "2024-01-01",
  "kv_namespaces": [
    {
      "binding": "KV",
      "id": "YOUR_KV_NAMESPACE_ID"
    }
  ]
}
EOF

  # Create basic tail worker
  cat > "$TAIL_WORKER_DIR/src/index.ts" << 'EOF'
interface TailEvent {
  scriptName: string;
  event: {
    request?: { url: string; method: string };
    response?: { status: number };
  };
  logs: Array<{ level: string; message: unknown[]; timestamp: number }>;
  exceptions: Array<{ name: string; message: string; timestamp: number }>;
  outcome: string;
  eventTimestamp: number;
}

interface Env {
  KV: KVNamespace;
  SLACK_WEBHOOK?: string;
}

export default {
  async tail(events: TailEvent[], env: Env): Promise<void> {
    // Filter for errors and exceptions
    const errorEvents = events.filter(
      (e) =>
        e.outcome !== 'ok' ||
        e.exceptions.length > 0 ||
        e.logs.some((l) => l.level === 'error')
    );

    if (errorEvents.length === 0) return;

    // Forward to external service or alert
    for (const event of errorEvents) {
      console.log(JSON.stringify({
        worker: event.scriptName,
        outcome: event.outcome,
        exceptions: event.exceptions,
        errors: event.logs.filter((l) => l.level === 'error'),
      }));

      // Optional: Send to Slack
      if (env.SLACK_WEBHOOK) {
        await sendSlackAlert(event, env.SLACK_WEBHOOK);
      }
    }
  },
};

async function sendSlackAlert(event: TailEvent, webhookUrl: string): Promise<void> {
  const exception = event.exceptions[0];

  await fetch(webhookUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `🚨 Worker Error: ${event.scriptName}`,
      blocks: [
        {
          type: 'section',
          fields: [
            { type: 'mrkdwn', text: `*Worker:* ${event.scriptName}` },
            { type: 'mrkdwn', text: `*Outcome:* ${event.outcome}` },
          ],
        },
        exception && {
          type: 'section',
          text: { type: 'mrkdwn', text: `*Error:* \`${exception.name}: ${exception.message}\`` },
        },
      ].filter(Boolean),
    }),
  });
}
EOF

  echo -e "  ${GREEN}βœ“ Tail Worker created at $TAIL_WORKER_DIR${NC}"

  # Add tail_consumers to main worker
  echo ""
  echo -e "${YELLOW}Step 4: Configuring tail consumer...${NC}"

  if grep -q '"tail_consumers"' "$WRANGLER_FILE"; then
    echo "  Tail consumers already configured"
  else
    if command -v jq &> /dev/null; then
      TMP_FILE=$(mktemp)
      stripped_wrangler | jq --arg name "$TAIL_WORKER_NAME" '. + {"tail_consumers": [{"service": $name}]}' > "$TMP_FILE"
      safe_write_wrangler "$TMP_FILE"
      echo -e "  ${GREEN}βœ“ Tail consumer configured${NC}"
    else
      echo -e "  ${YELLOW}Warning: jq not found. Please manually add to $WRANGLER_FILE:${NC}"
      echo '    "tail_consumers": ['
      echo '      {'
      echo "        \"service\": \"$TAIL_WORKER_NAME\""
      echo '      }'
      echo '    ]'
    fi
  fi

  # Create KV namespace
  echo ""
  echo -e "${YELLOW}Step 5: Creating KV namespace for rate limiting...${NC}"
  echo "  Run: wrangler kv:namespace create \"ALERT_RATE_LIMIT\""
  echo "  Then update KV namespace ID in $TAIL_WORKER_DIR/wrangler.jsonc"
fi

# Summary
echo ""
echo -e "${BLUE}========================================"
echo "Setup Complete!"
echo -e "========================================${NC}"
echo ""
echo "Next steps:"
echo "  1. Deploy your worker: wrangler deploy"
if [ "$WITH_TAIL_WORKER" = true ]; then
  echo "  2. Deploy tail worker: cd $TAIL_WORKER_DIR && wrangler deploy"
  echo "  3. Create KV namespace: wrangler kv:namespace create \"ALERT_RATE_LIMIT\""
fi
echo ""
echo "View logs:"
echo "  β€’ Real-time: wrangler tail"
echo "  β€’ Dashboard: https://dash.cloudflare.com β†’ Workers β†’ $WORKER_NAME β†’ Logs"
echo ""
echo -e "${GREEN}Done!${NC}"
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall