Colibri msg initiated pcap capture

[dkirov-dev]

This PR introduces new functionality to start pcap capture per endpoint from a colibri message.
If the colibri message "conference-modify"/"endpoint" has new parameters "context-id" and "pcap-rec-mode" set to enable capture, then jvb will produce pcap files for this specific endpoint.

`<endpoint xmlns='jitsi:colibri2' id='32bbe701' create='true' stats-id='Sallie-XSA' context-id='919633fd-93f7-43eb-802e-f285a0248065' pcap-rec-mode='audio'>`

The new functionality is configured / enabled by adding a new section named "metadata-pcap-recording" in
jitsi-media-transform/src/main/resources/reference.conf

  metadata-pcap-recording {
    enabled=true
    // Base path for storing the pcap and metadata files
    base-path="/tmp/jvb-rec"
  }

For each recorded endpoint / context pair, JVB produces 2 pcap and 2 json metadata files describing the pcap files.
The file name is generated as a function of

<base-path>/<context-id>_<endpoint-id>_<capture-end>.

For example:
919633fd-93f7-43eb-802e-f285a0248065_5d9bdf3b_fe.json
919633fd-93f7-43eb-802e-f285a0248065_5d9bdf3b_fe.pcap
919633fd-93f7-43eb-802e-f285a0248065_5d9bdf3b_ne.json
919633fd-93f7-43eb-802e-f285a0248065_5d9bdf3b_ne.pcap

The JSON metadata file includes the endpoint_id, context_id, capture_end and payload_map describing a specific pcap file with the same name.

{
  "endpoint_id": "5d9bdf3b",
   "context_id": "919633fd-93f7-43eb-802e-f285a0248065",
   "capture_end": "fe",
   "capture_mode": "audio-video",
   "payload_map": [
    {
      "payload_type": 101,
      "media_type": "video",
      "clock_rate": 90000,
      "encoding": "vp9"
    },
    {
      "payload_type": 126,
      "media_type": "audio",
      "clock_rate": 8000,
      "encoding": "telephone-event"
    },
    {
      "payload_type": 111,
      "media_type": "audio",
      "clock_rate": 48000,
      "encoding": "opus"
    }
  ]
}

The pcap file will contain RTP packets for audio if the new parameter pcap-rec-mode = "audio" or "audio-video" and it will contain video packets if pcap-rec-mode = "video" or "audio-video".
The "context-id" identifies a specific instance of a jitsi room and allows a jitsi customer to select whether jvb should produce pcap files for a specific endpoint on the fly and to correlate a specific instance of a video conferencing room with a specific participant / endpoint pcap captures.
This new functionality should be considered as an extension or replacement of TRANSCEIVER_PCAP_DUMP debug feature that is driven from colibri message instead of config settings.
A system integrator can simply start pcap with metadata recordings from prosody plugin for a specific participant of a video conferencing room based on a logic specific to this system integrator and without any other changes in the jitsi code.

[dkirov-dev]

@damencho , @emcho , @bgrozev , @JonathanLennox please review.

[jitsi-jenkins]

Hi, thanks for your contribution!
If you haven't already done so, could you please make sure you sign our CLA (https://jitsi.org/icla for individuals and https://jitsi.org/ccla for corporations)? We would unfortunately be unable to merge your patch unless we have that piece :(.

[bgrozev]

Jenkins, add to whitelist

[codecov]

Codecov Report

Merging #2072 (efd9993) into master (7a4dc8b) will decrease coverage by 0.32%.
Report is 3 commits behind head on master.
The diff coverage is 0.00%.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #2072      +/-   ##
============================================
- Coverage     44.23%   43.91%   -0.32%     
- Complexity     1924     1928       +4     
============================================
  Files           340      341       +1     
  Lines         18879    19031     +152     
  Branches       2592     2620      +28     
============================================
+ Hits           8351     8358       +7     
- Misses         9663     9809     +146     
+ Partials        865      864       -1     

Files	Coverage Δ
...sform/src/main/kotlin/org/jitsi/nlj/RtpReceiver.kt	0.00% <ø> (ø)
...ansform/src/main/kotlin/org/jitsi/nlj/RtpSender.kt	0.00% <ø> (ø)
.../kotlin/org/jitsi/nlj/transform/node/PcapWriter.kt	0.00% <0.00%> (ø)
...sform/src/main/kotlin/org/jitsi/nlj/Transceiver.kt	0.00% <0.00%> (ø)
...g/jitsi/videobridge/relay/RelayMessageTransport.kt	8.33% <0.00%> (-0.05%)	⬇️
...m/src/main/kotlin/org/jitsi/nlj/RtpReceiverImpl.kt	0.00% <0.00%> (ø)
...orm/src/main/kotlin/org/jitsi/nlj/RtpSenderImpl.kt	0.00% <0.00%> (ø)
.../videobridge/colibri2/Colibri2ConferenceHandler.kt	1.01% <0.00%> (-0.03%)	⬇️
...org/jitsi/nlj/transform/node/MetadataPcapWriter.kt	0.00% <0.00%> (ø)

... and 3 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 814bffd...efd9993. Read the comment docs.

[bgrozev]

Are you also planning to contribute changes to jicofo for this feature?

[dkirov-dev]

@bgrozev I am not sure if changes in jicofo are needed for this and we need your team advice here.
So far I was able to test it with a simple prosody plugin which does not require changing the colibri message structure:

function on_iq_received(event)
   if event and event.stanza and event.stanza.name == "iq" then
      local colibri = event.stanza:get_child("conference-modify", "jitsi:colibri2");
      if colibri ~= nil then
         local endpoint = colibri:get_child("endpoint");
         if endpoint ~= nil then
            endpoint.attr["pcap-rec-mode"] = "audio-video"
            endpoint.attr["context-id"] = "919633fd-93f7-43eb-802e-f285a0248065" 
            module:log("info", "pcap rec enabled for endpoint: %s", endpoint.attr.id);
         end
      end
   end
end

module:hook("pre-iq/full", on_iq_received);
module:log("info", "Loaded mod_room_pcaprec");

But technically speaking, the "context-id" is more appropriately placed in the conference-modify section and not in the endpoint section, but that would require changing the classes that define the message structures.
Your input here is appreciated. Thanks!