Karakeep

Karakeep Application Monitoring Dashboard

A comprehensive Grafana dashboard for monitoring Karakeep application performance, including HTTP requests, tRPC operations, queue jobs, and application metrics.

📋 Overview

This dashboard provides real-time monitoring and performance analysis of your Karakeep application. Track service health, request performance, queue status, user activity, and resource utilization with detailed insights into both HTTP and tRPC operations.

✨ Features

🎯 Application Health

• Service Status: Real-time UP/DOWN monitoring
• Total Bookmarks: Current bookmark count
• Total Users: Active user tracking
• Queue Jobs: Background job monitoring

🌐 HTTP Performance Metrics

• Request Count: Rate of HTTP requests over time
• Request Duration: Response time analysis
• Request Sum: Cumulative request duration
• Request Bucket: Distribution of request latencies

🔌 tRPC Monitoring

• Request Duration: tRPC operation latency
• Request Count: Rate of tRPC calls
• Request Sum: Total processing time
• Requests Total: Aggregate tRPC operations

📊 Prometheus Scraping Metrics

• Scrape Duration: Time taken to scrape metrics
• Scrape Samples: Number of metrics collected
• Scrape Series Added: New time series tracking
• Sample Relabeling: Post-processing metrics

💾 Resource Monitoring

• Total Asset Size: Storage utilization in bytes
• Queue Status: Background job queue depth

🖼️ Dashboard Structure

The dashboard is organized into four main sections:

Top Row - Key Metrics

HTTP Performance Section

tRPC Operations Section

System & Queue Monitoring

📦 Requirements

Prerequisites

• Grafana: Version 12.0 or higher
• Prometheus: As data source
• Karakeep: Application with Prometheus metrics endpoint

Required Panels

• Stat panel
• Time series panel

🚀 Installation

Method 1: Import via Grafana UI

1. Log in to your Grafana instance
2. Navigate to Dashboards → New → Import
3. Paste the dashboard JSON or upload the JSON file
4. Select your Prometheus data source
5. Click Import

Method 2: Import via Dashboard ID

(If published to Grafana.com)

1. Navigate to Dashboards → New → Import
2. Enter the dashboard ID: XXXXX
3. Click Load
4. Select your Prometheus data source
5. Click Import

⚙️ Configuration

Karakeep Metrics Endpoint

Ensure your Karakeep application exposes Prometheus metrics:

YAML Copy

# Example application configuration
metrics:
  enabled: true
  port: 9090
  path: /metrics

The metrics endpoint should be accessible at:

Copy

http://your-karakeep-instance:9090/metrics

Prometheus Configuration

Add Karakeep as a scrape target in your prometheus.yml:

YAML Copy

scrape_configs:
  - job_name: 'karakeep'
    scrape_interval: 15s
    scrape_timeout: 10s
    static_configs:
      - targets: ['karakeep:9090']
    metrics_path: '/metrics'

For multiple Karakeep instances:

YAML Copy

scrape_configs:
  - job_name: 'karakeep-production'
    scrape_interval: 15s
    static_configs:
      - targets: 
          - 'karakeep-prod-1:9090'
          - 'karakeep-prod-2:9090'
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
        
  - job_name: 'karakeep-staging'
    scrape_interval: 30s
    static_configs:
      - targets: ['karakeep-staging:9090']

Dashboard Variables

The dashboard includes a Job variable that allows filtering by Prometheus job name:

• Variable: $job
• Query: label_values(karakeep_total_bookmarks, job)
• Multi-select: No
• Refresh: On dashboard load

This allows you to switch between different Karakeep deployments (production, staging, etc.).

📊 Metrics Reference

Application Metrics

HTTP Request Metrics

tRPC Metrics

Prometheus Metrics

🎨 Customization

Adjusting Time Windows

Modify the time range for your use case:

JavaScript Copy

// Default: Last 6 hours
"time": {
  "from": "now-6h",
  "to": "now"
}

// For daily analysis
"time": {
  "from": "now-24h",
  "to": "now"
}

// For weekly trends
"time": {
  "from": "now-7d",
  "to": "now"
}

Adding Custom Panels

Example: Add a panel for bookmark creation rate:

YAML Copy

- title: "Bookmark Creation Rate"
  type: timeseries
  targets:
    - expr: rate(karakeep_total_bookmarks[5m])
      legendFormat: "Creation Rate"

Modifying Status Colors

Edit the Status panel thresholds:

1. Click on Status panel → Edit
2. Navigate to Field → Mappings
3. Adjust colors:
   • 0 (DOWN): Red (semi-dark-red)
   • 1 (UP): Green (semi-dark-green)

Setting up Alerts

Create alerts based on metrics:

YAML Copy

# Example: Alert when service is down
- alert: KarakeepServiceDown
  expr: up{job="karakeep"} == 0
  for: 1m
  annotations:
    summary: "Karakeep service is down"
    
# Example: High request latency
- alert: HighRequestLatency
  expr: rate(karakeep_http_request_duration_seconds_sum[5m]) > 1
  for: 5m
  annotations:
    summary: "High HTTP request latency detected"

🔧 Troubleshooting

No Data Displayed

1. Verify metrics endpoint is accessible:

   Bash Copy

   curl http://karakeep:9090/metrics

2. Check Prometheus is scraping:

   • Go to Prometheus UI → Status → Targets
   • Verify karakeep target is UP
   • Check for scrape errors

3. Verify metric names:

   promql Copy

   # In Prometheus UI, query:
   {job="karakeep"}

Status Shows DOWN

If the service appears DOWN but is running:

1. Check the up metric:

   promql Copy

   up{job="karakeep"}

2. Verify Prometheus can reach the endpoint

3. Check firewall rules

4. Review Prometheus logs for connection errors

High Queue Job Count

If queue jobs are accumulating:

1. Check worker status
2. Review application logs
3. Monitor system resources (CPU, memory)
4. Consider scaling workers

Missing tRPC Metrics

If tRPC panels show no data:

1. Verify tRPC instrumentation is enabled in Karakeep
2. Check if tRPC endpoints are being called
3. Ensure metrics are properly exported

📈 Performance Analysis

Request Rate Analysis

Calculate requests per second:

promql Copy

rate(karakeep_http_requests_total[5m])

Average Response Time

Calculate average HTTP response time:

promql Copy

rate(karakeep_http_request_duration_seconds_sum[5m]) 
/ 
rate(karakeep_http_request_duration_seconds_count[5m])

95th Percentile Latency

promql Copy

histogram_quantile(0.95, 
  rate(karakeep_http_request_duration_seconds_bucket[5m])
)

Queue Processing Rate

Monitor how fast jobs are processed:

promql Copy

rate(karakeep_queue_jobs[5m])

💡 Best Practices

Monitoring Strategy

1. Baseline Establishment: Run for 1-2 weeks to establish normal patterns
2. Set Realistic Thresholds: Base alerts on your baseline ±30%
3. Monitor Trends: Look for gradual degradation over time
4. Correlate Metrics: Cross-reference HTTP and tRPC metrics

Alert Recommendations

Create alerts for:

• Service Down: up == 0 for > 1 minute
• High Latency: P95 > 2 seconds for > 5 minutes
• Queue Buildup: Queue jobs > 1000 for > 10 minutes
• High Error Rate: Error rate > 5% for > 5 minutes
• Storage Growth: Asset size increasing > 10% per day

Performance Optimization

Monitor these indicators:

1. HTTP Request Duration: Should be < 500ms for most endpoints
2. tRPC Latency: Should be < 200ms for API calls
3. Queue Jobs: Should trend toward 0 during off-peak hours
4. Scrape Duration: Should be < 1 second

📝 Use Cases

Development & Debugging

• Identify slow endpoints
• Monitor request patterns during testing
• Track resource usage during development

Production Monitoring

• Real-time service health monitoring
• Performance regression detection
• Capacity planning based on growth trends

Incident Response

• Quick identification of performance issues
• Historical data for root cause analysis
• Correlation between different metrics

Capacity Planning

• Track user growth trends
• Monitor storage utilization
• Plan infrastructure scaling

🤝 Contributing

Contributions are welcome! Areas for enhancement:

1. Additional application-specific metrics
2. Custom alert rule templates
3. Enhanced visualization options
4. Integration with other monitoring tools

To contribute:

1. Fork the repository
2. Create your feature branch
3. Submit a pull request with clear description

📝 Changelog

Version 1.0.0 (2024)

• Initial release
• Service health monitoring
• HTTP and tRPC metrics
• Queue job tracking
• User and bookmark statistics
• Prometheus scraping metrics
• Asset storage monitoring

📄 License

This dashboard is released under the MIT License.

🔗 Links

Documentation

• Grafana Documentation
• Prometheus Documentation
• Prometheus Best Practices

Tools

• Karakeep Project
• Prometheus Node Exporter
• Grafana Alerting

Community

• Grafana Community Forums
• Prometheus Community

💬 Support

For issues or questions:

• Check Karakeep documentation
• Open an issue on GitHub
• Visit the Grafana community forums
• Review Prometheus metrics troubleshooting guide

🙏 Acknowledgments

• Karakeep development team for metrics instrumentation
• Prometheus and Grafana communities
• Contributors to monitoring best practices

⚠️ Important Notes

Metric Retention

Configure appropriate retention in Prometheus:

YAML Copy

# prometheus.yml
storage:
  tsdb:
    retention.time: 30d  # Adjust based on needs
    retention.size: 50GB

Scrape Intervals

Balance between data granularity and resource usage:

• Production: 15s interval
• Staging: 30s interval
• Development: 60s interval

Resource Considerations

Monitor Prometheus resource usage:

• CPU: Increases with cardinality
• Memory: ~2-3 bytes per time series
• Disk: Depends on retention and cardinality

Monitor your Karakeep application effectively! 📊🚀💾