TrackJS - Documentation

Getting Started

Installation

TrackJS integrates seamlessly into your applications via a small JavaScript snippet. The installation method varies slightly depending on your application’s framework and build process. Generally, you’ll need to include the TrackJS script in your HTML, typically within the <head> or just before the closing </body> tag.

For most applications: You’ll obtain your unique application key from your TrackJS dashboard after creating a new application. Then include the following script, replacing YOUR_APPLICATION_KEY with your key:

<script src="https://d16ntop171648.cloudfront.net/trackjs/track.js"></script>
<script>
  trackJs.configure({
    token: 'YOUR_APPLICATION_KEY'
  });
</script>

Using a Package Manager (npm or yarn): While not strictly necessary for basic integration, using a package manager can streamline the process and help manage updates. Currently, there’s no official npm package, but you can still easily use the CDN method above.

Important Considerations: Ensure the TrackJS script is loaded after your main application JavaScript files to ensure proper error capturing. For optimal performance, consider placing it asynchronously (though not strictly required).

Configuration

Beyond the application token, TrackJS offers extensive configuration options allowing customization to your specific needs. These options are set via the trackJs.configure() method. Key configuration settings include:

Example of advanced configuration:

trackJs.configure({
  token: 'YOUR_APPLICATION_KEY',
  application: 'My Awesome App',
  user: { email: 'user@example.com', id: 123 },
  custom: { environment: 'production', version: '1.2.3' },
  console: false,
  samplingRate: 0.1 // 10% sampling
});

Refer to the full API documentation for a complete list of configuration options.

First Application

The simplest application to demonstrate TrackJS is a single HTML file with some JavaScript that intentionally throws an error. Create a file named index.html with the following content:

<!DOCTYPE html>
<html>
<head>
  <title>TrackJS Example</title>
  <script src="https://d16ntop171648.cloudfront.net/trackjs/track.js"></script>
  <script>
    trackJs.configure({ token: 'YOUR_APPLICATION_KEY' });

    function myFunction() {
      throw new Error("This is a test error!");
    }

    myFunction();
  </script>
</head>
<body>
  <h1>TrackJS Example</h1>
</body>
</html>

Replace YOUR_APPLICATION_KEY with your actual key. Open this file in your browser. The error should be caught by TrackJS and displayed in your TrackJS dashboard.

Quick Start Guide

  1. Sign up for a TrackJS account: Create a free account on the TrackJS website.
  2. Create a new application: This will generate your unique application token.
  3. Install the TrackJS snippet: Add the JavaScript snippet provided in the Installation section to your application. Remember to replace the placeholder token with your application token.
  4. Configure (optional): Use the trackJs.configure() method to customize error reporting and add relevant context.
  5. Deploy your application: Deploy your application and trigger some errors.
  6. Monitor errors in your TrackJS dashboard: Log in to your TrackJS dashboard to view, analyze, and debug the captured errors.

Core Concepts

Error Tracking

TrackJS’s core functionality centers around robust error tracking. It captures JavaScript exceptions, AJAX errors, and unhandled promise rejections, providing detailed information to help developers quickly identify and resolve issues. This goes beyond simple stack traces, including:

Performance Monitoring

TrackJS extends beyond error tracking to provide insights into your application’s performance. By monitoring key metrics such as page load times and long tasks, it helps identify performance bottlenecks. This performance monitoring enables you to proactively address slowdowns and improve the user experience. Key features include:

User Session Tracking

While not directly providing a full session recording, TrackJS provides valuable context through user-level data associated with errors and performance issues. By incorporating user identifiers in your configuration, you can see which users experienced particular errors or slowdowns, aiding in understanding user impact and prioritizing fixes. This helps target problem areas related to specific user workflows or segments.

Data Collection

TrackJS collects error and performance data responsibly. The amount of data collected can be controlled via the samplingRate configuration option. Data collected includes:

TrackJS’s privacy policy should be carefully reviewed to understand its data handling practices.

Application Insights

Through the combination of error tracking and performance monitoring, TrackJS provides comprehensive insights into your application’s health and performance. These insights help you:

