botserver/templates/platform/analytics.gbai/README.md

Platform Analytics Template (analytics.gbai)

A General Bots template for platform metrics, performance monitoring, and custom report generation.

Overview

The Analytics template provides comprehensive platform analytics capabilities, allowing administrators and stakeholders to monitor usage, track performance, analyze trends, and generate custom reports through conversational AI.

Features

• Platform Overview - Key metrics summary with trend analysis
• Message Analytics - Conversation statistics by channel and bot
• User Analytics - Active users, sessions, and engagement
• Performance Metrics - Response times and throughput monitoring
• LLM Usage Tracking - Token consumption and cost analysis
• Storage Analytics - Disk usage and file statistics
• Error Analysis - Error patterns and troubleshooting insights
• Custom Report Generator - Build and schedule personalized reports
• AI-Powered Insights - Automatic trend analysis and recommendations

Package Structure

analytics.gbai/
├── README.md
├── analytics.gbdialog/
│   ├── start.bas              # Main menu and navigation
│   ├── platform-overview.bas  # Key metrics dashboard
│   └── custom-report.bas      # Custom report builder
└── analytics.gbot/
    └── config.csv             # Bot configuration

Scripts

File	Description
start.bas	Main entry point with analytics menu options
platform-overview.bas	Platform-wide metrics with trends and export
custom-report.bas	Interactive custom report generator with scheduling

Available Analytics

1. Platform Overview

High-level metrics summary including:

• Total messages and trend percentage
• Average active sessions
• Response time performance
• Error rates
• LLM token consumption

2. Message Analytics

• Message volume by time period
• Breakdown by channel (WhatsApp, Web, API)
• Bot-specific conversation stats
• Peak usage times

3. User Analytics

• Active users (daily, weekly, monthly)
• Session duration analysis
• User retention rates
• Geographic distribution

4. Performance Metrics

• Average response time
• Response time distribution
• Throughput (messages per second)
• Latency percentiles (p50, p95, p99)

5. LLM Usage

• Token consumption by model
• Cost analysis
• Usage patterns
• Optimization recommendations

6. Storage Analytics

• Disk usage trends
• File count and types
• Storage by bot/package
• Cleanup recommendations

7. Error Analysis

• Error frequency and patterns
• Error categorization
• Root cause analysis
• Resolution suggestions

8. Custom Reports

• Select metrics to include
• Choose time ranges
• Set grouping intervals
• Export in multiple formats
• Schedule automatic delivery

Usage

Starting Analytics

User: Show me analytics
Bot: Welcome to the Analytics Center. I can help you understand your platform metrics and generate reports.

What would you like to analyze?
1. Platform Overview - Key metrics summary
2. Message Analytics - Conversation statistics
3. User Analytics - Active users and sessions
4. Performance Metrics - Response times and throughput
5. LLM Usage - Token consumption and costs
6. Storage Analytics - Disk usage and file statistics
7. Error Analysis - Error patterns and trends
8. Generate Custom Report

Platform Overview

User: 1
Bot: Generating platform overview...
     Select time range (1h, 6h, 24h, 7d, 30d): 24h

     Platform Overview for 24h
     
     📊 Messages
       Total: 15,432
       Trend: +12.5%
     
     👥 Sessions
       Average Active: 234
       Trend: +5.2%
     
     ⚡ Performance
       Avg Response Time: 145 ms
     
     ❌ Errors
       Total: 23
       Error Rate: 0.15%
     
     🤖 LLM Usage
       Total Tokens: 1,245,678

Custom Report Generation

User: I need a custom report
Bot: Custom Report Generator
     What would you like to name this report?

User: Weekly Performance Summary

Bot: Select the time range for your report:
     1. Last Hour
     2. Last 24 Hours
     3. Last 7 Days
     4. Last 30 Days
     5. Last 90 Days
     6. Custom Range

User: 3

Bot: Select metrics to include (enter numbers separated by commas):
     1. Message Volume
     2. Active Sessions
     3. Response Time
     4. LLM Token Usage
     5. Error Rate
     ...

User: 1,3,4,5

Bot: Select grouping interval:
     1. Hourly
     2. Daily
     3. Weekly
     4. Monthly

User: 2

Bot: Generating your custom report...
     
     Report generated successfully.
     Report Name: Weekly Performance Summary
     Time Range: Last 7 Days
     Download: https://example.com/reports/report_xxx.pdf
     
     Would you like to receive this report via email?

