xlog_user.sgml

来自「性能优秀的SIP Proxy」· SGML 代码 · 共 243 行

<!-- Module User's Guide -->

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1.6 $</revnumber>
		<date>$Date: 2005/11/28 13:39:19 $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<para>
		This module provides the possibility to print user formatted log or
		debug messages from &ser; scripts, similar to printf function but now
		a specifier is replaced with a part of the &sip; request or other
		variables from system.
		<xref linkend="sec-implemented-specifiers"> shows what can be printed
		out.
	</para>
	</section>
	<section id="sec-implemented-specifiers">
	<title>Implemented Specifiers</title>
	<para>
	The specifiers have been replaced by pseudo-variables which are
	now part of &ser; core and are used by other modules as well (e.g., avpops
	in the function avp_printf())
	</para>
	<para>
	The most important changes are:
	</para>
	<itemizedlist>
		<listitem>
		<para>
		- '%' has been replaced by '$'
		</para>
		</listitem>
		<listitem>
		<para>
		- to print a header, use now $hdr(header_name[index]) instead of
		%{header_name[index]}
		</para>
		</listitem>
		<listitem>
		<para>
		- to print an AVP, use now $avp([si]:avp_id[index]) instead of
		%{[si]:avp_id[index]} or $avp([$avp_alias[index]) instead of
		%{[$avp_alias[index]}
		</para>
		</listitem>
	</itemizedlist>
	<para>
	The full list of available pseudo-variables in &ser; is availabe at:
	<ulink url="http://openser.org/docs/pseudo-variables-1.1.x.html">
	http://openser.org/docs/pseudo-variables-1.1.x.html</ulink>
	</para>
	</section>
	<section>
	<title>Dependencies</title>
	<section>
		<title>&ser; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &ser; modules</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&ser; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>buf_size</varname> (integer)</title>
		<para>
		Maximum size of the log message.
		</para>
		<para>
		<emphasis>
			Default value is 4096.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>buf_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("xlog", "buf_size", 8192)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>force_color</varname> (integer)</title>
		<para>
		When set to 1, forces color printing even if log_stderror=0.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>force_color</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("xlog", "force_color", 0)
...
</programlisting>
		</example>
	</section>
	</section>
	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">xlog([level,] format)</function>
		</title>
		<para>
		Print a formated message using LOG function.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>level</emphasis> - The level that will be used in LOG function. It can be:
			</para>
			<itemizedlist>
			<listitem>
				<para>
				L_ALERT
				</para>
			</listitem>
			<listitem>
				<para>
				L_CRIT
				</para>
			</listitem>
			<listitem>
				<para>
				L_ERR
				</para>
			</listitem>
			<listitem>
				<para>
				L_WARN
				</para>
			</listitem>
			<listitem>
				<para>
				L_NOTICE
				</para>
			</listitem>
			<listitem>
				<para>
				L_INFO
				</para>
			</listitem>
			<listitem>
				<para>
				L_DBG
				</para>
			</listitem>
			</itemizedlist>
			<para>
			What really matters is the third letter of the value.
			</para>
			<para>
			If this parameter is missing, the implicit log level is 'L_ERR'.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>format</emphasis> - The formatted string to be printed. 
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>xlog</function> usage</title>
		<programlisting format="linespecific">
...
xlog("L_ERR", "time [$Tf] method <$rm> r-uri <$ru> 2nd via <$hdr(via[1])>\n");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">xdbg(format)</function>
		</title>
		<para>
		Print a formatted message using DBG function.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>format</emphasis> - The formatted string to be printed.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE.
		</para>

		<example>
		<title><function>xdbg</function> usage</title>
		<programlisting format="linespecific">
...
xdbg("time $Cbx[$Tf]$Cxx method <$rm> r-uri <$ru>\n");
...
</programlisting>
		</example>
	</section>
	</section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("xlog.sgml" "Book" "chapter")
End:
-->