The dashboard provides various visualizations and filtering options, making it easy to analyze the data and gain valuable insights into your application’s behavior.

API Reference

trackJs.configure()

The core configuration method. Use this to set various options affecting how TrackJS collects and reports data. All options are set as key-value pairs within an object.

Parameters:

Example:

trackJs.configure({
  token: 'YOUR_APPLICATION_KEY',
  application: 'My App',
  user: { id: 123, email: 'user@example.com' }
});

Return Value: undefined

trackJs.add()

This method is generally not recommended for direct use. It’s primarily used internally by TrackJS to manage error contexts and should not be called explicitly by developers.

trackJs.remove()

Similar to trackJs.add(), this method is generally not recommended for direct use and is primarily used internally by TrackJS.

trackJs.notify()

This method allows you to manually send a message to the TrackJS server, useful for logging custom events or application state information. This doesn’t capture an error in the same way as trackJs.capture(), but adds a custom message to the context of your application’s activity.

Parameters:

Example:

trackJs.notify('User logged in', { userId: 123 });

Return Value: undefined

trackJs.capture()

This method allows you to manually capture and report an error to TrackJS. Useful for handling errors that might not be automatically caught by TrackJS’s built-in exception handling.

Parameters:

Example:

try {
  // Some code that might throw an error
} catch (error) {
  trackJs.capture(error, 'Custom error message', {context: 'specific function'});
}

Return Value: undefined

trackJs.send()

This method forces TrackJS to immediately send any pending error reports to the server. Generally, TrackJS handles sending asynchronously, so this method is usually unnecessary. However, it can be useful in situations where you need to guarantee data is sent before closing a connection or unloading a page.

Parameters: None

Example:

trackJs.send();

Return Value: undefined

Event Handling

TrackJS doesn’t directly expose an API for handling specific error events within your application code. Error handling is largely implicit; the library catches and reports errors automatically. The configuration options, including custom data, provide control over what context is included in reports.

Custom Error Handling

While TrackJS automatically captures many errors, you can add custom error handling to provide additional context or to handle specific errors differently. This typically involves using a try...catch block to handle potential errors, adding any relevant information to trackJs.capture() before re-throwing the error (if appropriate):

try {
  // Code that might throw an error
} catch (error) {
  const customData = {
    userInput: document.getElementById('user-input').value,
    action: 'button click'
  };
  trackJs.capture(error, 'Custom Error Context', customData);
  //Optionally rethrow if you want to handle the error in another way.  Consider the implications of rethrowing vs. not.
  //throw error; 
}

Remember that even with custom handling, TrackJS will still attempt to catch any errors that escape your try...catch blocks.

Integrations

TrackJS is designed to be framework-agnostic, working effectively with most JavaScript frameworks. While there isn’t framework-specific SDKs, the core JavaScript snippet integrates easily into most environments. The key is ensuring the TrackJS script is loaded correctly within your application’s lifecycle.

General Approach: The standard integration method involves adding the TrackJS script tag to your HTML, typically within the <head> or before the closing </body> tag.

React, Angular, Vue, etc.: These frameworks typically handle JavaScript loading within their build process. Include the TrackJS script in your HTML template or your main application file according to your framework’s best practices. Pay attention to the timing of the script’s inclusion to ensure it executes after your application’s JavaScript.

Specific Framework Considerations:

Custom Integrations

If you need to integrate TrackJS with a custom system or a less common framework, the flexibility of the TrackJS API allows for considerable customization. You could create a custom wrapper or integrate it into your existing logging or error-handling mechanisms.

The core interaction point is the trackJs.capture() method, which allows you to manually send error information to TrackJS. You can send additional data providing context relevant to your custom environment. This will require a deeper understanding of your system’s architecture and error handling flows.

Server-Side Integrations

TrackJS is primarily focused on client-side JavaScript error tracking. There’s no direct server-side integration provided by TrackJS itself. While you can’t send server-side errors directly to TrackJS, you can integrate your server-side logging with a separate system and potentially correlate server-side events with client-side errors reported by TrackJS via shared identifiers like user IDs or session tokens. This may require custom logic to link server-side error logs and TrackJS data for a holistic view of application behavior.

