Application Real-Time Monitoring Service:Diagnose API errors with front-to-back tracing

Configure ARMS browser monitoring

Same-origin API requests

1. Confirm that a mapping exists between your frontend site and the backend application.

2. Ensure that automatic API reporting is enabled.

3. Set the enableLinkTrace parameter to true to enable front-to-back tracing. The following code shows an example configuration:

   <script>
   !(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxx",imgUrl:"https://arms-retcode.aliyuncs.com/r.png?", enableLinkTrace: true};
   with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
   })(window,document,"https://sdk.rum.aliyuncs.com/v1/bl.js","__bl");
   </script>                         

Cross-origin API requests

1. Confirm that a mapping exists between your frontend site and the backend application.

2. Set the enableLinkTrace and enableApiCors parameters to true.

   <script>
   !(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxx",imgUrl:"https://arms-retcode.aliyuncs.com/r.png?", 
   enableLinkTrace: true, enableApiCors: true};
   with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
   })(window,document,"https://sdk.rum.aliyuncs.com/v1/bl.js","__bl");
   </script>

   Important

   If you set the enableApiCors parameter to true, your backend service must also support cross-origin requests and custom header values. Ensure that all requests work correctly during integration testing. Otherwise, the requests may fail. The following code shows a sample Nginx configuration:

   upstream test {
           server 192.168.220.123:9099;
           server 192.168.220.123:58080;
       }
       server {
           listen    5800;
           server_name  192.168.220.123;
           root         /usr/share/nginx/html;
           include /etc/nginx/default.d/*.conf;
           location / {
               proxy_pass http://test;
               proxy_set_header Host $host:$server_port;
               proxy_set_header X-Real-IP $remote_addr;
               proxy_set_header X-Real-PORT $remote_port;
               proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
               proxy_set_header   EagleEye-TraceID $eagleeye_traceid;
               proxy_set_header   EagleEye-SessionID $eagleEye_sessionid;
               proxy_set_header   EagleEye-pAppName $eagleeye_pappname;
           }

3. To configure ignore, see ignore. The configuration is as follows:

   let whitelist = ['api.xxx','source3']; // Whitelist.
   let blacklist = ['source2','source6']; // Blacklist.
   // Choose between a whitelist or blacklist based on your needs by returning true or false in the function.
   ignore: {
               ignoreApis: [
                   function(str) {   // Function.
                       if (whitelist.includes(str)) {
                           return false;
                       }
                       return true; // Return true to ignore.
                   }]
            }

   Note

   The ignore parameter acts as a whitelist or blacklist. It prevents header modifications for requests to specific third-party resources, which helps avoid request errors.

How it works

• When automatic API reporting is enabled, the SDK adds two custom headers, EagleEye-TraceID and EagleEye-SessionID, to API requests sent to the same origin.

• If the API request is sent to a different origin, the SDK does not add these custom headers. This ensures that the cross-origin request can be sent without errors.

• To verify that the front-to-back tracing configuration is active, open your browser's developer console and inspect the request headers of an API call. If the EagleEye-TraceID and EagleEye-SessionID headers are present, the feature is active.

  Warning

  The values for EagleEye-TraceID and EagleEye-SessionID have specific meanings and are generated automatically. Do not generate them manually.

Use cases and examples

The timeline helps determine if high latency originates from network transport or the backend process. Clicking the method stack for the backend application displays the complete backend invocation trace for the request.

• If an API returns an error code or a business logic error occurs, follow these steps to identify the cause:

  1. Log on to the ARMS console. In the left-side navigation pane, choose Browser Monitoring > Browser Monitoring.

  2. On the Browser Monitoring page, select a region in the top navigation bar and click the name of the application that you want to manage.

  3. In the left-side navigation pane, click API request.

  4. In the API link trace (TOP 20) section on the right, find the relevant API or trace ID in the API failure list and click Managed Service for OpenTelemetry in the Actions column. This opens a view showing the overall frontend time and a timeline of the backend calls.

     The trace results are displayed in a table on the Invocation trace tab. The columns include Application name, Log time, Status, IP address, Invocation type, Service name, Method stack, Thread profiling, and Timeline. In this table, you can view the invocation type (such as Browser or HTTP Entry), status (a red dot indicates an error, a green dot indicates success), and a comparison of the time taken by each span.

  5. Use the timeline to determine whether the high latency is caused by network transport or backend processing.

  6. For the backend application, click the magnifier icon in the Method Stack column to view the complete backend invocation trace for this request. You can then identify the cause of the API error based on your business logic.

     The invocation trace details panel displays a table showing the call hierarchy, line number, extended information, and timeline (in milliseconds) for each method. Method names with unusually high latency are highlighted in red, and the blue bars on the right visualize the time proportion of each method, helping you quickly locate performance bottlenecks.

• If an API request has high latency, follow these steps to identify the cause:

  1. Log on to the ARMS console. In the left-side navigation pane, choose Browser Monitoring > Browser Monitoring.

  2. On the Browser Monitoring page, select a region in the top navigation bar and click the name of the application that you want to manage.

  3. In the left-side navigation pane, click API request.

  4. In the API link trace (TOP 20) section on the right, sort the APIs by request duration in descending order to find the API or trace ID with high latency.

  5. Click the Managed Service for OpenTelemetry link in the Actions column to view the overall frontend time and a timeline of the backend calls.

     • If a short backend processing time accompanies a long overall response time, this indicates high network latency. In this case, click View details to inspect session details, including network, region, browser, device, and operating system.

     • If the backend processing time is long, it indicates poor performance. Click the magnifier icon in the Method Stack column. In the local method stack dialog box, examine the backend trace to find the most time-consuming part and pinpoint the issue.