Resolving Discrepancies Between Application-Side Call Duration and Agora Analytics Records

Issue Description

Developers may encounter inconsistencies when comparing session durations tracked within their local application logic against the metrics displayed in the Agora Analytics Dashboard or backend usage reports. Common symptoms of this discrepancy include instances where application-layer logs report longer durations than the Agora platform, the appearance of multiple short, fragmented sessions in the dashboard, or the absence of a standard "leave" event marker in the Analytics timeline.

Platform/SDK

• Services: Agora RTC / Agora Analytics (Crystal Ball) / Event Notifications (Webhooks)

• Applicability: Applications implementing custom client-side or server-side session tracking logic.

Root Cause

Duration discrepancies typically originate from a fundamental difference between application-level heartbeat logic and the network-level session lifecycle maintained by Agora SD-RTN.

If a user experiences a sudden network failure or terminal timeout instead of executing an explicit leave command, the local application may continue to mark the session as active until a local heartbeat fails. Conversely, the Agora service will terminate the session immediately after the connection state transitions to a timed-out status due to a lack of data packets. This misalignment leads to gaps in recorded duration and the absence of a "quit" event marker in diagnostic tools.

Step-by-Step Solution

1. Synchronize Timezones for Data Comparison

   Standardize all comparison timestamps to Coordinated Universal Time (UTC). Agora backend records and dashboard logs exclusively utilize UTC typically. Local application logs must be converted to this standard to ensure an accurate temporal comparison.

2. Audit Session Continuity via Agora Analytics Dashboard

   Utilize the filtering and sorting functions within the Agora Dashboard to organize sessions by start and end timestamps. This analysis confirms whether a single logical call was split into multiple physical connection attempts due to network re-establishment or repeated join-and-leave cycles.

3. Distinguish Between Left Normally and Connection Timeout

   Interpret the presence or absence of the blue "leave" marker in Agora Analytics as follows:

   • Presence of Blue Marker: Confirms a successful execution of the leaveChannel API.

   • Absence of Blue Marker: Indicates the session ended due to a timeout, network loss, or a failed reconnection attempt where the client could not send the final "quit" signal.

4. Review SDK connection callbacks in your app

   Refine the application logic for handling the onConnectionStateChanged callback. Ensure that the local tracking mechanism stops immediately if the connection state transitions to FAILED or stays in RECONNECTING beyond a defined business threshold. Relying on application-level heartbeat or pings often results in overestimating the actual RTC engagement time.

5. Audit the Discrepancy Between Application Logic and RTC Lifecycle

   Analyze your internal logs to determine if session tracking relies solely on application-layer commands, such as your own "start" or "stop" APIs. Discrepancies frequently occur when an RTC session terminates on the Agora SD-RTN due to network instability while the local application continues to wait for a heartbeat or an explicit API call that never arrives.

6. Use Agora Event Notifications for server-side accuracy

   Implement Agora Event Notifications (Webhooks) to establish a single source of truth for session lifecycles. By subscribing to events such as User Join, User Leave, and User Timeout, your backend can align its records directly with Agora's data. To ensure data integrity, your implementation must include logic to handle potential duplicate notifications or out-of-order event delivery.

   • Enable Agora Event Notifications in the Agora Console.

   • To maintain data integrity during network retries or out-of-order delivery, your implementation must include a deduplication and sequencing strategy:

     1. Identify Unique Sessions: Create a composite key by combining the channel name and the UID to isolate events belonging to a specific participant session.

     2. Implement Idempotency: Utilize the noticeId to identify and discard duplicate payloads of the same event notification.

     3. Enforce Event Sequencing: Compare the clientSeq values of incoming messages. Prioritize events with higher sequence numbers to ensure that the final session state correctly reflects the chronological order of updates.

7. Gather Diagnostic Data for Comparative Analysis

   If discrepancies persist after aligning timezones and implementing Webhook tracking, perform a deep-dive audit by collecting the following datasets for a specific session:

• Agora SDK logs
• Application ping records
• Timestamps for start, reconnect, and end logic
• Compare those with Agora Analytics or webhook events

 

Best Practice

• Use Agora Event Notifications to track session state on the server side.
• Calculate duration on RTC join/leave/timeout events instead of only app pings.
• Ensure your reconnection logic cleanly ends the session after retry failures.
• Account for UTC when comparing Agora records with local app logs.
• Review onConnectionStateChanged() handling to avoid keeping a session marked as active after RTC has timed out.

Corresponding Document/Link

- Receive Notifications About Channel Events