Follow these guidelines to get the most out of TraceLog while maintaining good performance and privacy standards.

Initialize Early

Set up TraceLog as soon as possible in your app for complete tracking coverage.

import { TraceLog } from '@tracelog/client';

// Initialize in your main app file
await TraceLog.init({
  id: 'your-project-id'
});

Important: TraceLog.init() can only be called once per page load.

Event Naming

Use clear, descriptive names that make sense to your team.

✅ Good:

TraceLog.event('product_added_to_cart');
TraceLog.event('checkout_completed');
TraceLog.event('user_signed_up');

❌ Avoid:

TraceLog.event('click');
TraceLog.event('event1');
TraceLog.event('user_action');

Naming Convention

Use snake_case with descriptive verbs:

• {object}_{action} - button_clicked, video_played
• {process}_{stage} - checkout_started, signup_completed

Metadata Structure

Keep metadata consistent and meaningful.

✅ Good structure:

TraceLog.event('product_purchased', {
  productId: 'SKU-123',
  category: 'electronics',
  price: 299.99,
  currency: 'USD'
});

❌ Inconsistent structure:

// Don't mix data types for similar events
TraceLog.event('product_purchased', {
  product: 'SKU-123',
  cat: 'electronics',
  cost: '$299.99' // String instead of number
});

Privacy & Security

Never Track Personal Information

Avoid collecting personally identifiable information (PII).

✅ Safe:

TraceLog.event('form_submitted', {
  formType: 'contact',
  fieldCount: 5,
  hasErrors: false
});

❌ Unsafe:

TraceLog.event('form_submitted', {
  email: 'user@example.com', // PII!
  name: 'John Doe' // PII!
});

Remove Sensitive Query Parameters

Configure TraceLog to strip sensitive data from URLs.

TraceLog.init({
  id: 'your-project-id',
  sensitiveQueryParams: [
    'token',
    'password',
    'email',
    'api_key'
  ]
});

Data Limits

Respect TraceLog's built-in limits for optimal performance:

• Event names: 120 characters max
• Metadata: 8KB total per event
• Keys: 10 keys max per event
• Arrays: 10 items max

// Within limits ✅
TraceLog.event('user_signup', {
  source: 'homepage',
  plan: 'premium',
  features: ['analytics', 'api']
});

// Exceeds limits ❌
TraceLog.event('user_performed_extremely_long_action_name_that_goes_beyond_reasonable_character_limits', {
  // Too many keys...
  key1: 'value', key2: 'value', /* ... */ key15: 'value'
});

Environment Setup

Configure TraceLog differently for each environment.

Development

TraceLog.init({
  id: 'dev-project-id',
  allowHttp: true, // Allow localhost
  globalMetadata: {
    environment: 'development'
  }
});

Production

TraceLog.init({
  id: 'prod-project-id',
  globalMetadata: {
    environment: 'production',
    version: '1.2.0'
  }
});

Global Metadata

Use global metadata for data that applies to all events.

TraceLog.init({
  id: 'your-project-id',
  globalMetadata: {
    appVersion: '2.1.0',
    platform: 'web',
    userType: 'premium'
  }
});

Good candidates for global metadata:

• App version
• Environment (dev/staging/prod)
• User segment
• Feature flags
• Platform/device type

Error Handling

Handle TraceLog gracefully in different scenarios.

Browser Detection

// Only initialize in browser environments
if (typeof window !== 'undefined') {
  TraceLog.init({
    id: 'your-project-id'
  });
}

Initialization Safety

try {
  await TraceLog.init({
    id: 'your-project-id'
  });
} catch (error) {
  console.error('Analytics initialization failed:', error);
  // App continues to work without tracking
}

Performance Tips

Use Global Metadata

Instead of repeating the same data in every event:

❌ Inefficient:

TraceLog.event('page_view', { version: '1.0', env: 'prod' });
TraceLog.event('button_click', { version: '1.0', env: 'prod' });

✅ Efficient:

// Set once during initialization
TraceLog.init({
  id: 'your-project-id',
  globalMetadata: { version: '1.0', env: 'prod' }
});

TraceLog.event('page_view');
TraceLog.event('button_click');

Batch Related Events

For related user actions, consider combining into single events:

// Instead of multiple events
TraceLog.event('form_field_focused');
TraceLog.event('form_field_filled');
TraceLog.event('form_submitted');

// Consider single event with details
TraceLog.event('form_interaction', {
  action: 'submitted',
  fieldsCompleted: 5,
  timeSpent: 120
});

Testing & Debugging

Development Logging

TraceLog provides helpful console logs in development mode.

Verify Events

Check your browser's Network tab to confirm events are being sent.

Dashboard Monitoring

Regularly check your TraceLog dashboard to ensure events are being received.

Regular Maintenance

Monthly Reviews

• Audit event names and metadata
• Remove unused events
• Update global metadata
• Check data volume and patterns

Keep Updated

npm update @tracelog/client

Security Practices

• Rotate project IDs if compromised
• Review sensitive query parameters list
• Audit metadata for PII leakage

Common Patterns

E-commerce

// Product interactions
TraceLog.event('product_viewed', {
  productId: 'SKU-123',
  category: 'electronics',
  price: 299.99
});

TraceLog.event('cart_updated', {
  action: 'add',
  productId: 'SKU-123',
  quantity: 1,
  cartTotal: 299.99
});

Content Sites

// Article engagement
TraceLog.event('article_viewed', {
  articleId: 'article-123',
  category: 'technology',
  readTime: 180
});

TraceLog.event('article_shared', {
  articleId: 'article-123',
  platform: 'twitter'
});

SaaS Applications

// Feature usage
TraceLog.event('feature_used', {
  feature: 'dashboard',
  section: 'analytics',
  userPlan: 'premium'
});

TraceLog.event('subscription_changed', {
  from: 'basic',
  to: 'premium',
  billingCycle: 'monthly'
});