Call diagnostics: the SIP flow of a single call

What it is for

Call diagnostics answers the question of what happened to one specific call at signalling level. You pick the call in the call list (CDR) or in the CURRI log. EasyUC then loads the SDL traces of the Cisco CallManager service from all CallManager nodes of the cluster for exactly that time, extracts the SIP messages of this one call and shows them as a ladder diagram.

This replaces collecting and searching trace files by hand with RTMT. The function only reads existing trace files through the CUCM log collection interface. It does not change any CUCM configuration and does not switch on traces.

If the call went through a CUBE with debug capture switched on, EasyUC merges its SIP messages into the same flow. This happens only for users with read access to the CUBEs.

Prerequisites

• Licence module cucm and a working CUCM connection.
• Role ROLE_APP_CALL_DIAGNOSTICS ("Analyze CUCM Calls" in the role editor). It allows starting, viewing and exporting, and includes the page role ROLE_APP_VIEW_CALL_DIAGNOSTICS_PAGE and read access to the call list.
• The AXL user of the CUCM connection has the CUCM roles Standard CCM Admin Users and Standard RealtimeAndTraceCollection. Without them the node reports a missing role.
• On the CUCM, the Cisco CallManager service uses trace level Detailed with Enable SIP Call Processing Trace. Without this setting the traces contain no SIP messages.
• EasyUC reaches every CallManager node under its name from the CUCM over HTTPS (port 8443).
• When starting from the call list: the CDR import of the connection is running. When starting from CURRI: the call is in the CURRI log.
• SSH credentials (platform/OS administrator) are not needed for call diagnostics. They are only used for "Details (SSH)" of the CUCM nodes.
• The background service for trace collection is running. It processes only one collection at a time.
• For CUBE messages in the flow: read access to the CUBEs (ROLE_APP_GATEWAYS with ROLE_APP_GATEWAYS_CUBE). Administrators always have it.

Step by step: start a diagnosis from the call list

1. Select the CUCM connection the call went through in the header.
2. Open Logs → Call Diagnostics and click Select a call. This takes you to the call list under Reporting → Nutzung & Erreichbarkeit → Calls.
3. Find the call by period and number.
4. In the row of the call, click Analyze in the Call diagnostics column.
5. In the Analyze this call dialog, check the Timezone and the prefilled time window. It covers 60 seconds before and after the call.
6. Narrow the window with Start Time and End Time if required.
7. Click Start call analysis. EasyUC opens the detail page of the diagnosis.
8. Wait until the progress display has finished. It shows "Determining CallManager nodes", "Listing trace files", "Downloading trace files", "Correlating SIP messages" and "Saving the call flow" in turn, together with the node and the file counter.
9. Read the result on the Call flow tab.

Step by step: start a diagnosis from the CURRI log

1. Open CURRI → Curri Logs.
2. Find the row of the call.
3. In the Call flow column, click the diagram icon (Show SIP flow).
4. EasyUC starts the diagnosis without a further dialog and opens the detail page. The time window runs from 60 seconds before the CURRI entry to 10 minutes after it.
5. If the same row was analysed within the last 15 minutes, EasyUC opens the existing diagnosis instead of starting a new one.

Step by step: export a result and find it again

1. Open Logs → Call Diagnostics. Under Recent diagnoses there is one card per diagnosis with status, source (CDR or CURRI), diagnosis number, caller, destination, time and device.
2. Click a card to open the diagnosis again.
3. Click SIP messages (text), Filtered logs or Analysis (JSON) at the top right to download the result.
4. On the Call flow tab, click Download SVG to save the diagram as an image.

Fields and options

How to read the ladder diagram

Check the result and narrow down errors

• You recognise success by the status Completed and a diagram that starts with INVITE and ends with BYE or an error response.
• "The traces contain no SIP messages. Set the trace level of the Cisco CallManager service to "Detailed" and enable "Enable SIP Call Processing Trace".": correct the trace setting on all CallManager nodes of the CUCM and repeat the call.
• "The call is older than two hours; its traces may have been rotated on the CUCM.": the CUCM rotates its trace files. Start the diagnosis as soon as possible after the call.
• "Role missing: the AXL user needs "Standard CCM Admin Users" and "Standard RealtimeAndTraceCollection"": add the roles to the AXL user in the CUCM.
• "Only the calling number matched; the call flow may belong to another call of this caller.": compare time and destination and check the Other matching calls table.
• "The call was still in progress when the traces were read; the call flow ends there.": start the diagnosis again after the call has ended.
• "Another call diagnosis is running on this CUCM connection": one diagnosis runs per CUCM connection at a time. EasyUC opens the running one. Further diagnoses wait in the order they were started.
• "The analysis did not finish: the background worker has not reported for 10 minutes." or the notice that the worker has not picked it up for an hour: the background worker for trace collection is not working. Start the diagnosis again and check the workers if it happens repeatedly.
• "Das Zeitfenster der Anrufdiagnose muss zwischen einer Sekunde und 30 Minuten liegen." (the server returns this message in German): reduce the window with Start Time and End Time.
• Limits per diagnosis: at most 8 CallManager nodes, 12 trace files per node, 64 MiB per file and 800 messages in the diagram. When a limit is reached, the result stays visible and gets the status Partial with a notice.
• If the diagram does not show the CUBE although the call went through it, the notices state the reason, for example that its debug capture is switched off or that the capture is kept for fewer days than the age of the call.
• "The CUCM node list was not available; only the AXL host was searched.": EasyUC could not determine the nodes of the cluster. If the call went through another node, it is missing. Check the AXL access.
• "The time zone of … is unknown; UTC is assumed.": the times of this node may be shifted. Compare with the times of the other nodes.
• "The traces on … start after the call began; the beginning may be missing." and "The CUCM did not provide SDL trace files for the time of the call.": the traces have already been overwritten.
• "More trace files cover the call on … than the limit of …; the end of the call may be missing." and "The trace analysis stopped after … MiB of trace data.": reduce the time window.
• "More than … SIP messages in the call window; later messages were ignored." and "The call flow was limited to … messages.": the time window is too large for the traffic on the cluster. Reduce it.
• "The traces contain SIP messages, but none at the time of the call (rotated traces or a time zone offset).": check the time zone in the dialog and the clock of the CUCM.
• "No SIP dialog in the traces matches the numbers and the time of the call.": the call did not use SIP, or the numbers were rewritten before the node. Extend the time window.
• Notices about the CUBE: "The debug capture of the CUBE … holds no SIP messages of this call.", "The CUBE debug capture could not be read; the call flow shows the CUCM traces only." and "… could only be read in part". The flow from the CUCM traces remains valid in all cases.
• Credentials and SRTP keys are removed before display and in all exports. The function only reads and changes nothing on the CUCM.