flopsar.github.io/user.html at master · flopsar/flopsar.github.io · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000


<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">

  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  <title>1. Workstation Installation &mdash; Flopsar Documentation</title>


  <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="_static/hacks.css" type="text/css" />
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="1. Agent API" href="developer.html" />
    <link rel="prev" title="5. Database" href="database.html" />


  <script src="_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav">


  <div class="wy-grid-for-nav">


    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">


            <a href="index.html">


            <img src="_static/flopsar_logo.png" class="logo" alt="Logo"/>

          </a>


              <div class="version">
                2.4
              </div>


<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>


        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">


              <p class="caption"><span class="caption-text">Overview</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="overview.html">1. What is Flopsar</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html#versioning">2. Versioning</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html#releasing">3. Releasing</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html#licensing">4. Licensing</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html#architectural-fundamentals">5. Architectural Fundamentals</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html#supported-platforms-and-requirements">6. Supported Platforms and Requirements</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html#distribution-package">7. Distribution Package</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html#release-notes">8. Release Notes</a></li>
</ul>
<p class="caption"><span class="caption-text">Administrator Guide</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="admin.html">1. Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="admin.html#logging">2. Logging</a></li>
<li class="toctree-l1"><a class="reference internal" href="admin.html#id2">3. Agent</a></li>
<li class="toctree-l1"><a class="reference internal" href="manager.html">4. Manager</a></li>
<li class="toctree-l1"><a class="reference internal" href="database.html">5. Database</a></li>
</ul>
<p class="caption"><span class="caption-text">User Guide</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">1. Workstation Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="#accessing-flopsar-environment">2. Accessing Flopsar Environment</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#remote-access">2.1. Remote Access</a></li>
<li class="toctree-l2"><a class="reference internal" href="#local-access">2.2. Local Access</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#start-page">3. Start Page</a></li>
<li class="toctree-l1"><a class="reference internal" href="#settings">4. Settings</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#general">4.1. General</a></li>
<li class="toctree-l2"><a class="reference internal" href="#connections">4.2. Connections</a></li>
<li class="toctree-l2"><a class="reference internal" href="#permissions">4.3. Permissions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#configurations">5. Configurations</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#instrumentation-rules">5.1. Instrumentation Rules</a></li>
<li class="toctree-l2"><a class="reference internal" href="#hot-methods">5.2. Hot Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="#jmx">5.3. JMX</a></li>
<li class="toctree-l2"><a class="reference internal" href="#deploying-configurations">5.4. Deploying Configurations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#galaxies">6. Galaxies</a></li>
<li class="toctree-l1"><a class="reference internal" href="#agents">7. Agents</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#charts">7.1. Charts</a></li>
<li class="toctree-l2"><a class="reference internal" href="#system-properties">7.2. System Properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="#application-packages">7.3. Application Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="#class-loaders">7.4. Class Loaders</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#queries">8. Queries</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#flame-graph-of-transactions">8.1. Flame Graph of Transactions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#galaxy-of-transactions">8.2. Galaxy of Transactions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#garbage-collector">8.3. Garbage Collector</a></li>
<li class="toctree-l2"><a class="reference internal" href="#generic-key-value-metric">8.4. Generic Key-Value Metric</a></li>
<li class="toctree-l2"><a class="reference internal" href="#method-execution-analysis">8.5. Method Execution Analysis</a></li>
<li class="toctree-l2"><a class="reference internal" href="#transactions">8.6. Transactions</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#execution-stack-interpretation">8.6.1. Execution Stack Interpretation</a></li>
<li class="toctree-l3"><a class="reference internal" href="#threads-subview">8.6.2. Threads Subview</a></li>
<li class="toctree-l3"><a class="reference internal" href="#components-subview">8.6.3. Components Subview</a></li>
<li class="toctree-l3"><a class="reference internal" href="#errors-subview">8.6.4. Errors Subview</a></li>
<li class="toctree-l3"><a class="reference internal" href="#time-and-duration-subviews">8.6.5. Time and Duration Subviews</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#threads-dump">8.7. Threads Dump</a></li>
<li class="toctree-l2"><a class="reference internal" href="#top-30-exceptions">8.8. Top 30 Exceptions</a></li>
</ul>
</li>
</ul>
<p class="caption"><span class="caption-text">Developer Guide</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="developer.html">1. Agent API</a></li>
<li class="toctree-l1"><a class="reference internal" href="developer.html#agent-formatters">2. Agent Formatters</a></li>
<li class="toctree-l1"><a class="reference internal" href="developer.html#database-api">3. Database API</a></li>
<li class="toctree-l1"><a class="reference internal" href="developer.html#plugins">4. Plugins</a></li>
</ul>
<p class="caption"><span class="caption-text">Miscellaneous</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="tshooting.html">Troubleshooting</a></li>
<li class="toctree-l1"><a class="reference internal" href="demo.html">Demo</a></li>
<li class="toctree-l1"><a class="reference internal" href="contrib.html">Third-party Components</a></li>
</ul>


        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">


      <nav class="wy-nav-top" aria-label="top navigation">

          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">Flopsar</a>

      </nav>


      <div class="wy-nav-content">

        <div class="rst-content">


<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">

      <li><a href="index.html">Docs</a> &raquo;</li>

      <li>1. Workstation Installation</li>


      <li class="wy-breadcrumbs-aside">


      </li>

  </ul>


  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">

  <p>This guide describes Flopsar Workstation usage.</p>
