[mi_http] updated docs concerning tracing

OpenSIPS · Jan 30, 2017 · 1ccbc99 · 1ccbc99
1 parent aecb7e6
commit 1ccbc99
Show file tree

Hide file tree

Showing 2 changed files with 136 additions and 5 deletions.
diff --git a/modules/mi_http/README b/modules/mi_http/README
@@ -27,6 +27,8 @@ Ovidiu Sas
 
               1.4.1. mi_http_root(string)
               1.4.2. mi_http_method(integer)
+              1.4.3. trace_destination (string)
+              1.4.4. trace_bwlist (string)
 
         1.5. Exported Functions
         1.6. Known issues
@@ -35,6 +37,8 @@ Ovidiu Sas
 
    1.1. Set mi_http_root parameter
    1.2. Set mi_http_method parameter
+   1.3. Set trace_destination parameter
+   1.4. Set trace_destination parameter
 
 Chapter 1. Admin Guide
 
@@ -83,6 +87,57 @@ modparam("mi_http", "mi_http_root", "opensips_mi")
 modparam("mi_http", "mi_http_method", 1)
 ...
 
+1.4.3. trace_destination (string)
+
+   Trace destination as defined in the tracing module. Currently
+   the only tracing module is proto_hep. This is where traced mi
+   messages will go.
+
+   WARNING: A tracing module must be loaded in order for this
+   parameter to work. (for example proto_hep).
+
+   Default value is none(not defined).
+
+   Example 1.3. Set trace_destination parameter
+...
+modparam("proto_hep", "trace_destination", "[hep_dest]10.0.0.2;transport
+=tcp;version=3")
+
+modparam("mi_http", "trace_destination", "hep_dest")
+...
+
+1.4.4. trace_bwlist (string)
+
+   Filter traced mi commands based on a blacklist or a whitelist.
+   trace_destination must be defined for this parameter to have
+   any purpose. Whitelists can be defined using 'w' or 'W',
+   blacklists using 'b' or 'B'. The type is separate by the actual
+   blacklist by ':'. The mi commands in the list must be separated
+   by ','.
+
+   Defining a blacklists means all the commands that are not
+   blacklisted will be traced. Defining a whitelist means all the
+   commands that are not whitelisted will not be traced. WARNING:
+   One can't define both a whitelist and a blacklist. Only one of
+   them is allowed. Defining the parameter a second time will just
+   overwrite the first one.
+
+   WARNING: A tracing module must be loaded in order for this
+   parameter to work. (for example proto_hep).
+
+   Default value is none(not defined).
+
+   Example 1.4. Set trace_destination parameter
+...
+## blacklist ps and which mi commands
+## all the other commands shall be traced
+modparam("mi_http", "trace_bwlist", "b: ps, which")
+...
+## allow only sip_trace mi command
+## all the other commands will not be traced
+modparam("mi_http", "trace_bwlist", "w: sip_trace")
+...
+
 1.5. Exported Functions
 
    No function exported to be used from configuration file.

diff --git a/modules/mi_http/doc/mi_http_admin.xml b/modules/mi_http/doc/mi_http_admin.xml
@@ -1,17 +1,17 @@
 <!-- Module User's Guide -->
 
 <chapter>
-	
+
 	<title>&adminguide;</title>
-	
+
 	<section>
 	<title>Overview</title>
 	<para>
 		This module provides an HTTP transport layer implementation
 		for &osips;'s Management Interface.
 	</para>
 	</section>
-	
+
 	<section>
 	<title>To-do</title>
 		<para>
@@ -23,7 +23,7 @@
 			</para></listitem>
 		</itemizedlist>
 	</section>
-	
+
 	<section>
 	<title>Dependencies</title>
 	<section>
@@ -40,7 +40,7 @@
 		</para>
 	</section>
 	</section>
-	
+
 	<section>
 	<title>Exported Parameters</title>
 	<section>
@@ -84,6 +84,82 @@ modparam("mi_http", "mi_http_method", 1)
 </programlisting>
 		</example>
 	</section>
+
+	<section>
+		<title><varname>trace_destination</varname> (string)</title>
+		<para>
+			Trace destination as defined in the tracing module. Currently
+		the only tracing module is <emphasis role="bold">proto_hep</emphasis>.
+		This is where traced mi messages will go.
+		</para>
+		<para>
+			<emphasis role="bold">WARNING: </emphasis>A tracing module must be
+			loaded in order for this parameter to work. (for example
+			<emphasis role="bold">proto_hep</emphasis>).
+		</para>
+		<para>
+		<emphasis>
+			Default value is none(not defined).
+		</emphasis>
+		</para>
+		<example>
+		<title>Set <varname>trace_destination</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("proto_hep", "trace_destination", "[hep_dest]10.0.0.2;transport=tcp;version=3")
+
+modparam("mi_http", "trace_destination", "hep_dest")
+...
+</programlisting>
+		</example>
+	</section>
+
+	<section>
+		<title><varname>trace_bwlist</varname> (string)</title>
+		<para>
+			Filter traced mi commands based on a blacklist or a whitelist.
+		<emphasis role="bold">trace_destination</emphasis> must be defined for
+		this parameter to have any purpose. Whitelists can be defined using
+		'w' or 'W', blacklists using 'b' or 'B'. The type is separate by the
+		actual blacklist by ':'. The mi commands in the list must be separated
+		by ','.
+		</para>
+		<para>
+			Defining a blacklists means all the commands that are not blacklisted
+			will be traced. Defining a whitelist means all the commands that are
+			not whitelisted will not be traced.
+			<emphasis role="bold">WARNING: </emphasis> One can't define both
+			a whitelist and a blacklist. Only one of them is allowed. Defining
+			the parameter a second time will just overwrite the first one.
+		</para>
+		<para>
+			<emphasis role="bold">WARNING: </emphasis>A tracing module must be
+			loaded in order for this parameter to work. (for example
+			<emphasis role="bold">proto_hep)</emphasis>.
+		</para>
+		<para>
+		<emphasis>
+			Default value is none(not defined).
+		</emphasis>
+		</para>
+		<example>
+		<title>Set <varname>trace_destination</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+## blacklist ps and which mi commands
+## all the other commands shall be traced
+modparam("mi_http", "trace_bwlist", "b: ps, which")
+...
+## allow only sip_trace mi command
+## all the other commands will not be traced
+modparam("mi_http", "trace_bwlist", "w: sip_trace")
+...
+</programlisting>
+		</example>
+	</section>
+
+
+
 	</section>
 
 	<section>