src/man/sssd-systemtap.5.xml - master - githubmirror/sssd

src/man/sssd-systemtap.5.xml
460 строк15 KB
Tomasz Kłoczko
Bump DocBook DTD version to latest stable 4.5
14 фев 2024, 13:31
14 фев 2024, 13:314027930
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/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
attrs: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_parse_entry</term>
                    <listitem>
                        <para>
                            Probes the sdap_parse_entry()
                            function. It is called repeatedly
                            with every received attribute.
                        </para>
                        <programlisting>
attr:string
value:string
                        </programlisting>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>probe sdap_parse_entry_done</term>
                    <listitem>
                        <para>
                            Probes the sdap_parse_entry()
                            function. It is called when
                            parsing of received object is
                            finished.
                        </para>
                    </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>

    <refsect1 id='sample-systemtap-scripts'>
        <title>SAMPLE SYSTEMTAP SCRIPTS</title>
        <para>
            Start the SystemTap script
            (<command>stap /usr/share/sssd/systemtap/&lt;script_name&gt;.stp</command>),
            then perform an identity operation and the script
            will collect information from probes.
        </para>
        <para>
            Provided SystemTap scripts are:
        </para>
        <variablelist>
            <varlistentry>
                <term>dp_request.stp</term>
                <listitem>
                    <para>
                        Monitoring of data provider request performance.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>id_perf.stp</term>
                <listitem>
                    <para>
                        Monitoring of <command>id</command> command
                        performance.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
          <term>ldap_perf.stp</term>
          <listitem>
              <para>
                  Monitoring of LDAP queries.
              </para>
          </listitem>
            </varlistentry>
            <varlistentry>
                <term>nested_group_perf.stp</term>
                <listitem>
                    <para>
                        Performance of nested groups resolving.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsect1>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/seealso.xml" />

</refentry>
</reference>