Td User Manual: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(37 intermediate revisions by the same user not shown)
Line 1: Line 1:
=Internal=
=Internal=


* [[tda#User_Manual|tda]]
* [[events-java-threads#User_Manual|events-java-threads]]


=Overview=


The utility works by default in a manner similar to grep, processing the thread dump file sequentially, one thread dump at a time. It filters the thread stacks based on given regular expression and displays the output, subject to options. More than one thread dump in a single file are supported.
{{Error|REFACTOR}}
 
=NEW SYNTAX=
 
 
td <''field-name''>:<''regex''> [''procedure''] ./stacks.txt
 
 
Fields:
 
* ''thread-name''
* ''os-prio''
* ''prio''
* ''tid''
* ''nid''
* ''thread-state''
* ''daemon''
* ''object-wait-monitor''
* ''stack''
 
==Generic Procedures==
 
====count====
<font color=red>TODO - link</font>
 
====describe====
<font color=red>TODO - link</font>
 
====exclude====
<font color=red>TODO - link</font>
 
====output====
 
<font color=red>TODO - link</font>
 
====timegaps====
<font color=red>TODO - link</font>
 
==td Specific Procedures==
 
====count====
 
Counts the number of stack traces (possibly only those that matched the query, if a query was used) per thread dump, in a time series CSV format.
 
====names====
 
Thread dump names, alphabetically (subject to query).
 


=Syntax=


tda [options] <regex|command> <thread-dump-file> [thread-dump-file, ...]
{{Error|REFACTOR}}


=grep Mode=
=Overview=


The default command, and simplest possible usage is to filter and display at standard output only
tda (Thread Dump Analyzer) is a command-line utility that can be used to process Java thread dumps.  
the stack traces that match the given regular expression. For example:


    tda http- thread-dump-file.txt
This documentation defines a [[Java_Threads#Thread_Dump|thread dump]] as the result of one invocation of the [[jstack]] command, or of sending [[Linux_Signals#SIGQUIT_.283.29|SIGQUIT]] (-3) into the Java virtual machine process. A thread dump consists in a set of [[Java_Threads#Stack_Trace|stack traces]], one stack trace for each thread in the Java virtual machine.


will display at stdout only the stack traces that contain "http-".
tda works by default in a manner [[#grep_Mode|similar to grep]], processing the thread dump file sequentially, one thread dump at a time. Multiple thread dumps (i.e. the result of multiple invocations, at different moments in time), may be present in the file, and tda distinguishes this situation, by handling each thread dump individually. Once the stack trances are parsed, tda matches their content against the given regular expression and displays the stack traces that match.  


The regular expression uses the grep syntax. More details about supported regular expressions are available in the "[[#Regular_Expression_Syntax|Regular Expression Syntax]]" section.


Options:
=Syntax=


    -v <regex> <thread-dump-file> - sequentially reads the thread dump file and outputs
tda [options] [regex|command] <thread-dump-file> [thread-dump-file, ...]
            at stdout all thread dumps that DO NOT contain the regular expression.


    -c (count) counts the number of threads that match the regular expression, but does not
=grep Mode=
            display them. It displays the count at stdout instead. If only the file name is
            specified, the regular expression is assumed to be "match all", as in the following
            example:


                tda -c thread-dump-file.txt
The utility filters and displays at standard output only the stack traces that match the given regular expression. For example:


     -s (split) extracts individual thread dumps from the log file and places them into separate
     tda http- thread-dump-file.txt
            files. The name of the files is built based on the counter and timestamp (if
            available).


    --<ExtensionClassName> (example --FSI, --FFM) where the class should be available in
will display at stdout only the stack traces that contain "http-", anywhere in the stack trace, including method invocation lines. The regular expression is optional. If missing, all stack traces present in the file will be displayed. The output can be modified with the following options:
            com/novaordis/universus/tdanalyzer/extensions


Regular Expression Syntax:
==-c==


tda is designed to use the same regular expressions as grep.
Counts the number of threads that match the regular expression, and display the number. If only the file name is specified, the regular expression is assumed to be "match all".


    Spaces - enclosing the regular expression in double quotes preserves spaces. Example
==-v==


            tda "on object monitor" thread-dump-file.txt
Invert match. Select the stack traces that do not match the regular expression.


Other commands:
=Regular Expression Syntax=


    diff <thread-dump-file-1> <thread-dump-file-2> shows the difference between the thread dumps.
tda is designed to use the same regular expressions as grep.


    help
If the regular expression contains spaces, it can be specified on command line by enclosing it in double quotes: double quotes preserve spaces, which are passed as such to the Java runtime:


    version
tda "on object monitor" thread-dump-file.txt


=Other Commands=
=Other Commands=


==count==
==split==
 
Extracts individual thread dumps from the a thread dump file that contains a concatenation of multiple thread dumps, and places them into separate files. The files are named based on the counter and timestamp (if available).


==diff==
==diff==
Line 64: Line 104:
  tda diff ''<thread-dump-file1.out>'' ''<thread-dump-file2.out>''
  tda diff ''<thread-dump-file1.out>'' ''<thread-dump-file2.out>''


The simplest form of the diff command compares the thread dump files and displays the names of the names of the threads that are present in one file and not in the other.
The current implementation of the diff command compares two thread dumps and displays the names of the threads that are found in one dump, but not in another, based on a TID comparison.


==version==
==version==
Displays the tda version.


==help==
==help==


In-line help.
Displays a brief in-line help that contains a link to this page.
 
=Extensions=
 
--<ExtensionClassName>
 
--FSI,
--FFM
 
where the class should be available in com/novaordis/universus/tdanalyzer/extensions.
 
<font color=red>To review this.</font>

Latest revision as of 08:20, 30 November 2017

Internal



REFACTOR

NEW SYNTAX

td <field-name>:<regex> [procedure] ./stacks.txt


Fields:

  • thread-name
  • os-prio
  • prio
  • tid
  • nid
  • thread-state
  • daemon
  • object-wait-monitor
  • stack

Generic Procedures

count

TODO - link

describe

TODO - link

exclude

TODO - link

output

TODO - link

timegaps

TODO - link

td Specific Procedures

count

Counts the number of stack traces (possibly only those that matched the query, if a query was used) per thread dump, in a time series CSV format.

names

Thread dump names, alphabetically (subject to query).



REFACTOR

Overview

tda (Thread Dump Analyzer) is a command-line utility that can be used to process Java thread dumps.

This documentation defines a thread dump as the result of one invocation of the jstack command, or of sending SIGQUIT (-3) into the Java virtual machine process. A thread dump consists in a set of stack traces, one stack trace for each thread in the Java virtual machine.

tda works by default in a manner similar to grep, processing the thread dump file sequentially, one thread dump at a time. Multiple thread dumps (i.e. the result of multiple invocations, at different moments in time), may be present in the file, and tda distinguishes this situation, by handling each thread dump individually. Once the stack trances are parsed, tda matches their content against the given regular expression and displays the stack traces that match.

The regular expression uses the grep syntax. More details about supported regular expressions are available in the "Regular Expression Syntax" section.

Syntax

tda [options] [regex|command] <thread-dump-file> [thread-dump-file, ...]

grep Mode

The utility filters and displays at standard output only the stack traces that match the given regular expression. For example: 

   tda http- thread-dump-file.txt

will display at stdout only the stack traces that contain "http-", anywhere in the stack trace, including method invocation lines. The regular expression is optional. If missing, all stack traces present in the file will be displayed. The output can be modified with the following options:

-c

Counts the number of threads that match the regular expression, and display the number. If only the file name is specified, the regular expression is assumed to be "match all".

-v

Invert match. Select the stack traces that do not match the regular expression.

Regular Expression Syntax

tda is designed to use the same regular expressions as grep.

If the regular expression contains spaces, it can be specified on command line by enclosing it in double quotes: double quotes preserve spaces, which are passed as such to the Java runtime: 

tda "on object monitor" thread-dump-file.txt

Other Commands

split

Extracts individual thread dumps from the a thread dump file that contains a concatenation of multiple thread dumps, and places them into separate files. The files are named based on the counter and timestamp (if available).

diff

tda diff <thread-dump-file1.out> <thread-dump-file2.out>

The current implementation of the diff command compares two thread dumps and displays the names of the threads that are found in one dump, but not in another, based on a TID comparison.

version

Displays the tda version.

help

Displays a brief in-line help that contains a link to this page.

Extensions

--<ExtensionClassName> 

--FSI, 
--FFM

where the class should be available in com/novaordis/universus/tdanalyzer/extensions.

To review this.

Retrieved from "https://kb.novaordis.com/index.php?title=Td_User_Manual&oldid=33184"