Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

utils: add helper to interact with janus admin API #3097

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

lionelnicolas
Copy link
Contributor

@lionelnicolas lionelnicolas commented Nov 1, 2022

Useful for live-enable/disable locks and refcount debugging on production, or start a PCAP dump, when the admin API is not easily accessible (e.g. janus running in a kubernetes pod). Using this you can simply:

kubectl exec your-janus-pod -- janus-admin-cli -r set_log_level -o level=5

See https://janus.conf.meetecho.com/docs/admin.html for more commands.

Janus admin connection can be configure using parameters or env vars (JANUS_HOST, JANUS_ADMIN_PORT, JANUS_ADMIN_SECRET, JANUS_ADMIN_ENDPOINT )

Examples:

#~ janus-admin-cli -r ping
{
  "janus": "pong",
  "transaction": "aNexVTIgcYbc"
}
#~ janus-admin-cli -r list_sessions
{
  "janus": "success",
  "transaction": "GgaL0xmUbBI4",
  "sessions": [
    3236169122271256,
    295460503767564,
    5854530659370442,
    5714856303331417,
    4512308604273274,
    3642487421981464,
    8938575577523615
  ]
}
#~ janus-admin-cli -r list_handles -o session_id=3236169122271256
{
  "janus": "success",
  "session_id": 3236169122271256,
  "transaction": "rR4lYK1hZTuB",
  "handles": [
    8548304105222430
  ]
}
#~ janus-admin-cli -r handle_info -o session_id=3236169122271256 -o handle_id=8548304105222430
{
  "janus": "success",
  "session_id": 3236169122271256,
  "transaction": "nXEemi7vqYzP",
  "handle_id": 8548304105222430,
  "info": {
    "session_id": 3236169122271256,
    "session_last_activity": 491266556101,
    "session_timeout": 300,
    "session_transport": "janus.transport.websockets",
    "handle_id": 8548304105222430,
    "opaque_id": "videoroom-2bjwk899v3jwrcleiqhq",
    "loop-running": true,
    "created": 426360304549,
    "current_time": 491278863887,
    "plugin": "janus.plugin.videoroom",
    "plugin_specific": {
      "hangingup": 0,
      "destroyed": 0
    },
    "flags": {
      "got-offer": false,
      "got-answer": false,
      "negotiated": false,
      "processing-offer": false,
      "starting": false,
      "ice-restart": false,
      "ready": false,
      "stopped": false,
      "alert": false,
      "trickle": false,
      "all-trickles": false,
      "resend-trickles": false,
      "trickle-synced": false,
      "data-channels": false,
      "has-audio": false,
      "has-video": false,
      "new-datachan-sdp": false,
      "rfc4588-rtx": false,
      "cleaning": false,
      "e2ee": false
    },
    "sdps": {},
    "queued-packets": 0,
    "streams": []
  }
}
#~ janus-admin-cli -r start_pcap -o session_id=3236169122271256 -o handle_id=8548304105222430 -o folder=/tmp
{
  "janus": "success",
  "transaction": "ZPPhyQqNfLwp"
}
#~ janus-admin-cli -r stop_pcap -o session_id=3236169122271256 -o handle_id=8548304105222430
{
  "janus": "success",
  "transaction": "mm74LKsRVaKW"
}
#~ janus-admin-cli -r set_log_level -o level=5
{
  "janus": "success",
  "transaction": "D1sGjlV3KLnm",
  "level": 5
}
#~ janus-admin-cli -r set_log_timestamps -o timestamps=true
{
  "janus": "success",
  "transaction": "hpSA0VgL8HxQ",
  "log_timestamps": true
}
#~ janus-admin-cli -r set_locking_debug -o debug=true
{
  "janus": "success",
  "transaction": "wt15AgETbPrn",
  "locking_debug": true
}

@lionelnicolas
Copy link
Contributor Author

lionelnicolas commented Nov 1, 2022

I created a utils/ directory to put this script. Let me know if you want me to rename this directory.

@lminiero
Copy link
Member

lminiero commented Nov 2, 2022

This looks like a useful tool (some time ago I wrote a similar one in nodejs), but I'm not sure it belongs here. Maybe it could be its own separate repo?

@alexamirante
Copy link
Member

This looks like a useful tool (some time ago I wrote a similar one in nodejs), but I'm not sure it belongs here. Maybe it could be its own separate repo?