Advanced Usage

Custom Error Reporting

Beyond the automatic error capture, TrackJS allows for highly customized error reporting. This involves using trackJs.capture() to explicitly report errors, adding context beyond what’s automatically collected. This is crucial for scenarios where you need to include specific data relevant to the application’s state or user interaction that TrackJS might not otherwise capture. Remember that even with custom reporting, TrackJS’s built-in error handling remains active, catching any unhandled exceptions.

Custom Data Attributes

Enrich your error reports with custom data attributes using the custom property in trackJs.configure() or as part of the data parameter in trackJs.capture(). This allows you to include application-specific information crucial for debugging, such as user IDs, session IDs, feature flags, or other relevant contextual details. Careful planning of what data to include is essential, balancing the value of the additional context with data privacy and security considerations.

Filtering and Tagging

TrackJS’s dashboard provides robust filtering capabilities to efficiently analyze error data. You can filter by error message, browser, operating system, application version, and custom attributes. Effectively using custom data attributes (as described above) enhances filtering capabilities, allowing you to isolate errors affecting specific user segments or application features. The ability to effectively tag and filter errors is critical for managing and prioritizing error resolution in complex applications.

User Privacy

Protecting user privacy is paramount. When using TrackJS, carefully consider the data you include in error reports. Avoid including sensitive personal information (PII) such as credit card numbers, social security numbers, or precise geolocation data. If you need to include identifying information, consider using anonymized or hashed versions where possible. Review and comply with all relevant privacy regulations (GDPR, CCPA, etc.) and TrackJS’s own privacy policy.

Data Security

TrackJS employs industry-standard security measures to protect the data it collects. However, it’s essential to be mindful of the security implications of the data you include in error reports. Avoid including sensitive API keys, database credentials, or other security-sensitive information. Use appropriate authentication and authorization mechanisms within your application to prevent unauthorized access to sensitive data. Refer to TrackJS’s security documentation for detailed information on their security practices.

Rate Limiting

To prevent overwhelming the TrackJS servers and to manage data volume, TrackJS may employ rate limiting. While generally not an issue for typical applications, extremely high volumes of errors could trigger rate limiting. If you’re experiencing high error rates, consider using the samplingRate configuration option to reduce the number of errors sent to TrackJS. This reduces the load on the service while still providing a representative sample of errors for analysis. Contact TrackJS support if you believe you are encountering issues due to rate limiting.

Troubleshooting

Common Issues

Debugging Tips

Troubleshooting Errors

When encountering errors, start by examining the details provided in the TrackJS dashboard. Pay close attention to:

If the error is not immediately obvious, use the debugging tips outlined above to investigate further. Refer to the TrackJS documentation and community forums for additional assistance.

Support Resources

Dashboard & Reporting

The TrackJS dashboard provides a central location for monitoring and analyzing your application’s errors and performance. The specific layout might vary slightly over time, but generally, you’ll find sections for:

Navigation typically involves menus, filters, and interactive charts and tables. Familiarize yourself with the dashboard’s interface to effectively utilize its features.

Understanding Reports

TrackJS reports provide summarized views of your application’s error and performance data. Reports often include:

Use reports to identify patterns, trends, and areas for improvement in your application’s reliability and performance.

Error Analysis

Error analysis involves investigating individual errors and identifying root causes. The TrackJS dashboard facilitates this through:

The goal of error analysis is to understand why errors occur, allowing you to develop effective solutions and prevent future issues.

Performance Analysis

Performance analysis focuses on identifying and addressing performance bottlenecks. TrackJS helps with this through:

Performance analysis aims to improve user experience by optimizing your application’s speed and responsiveness.

Custom Dashboards

Some versions of TrackJS might offer the ability to create custom dashboards. This allows you to tailor the dashboard view to your specific needs and preferences. Custom dashboards can focus on particular metrics, errors, or user segments. This feature can significantly improve the efficiency of your monitoring process by focusing on the most critical information for your application. Consult the TrackJS documentation for details on creating and managing custom dashboards if this feature is available in your plan.