ai-tracking
Advanced tools
Comprehensive AI interaction tracking library with advanced analytics and failure monitoring
A comprehensive AI interaction tracking library with advanced analytics and failure monitoring capabilities. This library provides the same functionality as the Raindrop AI SDK but with enhanced customization and extensibility.
npm install ai-tracking
import { AITracker, FailureTracker } from 'ai-tracking';
// Initialize the tracker
const tracker = new AITracker({
apiKey: 'your-api-key-here',
debugLogs: true,
redactPii: true
});
// Initialize failure tracker
const failureTracker = new FailureTracker(tracker);
// Track a chat message
await tracker.trackChatMessage({
userId: 'user-123',
input: 'Hello, how are you?',
output: 'I am doing well, thank you for asking!',
model: 'gpt-4o-mini',
conversationId: 'conv-123'
});
// Track user feedback
await tracker.trackFeedback({
userId: 'user-123',
eventId: 'event-123',
type: 'thumbs_up',
comment: 'Great response!',
sentiment: 'POSITIVE'
});
// Track tool usage
await tracker.trackToolUsage({
userId: 'user-123',
toolName: 'web_search',
input: 'weather in New York',
output: 'Current weather is 72°F and sunny',
success: true,
duration: 1500
});
// Auto-detect failure category
await failureTracker.trackFailure({
userId: 'user-123',
errorMessage: 'API error: Rate limit exceeded',
details: {
statusCode: 429,
retryAfter: 60
}
});
// Manual failure category
await failureTracker.trackFailure({
userId: 'user-123',
errorMessage: 'Custom business logic error',
category: 'business_logic_error',
severity: 'medium',
details: {
ruleViolated: 'user_quota_exceeded',
currentUsage: 95
}
});
new AITracker(config: TrackingConfig)
trackAi(params)Track AI interactions with comprehensive metadata.
await tracker.trackAi({
eventId?: string;
event: string;
userId: string;
model?: string;
input?: string;
output?: string;
properties?: Partial<EventProperties>;
attachments?: Attachment[];
});
trackChatMessage(params)Track chat messages with full conversation context.
await tracker.trackChatMessage({
userId: string;
input: string;
output: string;
model?: string;
conversationId?: string;
properties?: Partial<EventProperties>;
});
trackFeedback(params)Track user feedback and ratings.
await tracker.trackFeedback({
userId: string;
eventId: string;
type: 'thumbs_up' | 'thumbs_down';
comment?: string;
sentiment?: 'POSITIVE' | 'NEGATIVE';
});
trackToolUsage(params)Track AI tool usage and execution.
await tracker.trackToolUsage({
userId: string;
toolName: string;
input: string;
output: string;
success: boolean;
duration?: number;
properties?: Partial<EventProperties>;
});
identify(userId, traits)Identify and profile users with comprehensive traits.
await tracker.identify(userId: string, traits: Partial<UserTraits>);
trackFailure(params)Track individual failure events with auto-detection or manual categorization.
await failureTracker.trackFailure({
userId: string;
errorMessage: string;
category?: string;
severity?: 'critical' | 'high' | 'medium' | 'low';
details?: Record<string, any>;
context?: Record<string, any>;
autoDetected?: boolean;
});
trackFailures(failures)Track multiple failures in batch for efficiency.
await failureTracker.trackFailures(failures: Array<FailureParams>);
getFailureStats()Get comprehensive failure statistics and analytics.
const stats = failureTracker.getFailureStats();
getCriticalFailures()Get critical failures requiring immediate attention.
const critical = failureTracker.getCriticalFailures();
The library tracks the following event types:
chat_message - AI conversation interactionschat_error - Chat processing errorsuser_feedback - User ratings and feedbackfeedback_analytics - Feedback analysis and insightsuser_intent - User behavior and intent analysisuser_behavior - Comprehensive user behavior trackingpage_loaded - Page lifecycle trackingpage_visibility_changed - User engagement trackingpage_before_unload - Session duration trackinguser_typing - Input behavior trackinginput_focused - Interaction engagementuser_scrolled - Content consumption trackingfeedback_submitted - Feedback submission analyticstool_usage - AI tool execution trackingfailure_detected - Failure and error trackinginterface TrackingConfig {
apiKey: string; // Required: Your API key
baseUrl?: string; // API endpoint URL
debugLogs?: boolean; // Enable debug logging
redactPii?: boolean; // Redact personally identifiable information
batchSize?: number; // Events per batch (default: 10)
flushInterval?: number; // Auto-flush interval in ms (default: 5000)
retryAttempts?: number; // Retry attempts for failed requests (default: 3)
timeout?: number; // Request timeout in ms (default: 10000)
}
The library automatically detects and categorizes failures:
Run the comprehensive test suite:
npm test
The test suite includes:
// Get failure statistics
const stats = failureTracker.getFailureStats();
// Check failure rates
const rate = failureTracker.getFailureRate('api_error', 3600000); // 1 hour window
// Get critical failures
const critical = failureTracker.getCriticalFailures();
// Get current queue size
const queueSize = tracker.getQueueSize();
// Manually flush events
await tracker.flush();
// Clear the queue
tracker.clearQueue();
Full TypeScript support with comprehensive type definitions:
import { AITracker, FailureTracker, UserTraits, EventProperties } from 'ai-tracking';
Contributions are welcome! Please feel free to submit a Pull Request.
MIT License - see LICENSE file for details.
For support and questions:
Made with ❤️ for the AI community
FAQs
Comprehensive AI interaction tracking library with advanced analytics and failure monitoring
We found that ai-tracking demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.