TIBCO FTL R Programming Tutorial Software Release 5.3 October 2017

Transcription

1 TIBCO FTL R Programming Tutorial Software Release 5.3 October 2017

2 1 Contents Introduction i 1 Getting Started with FTL Programming Set Up the Environment Start the Local Realm Server Build the Samples Run the Samples Understanding the Code ftlbasicpub.c ftlbasicsub.c Error Handling Running Without the Realm Server Adding Error Handling Understanding the Error Handling Code and Output Restart the Realm Server Working With Exceptions Messages and Fields FTL Field Types FTL API Functions to Set Field Values in a Message FTL API Functions to Get Field Values from a Message Working with Messages Introduction to Content Matchers Matcher Specification ftlbasicpub.c ftlbasicsub.c Build and Run the Samples Some Variations Exploring the Realm The Realm Server Web Interface The Realm Server Web API Defining an Application The Process Defining an Application Using the Realm Server Web Interface Defining an Application Using the Realm Server Web API... 45

3 78 Lesson 10: Client Metrics The realm server web interface makes available metrics as reported by each client program. In this lesson we ll look at some of the metrics available. Before looking at the metrics, a basic understanding of the communication between a client and the realm server is needed Client-Realm Server Communication The connection between a client program and the realm server is established by the tibrealm_connect() call. Once connected, basic identifying information is exchanged, and the realm server sends the realm definition to the client program. Next the client program sends a HELLO message to the realm server, containing additional identifying information. At this point the client program information 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 client program. 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, which causes the realm server to remove that client from its list of clients. The connection to the realm server is then closed. A client program that abnormally terminates (such as via ctrl + C or a fatal error) does not send a GOODBYE message. Instead it is subject to timeouts based on the absence of heartbeat messages before being 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 URL 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.

4 79 Figure 10.1: Applications grid Along the left side of the screen, the link denoted by the icon and labeled Realm Properties displays the Realm Properties page. Click it, resulting in a display similar to Figure 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

5 80 determines how much time can pass without the realm server receiving a heartbeat message from a client before 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 message to all client programs, while Timeout determines how much time can pass without the client receiving a heartbeat 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 program gathers 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 than one sample Run the Samples In order to look at the client metrics, let s run the sample client programs from lesson 9. Open a command window, navigate to the $TIBFTL_TUTDIR/code/lesson-09 directory, and start the subscriber. We ll specify 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 same application and endpoint names. We ll also instruct the publisher to send 1000 messages; this will give us sufficient time to look at the metrics../ftlpub -a App1 -e endpoint-1 -c Examine the Metrics In the open web browser (which should still be on the Realm Properties page as shown in Figure 10.2), the status area should show two active clients. Click anywhere in the status area to expose the Status Dashboard:

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

7 82 Figure 10.5: Subscriber Details Metrics are divided into categories. In Figure 10.5, four categories are shown, each corresponding to one of 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 received by the realm server. Since the default client heartbeat interval (as shown in Figure 10.2) is 60 seconds, it may take that long before the categories are displayed on your screen. Click the Application link to display the application metrics:

8 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 it belongs to; the context name appears under the Name column. A context defines a particular instance of the 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 single context in the Application category. The corresponding context name is exactly the application name passed 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 Process Peak RSS (KB) Process RSS (KB) Process VM (KB) System CPU Time (µsec) User CPU Time (µsec) The number of named dynamic formats used by the client program. The peak resident set size of the client program (in KB). The current resident set size of the client program (in KB). The current amount of virtual memory used by the client program (in KB). The amount of system-level CPU time used by the client program (in µseconds). 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.

9 84 Figure 10.7: Subscriber Endpoint metrics Each row in the Endpoints category corresponds to an endpoint instantiated by a call to tib_publishercreate() or tib_subscribercreate(), and the corresponding name is the endpoint name 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 Msgs Sent Store Mismatch Msgs Inbound data messages received through the endpoint. Outbound data messages sent through the endpoint. 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 event queue instantiated by a call to tibeventqueue_create(). Unlike other objects, event queues are named via properties; if no properties are passed to tibeventqueue_create(), the FTL library assigns a name. Two metrics are provided for event queues: Queue Backlog Queue Discards The maximum number of messages in the event queue during the Client Sampling Interval. Recall from Section 10.1, the Client Sampling Interval is a realm property which controls how often the client program gathers its metrics into a timestamped samples. After the metrics are gathered, the Queue Backlog is reset; thus the metric reflects the highest value over the interval. Number of inbound messages discarded by the event queue. To continue, click the Transports shortcut:

10 85 Figure 10.8: Subscriber Transport metrics Each row in the Transports category corresponds to a transport associated with an endpoint used by the client program. Four metrics are provided for transports: Bytes Recvd Bytes Sent Data Lost Format Unavailable Inbound data bytes received on the transport. Outbound data bytes sent on the transport. 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. 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 are transport 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 should look something like:

11 86 Figure 10.9: Subscriber Endpoint and Transport metrics Note the number of messages and bytes received. In Figure 10.9, 117 messages and bytes were received. The numbers on your screen will likely be different. We can approximate the number of bytes per message received: bytes message = Since metrics arrive at the realm server as part heartbeat messages from the client program, and the default client heartbeat interval is 60 seconds, wait a minute or two for additional metrics to arrive. The metrics refresh automatically approximately every five seconds, so you won t have to do anything to see new metrics as they arrive.

12 87 Figure 10.10: Subscriber Endpoint and Transport metrics after two minutes In Figure 10.10, we now have 237 messages and bytes received. This works out to: bytes message = As there is some initial overhead in the form of connection setup between the publisher and subscriber, the number 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 Client Label tibsub :

13 88 Figure 10.11: Publisher Details Regardless of the role of the client program, the metrics available are essentially the same. One major difference in Figure is the absence of a Queues shortcut on the right side. The publisher did not create an event queue: therefore no event queue metrics are generated. Click the Application shortcut: Figure 10.12: Application metrics

14 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 client program. Based on Figure 10.13, we can calculate the bytes per message sent: Wait a few minutes for additional samples to arrive: bytes message =

15 90 Figure 10.14: Publisher Endpoint and Transport metrics after two minutes bytes message = As we saw for the subscriber, the bytes per message sent is converging to approximately 90.