-
Notifications
You must be signed in to change notification settings - Fork 0
/
user.html
684 lines (550 loc) · 52.5 KB
/
user.html
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
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.7.4 at 11 Mar 2017
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="Date-Revision-yyyymmdd" content="20170311" />
<meta http-equiv="Content-Language" content="en" />
<title>Fine Grained Service Monitoring System – User Guide</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.6.min.css" />
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<script type="text/javascript" src="./js/apache-maven-fluido-1.6.min.js"></script>
</head>
<body class="topBarDisabled">
<a href="https://github.com/mil-oss/fgsms">
<img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"
src="https://s3.amazonaws.com/github/ribbons/forkme_right_green_007200.png"
alt="Fork me on GitHub">
</a>
<div class="container-fluid">
<div id="banner">
<div class="pull-left"><a href="http://mil-oss.org/" id="bannerLeft"><img src="images/mil-oss-logo.png" alt="Fine Grained Service Monitoring System"/></a></div>
<div class="pull-right"><div id="bannerRight"><img src="images/fgsms_logo_small.png" /></div>
</div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="projectVersion">Version: 7.0.0<span class="divider">|</span></li>
<li class=""><a href="https://www.mil-oss.org" class="externalLink" title="MIL-OSS">MIL-OSS</a><span class="divider">/</span></li>
<li class="active ">User Guide</li>
<li id="publishDate" class="pull-right">Last Published: 11 Mar 2017</li>
</ul>
</div>
<div class="row-fluid">
<div id="leftColumn" class="span2">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li><a href="index.html" title="Project Information"><span class="none"></span>Project Information</a> </li>
<li><a href="index2.html" title="Welcome"><span class="none"></span>Welcome</a> </li>
<li><a href="whitepaper.html" title="Whitepaper"><span class="none"></span>Whitepaper</a> </li>
<li><a href="architecture.html" title="Architecture"><span class="none"></span>Architecture</a> </li>
<li><a href="quickstart.html" title="Quick Start"><span class="none"></span>Quick Start</a> </li>
<li><a href="deployment-planning.html" title="Deployment Planning"><span class="none"></span>Deployment Planning</a> </li>
<li><a href="deployserver.html" title="Deploying the Server"><span class="none"></span>Deploying the Server</a> </li>
<li><a href="agentmatrix.html" title="Agent Matrix"><span class="none"></span>Agent Matrix</a> </li>
<li><a href="deployagent.html" title="Deploying Agents"><span class="none"></span>Deploying Agents</a> </li>
<li class="active"><a href="#"><span class="none"></span>User Guide</a>
</li>
<li><a href="reporting.html" title="Reports and data access"><span class="none"></span>Reports and data access</a> </li>
<li><a href="security.html" title="Security Guide"><span class="none"></span>Security Guide</a> </li>
<li><a href="permissions.html" title="Access Control"><span class="none"></span>Access Control</a> </li>
<li><a href="federation.html" title="Data Federation"><span class="none"></span>Data Federation</a> </li>
<li><a href="news.html" title="News"><span class="none"></span>News</a> </li>
<li><a href="sdk.html" title="SDK"><span class="none"></span>SDK</a> </li>
<li><a href="specs.html" title="Specs/ICD"><span class="none"></span>Specs/ICD</a> </li>
<li><a href="committer.html" title="Committers"><span class="none"></span>Committers</a> </li>
<li><a href="faq.html" title="FAQ"><span class="none"></span>FAQ</a> </li>
<li class="nav-header">Modules</li>
<li><a href="apache-tomcat/index.html" title="Pre-Configured Apache Tomcat"><span class="none"></span>Pre-Configured Apache Tomcat</a> </li>
<li><a href="apache-juddi/index.html" title="Pre-Configured Apache Juddi"><span class="none"></span>Pre-Configured Apache Juddi</a> </li>
<li><a href="fgsms-common-interfaces/index.html" title="fgsms Interfaces WS Stubs and Schema Bindings Generated from WSDL"><span class="none"></span>fgsms Interfaces WS Stubs and Schema Bindings Generated from WSDL</a> </li>
<li><a href="fgsms-common/index.html" title="fgsms Common"><span class="none"></span>fgsms Common</a> </li>
<li><a href="fgsms-agents/index.html" title="fgsms Embedded Agents"><span class="none"></span>fgsms Embedded Agents</a> </li>
<li><a href="fgsms-ws-notification/index.html" title="fgsms WS-Notification Parent"><span class="none"></span>fgsms WS-Notification Parent</a> </li>
<li><a href="fgsms-server/index.html" title="fgsms Server"><span class="none"></span>fgsms Server</a> </li>
<li><a href="fgsms-cli/index.html" title="fgsms Command Line Interface"><span class="none"></span>fgsms Command Line Interface</a> </li>
<li><a href="fgsms-samples/index.html" title="fgsms Examples Packages"><span class="none"></span>fgsms Examples Packages</a> </li>
<li><a href="fgsms-dist/index.html" title="fgsms Distribution"><span class="none"></span>fgsms Distribution</a> </li>
<li><a href="fgsms-netagent/index.html" title="fgsms.Net Components"><span class="none"></span>fgsms.Net Components</a> </li>
<li class="nav-header">Project Documentation</li>
<li><a href="project-info.html" title="Project Information"><span class="icon-chevron-right"></span>Project Information</a> </li>
<li><a href="project-reports.html" title="Project Reports"><span class="icon-chevron-right"></span>Project Reports</a> </li>
</ul>
<form id="search-form" action="https://www.google.com/search" method="get" >
<input value="https://mil-oss.github.io/" name="sitesearch" type="hidden"/>
<input class="search-query" name="q" id="query" type="text" />
</form>
<script type="text/javascript">asyncJs( 'https://cse.google.com/brand?form=search-form' )</script>
<hr />
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>
</div>
</div>
</div>
<div id="bodyColumn" class="span10" >
<h1>User Guide</h1>
<p>NOTICE: This page needs a lot of sceen shots and is a work in progess, sorry!</p>
<div class="section">
<h2><a name="Using_the_FGSMS_Web_GUI"></a>Using the FGSMS Web GUI</h2>
<p>Under normal circumstances, all necessary interactions for configuring and monitoring FGSMS can be performed using the FGSMS Web GUI. Alternatively, all of these interactions can be performed via web service interactions (See Using the FGSMS Web Services). </p>
<p>Information Assurance: Behind the scenes, all actions performed from the FGSMS Web GUI (OWG) are actually executed by the FGSMS web services. The OWG cannot communicate to the underlying database directly; this was done purposely. The web services act as the primary point of enforcing access control rules, both for accessing data and for making policy changes.</p>
<p>Browser Requirements: </p>
<ul>
<li>Internet Explorer 7 or higher</li>
<li>Firefox 3.6 or higher</li>
<li>Google Chrome 1.0 or higher</li>
</ul>
<p>The following sections detail the common actions that can be performed using the UI.</p>
<div class="section">
<h3><a name="Accessing_the_Web_Interface"></a>Accessing the Web Interface</h3>
<p>Once FGSMS is installed and running, the web interface can be accessed using the following URL template:</p>
<p><tt>http(s)://localhost :(port)/fgsmsBootstrap</tt></p>
<p>Depending on the authentication mode selected, you may be prompted for a username and password, or a PKI certificate.</p>
<p><img src="images/login_page.png" alt="‘Login page’" /></p>
<p>The disclaimer can be changed by editing the file <tt>login.jsp</tt> within <tt>fgsmsBootstrap.war</tt>.</p>
<p>Information Assurance Note – when operating with Username/Password authentication, the web gui passes the signed in user’s credentials along to the web server hosting the FGSMS web services. With PKI/CAC, the user’s identity is passed using headers.</p></div>
<div class="section">
<h3><a name="Navigation_Bar"></a>Navigation Bar</h3>
<p>The top portion of your browser should now contain the navigation bar. It contains links to access information and displays some critical information related to FGSMS and the services that are being monitored.</p>
<p><img src="images/home.png" alt="‘Home’" /></p>
<p>On the very top is the current classification level and caveats. (See [Increase the Security Classification of FGSMS]). Most people won’t have any need to mess with this, but it’s useful to remind users that information on the page has certain usage restrictions, caveats, etc. Common uses are “For Official Use Only” or “Confidential”.</p>
<p>Below that is the navigation menu which contains links to access all of the information collected by FGSMS, as well as configuration settings.</p>
<p>On the left is the quick status bar. This is a list of all services that you have access to, sorted by operating status (green is lower priority). This list also includes all FGSMS services and background processes. If everything is green, FGSMS, along with all your monitored services are online and responding. (great success!)</p>
<p><img src="images/statusbar.png" alt="‘Status bar’" /></p>
<p>Move your mouse over it, it will expand to provide more information.</p>
<p><img src="images/statusbar2.png" alt="‘Status bar’" /></p>
<p>Should a service go offline or encounter a fault, the Operating Status message will change from green to red and OK changes to ERROR. Clicking on the “details” link will provide more information.</p>
<p><img src="images/statusbarerror.png" alt="‘Status bar error’" /></p>
<p>There are several different states a service can be in. The state is calculated by a combination of faults/error counts, service available (online/offline), and service level agreement violations (SLA). In addition, <tt>unknown</tt> is a status that is generally for when a service is just added and it’s operating state is not yet currently know.</p>
<p>Should an agent fail to check in, crash, or there’s a network outage, in some cases, the status indicators can change to a <tt>stale</tt> state. This basically means that we have data for the service, but it’s old which could indicate a problem.</p></div></div>
<div class="section">
<h2><a name="FIXME_needs_to_moved_elsewhere"></a>FIXME needs to moved elsewhere</h2>
<p>In addition, there is a WARNING message if operating in non-SSL communication. These status messages are checked every time a page loads in FGSMS’s Web GUI and are not polled. In the center bottom, you may notice an orange box containing “X alerts waiting”. This represents Browser or GUI Based Alerting and represents the last 40 alerts that occurred in the last one half hour. Alerting is generally used for available or performance metrics.</p>
<h1>My Services</h1>
<p>Click on <tt>My Services</tt>. This displays the service list (again filtered by what you have access too). The list is sorted alphabetically but can be trimmed down to just the services that are offline or that have an issue. By default, when a new service is monitored, only FGSMS administrators can access them.</p>
<p>Each item is clickable to expand the view for more details.</p>
<p><img src="images/myservices.png" alt="‘My Services’" /></p>
<p><b>Pro tip</b>: if you set the <tt>Display Name</tt> for all your services, this will become much more readable.</p>
<p>Provided that at least one FGSMS agent is installed and reporting correctly, there should be at least one service listed within the “My Services” screen. Under each monitored service is a number of links. Which links are displayed are dependent on the type of thing that is being monitored. The type correlates to the Policy Type which is discussed in the Service Policies section. The following describes where each link goes to what information can be obtained from them. Click on one of them to expand the view.</p>
<p><img src="images/myservices_details.png" alt="‘My Services’" /></p>
<ul>
<li>(Service URL) – This will bring you to the performance viewer, showing only the statistics for this specific service.</li>
<li>Manage – This will display a consolidated view performance data, availability data, message transaction logs, and the current service policy for this specific service.</li>
<li>Availability – This will display a tabular view of date and time stamps when the service because unavailable or available.</li>
<li>Transactions – This will display the transaction viewer, displaying a listing of the most recent transactions that were recorded by FGSMS agents.</li>
<li>Performance – This will display performance data for this specific service.</li>
</ul>
<p>To continue the tour of the FGSMS web interface, click on “Manage” next to a particular service. This brings you to the Service Profile view.</p>
<h1>Service Profiles</h1>
<p><img src="images/profiles.png" alt="‘Profiles’" /></p>
<p>Above is the Service Profile editor. It provides access to not only per service configuration elements, but also access control rules, alertings, message logs, alerts and more. For now, let’s start with Service Policies.</p></div>
<div class="section">
<h2><a name="Service_Policies"></a>Service Policies</h2>
<p>FGSMS is a policy driven system. It is important to note that an FGSMS service policy is not based on WS-Policy, WSDM, or any other OASIS or W3C based standard. Although both specifications are appropriate for some tasks, service monitoring in the context of FGSMS is not one of them. Service Policies dictate a number of things within FGSMS and is the core data model used throughout the system. In starts with being able to uniquely identify a thing that is monitored. For web services, these are generally URLs. Non-web based services are generally notated by a URN. Each service policy is defined by a unique URI, which either be a Modified URL or some other type of URI</p>
<p><b>IMPORTANT</b></p>
<p>Original URL vs Modified URL FGSMS has the concept of Original URLs vs Modified URLs. The Original URL is typically used for connecting to something, whereas the Modified URL represents the original URL that has been modified to only include the hostname of the machine hosting the service. For example, using the provided FGSMS Agents, two URLs are recorded with each transaction. The first is the “Original URL”. For systems that are load balanced, this is typically something like <a class="externalLink" href="https://myloadbalancedurl.mybusiness.com/service1">https://myloadbalancedurl.mybusiness.com/service1</a>, however the actual service resides on two different servers with the hostname of www1 and www2, making the Modified URL to the service <a class="externalLink" href="https://www1/service1">https://www1/service1</a> and <a class="externalLink" href="https://www2/service2">https://www2/service2</a>.</p>
<p>The original URL can also contain things like “localhost” or an IP address. When an agent “sees” a message, it converts the request URL into the modified version which is more absolute and helps to distinguish different services within the FGSMS realm.</p>
<div class="section">
<h3><a name="Service_policy_types"></a>Service policy types</h3>
<p>Service Policies can be one of the following types that represent the thing being monitored.</p>
<ul>
<li>Transactional Web Service (SOAP/REST, etc)</li>
<li>Statistical (Message Broker)</li>
<li>Machine (general computer monitoring)</li>
<li>Process (monitors a process or service running on a computer</li>
<li>Status (provides operational information only)</li>
<li>Service Policy Common Settings</li>
</ul>
<p>Each policy type provides additional settings and configuration parameters that extend from the common settings which are available for all policy types. </p>
<div class="section">
<h4><a name="Basics_Settings"></a>Basics Settings</h4>
<p>The service policy editor starts on the with the <b>Basics</b>. These settings that are available for all service policy types include the following.</p>
<ul>
<li>URI – a unique identifier for the service. In most cases this is a URL but it can also represent other things that are specific to an agent.</li>
<li>Display Name – If no display name is defined, the GUI will default to using the URI for display purposes</li>
<li>Domain Membership – Identifies if the machine is joined to a Windows Domain and provides additional context as far as where the machine is located.</li>
<li>Bucket – Provides a general categorization of items</li>
<li>Description</li>
<li>Point of Contact</li>
<li>Geo Tagging – provides a decimal latitude longitude coordinates for the item represented.</li>
<li>Data Retention Time – this setting is important and defines how long data for this service is kept in the database. Retaining data for long periods of time can greatly affect the performance of the web interface and report generator.</li>
</ul>
<p><img src="images/policyeditornav.png" alt="‘Policy Editor’" /></p>
<p>Each service policy type has additional configuration parameters that are specific to each policy type.</p>
<p>!When making changes, always remember to click the “Save Policy” button when finished.</p>
<p>The following sections identify each setting and what they mean.</p></div>
<div class="section">
<h4><a name="Service_Level_Agreements"></a>Service Level Agreements</h4>
<p><img src="images/sla.png" alt="‘SLA’" /></p>
<p>FGSMS has support for Service Level Agreements (SLA). In FGSMS, a SLA is defined as a performance or content based rule that causes some kind of action to occur. These rules fall into two different categories, Transactional or Non-transactional. </p>
<p>Architectural Note: A transactional rule is something that can be measured from one specific transaction. Non-transactional rules are measured over a range or group of transactions or availability data.</p>
<p>Transaction Rules (examples):</p>
<ul>
<li>Every successful transaction</li>
<li>Every faulting transaction</li>
<li>Response time greater or less than a specific value</li>
<li>Request/response message size is greater or less than a specific value</li>
<li>XPath expression result</li>
<li>And many more</li>
</ul>
<p>Non-transaction Rules (examples):</p>
<ul>
<li>Invocation Rate/over time is greater/less than a specific value</li>
<li>Fault Rate/over time is greater/less than a specific value</li>
<li>MTBF/over time is greater/less than a specific value</li>
<li>And many more</li>
</ul>
<p>Why is this important?</p>
<p>It determines where the processing takes place and how often it is calculated.</p>
<p>To add a new SLA, click the Add button</p>
<p><img src="images/addsla.png" alt="‘Add SLA’" /></p>
<p>Current the available actions that are available are:</p>
<ul>
<li>Email Alert</li>
<li>Send a Log entry to a specific Logger</li>
<li>Send a WSDM Management Event Alert Message
<ul>
<li>JMS</li>
<li>AMQP</li>
<li>WS-Notification</li>
<li>UDP Multicast</li>
</ul></li>
<li>Others</li>
<li>Run a script</li>
<li>Restart</li>
</ul>
<p>SLA Processing occurs at several different locations depending on the type of action.</p>
<ol style="list-style-type: decimal">
<li>Alerting a. Data Collector Services (FGSMSServices.war): Transactional SLA alerts are processed asynchronously at each instance of a DCS. b. SLA Processor (timed process) (FGSMSServices.war): The SLA Processor runs at predefined intervals. It is used to process non-transactional SLAs.</li>
<li>Run a script – This can be executed at either the FGSMS Server or at the agent (only supported on Operating System Agents)</li>
<li>Restart - Only supported on Operating System Agents and on certain JMX based agents. See agent capability descriptors for more information.</li>
</ol>
<p>Example SLA Setting</p>
<p>SLA’s are specific to the type of policy and thus the type of data that is recorded. It would not make sense to have a broker rule on a web service, and vice versa.</p></div>
<div class="section">
<h4><a name="Federation"></a>Federation</h4>
<p>FGSMS supports the sharing of data through a number of different mechanisms. It is optional and will expose the selected data to one of several different “Federation Targets”. UDDI v3 compliant server, by appending tModels to endpoint binding templates. UDDI targets require that an administrator configure FGSMS’s UDDI Publisher to publish statistics to a single UDDI server or cluster. These settings are described on the Web GUI via Help > How do I?</p>
<p><img src="images/addfed.png" alt="‘Add Federation Policy’" /> Figure 2 Example Federation Target</p></div>
<div class="section">
<h4><a name="Status_Monitoring"></a>Status Monitoring</h4>
<p>FGSMS’s agents track the availability of services via a variety of mechanisms. Some are self reporting and others use some built in mechanism to poll the server, such as an HTTP request. In some cases, the administrator may need to provide credentials for these requests. On the <tt>Status Monitoring</tt> tab, there are settings for setting the credentials for accessing the service.</p>
<p><img src="images/statusmonitor.png" alt="‘Status Monitor’" /></p>
<p>This is generally used for when an agent needs to authenticate to the service before being able to identify if it’s operational or not. In addition, Transactional Web Services have some additional features discussed in the next section.</p>
<p>The <tt>Set Status Credentials</tt> functionality is also used for JMX based agents such as Apache Qpid, ServiceMix and HornetQ.</p>
<p>Another note: HTTP based services will also use FGSMS’s certificate for authenticating in cases where by a PKI certificate is required.</p>
<p>If by chance the discovered URL for a service is incorrect or cannot be accessed for some reason, an alternate URL can be specified in the general tab.</p></div></div>
<div class="section">
<h3><a name="Per_Policy_Type_Settings"></a>Per Policy Type Settings</h3>
<p>The following sections detail what’s different about each type of policy and how to use them effectively. Transactional Web Services</p>
<div class="section">
<h4><a name="Transactional_Web_Services"></a>Transactional Web Services</h4>
<p>This type of service policy is typically used for web accessible services, such as SOAP, REST, Servlets, or any web page.</p>
<ul>
<li>Defines what pieces of data to record during a web service transaction. Request and Response XML messages and how much of it to record</li>
<li>Defines what extra steps need to be performed after the data is collected, (service level agreements) such as Email alerts.</li>
<li>Defines mechanisms from which to identify the consumer (HTTP auth, XPATH)</li>
</ul>
<p>Also note that from this page, you can view and change the permissions for this specific service, delete the service policy and delete the performance and availability data for this service.</p>
<p>When an FGSMS Agent sees a web service transaction, it firsts retrieves the web service policy for it. At a minimum, transactional web service agents will always record the following performance statistics:</p>
<ul>
<li>Size of the request message</li>
<li>Size of the response message</li>
<li>The transaction state (Fault, Success). Note: Certain security faults may not be recorded as different agent implementations may not be triggered. This is implementation and SOAP stack specific.</li>
<li>The response time in milliseconds that it took for the service to process the request. Note: this may not include security header processing such as encryption or signing. This is implementation and SOAP stack specific.</li>
<li>The timestamp of when the request was received</li>
<li>The hostname of the machine hosting the service</li>
<li>The request URL of the transaction</li>
<li>The requested SOAP Action or Http Method, otherwise known as the operation or method that is being executed.</li>
<li>Transport headers (except for authentication tokens)</li>
</ul>
<div class="section">
<h5><a name="Status_Updating_for_Transactional_Web_Services"></a>Status Updating for Transactional Web Services</h5>
<p>Since web services are typically stateless, the only mechanism available to ascertain the operating system of them is to try and connect to it and perform some action. FGSMS does this via the Status Bueller.</p>
<p>Status Bueller – The Status Bueller connects to local or remote services and attempts to retrieve the WSDL document. If it cannot connect or a non HTTP 200 OK status message is returned, the service is flagged as unavailable.</p>
<p>In either case, it’s possible for the service to require authentication. For Username/Password scenarios, the Set Status Credentials and Clear Credentials settings can be used. For CAC/PKI scenarios, the Status Bueller uses the “defaults” grouping of settings. See General Settings for more information.</p></div>
<div class="section">
<h5><a name="Performance_Notes_on_Transactional_Service_Policies"></a>Performance Notes on Transactional Service Policies</h5>
<p>The settings you make as a service owner on the FGSMS policy can and will affect the performance characteristics of this service. The lowest overhead settings are as follows</p>
<p>| Parameter | Value | | — | — | |Record Request | False |Record Response |False |Record Both but only when faulting | False |Record Headers |True |User Identification |Empty, IP Address and Context Usernames are provided out of the box. This is only used for Http Headers or XPaths |Service Level Agreements | Has no affect on service performance, however certain SLAs require recording the request or response message for functionality (XPath) |Others | All other settings have no performance effect.</p>
<p>The reason for this additional performance penalty has to do with the conversion of XML to objects in memory. This process is called serialization or marshalling and is a relatively expensive process to perform in regards to CPU time.</p>
<p>In addition, when web services do not use SOAP Actions, agents will attempt to parse the XML message to determine what method is being invoked. This will also cause an additional delay. As a note to developers of web services, always use SOAP Actions. Many web service frameworks require it.</p></div>
<div class="section">
<h5><a name="Recording_PayloadsMessage_Logging"></a>Recording Payloads/Message Logging</h5>
<p>Agents, through service policies, can also record the web service transaction request and response XML messages. There are three options for recording web service transactions.</p>
<ul>
<li>Record the Request XML Message</li>
<li>Record the Response XML Message</li>
<li>Record the Request and Response XML Message, but only when the service faults.</li>
</ul>
<p>There are some limitations to how much information can be recorded. For performance and reliability reasons, the maximum amount of information recorded for a request or a response is 1MB, or roughly 1,024,000 characters of text. In most cases, this is enough information in order to identify a consumer and to record whatever auditing information is necessary. The amount of recorded data can be set, but only on a global basis (per FGSMS domain), up to the maximum of 1,024,000 bytes. This can be expanded by modifying the code for the PCS.</p>
<p>Information Assurance Note: Depending on the particular agent implementation, messages that have been encrypted on the wire may be transmitted to the FGSMS server using non-SSL communications. For message confidentiality, please ensure SSL is used from the agents to the FGSMS server. Message logs and associated HTTP headers are encrypted on disk using AES 256bit encryption. </p></div>
<div class="section">
<h5><a name="User_Identification"></a>User Identification</h5>
<p>Service policies do not just end with performance related data. On occasion, service owners may want to know who is executing their services. Often, this information is available via web service container log files, but is not always convenient to access. Through service policies, FGSMS agents can identity service customers through three ways:</p>
<ol style="list-style-type: decimal">
<li>XPath notation – By defining an XPath Query along with all the associated namespace prefixes used by a given service, a consuming entity can be identified to a particular string.</li>
<li>HTTP Credentials, including HTTP Client Certificates, Usernames, etc. For .NET Agents, this translates to anything that populates the HttpContext.Current.User principle or the HttpContext.Current.Request.ClientCertificate fields. For Java agents, the HttpServletRequest.getUserPrincipal() must be populated for the given security architecture.</li>
<li>HTTP Header – For systems that sit behind a reverse SSL proxy or through a HTTP server, user identity information is often transmitted via an HTTP Header. This is considered a secure mechanism because the only access point is from the proxy. In this scenario, the proxy acts as an authenticator and passes a user principle via a HTTP Header.</li>
</ol>
<p>Since there are infinite combinations of authentication and authorization practices, FGSMS allows system and service owners to defined multiple ways to identify consumers. They can be combined. After processing, the resultant set of user identities is accessible via the message logs as a semicolon delimited string. Implementation Note: When using XPath expressions to identify users, Java based FGSMS require the xpath query to NOT have XML Namespace prefixes and to NOT define any XML Namespaces.</p>
<p>.NET based agents require that the Xpath query contain all XML Namespace prefixes that that they are all defined. </p></div></div>
<div class="section">
<h4><a name="Statistical_Message_Brokers"></a>Statistical (Message Brokers)</h4>
<p>Statistical Policies indicate that general statistics are available from the item being monitored as well as its availability information. There are no other settings available. Depending on the type of broker being monitored, the data available can included:</p>
<ul>
<li>Operational Status</li>
<li>Topic or Queue Name</li>
<li>Messages In/Out/Dropped</li>
<li>Bytes In/Out/Dropped</li>
<li>Queue Depth</li>
<li>Active/Total Consumers</li>
</ul>
<p>Statistical services have the following SLA Rules available to them</p>
<ul>
<li>Change in Status</li>
<li>Queue or Topic Does Not Exist</li>
<li>Status Message Contains Ignoring Case</li>
<li>Queue Size Greater than</li>
</ul></div>
<div class="section">
<h4><a name="Machine"></a>Machine</h4>
<p>FGSMS comes with an Operating System Agent using the SIGARS API that provides monitoring on a variety of different platforms. The following data points can be recorded:</p>
<ul>
<li>CPU Usage</li>
<li>Disk Partition Usage (KB/sec)</li>
<li>Disk Partition Free Space</li>
<li>Memory Usage</li>
<li>Running Process List</li>
<li>Network Interface Card Usage (KB/sec)</li>
</ul>
<p><img src="images/machinepolicy.png" alt="‘Machine Policy’" /></p>
<p>The following SLA rules are supported</p>
<ul>
<li>Change in Status</li>
<li>Status Message Contains Ignoring Case</li>
<li>High CPU/Memory/Network/Disk IO</li>
<li>Low disk space</li>
</ul></div>
<div class="section">
<h4><a name="Process"></a>Process</h4>
<p>Processes are defined as some kind of program or application that runs on a Machine. The following data points are supported</p>
<ul>
<li>Open File Handles</li>
<li>CPU Usage</li>
<li>Memory Usage</li>
<li>Operating Status</li>
</ul>
<p>The following SLA’s are supported</p>
<ul>
<li>Change in Status</li>
<li>Status Message Contains Ignoring Case</li>
<li>High CPU/Memory</li>
<li>High File Handlers</li>
</ul></div>
<div class="section">
<h4><a name="Status"></a>Status</h4>
<p>The Status policy type is a generic policy type that enables an agent to set the status on virtually anything. The following data points are recorded:</p>
<ul>
<li>Operational Status</li>
</ul>
<p>The following SLAs are supported:</p>
<ul>
<li>Change in Status</li>
<li>Status Message Contains Ignoring Case</li>
</ul></div></div></div>
<div class="section">
<h2><a name="Global_Policies"></a>Global Policies</h2>
<p>FGSMS has a few global policies defined.</p>
<ul>
<li>Defines how often FGSMS Agents should to refresh service policies</li>
<li>Defines the default recorded message size cap (default and system maximum is 1MB). This value acts as the default value and can be overridden on a per service basis</li>
<li>Defines how often FGSMS publishes data to a UDDI server</li>
<li>Defines the current security classification level</li>
</ul>
<p>All of these policies can be defined via the Web GUI via Administration > Global Policies and Security Level, or via interactions with the Policy Configuration Service (PCS). The UDDI Publisher settings are now in General Settings section. In addition, a large number of default settings have been added, also in the General Settings section.</p></div>
<div class="section">
<h2><a name="Transaction_Logs_For_Transactional_Services"></a>Transaction Logs (For Transactional Services)</h2>
<p>By clicking on “Transaction Logs” will bring you to the transaction log viewer. This page will enable you to see all recorded transactions from a web service/resource. This view can be filtered by selected “All Transactions”, “Show Only Faulted Transactions”, and “Show Only SLA Violations”. </p>
<p>This view can further be expanded by altering the request URL. Parameter: offset=x, allows you to page through the results (you can also click on “next” and previous” Parameter: records=x, allows you to change the maximum number of records rendered on the screen at a time. I’d suggest using a record count of less than 2000.</p>
<p><img src="images/messagelog.png" alt="‘Message Logs’" /></p>
<p>When scrolling down, you can see the total number of records that are available. Displayed is also the identity of the requestor, their IP address, the “action” of the message, response time and timestamp. </p>
<p>Under the column labeled “REQ/RES”, if the letters REQ are present in the row, this means that the actual request message was recorded and is available. RES is for the response. Click on “Details” link to display the specific transaction log viewer.</p>
<p><img src="images/transactionviewer.pnp" alt="‘Transaction Viewer’" /></p>
<p>From this screen, the size of the message, the actual message, SLA fault information, the hostname of the server hosting the service, and the type of FGSMS agent that recorded the message are displayed.</p></div>
<div class="section">
<h2><a name="Transaction_Log_Filters"></a>Transaction Log Filters</h2>
<p>There is a second way to view transaction logs: via Data > Web Service Transaction Log Search.</p>
<p><img src="images/transactionlogsearch.png" alt="‘Transaction Search’" /></p>
<p>This screen will let you fine tune a transaction log query to return transaction log information. The minimum fields required is a date range and the number of records to return. All results are sorted by newest record first (descending). Click on “Fetch” to fetch the corresponding records. The filter panel will automatically hide after clicking on “Fetch”. To change the query, simply click on “Show Filters”.</p></div>
<div class="section">
<h2><a name="Reporting_System"></a>Reporting System</h2>
<p>FGSMS includes a Web GUI which has the ability to display commonly views of the available data in near real time. Also included with FGSMS is an HTML report generation capability. </p>
<div class="section">
<h3><a name="HTML_Reports"></a>HTML Reports</h3>
<p>Utilizing the Reporting Service, a zipped HTML report can be generated. This report is based off of user input that defines which services, report types and a date range to further scope data. Optionally, “All Services” and “All Report Types” can be selected.</p>
<p>Important note: when selecting data for reporting, only select the data that you need. When requesting large data sets, you may experience timeouts or exceptions. If this occurs, reduce the data set or use the Automated Reporting Service.</p>
<p><img src="images/reporting-html.png" alt="‘HTML Based Reporting’" /></p>
<p>Customization Tip: Reports can be customized by modifying the included HTML template and cascading style sheets (CSS). There is currently no support for including custom images such as logos via an embedded image, but it will be considered for future iterations. As a work around, a web facing logo or graphics file can simply be referenced within the template. Within the reporting.jar file, edit Header.txt and Footer.txt</p>
<p>Information Assurance - While anyone who can access the Web GUI can generate a report, only the service data that the user has access to can be returned. The reporting service merely ignores requested data that the user does not have access to. The following is a few screen captures from an <a href="report-sample.zip">example report</a>.</p></div>
<div class="section">
<h3><a name="Data_Export_to_Comma_Separated_Value"></a>Data Export to Comma Separated Value</h3>
<p>The Reporting Service also allows you to export data to a Comma Separated Value text file. The file is actually delimited by the pipe symbol “|”. This can easily be imported into Microsoft Excel or other spread sheet applications.</p>
<p><img src="images/reporting-csv.png" alt="‘CSV Exports’" /></p>
<p>A few things thing to keep in mind with exporting data. * Data is not removed from the database * If you select a type to export data and there is no data for that type of service, no data will be returned.</p></div>
<div class="section">
<h3><a name="Automated_Reporting_Service"></a>Automated Reporting Service</h3>
<p>The Automated Reporting Service (ARS) is a number of components that allows you to define reports (either HTML or CSV export) that are to be automatically generated on a schedule. Once a report has been generated, you will be notified via one or more of the notification systems. Reports can then be picked up at your leisure. They are stored in the database. Once a report is downloaded or is no longer needed, please remove it to save disk space.</p>
<p>To access the ARS, select Reports > Scheduled Reports.</p></div></div>
<div class="section">
<h2><a name="Infrastructure"></a>Infrastructure</h2>
<p>Under the Infrastructure tab of FGSMS’s web interface, are five links (as of RC6), Service Hosts, Data Collectors, Message Brokers, Agents, and Domains/Servers.</p>
<div class="section">
<h3><a name="Data_Collectors"></a>Data Collectors</h3>
<p>The FGSMS Data Collector Service (DCS) is the most fundamental and most important of all of the FGSMS services. Without it, data simply cannot be collected. Therefore it is important to know how much work each copy of the DCS is doing in relationship to others. The Data Collectors page lists all known data collectors as well as a percentage of transactions recorded by this service host.</p>
<p>TODO image</p></div>
<div class="section">
<h3><a name="Service_Hosts"></a>Service Hosts</h3>
<p>The Service Host page gives you a list of machines by hostname from which transactions have been recorded. This also includes transactions monitored from Client agents, meaning that client machines can also be listed here.</p>
<p>TODO image</p>
<p>Clicking on the “View” performance link will provide some general stats for this specific service host.</p></div>
<div class="section">
<h3><a name="Message_Brokers"></a>Message Brokers</h3>
<p>FGSMS supports monitoring Message Brokers. This is different than the standard “request/response” pattern seen with most SOAP/XML messages. The message broker also typically does not have the capability for FGSMS to “see” individual transactions but can obtain general statistical information as reported by the broker.</p>
<p>FGSMS ships with two AMQP agents for Apache Qpid/RedHat MRG which report back to FGSMS statistical data on Message Queues and Exchanges as well as the online status of the broker. The following screen shot shows example data captured by both AMQP JMX and Python based agents.</p>
<p>TODO image</p>
<p>By clicking on the URI of the broker, additional data is displayed by Queue/Exchange name.</p>
<p>TODO IMAGE</p></div>
<div class="section">
<h3><a name="Agents"></a>Agents</h3>
<p>By clicking on “Agents”, a listing of all recorded FGSMS agents will be displayed. This lists only the agents that are capable of reporting back data on a transactional basis (this implies that message brokers are not visible) and only agents that actually have reported back data will be displayed.</p></div>
<div class="section">
<h3><a name="DomainsServers"></a>Domains/Servers</h3>
<p>The Domains/Servers tabs gives you the ability to monitor specific processes or components running on a machine with an OS Agent running on it. This allows administrators to drill down from a domain to a server. It displays machine characterizes and enables administrators to start monitoring specific items on a machine.</p>
<p>TODO image</p>
<p>To monitor a specific process on this machine, click on “Running Processes” tab, then click on “Monitor this Item”.</p></div></div>
<div class="section">
<h2><a name="General_Settings"></a>General Settings</h2>
<p>The General Settings section of FGSMS is used to set general settings that control most aspects of the FGSMS server components, alerting functionality, default settings, SSL key stores and generally, any other setting that is needed.</p>
<p>All of these settings are defined and are accessible in the browser via <tt>Help > How Do I…</tt> under the heading of <tt>What settings are available for
me to tweak?</tt></p>
<p>General Settings also provides a single place to access configuration settings for all FGSMS components excluding configuration for the Web GUI itself.</p></div>
<div class="section">
<h2><a name="Configuring_the_Web_User_Interface"></a>Configuring the Web User Interface</h2>
<p>Global Administrators can modify the configuration of each instance of <tt>FGSMSBootstrap.war</tt> (the Web User Interface) via Administration > Connections.</p>
<p>This web page provides basic functionality for configuring the web site’s features remotely. It essentially allows you to modify on the <tt>config.properties</tt> file within <tt>FGSMSBootstrap.war</tt>.</p></div>
<div class="section">
<h2><a name="Alerting"></a>Alerting</h2>
<div class="section">
<h3><a name="Email_based_Alerting"></a>Email based Alerting</h3>
<p>FGSMS’s supports subscribing to SLA email alerts from the browser. Alerting is available for all SLA types.</p>
<p>To register your email address click on Settings > My Account To subscribe to alerts, click on Settings > Alerting</p>
<div class="section">
<h4><a name="GUI_Based_Alerting"></a>GUI Based Alerting</h4>
<p>FGSMS’s web GUI supports alerting right to the browser. Alerting includes:</p>
<ul>
<li>Recent service faults</li>
<li>Operating status other than OK</li>
<li>Recent SLA violations/alerts</li>
</ul>
<p>To enable alerts, click on Settings > Enable Alerts. This setting is set in a cookie on your machine. If moving to another machine, it will have to be re-enabled.</p>
<p>TODO image</p>
<p>By default, the refresh interval is set for 10 seconds. To adjust it, Settings > Alert Interval, then save. This feature requires both the Status Bueller and the Status Service. JMS, AMQP, WS-Notification, and more FGSMS can send alerts using the WSDM specification to anyone of the mentioned message brokers. Web Services Distributed Management (WSDM) is an OASIS specification. The specific message type is the Management Event message. The following is an example of what the messages look like after being delivered.</p>
<div class="source">
<div class="source"><pre class="prettyprint linenums"><ns4:managementEventType xmlns:ns4="http://docs.oasis-open.org/wsdm/muws1-2.xsd" xmlns="http://docs.oasis-open.org/wsdm/muws2-2.xsd" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns2="http://docs.oasis-open.org/wsdm/mows-2.xsd" xmlns:ns3="http://metadata.dod.mil/mdr/ns/netops/esm/qosm" xmlns:ns5="urn:us:gov:ic:ism:v2" xmlns:ns6="http://www.w3.org/2005/08/addressing" xmlns:ns7="http://docs.oasis-open.org/wsrf/rp-2" xmlns:ns8="http://docs.oasis-open.org/wsrf/bf-2" ReportTime="2012-03-12T12:10:20.134-04:00">
<ns4:EventId>urn:beeb1156-3b8e-41bb-8844-41f568418961</ns4:EventId>
<ns4:SourceComponent>
<ns4:ResourceId>http://FGSMSdev1:8180/TestServices/TestService</ns4:ResourceId>
</ns4:SourceComponent>
<Situation>
<SituationCategory xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AvailabilitySituation"/>
<SituationTime>2012-03-12T12:10:20.134-04:00</SituationTime>
<Severity>4</Severity>
<Message xml:lang="english">All Faults</Message>
</Situation>
</ns4:managementEventType>
</pre></div></div>
<p>Please see the Help > How Do I? > What settings are available? Section to how to configure each one.</p></div></div>
<div class="section">
<h3><a name="Loggers"></a>Loggers</h3>
<p>Alerts can also be sent via Log4j Loggers which can be mapped to a wide array of different targets, such as the Windows Event Log, Syslog, UPD Loggers, etc. Details for configuring Log4j is located within the Web GUI under Help > How Do I?</p></div>
<div class="section">
<h3><a name="Extras"></a>Extras</h3>
<div class="section">
<h4><a name="UDDI_Browser"></a>UDDI Browser</h4>
<p>FGSMS’s Web GUI supports basic functionality for retrieving data from a UDDI Server, which can include data published by FGSMS or any other entity. This provides basic read only access to the data. It is recommended that you use <a class="externalLink" href="http://juddi.apache.org">Apache jUDDI</a> user interface as it has more advanced features.</p>
<p>UDDI Browser is supported on the main “Federation” menu in FGSMS as well as on the “Performance” viewer and on “Service Profile” pages. </p>
<p>Configuration:</p>
<p>This is set via the fgsmsBootstrap.war properties file named “config.properties”. If no settings are configured, UDDI features from the GUI will be disabled. More information is available under Help > How Do I? Configure the UDDI Server associated with the GUI.</p></div></div>
<div class="section">
<h3><a name="Dashboard"></a>Dashboard</h3>
<p>TODO this needs updating</p>
<p>FGSMS’s Web GUI has two dashboards that support automatic updating, the “Home” page, and the “Performance” page. The Home page is automatically updated via Ajax/Javascript and references the cookie setting, AlertInterval. This can be adjusted in the settings page. Within the Performance page, simply click on the link for the dashboard. It is preset to display data over the last 24 hours.</p>
<p>TODO image</p></div></div>
<div class="section">
<h2><a name="Auditing"></a>Auditing</h2>
<p>Required Permission: Global administrator or global auditor roles</p>
<p>FGSMS has auditing logs for access to and modification of data. This log is stored in the database indefinitely. Audit logs can be viewed by users with global administrative privileges only via the web interface or via service invocation. </p>
<p>Audit logs can by clicking on <tt>Administration</tt>, then <tt>Auditing</tt>. <img src="images/admin.png" alt="‘Admin’" /></p>
<p>Audit logs can also be exported from the database using the Reporting Service or the Data Export function from the Web GUI.</p></div>
<div class="section">
<h2><a name="Theming_and_other_Browser_Specific_Settings"></a>Theming and other Browser Specific Settings</h2>
<p>The <a href="sdk.index">SDK</a> covers some aspects of reskinning or theming the user interface.</p>
<h1>Viewing Performance Data</h1></div>
<div class="section">
<h2><a name="Transactional_Web_Services"></a>Transactional Web Services</h2>
<p>Architectural Note: By default, when an agent retrieves the policy from the PCS and the policy does not already exist, a policy is automatically created and stored in the configuration database. This is an automatic registration process is only triggered when a service transaction is monitored. In other words, if a service is never executed, FGSMS doesn’t know it exists. By default, only global administrators have read access to performance data and write access for the service policy for newly discovered services. The default policy for “new” services can be configured by altering the PCS’s configuration.</p>
<p>To view the general performance statistics for a service, click on “Performance” from the top navigation bar.</p>
<p><img src="images/performance-feed.png" alt="‘Performance’" /></p></div>
<div class="section">
<h2><a name="Process_Performance"></a>Process Performance</h2>
<p>From the My Services page, locate the URI represent the Process you wish to view, then click on Performance.
</p>
<p><img src="images/process-performance.png" alt="‘Machine Performance’" /></p>
<div class="section">
<h3><a name="Machine_Performance"></a>Machine Performance</h3>
<p>From the My Services page, locate the URI represent the Machine or Process you wish to view, then click on Performance.
</p>
<p><img src="images/machineperformance.png" alt="‘Machine Performance’" /></p>
<h1>Administration</h1>
<p>TODO this section should be moved elsewhere</p></div></div>
<div class="section">
<h2><a name="SSL_Configuration"></a>SSL Configuration</h2>
<div class="section">
<h3><a name="FGSMS_Server"></a>FGSMS Server</h3>
<p>For configuration SSL, trusted certificate issues must be defined and stored in a Java Key Store JKS. By default, the FGSMS Server uses the key store located at /server/default/conf. Any password changes to this file requires the following changes. When using CAC/PKI authentication, these same files will need to be modified.</p>
<ul>
<li>Modify /tomcat/conf/server.xml</li>
<li>Modify /tomcat/webapps/fgsmsBootstrap/META-INF/config.properties</li>
<li>Web GUI > General Settings > update defaults trust store</li>
</ul></div>
<div class="section">
<h3><a name="FGSMS_Agents"></a>FGSMS Agents</h3>
<p>FGSMS’s agents use embedded configuration information stored within FGSMS.AgentCore.jar. This file contains all of the trust stores and key stores used for secure communications, as well as the passwords for these files. Any changes to trust store, key store, or credentials require the following changes</p>
<ul>
<li>Modify the keystore/trust as necessary in FGSMS.AgentCore.jar/META-INF</li>
<li>Modify fgsms-agentconfig.properties</li>
</ul></div></div>
<div class="section">
<h2><a name="Increase_the_Security_Classification_of_FGSMS"></a>Increase the Security Classification of FGSMS</h2>
<p>To increase the security classification of FGSMS, access the web interface. From the drop down menu, select Administration > Security Level</p>
<p>This setting is stored in Configuration Database and is broadcasted to agents via PCS. All services read the current level from the db. The web interface also gets the current classification level from the PCS. Colors and wording are adjusted as per the IC-ISM-v2.xsd file provided by Intelligence Community Security Markings, available at www.niem.gov.</p></div>
</div>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
</div>
</div>
</footer>
</body>
</html>