Subscriber trace
trace_subscriberBuild one time-ordered, multi-protocol timeline for a subscriber by IMSI or MSISDN across Diameter, GTP, PFCP, MAP and SIP, pairing requests with answers to diagnose why a subscriber failed.
Instructions
Build one time-ordered timeline for a subscriber across Diameter (User-Name),
GTPv2-C and GTPv1-C (IMSI/MSISDN IEs, then following the control-plane TEIDs), PFCP
(sessions naming the IMSI or a UE address the GTP rows allocated, followed by SEID), MAP (IMSI/MSISDN)
and SIP (From/To/P-Asserted-Identity containing the MSISDN). Each row carries the
protocol, message name, result (Result-Code, GTP cause, SIP final status), peers and
the request/answer pairing including unanswered: true. Give imsi, msisdn or
both as digit strings. The whole call shares one time budget (the per-run timeout);
when it runs out the timeline found so far is returned with truncated and the pass
that stopped marked timed_out. GTP rows carry the proxy-chain fields of
gtp_sessions (chain, leg_without_response, near_capture_end, duplicate_of_frame, note);
unanswered Diameter and GTP rows the capture stopped too soon after get near_capture_end,
counted in unanswered_near_capture_end.
Start here for "why did subscriber X fail" questions.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"path": "<path>"
},
"name": "trace_subscriber"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Same forms as start | |
| imsi | No | IMSI, 6 to 15 digits | |
| path | Yes | Capture file (absolute, in an allowed dir) or open_capture handle | |
| limit | No | Most rows per page | |
| start | No | ISO 8601, epoch s, +Ns from start, -Ns from end | |
| msisdn | No | MSISDN (E.164 digits, no +) | |
| offset | No | Rows to skip (next_offset) | |
| output | No | summary: all but rows, plus 3 rows (<8 KB) | rows |
| redact | No | Replace subscriber identifiers in this result with tokens; ids+ips hides every IP too | off |
| columns | No | Row keys to keep (frame keys stay) | |
| esp_null | No | Read SIP in NULL-encrypted ESP | |
| max_output_kb | No | Lower output cap, KB |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| error | No | ||
| ipsec | No | keys: esp_packets, spis, decoded_null, unreadable, esp_null, hint | |
| offset | No | ||
| passes | No | ||
| window | No | ||
| dropped | No | ||
| failures | No | ||
| has_more | No | ||
| identity | No | keys: imsi, msisdn | |
| returned | No | ||
| timeline | No | rows with keys: time, protocol, message, detail, result, identity, src, dst, request_frame, answer_frame, frame, rtt_ms, unanswered, failed, leg_without_response, near_capture_end, duplicate_of_frame, chain, note | |
| by_protocol | No | ||
| next_offset | No | ||
| total_found | No | ||
| total_matched | No | ||
| packets_matched | No | ||
| packets_scanned | No | ||
| total_is_lower_bound | No | ||
| unanswered_near_capture_end | No |