TIBCO FTL R Programming Tutorial · TIBCO FTL R Programming Tutorial. 88 Figure 10.11: Publisher Details Regardless of the role of the client program, the metrics available are essentially

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.


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”


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:


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”:


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:


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.


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:


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:


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.


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”:


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


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:


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.


Documents

TIBCO FTL R Programming Tutorial · TIBCO FTL R Programming Tutorial. 88 Figure 10.11: Publisher Details Regardless of the role of the client program, the metrics available are essentially