MAN: Add sssd-systemtap man page

Provide information for administrators and users to utilize
SSSD systemtap infrastructure.

Reviewed-by: Jakub Hrozek <jhrozek@redhat.com>
Reviewed-by: Lukáš Slebodník <lslebodn@redhat.com>

4 files changed, 401 insertions, 1 deletions

diff --git a/src/man/Makefile.am b/src/man/Makefile.am
index 0e35ac277..15022c4fe 100644
--- a/src/man/Makefile.am
+++ b/src/man/Makefile.am
@@ -30,6 +30,9 @@ endif
 if BUILD_SECRETS
 KCM_CONDS = ;with_kcm
 endif
+if BUILD_SYSTEMTAP
+STAP_CONDS = ;with_stap
+endif
 if GPO_DEFAULT_ENFORCING
 GPO_CONDS = ;gpo_default_enforcing
 else
@@ -43,7 +46,7 @@ FILES_CONDS = ;enable_files_domain
 else
 FILES_CONDS = ;no_enable_files_domain
 endif
-CONDS = with_false$(SUDO_CONDS)$(AUTOFS_CONDS)$(SSH_CONDS)$(PAC_RESPONDER_CONDS)$(IFP_CONDS)$(GPO_CONDS)$(SEC_CONDS)$(SYSTEMD_CONDS)$(FILES_CONDS)$(KCM_CONDS)
+CONDS = with_false$(SUDO_CONDS)$(AUTOFS_CONDS)$(SSH_CONDS)$(PAC_RESPONDER_CONDS)$(IFP_CONDS)$(GPO_CONDS)$(SEC_CONDS)$(SYSTEMD_CONDS)$(FILES_CONDS)$(KCM_CONDS)$(STAP_CONDS)
 
 
 #Special Rules:
@@ -92,6 +95,10 @@ if BUILD_KCM
 man_MANS += sssd-kcm.8
 endif
 
+if BUILD_SYSTEMTAP
+man_MANS += sssd-systemtap.5
+endif
+
 if BUILD_NFS_IDMAP
 man_MANS += sss_rpcidmapd.5
 endif
diff --git a/src/man/include/seealso.xml b/src/man/include/seealso.xml
index 9b9a72ce2..52798e460 100644
--- a/src/man/include/seealso.xml
+++ b/src/man/include/seealso.xml
@@ -97,5 +97,11 @@
                 <refentrytitle>sss_rpcidmapd</refentrytitle>
                 <manvolnum>5</manvolnum>
             </citerefentry>
+            <phrase condition="with_stap">
+                <citerefentry>
+                    <refentrytitle>sssd-systemtap</refentrytitle>
+                    <manvolnum>5</manvolnum>
+                </citerefentry>
+            </phrase>
         </para>
     </refsect1>
diff --git a/src/man/po/po4a.cfg b/src/man/po/po4a.cfg
index e9492cfe1..7fd4e3881 100644
--- a/src/man/po/po4a.cfg
+++ b/src/man/po/po4a.cfg
@@ -33,6 +33,7 @@
 [type:docbook] sssd-secrets.5.xml $lang:$(builddir)/$lang/sssd-secrets.5.xml
 [type:docbook] sssd-session-recording.5.xml $lang:$(builddir)/$lang/sssd-session-recording.5.xml
 [type:docbook] sssd-kcm.8.xml $lang:$(builddir)/$lang/sssd-kcm.8.xml
+[type:docbook] sssd-systemtap.5.xml $lang:$(builddir)/$lang/sssd-systemtap.5.xml
 [type:docbook] include/service_discovery.xml $lang:$(builddir)/$lang/include/service_discovery.xml opt:"-k 0"
 [type:docbook] include/upstream.xml $lang:$(builddir)/$lang/include/upstream.xml opt:"-k 0"
 [type:docbook] include/failover.xml $lang:$(builddir)/$lang/include/failover.xml opt:"-k 0"
