Classify the evidence failure before reproducing
Record whether the command is unavailable, capture will not enable, the unfiltered history is empty, only part of the exchange appears, a filter returns nothing, the list is too large, entries belong to another call, or memory and CLI responsiveness deteriorate. Preserve the exact command, response, Asterisk version, module state, timestamp and incident scope.
These symptoms have different owners. A missing module is not a filter problem; a filter that returns zero is not proof of an empty history; an empty history is not proof that no packet crossed another interface.
Verify module and capture timing in that order
Use the installed CLI help and module list to confirm res_pjsip_history exists and is running. If the package omits an extended-support module, follow the distribution’s supported packaging path rather than copying a binary from another Asterisk build. Record whether another operator, automation or reload changed module state during the incident.
Clear only after the existing evidence owner approves, enable history immediately before one authorized request and stop it immediately afterward. Confirm the reproduction actually reached this Asterisk process and PJSIP stack. Traffic handled by another node, interface, SIP service or legacy channel driver will not be made visible by PJSIP history on this process.
Inspect the unfiltered list before debugging the filter
Run the unfiltered history summary and locate a known request by time, direction, address and first line. Open its numbered entry and retain the full headers. If the expected method is absent, compare the capture start time, correct node, transport path and a narrowly scoped packet or peer-side observation before changing the query.
If the entry exists, copy its exact Call-ID and test the simplest supported expression. Add method, address, timestamp, boolean or LIKE conditions one at a time. Preserve parse errors and spacing; the published example notes that token spacing matters.
Explain incomplete sequences by leg and transaction
Match request and response with Call-ID, CSeq method and number, top Via branch, tags, direction and adjacent address. A challenge-response flow can contain the initial request, 401 or 407, ACK and authenticated retry. Retransmissions can repeat a request without creating a new dialog. Forks and transfers can produce several legitimate branches.
Do not expect one Call-ID filter to join Asterisk’s separate endpoint and trunk legs. Use channel, unique ID, linked ID, timestamp and dialplan evidence to correlate the legs, while preserving each leg’s own SIP identifiers.
Reduce noise without hiding the failing exchange
A busy server can retain REGISTER, OPTIONS, SUBSCRIBE, NOTIFY and unrelated call traffic alongside the incident. Shorten the approved capture window and reproduce one known event before relying on a complex filter. Filter the retained copy by an observed Call-ID or supported field; do not disable production keepalives, registrations or subscriptions merely to make the list quieter.
If long-lived or file-based collection is actually required, use the supported logger and rotation policy or an authorized capture system instead of leaving in-memory history on. Keep storage, access, redaction and deletion controls attached to that alternative.
Correct one boundary and retest from a clean window
Correct only the demonstrated cause: load the supported module, capture on the right node and time, use valid filter grammar, select the right Call-ID and leg, or choose logger or packet evidence for the actual question. Export the minimum approved evidence, then clear retained history and verify capture is off.
Repeat the same request and a nearby control in a new bounded window. Confirm the complete signaling sequence, Asterisk result and any downstream call or media outcome separately. No host, module, memory state, message, filter, credential, packet, dialog or live call was inspected or tested for this diagnostic.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Asterisk PJSIP History how-to ↗
- Asterisk res_pjsip_history source and CLI definitions ↗
- Asterisk PJSIP troubleshooting guide ↗
- Asterisk debug-information collection guidance ↗
- Asterisk CHANNEL function and PJSIP Call-ID ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.