Why so? It's a shell script, it won't hurt to have it here (I think it's quite useful instead) and having its own repo would be overkill IMHO.

@lminiero
Copy link
Member

lminiero commented Nov 2, 2022

Fair point 👍

@atoppi
Copy link
Member

atoppi commented Nov 2, 2022

IMHO this is a useful addition to the code base.

@lionelnicolas I'd suggest adding the admin endpoint as a parameter (default value should be/admin)

@lionelnicolas
Copy link
Contributor Author

I'd suggest adding the admin endpoint as a parameter (default value should be/admin)

Done

@NFhook
Copy link

NFhook commented Nov 25, 2022

👍 use ping to do health check

@lionelnicolas
Copy link
Contributor Author

+1 use ping to do health check

Good idea. If you want to use that for an health check, I've added -t parameter to be able to set the curl timeout, so you could set it to 1 second for example (default is 5 seconds). This will avoid curl to be stuck for a long time if your server or the network is not responding.

diff --git a/utils/janus-admin-cli b/utils/janus-admin-cli
index 5355683d..9c9a744b 100755
--- a/utils/janus-admin-cli
+++ b/utils/janus-admin-cli
@@ -13,11 +13,12 @@ janus_addr="${JANUS_HOST:-localhost}"
 janus_port="${JANUS_ADMIN_PORT:-7088}"
 janus_pass="${JANUS_ADMIN_SECRET:-janusoverlord}"
 janus_endpoint="${JANUS_ADMIN_ENDPOINT:-/admin}"
+janus_timeout="${JANUS_ADMIN_TIMEOUT:-5}"
 
 # define usage
 usage() {
        cat <<EOF
-usage: $0 [-h] [-a JANUS_ADDR] [-p JANUS_ADMIN_PORT] [-s JANUS_ADMIN_SECRET] [-e JANUS_ADMIN_ENDPOINT] [-o NAME=VALUE] -r REQUEST
+usage: $0 [-h] [-a JANUS_ADDR] [-p JANUS_ADMIN_PORT] [-s JANUS_ADMIN_SECRET] [-e JANUS_ADMIN_ENDPOINT] [-t JANUS_ADMIN_TIMEOUT] [-o NAME=VALUE] -r REQUEST
 
        -h      show this help message
        -r      janus request (required)
@@ -26,6 +27,7 @@ usage: $0 [-h] [-a JANUS_ADDR] [-p JANUS_ADMIN_PORT] [-s JANUS_ADMIN_SECRET] [-e
        -p      janus HTTP admin port (default: ${janus_port})
        -s      janus admin secret (default: ${janus_pass})
        -e      janus admin endpoint (default: ${janus_endpoint})
+       -t      janus response timeout (default: ${janus_timeout})
 EOF
 
        exit ${1:-1}
@@ -44,7 +46,7 @@ rand_str() {
 }
 
 # parse parameters
-while getopts "ha:p:s:e:o:r:" opt; do
+while getopts "ha:p:s:e:t:o:r:" opt; do
        case $opt in
                h) usage 0 ;;
                r) janus_request="${OPTARG}" ;;
@@ -53,6 +55,7 @@ while getopts "ha:p:s:e:o:r:" opt; do
                p) janus_port="${OPTARG}" ;;
                s) janus_pass="${OPTARG}" ;;
                e) janus_endpoint="${OPTARG}" ;;
+               t) janus_timeout="${OPTARG}" ;;
        esac
 done
 
@@ -103,6 +106,7 @@ curl \
        --silent \
        --fail \
        --show-error \
+       --max-time ${janus_timeout} \
        --write-out '\n' \
        --data "${http_payload}" \
        http://${janus_addr}:${janus_port}${janus_endpoint}${http_session_id}${http_handle_id}

@lminiero
Copy link
Member

@lionelnicolas could you add some text to the Admin API documentation too, maybe as a new section there, so that people interested in the Admin API are aware of this tool they can use as an alternative to the demo page? In currently ends here in the mainpage.dox file.

@lionelnicolas
Copy link
Contributor Author

@lionelnicolas could you add some text to the Admin API documentation too, maybe as a new section there, so that people interested in the Admin API are aware of this tool they can use as an alternative to the demo page? In currently ends here in the mainpage.dox file.

Done.

@lminiero Let me know if you want me to reword or add/remove stuff

@lionelnicolas
Copy link
Contributor Author

bump

@lminiero
Copy link
Member

Apologies for the awful delay in this response, I simply forgot about this... 🙈
I think it looks fine, even though there's probably a couple of things the documentation should clarify:

  1. The documentation should explain that this relies on the HTTP transport for the Admin API. In fact, we have multiple transports, and so people may be confused by which one is needed (even though HTTP is mentioned in the -h of the tool).
  2. It might also help to say explicitly that curl is needed for this to work, as libcurl is an optional dependency, and so not everyone may have it.
  3. Looking at how the script works, this definitely supports requests that are "flat" in their structure, meaning all attributes are in the root of the JSON object. We do have requests that are nested, though, like message_plugin, query_transport and possibly others (I should really document all of them in the Admin page). Not sure if it's indeed possible to pass a child JSON object as one of the attributes: looking at the code I suspect not, but maybe adding a curly bracket to the exceptions not to add quotes (not a string) may do it? If that doesn't work, it might be better to clarify that not all methods are supported, and that those that do expect a nested object currently aren't.

As a couple of additonal notes, this seems hardcoded to plain HTTP, but some may have the Admin API exposed via HTTPS. In that case, adding a -k to skip checking certificates may be useful, since it may be HTTPS with self-signed certs.

Sorry again for this late response!

@lionelnicolas
Copy link
Contributor Author

Sorry I missed the notification. I'll take a look by end of week.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants