PSA/docs/features/analytics-events-reference.md

Analytics Events Reference

This document provides a comprehensive reference of all analytics events tracked in Alga PSA.

Event Categories

1. Authentication Events

Event Name	Description	Properties
user_login	User successfully logs in	method, success
user_logout	User logs out	session_duration_minutes
user_registration	New user registers	method, company_size

2. Ticket Management Events

Event Name	Description	Properties
ticket_created	New ticket created	ticket_type, priority, has_attachments, created_via, has_asset
ticket_updated	Ticket information updated	fields_updated, update_type
ticket_status_changed	Ticket status changed	old_status, new_status
ticket_viewed	Ticket details viewed	ticket_id, status_id, status_name, is_closed, priority_id, category_id, channel_id, assigned_to, company_id, has_comments, comment_count, has_documents, document_count, has_additional_agents, additional_agent_count, has_schedule, total_scheduled_minutes, view_source

3. Time Tracking Events

Event Name	Description	Properties
time_entry_created	New time entry created	duration_minutes, billable, has_notes, entry_method
time_entry_updated	Time entry modified	fields_changed
time_sheet_submitted	Timesheet submitted for approval	total_hours, billable_hours, entries_count, submission_day

4. Billing Events

Event Name	Description	Properties
invoice_generated	Invoice created	invoice_type, line_items_count, has_tax, generation_time_ms
contract_line_created	New contract line created	contract_line_type, billing_frequency, has_custom_rates

5. Performance Metrics

Event Name	Description	Properties
performance_metric	Performance measurement	metric_name, value, unit, additional context
api_request_duration	API endpoint performance	endpoint, method, status_code, duration
feature_load_time	Feature loading performance	feature, duration

6. Feature Adoption Events

Event Name	Description	Properties
feature_used	Feature accessed by user	feature_name, feature_category, first_time
feature_discovered	User discovers new feature	feature_name, discovery_method
feature_enabled	Feature enabled	feature_name
feature_disabled	Feature disabled	feature_name
feature_first_use	First time using a feature	feature_name, feature_category
feature_retention	Continued feature usage	feature_name, retention_period, days_since_first_use

7. User Behavior Events

Event Name	Description	Properties
dashboard_viewed	Dashboard accessed	dashboard_type, widgets_count
power_user_score_calculated	Power user score calculated	score, unique_features_used, advanced_features_used
role_based_usage_pattern	Usage pattern by role	user_role, adoption_rate

8. Error Tracking Events

Event Name	Description	Properties
error_occurred	Error encountered	error_type, error_category, severity

Common Properties

All events include these standard properties:

• deployment_type: 'hosted' or 'on-premise'
• app_version: Current application version
• environment: Current environment (development/production)
• timestamp: Event timestamp
• distinct_id: Anonymized user/instance identifier

Feature Categories

Features are grouped into the following categories:

• ticketing: Ticket management features
• time_tracking: Time entry and timesheet features
• billing: Invoice and billing features
• reporting: Report generation and analytics
• integrations: Third-party integrations
• advanced: Advanced configuration features
• collaboration: Team collaboration features

Privacy Considerations

1. No PII: Events never include personally identifiable information
2. Anonymization: User IDs are hashed for on-premise deployments
3. Opt-out: Users can disable analytics with ALGA_USAGE_STATS=false
4. Data Retention: Events are retained according to PostHog's data retention policy

Testing Events

Test events can be identified by the test_run: true property. These are excluded from production analytics.

Implementation Examples

Tracking Feature Usage

import { featureAdoptionTracker } from '@/lib/analytics/featureAdoption';

// Track when a user uses a feature
featureAdoptionTracker.trackFeatureUsage('invoice_generation', userId, {
  invoice_count: 5,
  template_used: true
});

Tracking Performance

import { analytics } from '@/lib/analytics/posthog';

// Track API performance
analytics.capture('performance_metric', {
  metric_name: 'api_request_duration',
  value: responseTime,
  unit: 'ms',
  endpoint: '/api/tickets',
  method: 'GET',
  status_code: 200
}, userId);

Tracking Errors

analytics.capture('error_occurred', {
  error_type: 'validation_error',
  error_category: 'form_submission',
  severity: 'medium',
  form_name: 'ticket_create'
}, userId);

Dashboard Metrics

Key metrics derived from these events:

1. User Engagement: Daily/Weekly/Monthly active users
2. Feature Adoption: Percentage of users using each feature
3. Performance: P50/P90/P99 response times
4. Error Rate: Errors per user session
5. Power Users: Users with high feature adoption
6. Retention: Feature usage over time