diff --git a/src/man/sssd-systemtap.5.xml b/src/man/sssd-systemtap.5.xml
new file mode 100644
index 000000000..f7b04e0af
--- /dev/null
+++ b/src/man/sssd-systemtap.5.xml
@@ -0,0 +1,386 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<reference>
+<title>SSSD Manual pages</title>
+<refentry>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" />
+
+    <refmeta>
+        <refentrytitle>sssd-systemtap</refentrytitle>
+        <manvolnum>5</manvolnum>
+        <refmiscinfo class="manual">File Formats and Conventions</refmiscinfo>
+    </refmeta>
+
+    <refnamediv id='name'>
+        <refname>sssd-systemtap</refname>
+        <refpurpose>SSSD systemtap information</refpurpose>
+    </refnamediv>
+
+    <refsect1 id='description'>
+        <title>DESCRIPTION</title>
+        <para>
+            This manual page provides information about
+            the systemtap functionality
+            in
+            <citerefentry>
+                <refentrytitle>sssd</refentrytitle>
+                <manvolnum>8</manvolnum>
+            </citerefentry>.
+       </para>
+        <para>
+            SystemTap Probe points have been added into various
+            locations in SSSD code to assist in troubleshooting
+            and analyzing performance related issues.
+       </para>
+        <para>
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        Sample SystemTap scripts are
+                        provided in /usr/share/sssd/systemtap/
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Probes and miscellaneous functions are
+                        defined in /usr/share/systemtap/tapset/sssd.stp
+                        and /usr/share/systemtap/tapset/sssd_functions.stp
+                        respectively.
+                    </para>
+                </listitem>
+            </itemizedlist>
+        </para>
+    </refsect1>
+
+    <refsect1 id='probe-points'>
+        <title>PROBE POINTS</title>
+        <para>
+            The information below lists the probe points and arguments available
+            in the following format:
+        </para>
+            <variablelist>
+                <varlistentry>
+                    <term>probe $name</term>
+                    <listitem>
+                        <para>
+                            Description of probe point
+                        </para>
+                        <programlisting>
+variable1:datatype
+variable2:datatype
+variable3:datatype
+...
+                        </programlisting>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+
+        <refsect2 id='database-transaction-probes'>
+            <title>Database Transaction Probes</title>
+            <para>
+              <variablelist>
+                <varlistentry>
+                    <term>probe sssd_transaction_start</term>
+                    <listitem>
+                        <para>
+                            Start of a sysdb transaction, probes the
+                            sysdb_transaction_start() function.
+                        </para>
+                        <programlisting>
+nesting:integer
+probestr:string
+                        </programlisting>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>probe sssd_transaction_cancel</term>
+                    <listitem>
+                        <para>
+                            Cancellation of a sysdb transaction,
+                            probes the sysdb_transaction_cancel()
+                            function.
+                        </para>
+                        <programlisting>
+nesting:integer
+probestr:string
+                        </programlisting>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>probe sssd_transaction_commit_before</term>
+                    <listitem>
+                        <para>
+                            Probes the sysdb_transaction_commit_before()
+                            function.
+                        </para>
+                        <programlisting>
+nesting:integer
+probestr:string
+                        </programlisting>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>probe sssd_transaction_commit_after</term>
+                    <listitem>
+                        <para>
+                            Probes the sysdb_transaction_commit_after()
+                            function.
+                        </para>
+                        <programlisting>
+nesting:integer
+probestr:string
+                        </programlisting>
+                    </listitem>
+                </varlistentry>
+              </variablelist>
+            </para>
+        </refsect2>
+
+        <refsect2 id='ldap-search-probes'>
+            <title>LDAP Search Probes</title>
+            <para>
+              <variablelist>
+                <varlistentry>
+                    <term>probe sdap_search_send</term>
+                    <listitem>
+                        <para>
+                            Probes the sdap_get_generic_ext_send()
+                            function.
+                        </para>
+                        <programlisting>
+base:string
+scope:integer
+filter:string
+probestr:string
+                        </programlisting>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>probe sdap_search_recv</term>
+                    <listitem>
+                        <para>
+                            Probes the sdap_get_generic_ext_recv()
+                            function.
+                        </para>
+                        <programlisting>
+base:string
+scope:integer
+filter:string
+probestr:string
+                        </programlisting>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>probe sdap_deref_send</term>
+                    <listitem>
+                        <para>
+                            Probes the sdap_deref_search_send()
+                            function.
+                        </para>
+                        <programlisting>
+base_dn:string
+deref_attr:string
+probestr:string
+                        </programlisting>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>probe sdap_deref_recv</term>
+                    <listitem>
+                        <para>
+                            Probes the sdap_deref_search_recv()
+                            function.
+                        </para>
+                        <programlisting>
+base:string
+scope:integer
+filter:string
+probestr:string
+                        </programlisting>
+                    </listitem>
+                </varlistentry>
+              </variablelist>
+            </para>
+        </refsect2>
+
+       <refsect2 id='ldap-account-req-probes'>
+           <title>LDAP Account Request Probes</title>
+           <para>
+             <variablelist>
+               <varlistentry>
+                   <term>probe sdap_acct_req_send</term>
+                   <listitem>
+                       <para>
+                           Probes the sdap_acct_req_send()
+                           function.
+                       </para>
+                       <programlisting>
+entry_type:int
+filter_type:int
+filter_value:string
+extra_value:string
+                       </programlisting>
+                   </listitem>
+               </varlistentry>
+               <varlistentry>
+                   <term>probe sdap_acct_req_recv</term>
+                   <listitem>
+                       <para>
+                           Probes the sdap_acct_req_recv()
+                           function.
+                       </para>
+                       <programlisting>
+entry_type:int
+filter_type:int
+filter_value:string
+extra_value:string
+                       </programlisting>
+                   </listitem>
+               </varlistentry>
+            </variablelist>
+        </para>
+        </refsect2>
+
+       <refsect2 id='ldap-user-search-probes'>
+           <title>LDAP User Search Probes</title>
+           <para>
+             <variablelist>
+               <varlistentry>
+                   <term>probe sdap_search_user_send</term>
+                   <listitem>
+                       <para>
+                           Probes the sdap_search_user_send()
+                           function.
+                       </para>
+                       <programlisting>
+filter:string
+                       </programlisting>
+                   </listitem>
+               </varlistentry>
+               <varlistentry>
+                   <term>probe sdap_search_user_recv</term>
+                   <listitem>
+                       <para>
+                           Probes the sdap_search_user_recv()
+                           function.
+                       </para>
+                       <programlisting>
+filter:string
+                       </programlisting>
+                   </listitem>
+               </varlistentry>
+               <varlistentry>
+                   <term>probe sdap_search_user_save_begin</term>
+                   <listitem>
+                       <para>
+                           Probes the sdap_search_user_save_begin()
+                           function.
+                       </para>
+                       <programlisting>
+filter:string
+                       </programlisting>
+                   </listitem>
+               </varlistentry>
+               <varlistentry>
+                   <term>probe sdap_search_user_save_end</term>
+                   <listitem>
+                       <para>
+                           Probes the sdap_search_user_save_end()
+                           function.
+                       </para>
+                       <programlisting>
+filter:string
+                       </programlisting>
+                   </listitem>
+               </varlistentry>
+            </variablelist>
+        </para>
+        </refsect2>
+
+       <refsect2 id='data-provider-request-probes'>
+           <title>Data Provider Request Probes</title>
+           <para>
+             <variablelist>
+               <varlistentry>
+                   <term>probe dp_req_send</term>
+                   <listitem>
+                       <para>
+                           A Data Provider request is submitted.
+                       </para>
+                       <programlisting>
+dp_req_domain:string
+dp_req_name:string
+dp_req_target:int
+dp_req_method:int
+                       </programlisting>
+                   </listitem>
+               </varlistentry>
+               <varlistentry>
+                   <term>probe dp_req_done</term>
+                   <listitem>
+                       <para>
+                           A Data Provider request is completed.
+                       </para>
+                       <programlisting>
+dp_req_name:string
+dp_req_target:int
+dp_req_method:int
+dp_ret:int
+dp_errorstr:string
+                       </programlisting>
+                   </listitem>
+               </varlistentry>
+            </variablelist>
+        </para>
+        </refsect2>
+
+    <refsect2 id='miscellaneous-functions'>
+        <title>MISCELLANEOUS FUNCTIONS</title>
+        <para>
+            The information below lists the probe points and arguments available
+            in the following format:
+        </para>
+            <variablelist>
+                <varlistentry>
+                    <term>function acct_req_desc(entry_type)</term>
+                    <listitem>
+                        <para>
+                            Convert entry_type to string and return string
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>function sssd_acct_req_probestr(fc_name, entry_type,
+                          filter_type, filter_value, extra_value)</term>
+                    <listitem>
+                        <para>
+                            Create probe string based on filter type
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>function dp_target_str(target)</term>
+                    <listitem>
+                        <para>
+                            Convert target to string and return string
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>function dp_method_str(target)</term>
+                    <listitem>
+                        <para>
+                            Convert method to string and return string
+                        </para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+    </refsect2>
+
+    </refsect1>
+
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/seealso.xml" />
+
+</refentry>
+</reference>