secondsky/claude-skills / plugins/cloudflare-workers/skills/cloudflare-workers-observability
cloudflare-workers-observability
VerifiedCloudflare 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.0 KB |
| references/alerting.md | markdown | 10.1 KB |
| references/analytics-engine.md | markdown | 7.3 KB |
| references/custom-metrics.md | markdown | 8.4 KB |
| references/logging.md | markdown | 7.6 KB |
| references/tail-workers.md | markdown | 8.8 KB |
| scripts/analyze-logs.sh | script | 8.5 KB |
| scripts/setup-logging.sh | script | 10.1 KB |
| templates/analytics-worker.ts | script | 8.3 KB |
| templates/logging-setup.ts | script | 7.1 KB |
| templates/tail-worker.ts | script | 10.0 KB |
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}"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |