usage-tracker

name	usage-tracker
version	1.0.0
description	Track and analyze usage metrics with timestamped logging
author	workspace-hub
category	bash
tags	["bash","metrics","logging","analytics","tracking","reporting"]
platforms	["linux","macos"]

Usage Tracker

Patterns for tracking usage metrics, generating reports, and analyzing trends. Extracted from workspace-hub's Claude usage monitoring system.

When to Use This Skill

✅ Use when:

• Need to track tool/resource usage over time
• Generating usage reports (daily, weekly, monthly)
• Monitoring quotas or limits
• Analyzing usage patterns
• Building dashboards

❌ Avoid when:

• Real-time metrics (use proper monitoring tools)
• High-frequency events (>100/second)
• Sensitive data without encryption

Core Capabilities

1. Basic Usage Logging

Pipe-delimited log format for easy parsing:

#!/bin/bash
# ABOUTME: Basic usage tracking with timestamped logs
# ABOUTME: Pattern from workspace-hub check_claude_usage.sh

# Configuration
USAGE_LOG="${HOME}/.workspace-hub/usage.log"
USAGE_DIR="$(dirname "$USAGE_LOG")"

# Ensure directory exists
mkdir -p "$USAGE_DIR"

# Initialize log if needed
if [[ ! -f "$USAGE_LOG" ]]; then
    cat > "$USAGE_LOG" << EOF
# Usage Log
# Format: TIMESTAMP|CATEGORY|ITEM|VALUE|METADATA
# Created: $(date)
EOF
fi

# Log a usage event
log_usage() {
    local category="$1"
    local item="$2"
    local value="${3:-1}"
    local metadata="${4:-}"
    local timestamp=$(date '+%Y-%m-%d_%H:%M:%S')

    echo "${timestamp}|${category}|${item}|${value}|${metadata}" >> "$USAGE_LOG"
}

# Examples
log_usage    
log_usage    
log_usage    
log_usage    

2. Usage Aggregation

Aggregate usage by time period:

#!/bin/bash
# ABOUTME: Usage aggregation functions
# ABOUTME: Summarize by day, week, month

# Get usage for a specific period
get_usage_period() {
    local period="$1"  # today, week, month
    local category="${2:-}"
    local filter_date

    case "$period" in
        today)
            filter_date=$(date +%Y-%m-%d)
            ;;
        week)
            filter_date=$(date -d '7 days ago' +%Y-%m-%d)
            ;;
        month)
            filter_date=$(date -d '30 days ago' +%Y-%m-%d)
            ;;
        *)
            filter_date=$(date +%Y-%m-%d)
            ;;
    esac

    if [[ -n "$category" ]]; then
        grep "$filter_date" "$USAGE_LOG" 2>/dev/null | grep "|${category}|" || true
    else
        grep "$filter_date" "$USAGE_LOG" 2>/dev/null || true
    fi
}

# Count usage by category
count_by_category() {
    local period="$1"

    get_usage_period  | \
        awk -F  | \
         -k2 -nr
}


() {
     period=
     category=

    get_usage_period   | \
        awk -F  | \
         -k2 -nr
}


() {
     period=
     category=

    get_usage_period   | \
        awk -F 
}

3. Usage Summary Reports

Generate human-readable reports:

#!/bin/bash
# ABOUTME: Usage summary report generation
# ABOUTME: Pattern from check_claude_usage.sh

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

# Generate usage summary
generate_summary() {
    local period="${1:-today}"

    # Get counts
    local opus_count=$(count_by_item "$period" "model" | grep opus | awk '{print $2}')
    local sonnet_count=$(count_by_item "$period" "model" | grep sonnet | awk '{print $2}')
    local haiku_count=$(count_by_item "$period" "model" | grep haiku | awk '{print $2}')

    opus_count=${opus_count:-0}
    sonnet_count=${sonnet_count:-0}
    haiku_count=${haiku_count:-0}

    local total=$((opus_count + sonnet_count + haiku_count))

    if [[ $total -eq 0 ]]; then
        echo -e "${YELLOW}No usage recorded for $period${NC}"
        return
    fi

    # Calculate percentages
    local opus_pct=$((opus_count *  / total))
     sonnet_pct=$((sonnet_count *  / total))
     haiku_pct=$((haiku_count *  / total))

    
     -e 
     -e 
     -e 
     
     -e 
     
     -e 
     -e 
     -e 
     

    
     [[  -gt 50 ]]; 
         -e 
         -e 
         
    

     [[  -lt 20 ]]; 
         -e 
         -e 
         
    

     -e 
     -e 
     -e 
     -e 
}

4. Threshold Monitoring

Monitor against limits and thresholds:

#!/bin/bash
# ABOUTME: Threshold monitoring with alerts
# ABOUTME: Check usage against limits

# Thresholds
declare -A THRESHOLDS=(
    ["opus_daily"]=50
    ["sonnet_daily"]=100
    ["haiku_daily"]=200
    ["total_daily"]=250
    ["warning_pct"]=70
    ["critical_pct"]=90
)

# Check single threshold
check_threshold() {
    local current="$1"
    local limit="$2"
    local name="$3"

    if [[ $limit -eq 0 ]]; then
        return 0
    fi

    local pct=$((current * 100 / limit))

    if [[ $pct -ge ${THRESHOLDS[critical_pct]} ]]; then
        echo -e "${RED}⚠️  CRITICAL: $name at ${pct}% (${current}/${limit})${NC}"
        return 2
    elif [[ $pct -ge ${THRESHOLDS[warning_pct]} ]]; then
        echo -e "${YELLOW}⚠️  WARNING:  at % (/)"
         1
    
         -e 
         0
    
}


() {
     period=
     status=0

     -e 
     

     opus=$(count_by_item   | grep opus | awk )
     sonnet=$(count_by_item   | grep sonnet | awk )
     haiku=$(count_by_item   | grep haiku | awk )
     total=$(( +  + ))

    check_threshold    || status=$?
    check_threshold    || status=$?
    check_threshold    || status=$?
    check_threshold    || status=$?

     
}

5. Trend Analysis

Analyze usage trends over time:

#!/bin/bash
# ABOUTME: Usage trend analysis
# ABOUTME: Compare periods and identify patterns

# Get daily totals for last N days
get_daily_trend() {
    local days="${1:-7}"
    local category="${2:-}"

    for i in $(seq $days -1 0); do
        local date=$(date -d "$i days ago" +%Y-%m-%d)
        local count

        if [[ -n "$category" ]]; then
            count=$(grep "$date" "$USAGE_LOG" 2>/dev/null | \
                    grep "|${category}|" | \
                    awk -F'|' '{sum+=$4} END {print sum+0}')
        else
            count=$(grep "$date" "$USAGE_LOG" 2>/dev/null | \
                    awk -F'|' '{sum+=$4} END {print sum+0}')
        fi

        echo "$date $count"
    done
}

# Calculate moving average
moving_average() {
     window=
     values=()
     =0
     count=0

     val  ; 
        =$((sum + val))
        count=$((count + ))

         [[  -ge  ]]; 
             $((sum / window))
            =$((sum - ))
        
    
}


() {
     days=
     max_width=40

     
     
     

     max_val=0
     -a daily_data

      -r  count; 
        daily_data+=()
        [[  -gt  ]] && max_val=
     < <(get_daily_trend )

    [[  -eq 0 ]] && max_val=1

     entry  ; 
         =
         count=
         bar_len=$((count * max_width / max_val))
         bar=$(  |   )

            
    

     
}

6. Export and Reporting

Export data for external analysis:

#!/bin/bash
# ABOUTME: Export usage data to various formats
# ABOUTME: CSV, JSON, Markdown reports

# Export to CSV
export_csv() {
    local period="${1:-week}"
    local output="${2:-usage_export.csv}"

    echo "timestamp,category,item,value,metadata" > "$output"
    get_usage_period "$period" | tr '|' ',' >> "$output"

    echo "Exported to $output"
}

# Export to JSON
export_json() {
    local period="${1:-week}"
    local output="${2:-usage_export.json}"

    echo "[" > "$output"
    local first=true

    while IFS='|' read -r ts cat item val meta; do
        [[ "$ts" =~ ^#.*$ ]] && continue
        [[ -z "$ts" ]] && continue

        [[ "" ==  ]] &&   >> 
        first=

         >>  << 
     < <(get_usage_period )

      >> 
     
}


() {
     period=
     output=

     >  << 

     i  $( 6 -1 0); 
         =$( -d  +%Y-%m-%d)
         opus=$(grep   | grep  |  -l)
         sonnet=$(grep   | grep  |  -l)
         haiku=$(grep   | grep  |  -l)
         total=$((opus + sonnet + haiku))

          >> 
    

     >>  << 

     
}

Complete Example: Usage Monitor CLI

#!/bin/bash
# ABOUTME: Complete usage monitoring CLI tool
# ABOUTME: Track, analyze, and report on usage metrics

set -e

# ─────────────────────────────────────────────────────────────────
# Configuration
# ─────────────────────────────────────────────────────────────────

SCRIPT_NAME="usage-monitor"
USAGE_DIR="${HOME}/.${SCRIPT_NAME}"
USAGE_LOG="$USAGE_DIR/usage.log"

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

# ─────────────────────────────────────────────────────────────────
# Core Functions
# ─────────────────────────────────────────────────────────────────

init() {
    mkdir -p "$USAGE_DIR"
    [[ -f "$USAGE_LOG" ]] || echo "# Usage Log" > "$USAGE_LOG"
}

log_usage() {
    local category="$1"
    local item="$2"
    local value="${3:-1}"
    local metadata="${4:-}"

    echo  >> 
     -e 
}

() {
     period=

    
      
        today) filter=$( +%Y-%m-%d) ;;
        week)  filter=$( -d  +%Y-%m-%d) ;;
        month) filter=$( -d  +%Y-%m-%d) ;;
    

     -e 
     -e 
     -e 
     

    
     
    grep   2>/dev/null | \
        awk -F  | \
         -k2 -nr

     
     
     -e 
}

() {
     << 
}





init

  
    )
        
        [[  -lt 2 ]] && {  ;  1; }
        log_usage 
        ;;
    summary)
        show_summary 
        ;;
    check)
        check_all_thresholds 
        ;;
    )
          
            csv)  export_csv   ;;
            json) export_json   ;;
        
        ;;
    report)
        generate_markdown_report  
        ;;
    trend)
        display_trend_chart 
        ;;
    |--|-h)
        show_help
        ;;
    *)
        show_help
         1
        ;;

Best Practices

1. Consistent Log Format - Use pipe-delimited for easy parsing
2. Include Timestamps - Always log when events occur
3. Add Metadata - Extra context helps debugging
4. Rotate Logs - Prevent unbounded growth
5. Validate Input - Sanitize before logging

Resources

• awk One-Liners
• sed/awk Tutorial
• Date Manipulation in Bash

---

Version History

• 1.0.0 (2026-01-14): Initial release - extracted from workspace-hub check_claude_usage.sh