Recent versions of Janus introduced a new feature: an Admin/Monitor API that can be used to ask Janus for more specific information related to sessions and handles. This is especially useful when you want to debug issues at the media level.
The API, for security reasons, is not enabled by default. You can enable it by editing the [admin] section in the
janus.cfg
configuration file accordingly. The configuration is pretty much the same as the one for the Plain HTTP REST Interface so you can refer to that one. In addition, you can configure restrictions in the form of a password/secret that clients need to provide and access lists based on full/partial addresses.
For what concerns the syntax, it's very similar to the RESTful, WebSockets and RabbitMQ API and so this page will briefly discuss the differences. At the moment, a few different methods are exposed:
list_sessions:
list all the sessions currently active in Janus (returns an array of session identifiers);list_handles:
list all the ICE handles currently active in a Janus session (returns an array of handle identifiers);handle_info:
list all the available info on a specific ICE handle;set_log_level:
change the log level in Janus on the fly;set_locking_debug:
selectively enable/disable a live debugging of the locks in Janus on the fly (useful if you're experiencing deadlocks and want to investigate them).Following the same spirit of the RESTful, WebSockets and RabbitMQ API these methods need to be invoked on the right path and/or providing the right session_id
and handle_id
identifiers. Specifically, list_sessions
must be invoked without any session/handle information, as it's a global request. Here's an example of how such a request and its related response might look like:
POST /admin { "janus" : "list_sessions", "transaction" : "<random alphanumeric string>", "admin_secret" : "<password specified in janus.cfg, if any>" }
{ "janus" : "success", "transaction" : "<same as the request>", "sessions" : [ <session ID #1>, <session ID #2>, [..] <session ID #n> ] }
On the other hand, since list_handles
is related to a specific session, a session must be referenced correctly. Using the REST API, this can be done by appending the session identifier (e.g., one of the IDs returned by the previous call) to the API root:
POST /admin/12345678 { "janus" : "list_handles", "transaction" : "<random alphanumeric string>", "admin_secret" : "<password specified in janus.cfg, if any>" }
{ "janus" : "success", "transaction" : "<same as the request>", "session_id" : 12345678, "handles" : [ <handle ID #1>, <handle ID #2>, [..] <handle ID #n> ] }
Once a list of handles is available, detailed info on any of them can be obtained by means of a handle_info
call. Since this is a handle-specific request, the correct handle identifier must be referenced, e.g., by appending the ID to the session it belongs to:
POST /admin/12345678/98765432 { "janus" : "handle_info", "transaction" : "<random alphanumeric string>", "admin_secret" : "<password specified in janus.cfg, if any>" }
{ "janus" : "success", "transaction" : "<same as the request>", "session_id" : 12345678, "handle_id" : 98765432, "info" : { "plugin": "janus.plugin.echotest", "flags": { // flags }, "sdps": { "local": "v=0[..]", "remote": "v=0[..]" }, "streams": [ // streams, components, etc. ] } }
The actual content of the last response is omitted for brevity, but you're welcome to experiment with it in order to check whether more information (of a different nature, maybe) may be useful to have.
Finally, the syntax for the set_log_level
and set_locking_debug
commands is quite straightforward:
POST /admin { "janus" : "set_log_level", "level" : <integer between 0 and 7, see debug.h>, "transaction" : "<random alphanumeric string>", "admin_secret" : "<password specified in janus.cfg, if any>" }
POST /admin { "janus" : "set_locking_debug", "debug" : <0 to disable, 1 to enable>, "transaction" : "<random alphanumeric string>", "admin_secret" : "<password specified in janus.cfg, if any>" }
Both commands will return the updated level/debug setting if successful, and an error otherwise.