Metrics Query System

The template uses a metrics query system:

' Query metrics for a time range
messages = QUERY METRICS "messages" FOR "24h"
totalMessages = SUM(messages, "count")

' Query with grouping
hourlyMessages = QUERY METRICS "messages" FOR "24h" BY "1h"

' Query with offset for comparison
prevMessages = QUERY METRICS "messages" FOR "24h" OFFSET 1
trend = ((totalMessages - SUM(prevMessages, "count")) / SUM(prevMessages, "count")) * 100

Export Formats

Reports can be exported in multiple formats:

Format	Description
PDF	Formatted report with charts
XLSX	Excel spreadsheet
CSV	Raw data export
JSON	Structured data format

Scheduled Reports

Configure automatic report delivery:

Schedule	Cron Expression	Description
Daily	0 8 * * *	Every day at 8 AM
Weekly	0 8 * * 1	Monday at 8 AM
Monthly	0 8 1 * *	1st of month at 8 AM

SET SCHEDULE "0 8 * * 1", "generate-scheduled-report.bas"

Configuration

Configure in analytics.gbot/config.csv:

Parameter	Description	Example
Default Time Range	Default period for queries	7d
Data Retention Days	How long to keep metrics	90
Admin Email	Email for scheduled reports	admin@company.com
Enable AI Insights	Auto-generate insights	true
Export Path	Report storage location	/reports/

Customization

Adding Custom Metrics

' Track custom events
INSERT INTO "custom_metrics" VALUES {
    "name": "feature_usage",
    "value": 1,
    "tags": {"feature": "chat", "plan": "pro"},
    "timestamp": NOW()
}

' Query custom metrics
usage = QUERY METRICS "feature_usage" FOR "30d" WHERE tags.feature = "chat"

Custom Dashboard Widgets

' Add to start.bas
TALK "Custom Metrics:"
TALK "9. Feature Usage"
TALK "10. Revenue Analytics"
TALK "11. Customer Health Score"

' Handle custom options
CASE 9
    CALL "feature-usage.bas"
CASE 10
    CALL "revenue-analytics.bas"

AI-Powered Insights

' Generate AI insights from metrics
SET CONTEXT "You are an analytics expert. Generate executive insights from this data."

insights = LLM "Analyze this platform data and provide 3-5 key insights: " + JSON(report_data)

Integration

With Alerting

' Set up alerts based on metrics
errorRate = SUM(errors, "count") / SUM(messages, "count") * 100

IF errorRate > 5 THEN
    SEND EMAIL admin_email, "High Error Rate Alert", 
        "Error rate is " + errorRate + "%, above 5% threshold."
END IF

With External BI Tools

' Export data for external tools
data = QUERY METRICS "messages" FOR "30d" BY "1d"
WRITE "analytics_export.csv", CSV(data)

' Or send to webhook
POST "https://bi-tool.example.com/webhook", data

Best Practices

1. Set appropriate time ranges - Don't query more data than needed
2. Use caching - Cache expensive queries
3. Schedule off-peak - Run heavy reports during low traffic
4. Monitor the monitor - Track analytics query performance
5. Archive old data - Move historical data to cold storage
6. Validate insights - Review AI-generated insights for accuracy

Troubleshooting

Issue	Cause	Solution
Slow queries	Large time range	Reduce time range or add filters
Missing data	Metrics not being collected	Verify instrumentation
Export fails	Large report size	Export in chunks or use CSV
Stale data	Cache not refreshed	Clear cache or reduce TTL
Incorrect trends	Insufficient historical data	Wait for more data collection

Related Templates

• bi.gbai - Business Intelligence reporting
• talk-to-data.gbai - Natural language data queries
• crm.gbai - CRM analytics and pipeline reports

Use Cases

• Operations Teams - Monitor platform health and performance
• Product Managers - Track feature usage and engagement
• Executives - High-level KPI dashboards
• Support Teams - Identify error patterns
• Finance - LLM cost tracking and optimization

Data Privacy

• Analytics data is aggregated and anonymized
• User-level data requires appropriate permissions
• Respect data retention policies
• Comply with GDPR/CCPA as applicable

License

AGPL-3.0 - Part of General Bots Open Source Platform.

---

Pragmatismo - General Bots