<div class="section" id="workstation-installation">
<h1>1. Workstation Installation<a class="headerlink" href="#workstation-installation" title="Permalink to this headline">¶</a></h1>
<p>Flopsar Workstation is a GUI client of the Flopsar environment.</p>
<p>Installation is straightforward, just copy the <code class="file docutils literal notranslate"><span class="pre">workstation-2.4.zip</span></code> file to your machine and uncompress it. Next, run a <span class="opt">workstation</span> script from <code class="file docutils literal notranslate"><span class="pre">bin</span></code> directory.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You should have your Java environment set before you try to run the workstation application.</p>
</div>
</div>
<div class="section" id="accessing-flopsar-environment">
<h1>2. Accessing Flopsar Environment<a class="headerlink" href="#accessing-flopsar-environment" title="Permalink to this headline">¶</a></h1>
<p>When you execute the above command a login window <a class="reference internal" href="#gui-logon"><span class="std std-numref">Fig. 2.1</span></a> should appear.</p>
<div class="figure align-center" id="id4">
<span id="gui-logon"></span><img alt="_images/logon.png" src="_images/logon.png" />
<p class="caption"><span class="caption-number">Fig. 2.1 </span><span class="caption-text">Workstation Login: Remote Access</span></p>
</div>
<p>If you want to connect to some remote <span class="flp">manager</span>, select the <span class="guilabel">Remote</span> radio button.
If you want to access your local copy of some database, select the <span class="guilabel">Local</span> radio button.</p>
<div class="section" id="remote-access">
<h2>2.1. Remote Access<a class="headerlink" href="#remote-access" title="Permalink to this headline">¶</a></h2>
<p>If you run <span class="flp">workstation</span> for the first time, the <span class="guilabel">Connection ID</span> combo box control is empty. In order to connect to your <span class="flp">manager</span> instance, you must specify some connection identifier (label) and input <span class="flp">manager</span> socket address in the form <span class="opt">host:port</span>. You must also provide your credentials and then click the <span class="guilabel">Connect</span> button.
When you log to the <span class="flp">manager</span> instance successfully, the login window disappears and the main application window <a class="reference internal" href="#gui-start"><span class="std std-numref">Fig. 3.3</span></a> appears instead. After a successful connection, your connection data are stored locally so that next time you start the application, the combo box will be filled with this stored connection information.</p>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">Default credentials when using Flopsar Internal Authentication are as follows: the username is <strong>admin</strong> and the password is <strong>flopsar</strong>.</p>
</div>
</div>
<div class="section" id="local-access">
<h2>2.2. Local Access<a class="headerlink" href="#local-access" title="Permalink to this headline">¶</a></h2>
<p>In order to access your database locally, you just need to get the archive file from a selected database instance and copy it to your local disk.
Next, click the option menu in the login window <a class="reference internal" href="#gui-logon"><span class="std std-numref">Fig. 2.1</span></a> and then select the <span class="guilabel">Local</span> item.
Select either <span class="guilabel">Storage</span> or <span class="guilabel">Archive File</span> option and click on the <span class="guilabel">…</span> button to point to the database directory of the archive file, respectively.
Next, click the <span class="guilabel">CONNECT</span> button.</p>
<div class="figure align-center" id="id5">
<span id="gui-logon2"></span><img alt="_images/logon2.png" src="_images/logon2.png" />
<p class="caption"><span class="caption-number">Fig. 2.2 </span><span class="caption-text">Workstation Login: Local Access</span></p>
</div>
</div>
</div>
<div class="section" id="start-page">
<h1>3. Start Page<a class="headerlink" href="#start-page" title="Permalink to this headline">¶</a></h1>
<p>After you logged to the application, you should see its start page <a class="reference internal" href="#gui-start"><span class="std std-numref">Fig. 3.3</span></a>. There is a list of available queries
you can make to the databases.</p>
<p>At the bottom, there is your current connection information to your <span class="flp">manager</span> and the number of connected databases.
On the right side, there is a memory usage information of the application.</p>
<div class="figure align-center" id="id6">
<span id="gui-start"></span><img alt="_images/screen1.png" src="_images/screen1.png" />
<p class="caption"><span class="caption-number">Fig. 3.3 </span><span class="caption-text">Workstation: Start Page</span></p>
</div>
<p>If you access your local storage, you do not see the same <span class="flp">workstation</span> functionalities as in the remote access.
That is because you do not connect to any <span class="flp">manager</span> instance, and the <span class="flp">workstation</span> runs in a <em>viewer</em> mode.
At the bottom, there is a current local storage identifier and the number of connected databases (only one in this case).
In both cases (remote and local), if you click the database icon, the pop-up <a class="reference internal" href="#gui-databases"><span class="std std-numref">Fig. 3.4</span></a> will appear with a list of databases.
The list contains databases your manager is aware of. The list entries have socket addresses and versions of the databases.
There is a link icon, at the beginning of each entry, which denotes a connection status.
If the link is green, then the corresponding database connection is established.
The link turns red if the connection is lost or does not exist.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In case of local access, the database address is always <em>localhost</em>.</p>
</div>
<div class="figure align-center" id="id7">
<span id="gui-databases"></span><img alt="_images/screen17.png" src="_images/screen17.png" />
<p class="caption"><span class="caption-number">Fig. 3.4 </span><span class="caption-text">Connected Databases</span></p>
</div>
<p>You can switch between different contexts by clicking the hamburger menu in <a class="reference internal" href="#gui-start"><span class="std std-numref">Fig. 3.3</span></a>.
A drawer <a class="reference internal" href="#gui-drawer"><span class="std std-numref">Fig. 3.5</span></a> will appear with a list of contexts. In order to manage your configurations
click the <span class="guilabel">CONFIGURATIONS</span> (see <a class="reference internal" href="#manage-agent-conf"><span class="std std-ref">Configurations</span></a> for details). The <span class="guilabel">AGENTS</span>
leads to a view where you can explore all the available agents (see <a class="reference internal" href="#agents-health"><span class="std std-ref">Agents</span></a> for details).
The <span class="guilabel">GALAXIES</span> will take you to a view where you can manage your galaxies (see <a class="reference internal" href="#galaxies"><span class="std std-ref">Galaxies</span></a> for details).</p>
<div class="figure align-center" id="id8">
<span id="gui-drawer"></span><img alt="_images/drawer.png" src="_images/drawer.png" />
<p class="caption"><span class="caption-number">Fig. 3.5 </span><span class="caption-text">Workstation: Start Page Menu</span></p>
</div>
</div>
<div class="section" id="settings">
<h1>4. Settings<a class="headerlink" href="#settings" title="Permalink to this headline">¶</a></h1>
<p><span class="flp">workstation</span> stores its settings locally, on the machine it runs on.
It makes use of <a class="reference external" href="http://docs.oracle.com/javase/7/docs/technotes/guides/preferences/">Java Preferences API</a> to store its configuration.
The physical location of the settings depends on a platform the workstation runs on.</p>
<p>When you exit the application, it stores its current settings.
These settings include the main application window size, some tables columns width, galaxy colors and the like.</p>
<div class="section" id="general">
<h2>4.1. General<a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h2>
<p>By default, all the <span class="flp">workstation</span> logs are stored in a user home directory.
This can be changed in the preferences window <a class="reference internal" href="#gui-pref-logger"><span class="std std-numref">Fig. 4.2</span></a>, where you can set both the logger level and the logs location.
The logging levels are defined in <a class="reference internal" href="admin.html#logging"><span class="std std-ref">Logging</span></a>.</p>
<div class="figure align-center" id="id9">
<span id="gui-pref-logger"></span><img alt="_images/pref1.png" src="_images/pref1.png" />
<p class="caption"><span class="caption-number">Fig. 4.2 </span><span class="caption-text">Preferences: General</span></p>
</div>
<p>You can also check if there is a new Flopsar version available. In order to check it, just click the
<span class="guilabel">CHECK NOW</span> button. If you enable the <span class="guilabel">Check automatically</span>, then whenever you
start the workstation, it will check for updates automatically.</p>
</div>
<div class="section" id="connections">
<h2>4.2. Connections<a class="headerlink" href="#connections" title="Permalink to this headline">¶</a></h2>
<p>Besides the layout settings, your <span class="flp">manager</span> connections information is also stored in these settings.
You can either edit or delete these connections in the preferences window <a class="reference internal" href="#gui-pref-conns"><span class="std std-numref">Fig. 4.3</span></a>.</p>
<div class="figure align-center" id="id10">
<span id="gui-pref-conns"></span><img alt="_images/pref2.png" src="_images/pref2.png" />
<p class="caption"><span class="caption-number">Fig. 4.3 </span><span class="caption-text">Preferences: Connections</span></p>
</div>
</div>
<div class="section" id="permissions">
<h2>4.3. Permissions<a class="headerlink" href="#permissions" title="Permalink to this headline">¶</a></h2>
<p>In this view, you can check which permissions you are granted.
These settings are read-only and can be changed only in <span class="flp">manager</span> (see <a class="reference internal" href="manager.html#authorization"><span class="std std-ref">Authorization</span></a> for more details).</p>
<div class="figure align-center" id="id11">
<img alt="_images/perms.png" src="_images/perms.png" />
<p class="caption"><span class="caption-number">Fig. 4.4 </span><span class="caption-text">Preferences: Permissions</span></p>
</div>
</div>
</div>
<div class="section" id="configurations">
<span id="manage-agent-conf"></span><h1>5. Configurations<a class="headerlink" href="#configurations" title="Permalink to this headline">¶</a></h1>
<p>Agents configurations are managed from <span class="flp">workstation</span>.
You must click the <span class="guilabel">CONFIGURATIONS</span> menu item in <a class="reference internal" href="#gui-drawer"><span class="std std-numref">Fig. 3.5</span></a> view to get the list of all the configurations.</p>
<div class="figure align-center" id="id12">
<span id="gui-conf"></span><img alt="_images/configurations.png" src="_images/configurations.png" />
<p class="caption"><span class="caption-number">Fig. 5.7 </span><span class="caption-text">Agents’ Configurations</span></p>
</div>
<p>Configurations are stored in the manager. When you double-click a selected configuration,
the configuration is retrieved from the manager and displayed. Each configuration can have two copies: the active <a class="reference internal" href="#gui-configuration"><span class="std std-numref">Fig. 5.9</span></a> and inactive <a class="reference internal" href="#gui-conf-edit"><span class="std std-numref">Fig. 5.8</span></a> one.
The active configuration is the one that is currently deployed. The inactive configuration is the one that is currently edited.
If a configuration have both copies, the inactive one will be shown by default.
You can switch between configurations using the edit icon, just before the configuration label.</p>
<p>In order to add a new configuration, click the <span class="guilabel">+</span> button.</p>
<div class="figure align-center" id="id13">
<span id="gui-conf-edit"></span><img alt="_images/cedit.png" src="_images/cedit.png" />
<p class="caption"><span class="caption-number">Fig. 5.8 </span><span class="caption-text">Inactive Configuration</span></p>
</div>
<p>The edit view <a class="reference internal" href="#gui-conf-edit"><span class="std std-numref">Fig. 5.8</span></a> is divided into two parts.
The first tab is where you define instrumentation rules and the second one is where you define JMX beans to collect data from.</p>
<div class="figure align-center" id="id14">
<span id="gui-configuration"></span><img alt="_images/aconf.png" src="_images/aconf.png" />
<p class="caption"><span class="caption-number">Fig. 5.9 </span><span class="caption-text">Active Configuration</span></p>
</div>
<p>There is a third tab called <span class="guilabel">Attached Agents</span> in the active configuration view.
You can select and attach/detach agents to the configuration in this tab.</p>
<div class="section" id="instrumentation-rules">
<h2>5.1. Instrumentation Rules<a class="headerlink" href="#instrumentation-rules" title="Permalink to this headline">¶</a></h2>
<p>Each instrumentation rule is either enabled or disabled. You can turn on and off rules using their toggle buttons.
When a rule is disabled, it is not evaluated by agents.</p>
<p>There is either red or green bar at the beginning of each instrumentation rules entry. Exclusion rules are red and inclusion rules are green.</p>
<p>There are two <span class="guilabel">+</span> buttons in the list of instrumentation rules <a class="reference internal" href="#gui-conf-edit"><span class="std std-numref">Fig. 5.8</span></a>. If you want to define an inclusion rule you should click the green button, otherwise click the red one.</p>
<p>In the <span class="guilabel">threshold</span> field you can specify a threshold value for methods duration. In other words, you specify the lowest value of instrumented methods execution time above which these method calls will be reported. In the <span class="guilabel">cpu time</span> field you can select whether you want agents to report CPU time or not.</p>
<p>You have two types of rules at your disposal: <span class="red">exclusions</span> and <span class="green">inclusions</span> and two levels of rules: <em>class</em> and <em>method</em> ones. Basically, you should specify at least one inclusion rule for classes and one for methods to have a valid configuration.</p>
<div class="topic">
<p class="topic-title first">Including Classes</p>
<p>In order to add a class level rule, select <span class="guilabel">Class Rule</span> from the green button menu. In the <a class="reference internal" href="#gui-rule1inst"><span class="std std-numref">Fig. 5.10</span></a> form you specify which classes you want to instrument.
If you want to match classes by their names, you should select the <span class="guilabel">Class name</span> radio button. If you want to instrument classes, which extend some super class, you should select the <span class="guilabel">Super class</span>. In this case you need to specify the fully qualified super class name.
If you want to instrument classes which implement some interface, you should select the <span class="guilabel">Interface</span>. You must then specify a fully qualified name of the interface. Finally, if you want to instrument classes, which are annotated by some annotation, you should select the <span class="guilabel">Annotation</span>. You must then specify a fully qualified name of the annotation.</p>
</div>
<div class="figure align-center" id="id15">
<span id="gui-rule1inst"></span><img alt="_images/rule1inst.png" src="_images/rule1inst.png" />
<p class="caption"><span class="caption-number">Fig. 5.10 </span><span class="caption-text">Include Class Rule</span></p>
</div>
<p>If you want to instrument classes from particular packages, just select the <span class="guilabel">Class from Packages</span> from the green button menu.
This operation will retrieve available packages from all the attached agents. You can add rules by double-clicking selected packages.</p>
<div class="figure align-center" id="id16">
<span id="gui-rule2inst"></span><img alt="_images/rule2inst.png" src="_images/rule2inst.png" />
<p class="caption"><span class="caption-number">Fig. 5.11 </span><span class="caption-text">Include Packages</span></p>
</div>
<div class="topic">
<p class="topic-title first">Including Methods</p>
<p>In order to add a method level rule, select <span class="guilabel">Method Rule</span> from the green button menu.
You can specify methods for instrumentation by their access modifiers. Just select the modifier so that those methods are instrumented, whose modifiers match one of the selected.
You can also specify methods by exceptions they throw. Just select the <span class="guilabel">Exception</span> radio button and specify the exception class.</p>
</div>
<div class="figure align-center" id="id17">
<span id="gui-rule3inst"></span><img alt="_images/rule3inst.png" src="_images/rule3inst.png" />
<p class="caption"><span class="caption-number">Fig. 5.12 </span><span class="caption-text">Include Method Rule</span></p>
</div>
<p>If you want to instrument methods with formatters, you should select the <span class="guilabel">Formatted Method Rule</span> from the green button menu.</p>
<p>There are some input fields that need to be filled (<a class="reference internal" href="#gui-rule4inst"><span class="std std-numref">Fig. 5.13</span></a>).
In the <span class="guilabel">Class</span> field you can specify the exact class, your instrumented method should belong to.
If you do not want to specify the class, than you should select the <span class="guilabel">Any</span> checkbox.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Please note that any method, which matches the specified pattern, in any class will be instrumented with the formatter if you select <span class="guilabel">Any</span> checkbox.</p>
</div>
<p>In the second field (text area), you must specify the exact method signature you want to instrument.
You should ignore argument names and specify fully qualified class names of all objects.
In the <span class="guilabel">OPTIONS</span> row you have three, additional options to select.
If you want to ignore the configuration <span class="guilabel">threshold</span>, select the <span class="guilabel">Ignore threshold</span> checkbox.
If you want to instrument the method on exit, select the <span class="guilabel">Instrument on exit</span> checkbox.</p>
<p>Now, if you want to report only parameter values without any preprocessing you can now click the <span class="guilabel">OK</span> button and you have your rule defined.
However, if you want to add some custom processing you should select <span class="guilabel">Custom formatter</span> option.</p>
<div class="figure align-center" id="id18">
<span id="gui-rule4inst"></span><img alt="_images/rule4inst.png" src="_images/rule4inst.png" />
<p class="caption"><span class="caption-number">Fig. 5.13 </span><span class="caption-text">Include Formatted Method Rule</span></p>
</div>
<p>First of all, you must then specify the formatter signature.
There are two ways of specifying the formatter signature.
The first one is to specify it manually by entering the class and the method name of your formatter.
The second one is used when you already have some implemented formatters.
You just need to click the <span class="guilabel">IMPORT</span> button and select a jar file with your formatters.
The application will scan the jar and populate the formatters combo box with all the found and valid formatters.
Select one of the formatters, click the <span class="guilabel">OK</span> button and you have your formatter rule created.</p>
<div class="topic">
<p class="topic-title first">Excluding Classes</p>
<p>If you want to exclude some classes from the configuration, select the <span class="guilabel">Class Rule</span> from the red button menu.
Then, specify the pattern for fully qualified class names. If you specify the asterisk at the end, the rule will match every class, whose fully qualified name starts with the specified pattern. Otherwise, the exact match will be checked.</p>
</div>
<div class="figure align-center" id="id19">
<span id="gui-erule1inst"></span><img alt="_images/erule1inst.png" src="_images/erule1inst.png" />
<p class="caption"><span class="caption-number">Fig. 5.14 </span><span class="caption-text">Exclude Class</span></p>
</div>
<div class="topic">
<p class="topic-title first">Excluding Methods</p>
<p>When you are done with classes rules, you need to specify some method rules.
If you do not want to instrument getter/setter methods, you should select the <span class="guilabel">Method Accessors</span> from the red button menu.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">By setters/getters we mean accessor methods of a private instance field.</p>
</div>
<p>If you want to exclude some methods basing on their names, you should select the <span class="guilabel">Method Rule</span> from the red button menu.
Here, you must specify a regular expression pattern for names. Finally, you can also exclude specific methods by selecting them from a list retrieved from running agents by selecting the <span class="guilabel">Hot Methods</span> tab (see <a class="reference internal" href="#gui-hot-methods"><span class="std std-ref">Hot Methods</span></a> for details).</p>
<div class="figure align-center" id="id20">
<span id="gui-erule2inst"></span><img alt="_images/erule2inst.png" src="_images/erule2inst.png" />
<p class="caption"><span class="caption-number">Fig. 5.15 </span><span class="caption-text">Exclude Methods</span></p>
</div>
</div>
<div class="section" id="hot-methods">
<span id="gui-hot-methods"></span><h2>5.2. Hot Methods<a class="headerlink" href="#hot-methods" title="Permalink to this headline">¶</a></h2>
<p>This feature enables you to record instrumented methods executions. The Hot methods feature is very useful, when you tune your configuration for minimal performance impact. In this way, you can easily detect the most frequently executed methods and exclude them from instrumentation, unless you really need to instrument them. You can also exclude classes using this feature.</p>
<p>You can use this feature only when you have some agents attached to your configuration. In other words, agents are able to report their hot methods if and only if they instrumented these methods earlier. That means, you cannot use this feature when you create a new configuration and the configuration has not been deployed yet. You must first deploy the configuration, attach some agents to it and then edit the configuration again. Only then, this feature will be available to you.</p>
<p>If you cannot see any entries in the table, click the <span class="guilabel">Collect</span> button in the bottom-left corner. This will trigger an operation of retrieving hot methods from all the attached agents.</p>
<div class="figure align-center" id="id21">
<span id="gui-conf-hm"></span><img alt="_images/hm2.png" src="_images/hm2.png" />
<p class="caption"><span class="caption-number">Fig. 5.16 </span><span class="caption-text">Hot Methods</span></p>
</div>
<p>All the retrieved methods will populate the table <a class="reference internal" href="#gui-conf-hm"><span class="std std-numref">Fig. 5.16</span></a>. The results are always grouped by <span class="guilabel">classes</span>, <span class="guilabel">methods</span>, <span class="guilabel">classes &amp; methods</span> or <span class="guilabel">agents</span>. You can exclude classes or methods only from views grouped by either emph{classes} or emph{methods} respectively. Views grouped by emph{classes &amp; methods} and emph{agents} are only for information purposes. In order to exclude some entries, use a context menu over the table.</p>
<p>You can reset the results anytime and start to collect new results by clicking the <span class="guilabel">Reset</span> button. This will clear all the previous results and re-enable the Hot Methods feature on all the attached agents.</p>
</div>
<div class="section" id="jmx">
<h2>5.3. JMX<a class="headerlink" href="#jmx" title="Permalink to this headline">¶</a></h2>
<p>Configuring JMX for agents relies on specifying <span class="code">ObjectName</span> patterns and the data collecting frequency. In the <span class="guilabel">Period</span> field you can specify how frequently agents must report data. In order to add some patterns, you must click the <span class="guilabel">Manage MBeans</span> menu.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In order to add new <span class="code">ObjectName</span> patterns, you must have some configuration deployed and some agents attached.</p>
</div>
<p>Adding new patterns requires you to deploy some configuration and attach some agents in the first place. MBeans can be imported only from running agents, so there must be some agents attached to the configuration. Assuming your setup fullfills the aforementioned conditions, click the <span class="guilabel">Import MBeans…</span> menu item.
You should get a pop-up window with a list of available ObjectNames <a class="reference internal" href="#gui-conf-jmx1"><span class="std std-numref">Fig. 5.17</span></a>.</p>
<div class="figure align-center" id="id22">
<span id="gui-conf-jmx1"></span><img alt="_images/jmx1.png" src="_images/jmx1.png" />
<p class="caption"><span class="caption-number">Fig. 5.17 </span><span class="caption-text">Importing JMX ObjectNames</span></p>
</div>
<p>If the list is empty, click the <span class="guilabel">Collect</span> button in the bottom-left corner. This operation will collect all the available ObjectNames from all the attached agents. In order to add some selected record, either double-click the record or use the list context menu. When you are done with importing ObjectNames, click the <span class="guilabel">Close</span> button. Now, you should have the selected records added to the MBeans list in the <a class="reference internal" href="#gui-conf-edit"><span class="std std-numref">Fig. 5.8</span></a> view.</p>
<p>Usually, most of ObjectNames is specific to the servers they come from. Their names contain a server specific data such as IP addresses, ports etc. That means there are ObjectNames that are available only on particular servers. In order to make them available on most of the servers and simplify the configuration we need to modify their ObjectNames. This can be achieved by clicking the <span class="guilabel">Transform to Pattern…</span> menu item in the list context menu.
As a result you should get a similar pop-up window to this one <a class="reference internal" href="#gui-conf-jmx2"><span class="std std-numref">Fig. 5.18</span></a>.</p>
<div class="figure align-center" id="id23">
<span id="gui-conf-jmx2"></span><img alt="_images/jmx2.png" src="_images/jmx2.png" />
<p class="caption"><span class="caption-number">Fig. 5.18 </span><span class="caption-text">Transforming ObjectName</span></p>
</div>
<p>This is a view of a decomposed ObjectName into keys and values. The <span class="guilabel">Value</span> column is editable so that you can replace values with custom ones and transform some specific ObjectName into a pattern. In order to edit the values just double-click the record and modify it. The <span class="guilabel">Remove similar</span> checkbox is used if you want to get rid of other, similar ObjectNames, whose name matches your pattern.</p>
<div class="figure" id="id24">
<span id="gui-conf-jmxp"></span><a class="reference internal image-reference" href="_images/jmxp1.png"><img alt="_images/jmxp1.png" src="_images/jmxp1.png" style="width: 50%;" /></a>
<p class="caption"><span class="caption-number">Fig. 5.19 </span><span class="caption-text">Before Transformation</span></p>
</div>
<div class="figure" id="id25">
<a class="reference internal image-reference" href="_images/jmxp2.png"><img alt="_images/jmxp2.png" src="_images/jmxp2.png" style="width: 50%;" /></a>
<p class="caption"><span class="caption-number">Fig. 5.20 </span><span class="caption-text">After Transformation</span></p>
</div>
<p>In order to illustrate the transformation procedure see <a class="reference internal" href="#gui-conf-jmxp"><span class="std std-numref">Fig. 5.19</span></a>. There are multiple ObjectNames, which are very similar and the only key they differ is the <span class="opt">name</span>. By transforming the <span class="opt">name</span> value to <span class="opt">*</span> of just one of these similar records, we can easily simplify the entire set of similar records into a single ObjectName. That is exactly how the transformation procedure works.</p>
</div>
<div class="section" id="deploying-configurations">
<h2>5.4. Deploying Configurations<a class="headerlink" href="#deploying-configurations" title="Permalink to this headline">¶</a></h2>
<p>When your configuration is ready to be deployed, you should first save it by clicking the <span class="guilabel">Save</span> button in <a class="reference internal" href="#gui-conf-edit"><span class="std std-numref">Fig. 5.8</span></a>.
This operation will only persist the configuration in the <span class="flp">manager</span>.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">If you do not save your configuration before you exit <span class="flp">workstation</span>, all the changes you made will be lost.</p>
</div>
<p>In order to activate the configuration, you must click the <span class="guilabel">Deploy</span> button.
This operation will make the configuration active.
When the configuration is active, you can attach agents to it by clicking <span class="guilabel">+</span> button in <a class="reference internal" href="#gui-configuration"><span class="std std-numref">Fig. 5.9</span></a>.</p>
<p>During deployment operation all the attached agents are notified about it and the configuration is uploaded to them.
The agents will check whether there are any changes between their current configuration and the new one. If the agents detect instrumentation rules changes, they will reload their configuration. The reloading operation duration can vary and it strongly depends on the configuration and application itself. It can take from a few seconds to a minute.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Configuration reloading is a heavy operation and will degrade your application performance temporarily. It can even halt the entire application for the time of reloading operation. Do not reload a configuration when your application is under heavy load.</p>
</div>
</div>
</div>
<div class="section" id="galaxies">
<span id="id1"></span><h1>6. Galaxies<a class="headerlink" href="#galaxies" title="Permalink to this headline">¶</a></h1>
<p><em>Galaxies</em> are special views of collected data.
Basically, this is an alternative view of stacks executions, where stacks are represented as dots.
You can access the galaxy view by clicking the <span class="guilabel">GALAXIES</span> menu item in the <a class="reference internal" href="#gui-drawer"><span class="std std-numref">Fig. 3.5</span></a> view.</p>
<p>The galaxy is used to monitor recent 15 minutes of selected <span class="flp">agent</span> instances.
They can be managed from the galaxy explorer <a class="reference internal" href="#gui-galaxy"><span class="std std-numref">Fig. 6.1</span></a>.</p>
<div class="figure align-center" id="id26">
<span id="gui-galaxy"></span><img alt="_images/screen11.png" src="_images/screen11.png" />
<p class="caption"><span class="caption-number">Fig. 6.1 </span><span class="caption-text">Galaxies Explorer</span></p>
</div>
<p>A new galaxy can be added by double-clicking the <span class="guilabel">+</span> button.
You can see the galaxy details by double-clicking the corresponding galaxy entry in the list on the left.</p>
<p>This view contains a table with three columns.
There is an agent name along with a small, colored square in the first column.
The color of the square is used to distinguish among various agents on the galaxy view.
If you want to change the color, just click the square.
The second column is editable and allows you to decide whether you want the agent to be displayed on the galaxy view.
The third column shows the current uptime of the agent.
If you want to open the galaxy view <a class="reference internal" href="#gui-galaxy-view"><span class="std std-numref">Fig. 6.2</span></a>, just click the <span class="guilabel">Show</span> button.</p>
<div class="figure align-center" id="id27">
<span id="gui-galaxy-view"></span><img alt="_images/screen26.png" src="_images/screen26.png" />
<p class="caption"><span class="caption-number">Fig. 6.2 </span><span class="caption-text">Galaxy View</span></p>
</div>
<p>This is a live view of your attached agents. Each dot represents a single method execution.
The method duration is displayed on the vertical axis. The horizontal axis shows a time axis and the whole view moves from right to the left as time goes by.
If you want to change the graph scale, you can use your mouse scroll. In order to customize the graph, use its context menu <a class="reference internal" href="#gui-galaxy-ctx"><span class="std std-numref">Fig. 6.3</span></a>.</p>
<div class="figure align-center" id="id28">
<span id="gui-galaxy-ctx"></span><img alt="_images/screen28.png" src="_images/screen28.png" />
<p class="caption"><span class="caption-number">Fig. 6.3 </span><span class="caption-text">Galaxy Context Menu</span></p>
</div>
<p>The context menu has several options, which enable you to customize your galaxy. It also provides auxiliary information about your data reported by the agents. If you want to see the total load of the attached agents, select the <span class="guilabel">Load</span> checkbox item. It will display a stacked area graph of the load for all the attached agents <a class="reference internal" href="#gui-galaxy-load"><span class="std std-numref">Fig. 6.4</span></a>. The bottom area denotes those calls which threw exceptions. When the load is displayed, the number of total calls is displayed in the veritcal axis on the ride side of the graph.</p>
<div class="figure align-center" id="id29">
<span id="gui-galaxy-load"></span><img alt="_images/screen27.png" src="_images/screen27.png" />
<p class="caption"><span class="caption-number">Fig. 6.4 </span><span class="caption-text">Galaxy View: Load</span></p>
</div>
<p>This load view is an aggregated one so if you want to see how the load looks for each agent, click the <span class="guilabel">Load details…</span> menu item. You should see a view <a class="reference internal" href="#gui-galaxy-loadpa"><span class="std std-numref">Fig. 6.5</span></a> with the table and the graph on it. The <span class="guilabel">Errors</span> column shows the total number of calls that threw exceptions. The <span class="guilabel">Calls</span> column shows the total number of calls.</p>
<div class="figure align-center" id="id30">
<span id="gui-galaxy-loadpa"></span><img alt="_images/screen30.png" src="_images/screen30.png" />
<p class="caption"><span class="caption-number">Fig. 6.5 </span><span class="caption-text">Galaxy View: Load per Agent</span></p>
</div>
<p>If you want to customize some galaxy colors and scale, click the <span class="guilabel">Settings…</span> menu item. In the settings window <a class="reference internal" href="#gui-galaxy-settings"><span class="std std-numref">Fig. 6.6</span></a> you can change background, selection, load backgrounds colors. You can also change the duration range on the vertical axis.</p>
<div class="figure align-center" id="id31">
<span id="gui-galaxy-settings"></span><img alt="_images/screen29.png" src="_images/screen29.png" />
<p class="caption"><span class="caption-number">Fig. 6.6 </span><span class="caption-text">Galaxy View Settings</span></p>
</div>
<p>Your can switch between two types of galaxies: <em>flat</em> and <em>radar</em> ones. If you want to switch to the radar <a class="reference internal" href="#gui-galaxy-radar"><span class="std std-numref">Fig. 6.7</span></a>, select the <span class="guilabel">View Mode –&gt; Radar</span> menu item.</p>
<div class="figure align-center" id="id32">
<span id="gui-galaxy-radar"></span><img alt="_images/screen31.png" src="_images/screen31.png" />
<p class="caption"><span class="caption-number">Fig. 6.7 </span><span class="caption-text">Galaxy View: Radar</span></p>
</div>
<p>If you want to display only those method calls, which throw exception then select the <span class="guilabel">Errors only</span> checkbox item.</p>
<center>
<iframe width="560" height="315" src="https://www.youtube.com/embed/bwEKkCF-8qE?rel=0" frameborder="0" allowfullscreen></iframe>
<p class="caption">
<span class="caption-text">Galaxy Radar</span>
</p>
</center></div>
<div class="section" id="agents">
<span id="agents-health"></span><h1>7. Agents<a class="headerlink" href="#agents" title="Permalink to this headline">¶</a></h1>
<p>Agents health can be viewed by double-clicking the <span class="guilabel">AGENTS</span> item in the side menu <a class="reference internal" href="#gui-drawer"><span class="std std-numref">Fig. 3.5</span></a>.
If you click on some selected agent pane, you will see its status and health details.</p>
<div class="figure align-center" id="id33">
<span id="gui-agents-health"></span><img alt="_images/screen2.png" src="_images/screen2.png" />
<p class="caption"><span class="caption-number">Fig. 7.1 </span><span class="caption-text">Agent Status View</span></p>
</div>
<p>The view is divided into panes with either text information or graph on them. All the information in this view is reported by the agent. The reported data are collected from the agent start and reset everytime the agent restarts.</p>
<p>The <span class="guilabel">AGENT</span> pane contains the following data:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">connected from:</th><td class="field-body">Source socket address of the agent. It shows from which socket address the agent connects to <span class="flp">manager</span>.</td>
</tr>
<tr class="field-even field"><th class="field-name">started at:</th><td class="field-body">Agent startup time. It shows when the agent started.</td>
</tr>
<tr class="field-odd field"><th class="field-name">uptime:</th><td class="field-body">Agent uptime time. It shows how long the agent is up.</td>
</tr>
<tr class="field-even field"><th class="field-name">last update:</th><td class="field-body">Agent last report time. It shows how much time has passed since the last agent report received by <span class="flp">workstation</span>. When this time is greater than 15 seconds, its color turns from green to red.</td>
</tr>
</tbody>
</table>
<p>The <span class="guilabel">SETTINGS</span> pane contains the following data:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">configuration:</th><td class="field-body">Current configuration. It shows the configuration the agent is attached to.</td>
</tr>
<tr class="field-even field"><th class="field-name">database:</th><td class="field-body">Current database. It shows the database the agent sends its data to.</td>
</tr>
<tr class="field-odd field"><th class="field-name" colspan="2">configuration updated at:</th></tr>
<tr class="field-odd field"><td>&#160;</td><td class="field-body">Agent configuration deployment time. It shows the last time a configuration has been deployed to the agent.</td>
</tr>
<tr class="field-even field"><th class="field-name">hot methods:</th><td class="field-body">Hot Methods feature. It shows whether the Hot Methods feature is enabled or disabled.</td>
</tr>
<tr class="field-odd field"><th class="field-name">CPU time:</th><td class="field-body">CPU time feature. It shows whether the CPU time measurement is enabled or disabled.</td>
</tr>
</tbody>
</table>
<p>The <span class="guilabel">PACKETS TOTAL</span> pane contains the following data:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">sent:</th><td class="field-body">Number of sent packets. Each method call, symbol or some metric value is represented as a single packet. These packets are sent to a database. This shows the total number of such packets sent to the database from the moment of the agent start. If the agent is attached to another database, this value will be reset.</td>
</tr>
<tr class="field-even field"><th class="field-name">dropped:</th><td class="field-body">Number of dropped packets. It shows the number of packets that have been dropped inside the agents. There can be a few reasons which make the agent to drop packets. See <a class="reference internal" href="admin.html#data-collecting"><span class="std std-ref">Data Collecting Considerations</span></a> for details.</td>
</tr>
<tr class="field-odd field"><th class="field-name">saturation:</th><td class="field-body">Packets saturation. It shows the ratio of the number of received packets to the total number of packets. This total number is a sum of dropped and received packets. The value is displayed in percentages. If the value is 100% it means that all the packets, that have been collected on the agent, have been received by the database. If this value is low, it means that a large number of packets is dropped for some reason.</td>
</tr>
<tr class="field-even field"><th class="field-name">size sent:</th><td class="field-body">Data size sent. It shows how much data has been sent to the database. This value is counted from the moment of the agent start. If the agent is attached to another database, this value will be reset.</td>
</tr>
</tbody>
</table>
<p>The <span class="guilabel">LOGGER</span> pane contains the following data:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">current level:</th><td class="field-body">Logger level. It shows the current logger level set.</td>
</tr>
<tr class="field-even field"><th class="field-name">table:</th><td class="field-body">Number of messages logged at the corresponding logger level.</td>
</tr>
</tbody>
</table>
<div class="section" id="charts">
<h2>7.1. Charts<a class="headerlink" href="#charts" title="Permalink to this headline">¶</a></h2>
<p>There are five charts presenting additional information. You can change the order they appear. The following charts are presented in order of the default appearance:</p>
<ol class="arabic simple">
<li>This graph presents how many methods are currently instrumented.</li>
<li>This graph presents how much data is sent from the agent. The unit is Kibps (1024 bits per second).</li>
<li>This graph shows the CPU usage of the monitored Java process. Please note, this feature is available only for GNU/Linux machines.</li>
<li>This graph presents the memory usage of the Java process.</li>
</ol>
</div>
<div class="section" id="system-properties">
<h2>7.2. System Properties<a class="headerlink" href="#system-properties" title="Permalink to this headline">¶</a></h2>
<p>If you want to retrieve JVM system properties, just select the <span class="guilabel">System Properties</span> menu item in <a class="reference internal" href="#gui-agents-health"><span class="std std-numref">Fig. 7.1</span></a>.</p>
<div class="figure align-center" id="id34">
<span id="gui-asysprops"></span><img alt="_images/asysprops.png" src="_images/asysprops.png" />
<p class="caption"><span class="caption-number">Fig. 7.2 </span><span class="caption-text">JVM System Properties</span></p>
</div>
</div>
<div class="section" id="application-packages">
<h2>7.3. Application Packages<a class="headerlink" href="#application-packages" title="Permalink to this headline">¶</a></h2>
<p>This feature is useful if you want to know what packages are available in your Java environment, so that
you can add some class rules to your configuration. The packages are reported up to the third level.</p>
<div class="figure align-center" id="id35">
<span id="gui-pkg1"></span><img alt="_images/packages1.png" src="_images/packages1.png" />
<p class="caption"><span class="caption-number">Fig. 7.3 </span><span class="caption-text">Available Packages</span></p>
</div>
</div>
<div class="section" id="class-loaders">
<h2>7.4. Class Loaders<a class="headerlink" href="#class-loaders" title="Permalink to this headline">¶</a></h2>
<p>You can retrieve a list of classloaders detected by the agent. The result is presented in the form of a table.
Each reported class loader can be in one of the four available states:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">PENDING:</th><td class="field-body">to be instrumented,</td>
</tr>
<tr class="field-even field"><th class="field-name">NO NEED:</th><td class="field-body">has been checked and no instrumentation is needed,</td>
</tr>
<tr class="field-odd field"><th class="field-name">SKIPPED:</th><td class="field-body">has not been checked and will not be instrumented,</td>
</tr>
<tr class="field-even field"><th class="field-name">INSTRUM:</th><td class="field-body">has been instrumented.</td>
</tr>
</tbody>
</table>
<div class="figure align-center" id="id36">
<span id="gui-cl"></span><img alt="_images/cl.png" src="_images/cl.png" />
<p class="caption"><span class="caption-number">Fig. 7.4 </span><span class="caption-text">Class Loaders report</span></p>
</div>
</div>
</div>
<div class="section" id="queries">
<h1>8. Queries<a class="headerlink" href="#queries" title="Permalink to this headline">¶</a></h1>
<p>Whenever a query requires you to specify a time range, you must fill out the form below.</p>
<div class="figure align-center" id="id37">
<span id="time-form"></span><img alt="_images/timeform.png" src="_images/timeform.png" />
<p class="caption"><span class="caption-number">Fig. 8.1 </span><span class="caption-text">Time Range Form</span></p>
</div>
<p>You have two time range types to choose from. If you want to define an arbitrary period of time, you must specify both the base time and its range.
The resulting time range will span from the base time minus half of the specified range to the base time plus half of the range.
In order to specify the time range just click the value of the <span class="guilabel">Period</span> and select a value from the pop-up menu.
If you want to define a recent time period, just select the <span class="guilabel">Recent</span> checkbox and specify the range.</p>
<p>In case a query requires you to specify an agents pattern, you must fill out the form below.</p>
<div class="figure align-center" id="id38">
<span id="agents-form"></span><img alt="_images/agents_pat_form.png" src="_images/agents_pat_form.png" />
<p class="caption"><span class="caption-number">Fig. 8.2 </span><span class="caption-text">Agents Form</span></p>
</div>
<p>The pattern entry must be a valid <a class="reference external" href="http://www.regular-expressions.info/posix.html">regular expression</a>.
The input field has an autocomplete feature, so if you want to select one of the available agents, just enter space and select
from the pop-up list.</p>
<p>Any other entries depend on a selected query.</p>
<div class="section" id="flame-graph-of-transactions">
<span id="flame-graph"></span><h2>8.1. Flame Graph of Transactions<a class="headerlink" href="#flame-graph-of-transactions" title="Permalink to this headline">¶</a></h2>
<p>This query requires you to specify both a regular expression for agents and a time range.</p>
<div class="figure align-center" id="id39">
<span id="gui-fg-form"></span><img alt="_images/qform1.png" src="_images/qform1.png" />
<p class="caption"><span class="caption-number">Fig. 8.3 </span><span class="caption-text">Flame Graph Form</span></p>
</div>
<p>When you click the <span class="guilabel">SEARCH</span> button in <a class="reference internal" href="#gui-stack"><span class="std std-numref">Fig. 8.23</span></a>, you will get a Flame Graph view <a class="reference internal" href="#gui-stack-fgraph1"><span class="std std-numref">Fig. 8.26</span></a>.
This view presents an aggregated form of the execution stack.
It is composed of frames (rectangles), which represent aggregated methods executions.
The y-axis presents the stack depth. Although the x-axis itself has no meaning, the width of frames has one.
There are three criteria, that change the way you define the frames width.
These criteria can be selected exclusively on the top pane by clicking one of the radio buttons: <span class="guilabel">CALLS</span>, <span class="guilabel">CPU</span> and <span class="guilabel">OFF-CPU</span>.
When the <span class="guilabel">CALLS</span> is selected, the frames width denotes how often a particular method was executed within the stack.</p>
<div class="figure align-center" id="id40">
<span id="fgq"></span><img alt="_images/fgq.png" src="_images/fgq.png" />
<p class="caption"><span class="caption-number">Fig. 8.4 </span><span class="caption-text">Flame Graph</span></p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Please, note there can be multiple frames representing the same method. This situation happens when a method is called in multiple places (on different execution levels) within the stack.</p>
</div>
<p>When the <span class="guilabel">CPU</span> is selected, the frames width shows how long methods spend on the CPU executing their code. Finally, when the <span class="guilabel">OFF-CPU</span> is selected, the frames width shows how long methods spend off the CPU.</p>
<p>The right side view of <a class="reference internal" href="#fgq"><span class="std std-numref">Fig. 8.4</span></a> presents a distribution of calls in the flame graph. Only a limited number of calls is displayed for both <span class="guilabel">CPU</span> and <span class="guilabel">OFF-CPU</span> sets. By right-clicking on a selected record, you get a single menu item <span class="guilabel">Find on Flame Graph</span> from the context menu. When you click the menu item, each corresponding frame will be highlighted.
In this way you can easily find where your method is located in the Flame Graph.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The Flame Graph visualizations were introduced by <a class="reference external" href="http://www.brendangregg.com">Brendan Gregg</a>. For more details about flame graphs please refer to <a class="reference external" href="http://www.brendangregg.com/flamegraphs.html">http://www.brendangregg.com/flamegraphs.html</a>.</p>
</div>
</div>
<div class="section" id="galaxy-of-transactions">
<h2>8.2. Galaxy of Transactions<a class="headerlink" href="#galaxy-of-transactions" title="Permalink to this headline">¶</a></h2>
<p>This query allows you to explore data in a view similar to <a class="reference internal" href="#galaxies"><span class="std std-ref">Galaxies</span></a>. The query requires you to fill out the form below.</p>
<div class="figure align-center" id="id41">
<span id="grt-form"></span><img alt="_images/qform0.png" src="_images/qform0.png" />
<p class="caption"><span class="caption-number">Fig. 8.5 </span><span class="caption-text">Raw Transactions Form</span></p>
</div>
<p>When you click the <span class="guilabel">Search</span> button, you should get a similar result to <a class="reference internal" href="#gui-galaxy-result"><span class="std std-numref">Fig. 8.6</span></a>.
The view is divided into two regions. The left view presents your query results in a form of galaxy.
The right view contains a table of those agents, whose data are displayed on the galaxy.
In the first column, there is an agent name and its color.
You can change this color by clicking the small square and selecting a new color.
In the second column, you can either show or hide the data corresponding to the selected agent.
The third column contains a total share of calls of the corresponding agent on the galaxy.
The last column contains a total share of exceptions throws by calls of the corresponding agent.
You can either show or hide this table by clicking on the toggle button <span class="guilabel">Agents</span> in the right-top corner of the view.</p>
<div class="figure align-center" id="id42">
<span id="gui-galaxy-result"></span><img alt="_images/screen33.png" src="_images/screen33.png" />
<p class="caption"><span class="caption-number">Fig. 8.6 </span><span class="caption-text">Galaxy Result</span></p>
</div>
<p>The galaxy context menu <a class="reference internal" href="#gui-galaxy-result-ctx"><span class="std std-numref">Fig. 8.7</span></a> allows you to extend the analysis. If you select the <span class="guilabel">Load</span> menu item, you will get the load view in a form of a stacked area graph. The area colors correspond to the agents data. When the load is displayed, the calls count values are displayed on the right vertical axis.</p>
<div class="figure align-center" id="id43">
<span id="gui-galaxy-result-ctx"></span><img alt="_images/screen35.png" src="_images/screen35.png" />
<p class="caption"><span class="caption-number">Fig. 8.7 </span><span class="caption-text">Galaxy Result Context Menu</span></p>
</div>
<p>Using the <span class="guilabel">Scale</span> submenu you can change the graph scale which can be either linear or logarithmic. If you click the <span class="guilabel">Settings</span> menu item you can change the galaxy background and foreground colors.</p>
<p>If you want to find out what method calls are displayed, just click and drag your mouse to create a rectangle which covers the area you are interested in.
If you release the mouse button, a pop-up menu will appear with two options.
If you are interested in an exact list of transactions from the selected area, just select the <span class="guilabel">Raw Transactions</span> menu item.
If you want to make a flame graph out of the selected transactions, select the <span class="guilabel">Flame Graph</span> menu item.</p>
<p>Besides, the galaxy flat view, your query results can be presented in a form of galaxy clock view <a class="reference internal" href="#gui-galaxy-clock"><span class="std std-numref">Fig. 8.8</span></a>.
The view projects data onto a clock face. You can see only data from twelve hours range at a time. Use the <span class="guilabel">AM</span>, <span class="guilabel">PM</span> radio buttons and the date picker to change time.</p>
<div class="figure align-center" id="id44">
<span id="gui-galaxy-clock"></span><img alt="_images/screen36.png" src="_images/screen36.png" />
<p class="caption"><span class="caption-number">Fig. 8.8 </span><span class="caption-text">Galaxy Clock View</span></p>
</div>
<p>Additionally, there are two extra views available.
They can be displayed by clicking the <span class="guilabel">Manage –&gt; Switch View</span> submenu and selecting one of the available items.
If the <span class="guilabel">Duration Distribution</span> item is selected, <a class="reference internal" href="#gui-galaxy-dist-dur"><span class="std std-numref">Fig. 8.10</span></a> view will be displayed.
If the <span class="guilabel">Calls Distribution</span> is selected, <a class="reference internal" href="#gui-galaxy-dist-calls"><span class="std std-numref">Fig. 8.9</span></a> view will be displayed.</p>
<div class="topic">
<p class="topic-title first">Calls Distribution</p>
<p>This stacked-bar chart <a class="reference internal" href="#gui-galaxy-dist-calls"><span class="std std-numref">Fig. 8.9</span></a> presents methods calls distribution with respect to duration. Each color represents a single agent. The y-axis presents the number of calls. You can adjust both bar width (in milliseconds) and duration range (in milliseconds).</p>
<div class="figure align-center" id="id45">
<span id="gui-galaxy-dist-calls"></span><img alt="_images/screen40.png" src="_images/screen40.png" />
<p class="caption"><span class="caption-number">Fig. 8.9 </span><span class="caption-text">Galaxy Calls Distribution</span></p>
</div>
</div>
<div class="topic">
<p class="topic-title first">Duration Distribution</p>
<p>This stacked-bar chart <a class="reference internal" href="#gui-galaxy-dist-dur"><span class="std std-numref">Fig. 8.10</span></a> presents methods duration distribution with respect to time. Each color represents a single agent. The y-axis presents the number of calls. You can adjust both bar width (in milliseconds) and duration range (in milliseconds).</p>
<div class="figure align-center" id="id46">
<span id="gui-galaxy-dist-dur"></span><img alt="_images/screen39.png" src="_images/screen39.png" />
<p class="caption"><span class="caption-number">Fig. 8.10 </span><span class="caption-text">Galaxy Duration Distribution</span></p>
</div>
</div>
<p>When you double-click in a bar in either <a class="reference internal" href="#gui-galaxy-dist-calls"><span class="std std-numref">Fig. 8.9</span></a> or <a class="reference internal" href="#gui-galaxy-dist-dur"><span class="std std-numref">Fig. 8.10</span></a>, you will get a view <a class="reference internal" href="#gui-galaxy-bar-content"><span class="std std-numref">Fig. 8.11</span></a>, with list of methods from this bar.</p>
<div class="figure align-center" id="id47">
<span id="gui-galaxy-bar-content"></span><img alt="_images/screen32.png" src="_images/screen32.png" />
<p class="caption"><span class="caption-number">Fig. 8.11 </span><span class="caption-text">Galaxy Duration Distribution: Bar Content</span></p>
</div>
</div>
<div class="section" id="garbage-collector">
<h2>8.3. Garbage Collector<a class="headerlink" href="#garbage-collector" title="Permalink to this headline">¶</a></h2>
<p>This query retrieves a list of garbage collector metrics for a specified agents pattern.
When you click the <span class="guilabel">SEARCH</span>, you will get the list <a class="reference internal" href="#gc-select"><span class="std std-numref">Fig. 8.13</span></a>.</p>
<div class="figure align-center" id="id48">
<span id="gc-form"></span><img alt="_images/gc_form.png" src="_images/gc_form.png" />
<p class="caption"><span class="caption-number">Fig. 8.12 </span><span class="caption-text">Garbage Collector Form</span></p>
</div>
<p>You can select one of the available metrics from the list below and draw a graph for a specified time range.</p>
<div class="figure align-center" id="id49">
<span id="gc-select"></span><img alt="_images/gc.png" src="_images/gc.png" />
<p class="caption"><span class="caption-number">Fig. 8.13 </span><span class="caption-text">Garbage Collectors</span></p>
</div>
<p>This is basically, the same view as in the <a class="reference internal" href="#explore-env"><span class="std std-ref">Generic Key-Value Metric</span></a>.</p>
</div>
<div class="section" id="generic-key-value-metric">
<span id="explore-env"></span><h2>8.4. Generic Key-Value Metric<a class="headerlink" href="#generic-key-value-metric" title="Permalink to this headline">¶</a></h2>
<p>This query retrieves a list of all available metrics’ keys.
The query requires you to specify a pattern for the key, which must be a valid <a class="reference external" href="http://www.regular-expressions.info/posix.html">regular expression</a>.</p>
<div class="figure align-center" id="id50">
<span id="gui-explorer-env"></span><img alt="_images/screen7.png" src="_images/screen7.png" />
<p class="caption"><span class="caption-number">Fig. 8.14 </span><span class="caption-text">Data Explorer: Environment Form</span></p>
</div>
<p>When you click the <span class="guilabel">SEARCH</span> button, you will get the output similar to <a class="reference internal" href="#gui-explorer-dkeys"><span class="std std-numref">Fig. 8.15</span></a>.
The view contains a tree with all the found metrics keys.
Each tree leaf has a context menu, which enables you to make a quick graph for the last 15, 30, 60 or 120 minutes.
If you want to specify an exact time range for a graph, use the time range form at the top of the view.
If you either use quick graph or time range form, you should get a graph on the right side of the view.
Each time you make a graph, it is added to the graphs list on the right.
If you want to remove a graph from the list, just click the cross icon in the top-right corner of the selected graph.</p>
<div class="figure align-center" id="id51">
<span id="gui-explorer-dkeys"></span><img alt="_images/dkeys.png" src="_images/dkeys.png" />
<p class="caption"><span class="caption-number">Fig. 8.15 </span><span class="caption-text">Data Explorer: Environment Data Keys</span></p>
</div>
<p>When you click the <span class="guilabel">DRAW</span> button, the workstation sends a request to each database it is connected to and retrieves metrics for each agent, provided that the metric exists for the agent.
As a result, there can be multiple graphs on a single graph pane and each graph corresponds to some agent.
You can show or hide specific agents graphs by selecting the corresponding menu checkboxes from the context menu in the graph.</p>
<p>The graphs vertical axis displays raw values, in other words the values that are collected by agents.
No unit is displayed because <span class="flp">workstation</span> knows nothing about the data it retrieves.
It can be any data, provided by either <span class="flp">agent</span> or some user customized agent.
In case of JMX data, please refer to your application documentation to find out what units your JMX metrics use.</p>
<div class="figure align-center" id="id52">
<span id="gui-explorer-kvg"></span><img alt="_images/kvg.png" src="_images/kvg.png" />
<p class="caption"><span class="caption-number">Fig. 8.16 </span><span class="caption-text">Key-Value Data Graphs</span></p>
</div>
</div>
<div class="section" id="method-execution-analysis">
<span id="analytics"></span><h2>8.5. Method Execution Analysis<a class="headerlink" href="#method-execution-analysis" title="Permalink to this headline">¶</a></h2>
<p>This query retrieves an execution analysis of the specified method. The query requires you to specify both a class name and
a method signature. The class name must be fully qualified Java class name and the method signature must be specified along with its
name, for example <span class="code">void someMethod(int, long, java.lang.String)</span>. Optionally, you can specify a parameter key for the method along with
a pattern for its value. The key entry must match one of the exisiting method keys and the value must be a valid <a class="reference external" href="http://www.regular-expressions.info/posix.html">regular expression</a>.</p>
<div class="figure align-center" id="id53">
<span id="mea-form"></span><img alt="_images/qform2.png" src="_images/qform2.png" />
<p class="caption"><span class="caption-number">Fig. 8.17 </span><span class="caption-text">Method Execution Analysis Form</span></p>
</div>
<p>Depending on the <span class="guilabel">PARAMETER VALUE</span> text field value you can obtain different results.
If you do not use a subexpression (expression in parentheses), you will obtain the result similar to <a class="reference internal" href="#gui-analytics-dur"><span class="std std-numref">Fig. 8.19</span></a>.
If you use a subexpression, you will get the result similar to <a class="reference internal" href="#gui-analytics-groupby"><span class="std std-numref">Fig. 8.18</span></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Only a single subexpression in the <span class="guilabel">PARAMETER VALUE</span> text field is allowed.</p>
</div>
<p>In other words, if you want to obtain results grouped by some expression, you should put that expression pattern in parentheses so that it forms a subexpression.</p>
<div class="figure align-center" id="id54">
<span id="gui-analytics-groupby"></span><img alt="_images/analytics1.png" src="_images/analytics1.png" />
<p class="caption"><span class="caption-number">Fig. 8.18 </span><span class="caption-text">Analytics Result: Group By</span></p>
</div>
<div class="figure align-center" id="id55">
<span id="gui-analytics-dur"></span><img alt="_images/analytics2.png" src="_images/analytics2.png" />
<p class="caption"><span class="caption-number">Fig. 8.19 </span><span class="caption-text">Analytics Result: Duration Graph</span></p>
</div>
<div class="figure align-center" id="id56">
<span id="gui-analytics-calls"></span><img alt="_images/analytics3.png" src="_images/analytics3.png" />
<p class="caption"><span class="caption-number">Fig. 8.20 </span><span class="caption-text">Analytics Result: Calls Graph</span></p>
</div>
</div>
<div class="section" id="transactions">
<span id="explore-inst"></span><h2>8.6. Transactions<a class="headerlink" href="#transactions" title="Permalink to this headline">¶</a></h2>
<p>This query retrieves a list of transactions and presents it in a table. Use this query if you want to see a detailed view of
every transaction executed within the specified time range. The query requires you to fill out the <a class="reference internal" href="#gui-inst-form"><span class="std std-numref">Fig. 8.21</span></a> form.</p>
<div class="figure align-center" id="id57">
<span id="gui-inst-form"></span><img alt="_images/screen15.png" src="_images/screen15.png" />
<p class="caption"><span class="caption-number">Fig. 8.21 </span><span class="caption-text">Instrumentation Expanded Form</span></p>
</div>
<p>There are optional fields you can use to narrow down your search results.
The <span class="guilabel">DURATION</span> enables you to specify a duration range.
In the <span class="guilabel">CLASS NAME</span> entry you can specify a regular expression pattern for a class name.
In the <span class="guilabel">METHOD NAME</span> entry you can specify a regular expression pattern for a method name, and finally in the <span class="guilabel">PARAMETERS</span> entry you can set a regular expression for a parameter.</p>
<p>When you click the <span class="guilabel">SEARCH</span> button, you should see a similar view to <a class="reference internal" href="#gui-table-view"><span class="std std-numref">Fig. 8.22</span></a>.</p>
<div class="figure align-center" id="id58">
<span id="gui-table-view"></span><img alt="_images/screen18.png" src="_images/screen18.png" />
<p class="caption"><span class="caption-number">Fig. 8.22 </span><span class="caption-text">Table results: Records View</span></p>
</div>
<p>Each time when you search instrumentation data you receive only a part of the response data.
If you get more, you must click the <span class="guilabel">Load More Data</span> button.
You can repeat this procedure to receive more data until the button disappears.</p>
<div class="section" id="execution-stack-interpretation">
<h3>8.6.1. Execution Stack Interpretation<a class="headerlink" href="#execution-stack-interpretation" title="Permalink to this headline">¶</a></h3>
<p>When you double-click some selected record in table <a class="reference internal" href="#gui-table-view"><span class="std std-numref">Fig. 8.22</span></a>, you will get a window <a class="reference internal" href="#gui-stack"><span class="std std-numref">Fig. 8.23</span></a> with this record details. The window presents a tree representing an execution stack of the selected method call. This tree view is self-explanatory but there can be situations where this view can be a bit confusing. This can happen when the displayed execution stack does not exactly correspond to the execution flow you see in your application source code. In order to understand why this situation takes place you must understand how the execution stack tree is built.</p>
<div class="figure align-center" id="id59">
<span id="gui-stack"></span><img alt="_images/screen24.png" src="_images/screen24.png" />
<p class="caption"><span class="caption-number">Fig. 8.23 </span><span class="caption-text">Execution Stack</span></p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><span class="guilabel">CPU Time</span> column values are calculated as CPU percentage usage with respect to the corresponding duration value.</p>
</div>
<p>If you want to know the exact location of a method call within the execution stack, you can select the <span class="guilabel">Elements Position</span> in the tree options on the stack details. Next time, you expand a branch on the execution stack you should see the positions of methods <a class="reference internal" href="#gui-stack-debug"><span class="std std-numref">Fig. 8.24</span></a>. The position is determined by two numbers, the first one denotes the sequence number within the stack and the second one denotes the stack depth.</p>
<div class="figure align-center" id="id60">
<span id="gui-stack-debug"></span><img alt="_images/stack_debug.png" src="_images/stack_debug.png" />
<p class="caption"><span class="caption-number">Fig. 8.24 </span><span class="caption-text">Execution Stack: Methods Calls Position</span></p>
</div>
<p>When you select the <span class="guilabel">Table</span> item, you will get a spectrum view <a class="reference internal" href="#gui-stack-spectrum"><span class="std std-numref">Fig. 8.25</span></a>.
This view presents a <em>spectrum</em> of the execution stack, in other words it shows a collection of all the components which constitute the stack along with their calls and errors statistics.</p>
<div class="figure align-center" id="id61">
<span id="gui-stack-spectrum"></span><img alt="_images/rctable.png" src="_images/rctable.png" />
<p class="caption"><span class="caption-number">Fig. 8.25 </span><span class="caption-text">Execution Stack: Spectrum</span></p>
</div>
<p>When you select the <span class="guilabel">Flame Graph</span> item, you will get the Flame Graph view <a class="reference internal" href="#gui-stack-fgraph1"><span class="std std-numref">Fig. 8.26</span></a>.</p>
<div class="figure align-center" id="id62">
<span id="gui-stack-fgraph1"></span><img alt="_images/fg1.png" src="_images/fg1.png" />
<p class="caption"><span class="caption-number">Fig. 8.26 </span><span class="caption-text">Execution Stack: Flame Graph</span></p>
</div>
<p>In <a class="reference internal" href="#gui-assembly"><span class="std std-numref">Fig. 8.27</span></a> picture you can see four, sample execution stacks of some <span class="code">A</span> method call.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The first method in the execution stack we call a <em>transaction</em> or <em>root call</em>.</p>
</div>
<p>The first <em>a</em> view shows how the real execution stack looks. This is a real execution flow that takes place in your application. The second <em>b</em> view, presents the same stack instrumented by your agent. Depending on your configuration, the instrumentation may not cover the entire stack. The empty, gray boxes represent missed, uninstrumented methods. As you can see, at this very point your instrumented execution flow is not complete. Moreover, in your application runtime there can be situations when some of the instrumented method calls will not be reported (refer to <a class="reference internal" href="admin.html#data-collecting"><span class="std std-ref">Data Collecting Considerations</span></a> for details). The empty, red boxes in the third <em>c</em> view represent this situation. Finally, what you actually observe in <span class="flp">workstation</span> is the last <em>d</em> view. This view presents an assembled stack with missing calls ignored. Now you know how to interpret the execution stack in <span class="flp">workstation</span> and why the resulting stack can differ from the original one.</p>
<div class="figure align-center" id="id63">
<span id="gui-assembly"></span><img alt="_images/assembly.png" src="_images/assembly.png" />
<p class="caption"><span class="caption-number">Fig. 8.27 </span><span class="caption-text">Execution Stack Assembly</span></p>
</div>
</div>
<div class="section" id="threads-subview">
<h3>8.6.2. Threads Subview<a class="headerlink" href="#threads-subview" title="Permalink to this headline">¶</a></h3>
<p>If you want to classify your query results by threads, just select the <span class="guilabel">Threads</span> menu item from the <span class="guilabel">View</span> list in <a class="reference internal" href="#gui-table-view"><span class="std std-numref">Fig. 8.22</span></a> and you will get a view similar to <a class="reference internal" href="#gui-threads-view"><span class="std std-numref">Fig. 8.28</span></a>.</p>
<div class="figure align-center" id="id64">
<span id="gui-threads-view"></span><img alt="_images/screen37.png" src="_images/screen37.png" />
<p class="caption"><span class="caption-number">Fig. 8.28 </span><span class="caption-text">Data Explorer: Threads Subview</span></p>
</div>
<p>The view contains a tree table with the following columns:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Component:</th><td class="field-body">A tree item, structured as <em>agent</em> –&gt; <em>thread</em> –&gt; <em>class</em> –&gt; <em>method</em>. There are four component levels so the values in each column correspond to the current level.</td>
</tr>
<tr class="field-even field"><th class="field-name">Total Calls:</th><td class="field-body">A total number of calls.</td>
</tr>
<tr class="field-odd field"><th class="field-name">Total Errors:</th><td class="field-body">A total number of exceptions thrown.</td>
</tr>
<tr class="field-even field"><th class="field-name">CPU Time:</th><td class="field-body">A total CPU time (if enabled).</td>
</tr>
<tr class="field-odd field"><th class="field-name" colspan="2">Duration Median:</th></tr>
<tr class="field-odd field"><td>&#160;</td><td class="field-body">A median of duration.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Duration 90th Percentile:</th></tr>
<tr class="field-even field"><td>&#160;</td><td class="field-body">A 90th percentile of duration.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="components-subview">
<h3>8.6.3. Components Subview<a class="headerlink" href="#components-subview" title="Permalink to this headline">¶</a></h3>
<p>When you select the <span class="guilabel">Components</span> menu item in <a class="reference internal" href="#gui-table-view"><span class="std std-numref">Fig. 8.22</span></a> you will get <a class="reference internal" href="#gui-components-view"><span class="std std-numref">Fig. 8.29</span></a> a view:</p>
<div class="figure align-center" id="id65">
<span id="gui-components-view"></span><img alt="_images/screen19.png" src="_images/screen19.png" />
<p class="caption"><span class="caption-number">Fig. 8.29 </span><span class="caption-text">Data Explorer: Components Subview</span></p>
</div>
</div>
<div class="section" id="errors-subview">
<h3>8.6.4. Errors Subview<a class="headerlink" href="#errors-subview" title="Permalink to this headline">¶</a></h3>
<p>When you select the <span class="guilabel">Exceptions</span> menu item in <a class="reference internal" href="#gui-table-view"><span class="std std-numref">Fig. 8.22</span></a> you will get <a class="reference internal" href="#gui-errors-view"><span class="std std-numref">Fig. 8.30</span></a> view.
In this view you can see what exceptions have been thrown and how their distribution looks like with respect to agents.
When you click one of the exceptions you will get its distribution with respect to the agents.</p>
<div class="figure align-center" id="id66">
<span id="gui-errors-view"></span><img alt="_images/screen23.png" src="_images/screen23.png" />
<p class="caption"><span class="caption-number">Fig. 8.30 </span><span class="caption-text">Data Explorer: Errors Subview</span></p>
</div>
</div>
<div class="section" id="time-and-duration-subviews">
<h3>8.6.5. Time and Duration Subviews<a class="headerlink" href="#time-and-duration-subviews" title="Permalink to this headline">¶</a></h3>
<p>If you select the <span class="guilabel">Duration Distribution</span> menu item in <a class="reference internal" href="#gui-table-view"><span class="std std-numref">Fig. 8.22</span></a>, you will get a bar chart <a class="reference internal" href="#gui-duration-dist"><span class="std std-numref">Fig. 8.31</span></a> representing a distribution of calls duration. The bars colors correspond to agents.</p>
<div class="figure align-center" id="id67">
<span id="gui-duration-dist"></span><img alt="_images/screen21.png" src="_images/screen21.png" />
<p class="caption"><span class="caption-number">Fig. 8.31 </span><span class="caption-text">Duration Distribution</span></p>
</div>
<p>If you select the <span class="guilabel">Time Distribution</span> menu item in <a class="reference internal" href="#gui-table-view"><span class="std std-numref">Fig. 8.22</span></a>, you will get a bar chart <a class="reference internal" href="#gui-calls-dist"><span class="std std-numref">Fig. 8.32</span></a> representing a distribution of calls count. The bars colors correspond to agents.</p>
<div class="figure align-center" id="id68">
<span id="gui-calls-dist"></span><img alt="_images/screen22.png" src="_images/screen22.png" />
<p class="caption"><span class="caption-number">Fig. 8.32 </span><span class="caption-text">Calls Distribution</span></p>