Flashduty CLI Source Management and Error Tracking

Overview

Flashduty CLI is a command line tool forked from datadog-cli that allows users to upload sourcemap files to the Flashduty server. Through sourcemaps, frontend developers can track and debug errors more efficiently. Users can view uploaded sourcemap files in the "Application Management" - "Source Management" menu, and generate scripts for local execution through the upload panel. This document will provide detailed information about the purpose of sourcemaps, methods for generating and uploading them, management approaches, and how to use sourcemaps in the error tracking module to precisely locate issues.

Why Do We Need SourceMaps?

In modern frontend development, JavaScript and CSS files are often compressed and minified to optimize loading speed and performance. However, this compression makes it difficult to trace error locations (such as line and column numbers) in the original source code, increasing debugging difficulty. SourceMap files solve this problem:

Mapping Minified Code to Source Code: SourceMaps record the mapping relationship between compressed code and original code, allowing developers to view uncompressed source code during debugging.

Precise Error Location: Through SourceMaps, you can directly locate specific positions in the original source code when tracking errors, not just in the compressed files.

Improved Debugging Efficiency: Developers don't need to manually decode compressed files, saving time in troubleshooting.

How to Generate and Upload SourceMaps?

Generating SourceMaps

Most modern build tools (such as Webpack, Rollup, or Vite) support generating SourceMaps. Here's an example configuration using Webpack:

Enable SourceMap generation in webpack.config.js:

After building, the dist directory will contain bundle.js and its corresponding bundle.js.map file.

Uploading SourceMaps Using Flashduty CLI

Flashduty CLI provides the sourcemaps command for uploading sourcemap files to the Flashduty server. Here are the specific steps:

Install Flashduty CLI

Ensure Node.js is installed, then install flashcat-cli via npm:

Configure API Key and Service Information

In the Application Management - Source Management menu, click the "Upload Source" panel, fill in the following information, and generate an upload script:

API Key: Used to authenticate your identity (e.g., test2).

Service Name: The service name of your application (e.g., my-service).

Version Number: The release version of your application (e.g., 1.0.0).

Minified File Prefix: The path prefix for compressed files (e.g., /assets).

Example generated script:

Execute Upload

Run the generated script in your project root directory, ensuring the sourcemap files are located in the specified path (such as the dist directory). Flashduty CLI will upload the sourcemap files to the server.

Note:

Ensure the minified-path-prefix matches the actual deployed path of your compressed files.

After successful upload, you can view the uploaded sourcemap files in Application Management - Source Management.

How to Manage SourceMaps?

On the Flashduty platform, sourcemap files are managed through the Application Management - Source Management menu:

View Uploaded SourceMaps: The menu lists all uploaded sourcemap files, including file paths, service names, version numbers, sizes, and upload times.

Version Management: Through the service and release-version parameters, you can manage sourcemaps for different versions of your application, facilitating parallel debugging across multiple versions.

Permission Control: Through the API Key, only authorized users can upload or manage sourcemaps.

How to View Source Code in the Error Tracking Module?

Flashduty RUM (Real User Monitoring) integrates sourcemap functionality, supporting direct viewing of original source code in the error tracking module for precise issue location. Here's the workflow:

Capture Frontend Errors

Flashduty RUM SDK automatically captures frontend errors (such as JavaScript exceptions, Promise rejections, network errors, etc.) and sends error stack information to the server.

Example: Automatically capture unhandled exceptions

Associate SourceMaps

When the file paths and line numbers in the error stack match with uploaded sourcemaps, Flashduty automatically maps the error location in compressed code to the original source code.

For example, an error stack from compressed file /assets/index-5e0391ac.js:

Error: Something went wrong
    at Object.<anonymous> (/assets/index-5e0391ac.js:1:123)

Through sourcemap, mapped to original source code src/components/App.js:

Error: Something went wrong
    at App.render (src/components/App.js:45:10)

View Error Details

In the Flashduty error tracking module, click on a specific error record to view the following information:

Error Message: Such as Something went wrong.

Original Stack: Mapped source code file paths, line numbers, and column numbers (e.g., src/components/App.js:45:10).

Context Code: Displays source code snippets around the error location, facilitating quick problem identification.

Debug and Fix

Based on the mapped source code location, developers can directly find the corresponding code in their local development environment, analyze the root cause, and fix the issue.

Best Practices

Standardize SourceMap Upload:

Integrate the flashcat-cli sourcemaps upload command into your CI/CD pipeline to ensure automatic upload of sourcemaps with each release.

Example (GitHub Actions):

Version Management:

Use the --release-version parameter consistent with your application version number for easier tracking of specific sourcemap versions.

Clean Source Code:

Delete sourcemap files before uploading resources to CDN to avoid including source code information in the production environment.

Test Mapping Effect:

After uploading sourcemaps, proactively throw test errors to verify if the error tracking module can correctly map to source code.

Common Issues

1. Why isn't the error stack mapping to source code?

Confirm that sourcemaps were successfully uploaded and that the minified-path-prefix matches the actual deployment path.

Check if the service and release-version match the application version when the error occurred.

2. How to prevent SourceMaps from leaking sensitive information?

Ensure sourcemap files are only uploaded to the Flashduty server and not directly exposed on the public internet.

In production environments, remove direct access to sourcemap files (e.g., through Nginx configuration).

3. What if uploading SourceMaps fails?

Check if the API Key is valid.

Ensure network connection is normal and the CLI version is up-to-date.

Next Steps

Error Grouping

Issue Status

Source Mapping

Flashduty CLI Source Management and Error Tracking#

Overview#

Why Do We Need SourceMaps?#

How to Generate and Upload SourceMaps?#

Generating SourceMaps#

Uploading SourceMaps Using Flashduty CLI#

How to Manage SourceMaps?#

How to View Source Code in the Error Tracking Module?#

Best Practices#

Common Issues#

1. Why isn't the error stack mapping to source code?#

2. How to prevent SourceMaps from leaking sensitive information?#

3. What if uploading SourceMaps fails?#

Next Steps#