ftl_tutorial_10.pdf - · pdf file83 figure 10.6: subscriber application metrics each metrics...
TRANSCRIPT
TIBCO FTL R�
Programming TutorialSoftware Release 5.3October 2017
1
Contents
Introduction i
1 Getting Started with FTL Programming 11.1 Set Up the Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Start the Local Realm Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3 Build the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.4 Run the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2 Understanding the Code 42.1 ftlbasicpub.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.2 ftlbasicsub.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 Error Handling 93.1 Running Without the Realm Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.2 Adding Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.3 Understanding the Error Handling Code and Output . . . . . . . . . . . . . . . . . . . . . . 123.4 Restart the Realm Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.5 Working With Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4 Messages and Fields 164.1 FTL Field Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.2 FTL API Functions to Set Field Values in a Message . . . . . . . . . . . . . . . . . . . . . 164.3 FTL API Functions to Get Field Values from a Message . . . . . . . . . . . . . . . . . . . . 174.4 Working with Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5 Introduction to Content Matchers 205.1 Matcher Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205.2 ftlbasicpub.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205.3 ftlbasicsub.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.4 Build and Run the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225.5 Some Variations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6 Exploring the Realm 266.1 The Realm Server Web Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266.2 The Realm Server Web API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
7 Defining an Application 357.1 The Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357.2 Defining an Application Using the Realm Server Web Interface . . . . . . . . . . . . . . . . 357.3 Defining an Application Using the Realm Server Web API . . . . . . . . . . . . . . . . . . 45
TIBCO FTL R� Programming Tutorial
78
Lesson 10: Client Metrics
The realm server web interface makes available metrics as reported by each client program. In this lessonwe’ll look at some of the metrics available.
Before looking at the metrics, a basic understanding of the communication between a client and the realmserver is needed.
10.1 Client-Realm Server Communication
The connection between a client program and the realm server is established by thetibRealm_Connect() call. Once connected, basic identifying information is exchanged, and the realmserver sends the realm definition to the client program. Next the client program sends a HELLO message tothe realm server, containing additional identifying information. At this point the client programinformation appears in the realm server’s list of clients (see Figure 9.3, page 77 for an example).
While the client program is running, the realm server periodically sends heartbeat messages to the clientprogram. In a similar manner, the client program periodically sends heartbeat messages to the realm server.Any metrics gathered since the last heartbeat message sent to the realm server are included.
A client program’s call to tibRealm_Close() sends a GOODBYE message to the realm server, whichcauses the realm server to remove that client from its list of clients. The connection to the realm server isthen closed.
A client program that abnormally terminates (such as via ctrl + C or a fatal error) does not send aGOODBYE message. Instead it is subject to timeouts based on the absence of heartbeat messages beforebeing removed from the realm server’s list of clients.
The frequency at which heartbeat messages are sent by either side is determined by the realm properties,which are part of the realm definition. Let’s take a look at these properties.
Ensure the realm server is still running, open a web browser, and navigate to the URLhttp://localhost:8080. If the realm server login page is displayed, login as you did in Section 6.1,page 26. Bring up the Applications grid by clicking on the link on the left side of the screen.
TIBCO FTL R� Programming Tutorial
79
Figure 10.1: Applications grid
Along the left side of the screen, the link denoted by the icon and labeled “Realm Properties” displaysthe Realm Properties page. Click it, resulting in a display similar to Figure 10.2.
Figure 10.2: Realm Properties page
We’re interested in the information in the “Intervals” box. Under “Client ! Realm Server”, “Heartbeat”controls how often the client program sends a heartbeat message to the realm server, while “Timeout”
TIBCO FTL R� Programming Tutorial
80
determines how much time can pass without the realm server receiving a heartbeat message from a clientbefore the realm server removes that client from its list of clients.
Under “Realm Server ! Client”, “Hearbeat” controls how often the realm server sends a heartbeat messageto all client programs, while “Timeout” determines how much time can pass without the client receiving aheartbeat message from the realm server before the client attempts to reconnect to the realm server.
Under “Client Statistics Sampling”, “Client Sampling Interval” controls how often the client programgathers its metrics into a timestamped sample. If “Client Sampling Interval” is smaller than the “Client !Realm Server” heartbeat interval, each heartbeat message sent to the realm server may contain more thanone sample.
10.2 Run the Samples
In order to look at the client metrics, let’s run the sample client programs from lesson 9. Open a commandwindow, navigate to the $TIBFTL_TUTDIR/code/lesson-09 directory, and start the subscriber. We’llspecify that application “App1” and endpoint “endpoint-1” be used:
./ftlsub -a App1 -e endpoint-1
In another command window, navigate to the same directory and start the publisher. Specify the sameapplication and endpoint names. We’ll also instruct the publisher to send 1000 messages; this will give ussufficient time to look at the metrics.
./ftlpub -a App1 -e endpoint-1 -c 1000
10.3 Examine the Metrics
In the open web browser (which should still be on the Realm Properties page as shown in Figure 10.2), thestatus area should show two active clients. Click anywhere in the status area to expose the StatusDashboard:
TIBCO FTL R� Programming Tutorial
81
Figure 10.3: Status Dashboard
Click the “Clients” count:
Figure 10.4: Client Status Display
Click anywhere in the row for the subscriber, with the “Client Label” “tibsub”:
TIBCO FTL R� Programming Tutorial
82
Figure 10.5: Subscriber Details
Metrics are divided into categories. In Figure 10.5, four categories are shown, each corresponding to oneof the links on the right side: “Application”, “Endpoints”, “Queues”, and “Transports”.
Note that these categories will not appear until a heartbeat message containing the client metrics is receivedby the realm server. Since the default client heartbeat interval (as shown in Figure 10.2) is 60 seconds, itmay take that long before the categories are displayed on your screen.
Click the “Application” link to display the application metrics:
TIBCO FTL R� Programming Tutorial
83
Figure 10.6: Subscriber Application metrics
Each metrics category contains one or more rows of metric data. Each row is identified by the context itbelongs to; the context name appears under the “Name” column. A context defines a particular instance ofthe category, and its name is established when the corresponding object is instantiated.
Application metrics pertain to the client application as a whole. Thus it makes sense that there is a singlecontext in the “Application” category. The corresponding context name is exactly the application namepassed to tibRealm_Connect(). As an example, refer back to line 75 of Listing 8.4, page 52.
The metrics provided for applications are:
Dynamic Formats The number of named dynamic formats used by the client program.Process Peak RSS (KB) The peak resident set size of the client program (in KB).Process RSS (KB) The current resident set size of the client program (in KB).Process VM (KB) The current amount of virtual memory used by the client program (in KB).System CPU Time (µsec) The amount of system-level CPU time used by the client program (in
µseconds).User CPU Time (µsec) The amount of user-level CPU time used by the client program (in µseconds).
To continue, click the “Endpoints” link on the right side of the screen.
TIBCO FTL R� Programming Tutorial
84
Figure 10.7: Subscriber Endpoint metrics
Each row in the “Endpoints” category corresponds to an endpoint instantiated by a call totib_PublisherCreate() or tib_SubscriberCreate(), and the corresponding name is the endpointname specified in the call. Refer back to line 77 of Listing 8.4, page 52 (for tib_PublisherCreate()),and line 183 of Listing 8.8, page 54 (for tib_SubscriberCreate()) for examples.
The metrics provided for endpoints include:
Msgs Recvd Inbound data messages received through the endpoint.Msgs Sent Outbound data messages sent through the endpoint.Store Mismatch Msgs The number of message flows that result from a store mismatch. This deals with
persistence and is discussed in a later lesson.
Immediately below the “Endpoints” category is the “Queues” category. Each row corresponds to an eventqueue instantiated by a call to tibEventQueue_Create(). Unlike other objects, event queues are namedvia properties; if no properties are passed to tibEventQueue_Create(), the FTL library assigns a name.
Two metrics are provided for event queues:
Queue Backlog The maximum number of messages in the event queue during the Client SamplingInterval. Recall from Section 10.1, the Client Sampling Interval is a realm propertywhich controls how often the client program gathers its metrics into a timestampedsamples. After the metrics are gathered, the Queue Backlog is reset; thus the metricreflects the highest value over the interval.
Queue Discards Number of inbound messages discarded by the event queue.
To continue, click the “Transports” shortcut:
TIBCO FTL R� Programming Tutorial
85
Figure 10.8: Subscriber Transport metrics
Each row in the “Transports” category corresponds to a transport associated with an endpoint used by theclient program.
Four metrics are provided for transports:
Bytes Recvd Inbound data bytes received on the transport.Bytes Sent Outbound data bytes sent on the transport.Data Lost Number of inbound data loss events on the transport. This does not reflect the
number of bytes or messages lost, only the number of discrete loss events.Format Unavailable The number of messages with an unrecognized format received on the transport.
It is important to note that messages sent or received are endpoint metrics, while bytes sent or received aretransport metrics. In addition, even though this is a subscriber, the transport shows non-zero bytes sent.This reflects the data exchange which is part of the initial setup traffic between the publisher and subscriber.
Scroll the details window so that both the endpoint and transport metrics are visible. Your screen shouldlook something like:
TIBCO FTL R� Programming Tutorial
86
Figure 10.9: Subscriber Endpoint and Transport metrics
Note the number of messages and bytes received. In Figure 10.9, 117 messages and 10705 bytes werereceived. The numbers on your screen will likely be different.
We can approximate the number of bytes per message received:
bytesmessage
=10705
117⇡ 91.495
Since metrics arrive at the realm server as part heartbeat messages from the client program, and the defaultclient heartbeat interval is 60 seconds, wait a minute or two for additional metrics to arrive. The metricsrefresh automatically approximately every five seconds, so you won’t have to do anything to see newmetrics as they arrive.
TIBCO FTL R� Programming Tutorial
87
Figure 10.10: Subscriber Endpoint and Transport metrics after two minutes
In Figure 10.10, we now have 237 messages and 21505 bytes received. This works out to:
bytesmessage
=21505
237⇡ 90.738
As there is some initial overhead in the form of connection setup between the publisher and subscriber, thenumber of bytes received will never be an exact multiple of the number of messages received. However,over time the ratio will converge to about 90 bytes per message.
Now, let’s look at the publisher metrics. Click anywhere in the row for the publisher, with the “ClientLabel” “tibsub”:
TIBCO FTL R� Programming Tutorial
88
Figure 10.11: Publisher Details
Regardless of the role of the client program, the metrics available are essentially the same. One majordifference in Figure 10.11 is the absence of a “Queues” shortcut on the right side. The publisher did notcreate an event queue: therefore no event queue metrics are generated.
Click the “Application” shortcut:
Figure 10.12: Application metrics
TIBCO FTL R� Programming Tutorial
89
The application metrics provided are the same as those provided for the subscriber client program.
Click the “Transports” shortcut:
Figure 10.13: Publisher Endpoint and Transport metrics
The endpoint and transport metrics provided are again the same as those provided for the subscriber clientprogram.
Based on Figure 10.13, we can calculate the bytes per message sent:
bytesmessage
=27265
301⇡ 90.581
Wait a few minutes for additional samples to arrive:
TIBCO FTL R� Programming Tutorial
90
Figure 10.14: Publisher Endpoint and Transport metrics after two minutes
bytesmessage
=37975
420⇡ 90.416
As we saw for the subscriber, the bytes per message sent is converging to approximately 90.
TIBCO FTL R� Programming Tutorial