IoT C/C++ SDKでのアプリケーションのインストゥルメンテーション

IoT C++ SDK は、産業用またはホームゲートウェイ、POS、スマート TV、または車のインフォテインメント システムなど、接続されたデバイス上で実行されている C++ アプリケーションをインストゥルメント化する API を提供します。ここでは、C++ SDK をインストールし、IoT アプリケーションをインストゥルメント化する方法について説明します。

EUM アプリケーションキーを取得し、IoT C/C++ アプリケーションをインストゥルメント化するには、次の手順を実行します。

注: ANSI-C アプリケーションがある場合、またはプラットフォームが Linux x86 でない場合は、カスタマーサポートにお問い合わせください。

C/C++ SDK について

C++ SDK の次のことを知っている必要があります。

  • アプリケーションスレッド内で動作し、新しいスレッドを生成しません。
  • すべてのイベントデータをメモリに保持し、ディスクには保持しません。
  • ネットワーク インターフェイスに登録する API を提供します。
  • アプリケーションの HTTPS スタックを使用して EUM サーバと通信します。
  • SDK ログメッセージを取得する API を提供します。アプリケーション開発者は、ログメッセージを stderr またはログファイルに書き込むことによってログを管理する必要があります。
  • 静的にリンクされているオープンソースの json-c ライブラリを使用します。
  • スレッドセーフではない同期ブロック API コールを発信します。スレッドセーフコールはアプリケーション開発者が発信します。

要件の確認

開始する前に、次の要件を満たしていることを確認します。

  • 32/64 ビットアーキテクチャ用の GNU C++ コンパイラ(g++)バージョン 4.2
  • glibc 2.20 以降をベースとする Linux ディストリビューション
  • ビーコンを EUM クラウドに送信するための HTTPS スタック
  • EUM アプリケーションキー

IoT C++ SDK の取得

C++ SDK は、GitHub から IoT C++ SDK を複製またはダウンロードすることによって取得できます。「Installation」に記載されている手順に従って、IoT C++ SDK をビルドします。

IoT C++ SDK のアップグレード

GitHub にある IoT C++ SDK のクローンのルートディレクトリで、次のようにします。

  • 次のリポジトリを更新します。$ git pull origin master
  • Installation」に記載されている手順に従って、IoT C++ SDK を再構築します。

アプリケーションへの C++ SDK のインストール

C++ SDK は tar zip ファイルとしてパッケージ化されていて、以下が含まれています。

  • include:C++ SDK で使用するパブリック API のヘッダーが格納されているディレクトリ
  • lib:C++ SDK の共有オブジェクトファイルが格納されているディレクトリ

SDK ヘッダーの追加

SDK ヘッダーファイルが含まれている include ディレクトリをアプリケーション ディレクトリにコピーまたは移動し、SDK API にアクセスするためにコードに含めます。

CODE
#include "appd_iot_interface.h"
....
{

Initialize the SDK

You must initialize the C++ SDK by providing the SDK and device configuration as input parameters and then calling the function appd_iot_init_sdk as shown below. The SDK configuration takes in parameters for the app key, log level, and the EUM Collector URL. The SDK uses the EUM Collector URL to send data to the EUM Server. The device configuration contains information to identify a unique device.

注: See Splunk AppDynamics SaaS Domains and IP Ranges for EUM Collector URLs in each geographic region. If the EUM Collector URL is not specified, the default SaaS Collector URL is used.
CODE
#include "appd_iot_interface.h"
....
{
// Declare config variables for the SDK and device.
appd_iot_sdk_config_t sdkcfg;
appd_iot_device_config_t devcfg;
appd_iot_init_to_zero(&sdkcfg, sizeof(sdkcfg));
appd_iot_init_to_zero(&devcfg, sizeof(devcfg));
// Set the initialization configurations for the SDK
sdkcfg.appkey = "<EUM_APP_KEY>";
// Set the device configurations
devcfg.device_id = "1111";
devcfg.device_type = "SmartCar";
devcfg.device_name = "AudiS3";
// Initialize the instrumentation
appd_iot_init_sdk(sdkcfg, devcfg);
}

ネットワーク インターフェイスの登録

SDK には、EUM サーバにイベントを送信するための HTTPS インターフェイスが必要です。アプリケーション開発者は、SDK が HTTPS リクエストを実行するためのコールバック関数を指定する必要があります。libcurl を使用するネットワーク インターフェイスの実装例については、「サンプルアプリケーションの実行」を参照してください。

JAVASCRIPT
#include "appd_iot_interface.h"
....
{
appd_iot_http_cb_t http_cb;
//Callback function triggered by SDK to send http request and receive http response
http_cb.http_req_send_cb = &your_network_interface_send_cb;
//Callback function triggered by SDK to indicate completion of http response processing
http_cb.http_resp_done_cb = &your_network_interface_resp_done_cb;
//register http interface callbacks
appd_iot_register_network_interface(http_cb);
...
}

イベントの追加と送信

さまざまなタイプのイベントを理解するために、 以下のセクションに示すスマートカー IoT アプリケーションの例を使用します。

カスタム イベント

「SmartCar」の技術的な統計情報をキャプチャするカスタムイベント。

CODE
#include "appd_iot_interface.h"
....
{
appd_iot_custom_event_t custom_event;
appd_iot_init_to_zero(&custom_event, sizeof(custom_event));
custom_event.type = "SmartCar Stats";
custom_event.summary = "Technical Stats of SmartCar";
custom_event.timestamp_ms = ((int64_t)time(NULL) * 1000);
custom_event.data = (appd_iot_data_t*)calloc(2, sizeof(appd_iot_data_t));
appd_iot_data_set_integer(&custom_event.data[0], "Speed mph", 65);
appd_iot_data_set_double(&custom_event.data[1], "Oil Temperature", 220);
appd_iot_add_custom_event(custom_event);
free(custom_event.data);
....
appd_iot_send_all_events();
}

ネットワーク リクエスト イベント

HTTPS コールのパフォーマンスをキャプチャして天気情報を取得するネットワーク リクエスト イベント。

JSON
#include "appd_iot_interface.h"
....
{
appd_iot_network_request_event_t network_event;
appd_iot_init_to_zero(&network_event, sizeof(network_event));
network_event.url = "https://apdy.api/weather";
network_event.resp_code = 202;
network_event.duration_ms = 10;
network_event.req_content_length = 300;
network_event.req_content_length = 100;
network_event.timestamp_ms = ((int64_t)time(NULL) * 1000);
network_event.data = (appd_iot_data_t*)calloc(1, sizeof(appd_iot_data_t));
appd_iot_data_set_string(&network_event.data[0], "city", "San Francisco");
appd_iot_add_network_request_event(network_event);
free(network_event.data);
....
appd_iot_send_all_events();
}

error イベント

次のエラーイベントは、SmartCar アプリケーションで Bluetooth エラーをキャプチャするために使用されます。

CODE
#include "appd_iot_interface.h"
....
{
appd_iot_error_event_t error_event;
appd_iot_init_to_zero(&error_event, sizeof(error_event));
error_event.name = "Bluetooth Connection Error";
error_event.message = "connection dropped due to bluetooth exception";
error_event.severity = APPD_IOT_ERR_SEVERITY_CRITICAL;
error_event.timestamp_ms = ((int64_t)time(NULL) * 1000);
error_event.data = (appd_iot_data_t*)calloc(1, sizeof(appd_iot_data_t));
appd_iot_data_set_integer(&error_event.data[0], "Bluetooth Error Code", 43);
appd_iot_add_error_event(error_event);
free(error_event.data);
....
appd_iot_send_all_events();
}

ビジネストランザクションをネットワークリクエストと関連付ける(オプション)

ビジネストランザクション(BT)をネットワークリクエストと関連付けるには、ビジネスアプリケーションをインストゥルメント化し、コントローラ UI でビジネストランザクションを有効にしておく必要があります。IoT モニタリング用のビジネストランザクションの相関 IoT モニタリング用のビジネストランザクションの相関

次の手順では、BT 応答ヘッダーを取得し、それらを使用して、その BT を IoT ネットワーク リクエスト イベントと関連付ける方法について説明します。

  1. Splunk AppDynamics HTTP ヘッダー ADRUMADRUM_1 をビジネスアプリケーションに対するネットワークリクエストの一部として設定します。
    JAVASCRIPT
    /* Initialize all the data structures for the request and response. */
    appd_iot_http_req_t http_req;
    appd_iot_http_req_t http_resp;
    /* Initialize the request and response. */
    appd_iot_init_to_zero(&http_req, sizeof(http_req));
    appd_iot_init_to_zero(&http_resp, sizeof(http_resp));
    /* Provide the URL to your instrumented business app that is enabled for business transaction correlation. */
    http_req.url = "<url-to-your-business-app-enabled-for-bt>";
    /* Add your other HTTP request parameters here:
    ...
    */
    /* Call the SDK method to get the headers for ADRUM and ADRUM_1. */
    const appd_iot_data_t* correlation_headers = appd_iot_get_server_correlation_headers();
    for (size_t i = 0; i < APPD_IOT_NUM_SERVER_CORRELATION_HEADERS; i++)
    {
    appd_iot_data_set_string(&http_req.headers[i], correlation_headers[i].key, correlation_headers[i].strval);
    }
    /* Make the request, and assign the response to a variable. */
    http_resp = http_curl_req_send_cb(&http_req);
  2. コールは、ビジネストランザクションを関連付けるための情報を含む応答ヘッダー(つまり、)を返します。これらの BT 応答ヘッダーを出力する場合は、次のように表示されます。
    CODE
    ADRUM_0: clientRequestGUID:0f5c7602-9b69-4e40-85a6-e0abf288accf
    ADRUM_1: globalAccountName:eum-mobile_4debdbad-3f8e-4f6d-8faf-e5f5781ec0d7
    ADRUM_2: btId:3867
    ADRUM_3: serverSnapshotType:f
    ADRUM_4: btDuration:829
  3. EUM サーバに送信するネットワークイベントに、次の BT 応答ヘッダーを追加します。
    PYTHON
    /* Create a network event to report to the EUM Server. */
    appd_iot_network_request_event_t network_event;
    appd_iot_init_to_zero(&network_event, sizeof(appd_iot_network_request_event_t));
    /* Add information about the network event that you want to report. */
    network_event.url = "<url-to-your-business-app-enabled-for-bts>";
    network_event.resp_code = http_resp->resp_code;
    /* Assign the returned BT response headers from the call to the business app to the headers of the request. */
    network_event.resp_headers = http_resp->headers;
    // Add the network event to beacon to send to the EUM Server. */
    appd_iot_add_network_request_event(network_event);
    appd_iot_send_all_events();
  4. コントローラ UI では、関連するビジネストランザクションを [] ダイアログで確認できます。

SDK ライブラリファイルを使用したアプリケーションのコンパイルおよび実行

  1. プログラムをコンパイルします。たとえば、ドライバファイルが main.cpp の場合は、次のようにします。
    CODE
    $ g++ -c main.cpp -I<appd_iot_sdk_dir>/include
  2. アプリケーションのオブジェクトコードを使用し、Splunk AppDynamics IoT C++ SDK ライブラリをリンクするバイナリを作成します。
    Linux
    CODE
    $ g++ main.o <appd_iot_sdk_dir>/lib/libappdynamics_iot.so -o main
    手順 1 と 2 を次の 1 つの手順に組み合わせることができます。
    Mac
    CODE
    $ g++ main.o <appd_iot_sdk_dir>/lib/libappdynamics_iot.dylib -o main
    手順 1 と 2 を次の 1 つの手順に組み合わせることができます。
    CODE
    $ g++ main.cpp -o main -I<appd_iot_cpp_sdk_dir>/include -L<appd_iot_cpp_sdk_dir>/lib -lappdynamics_iot
  3. 環境変数 DYLD_LIBRARY_PATH を SDK ライブラリがインストールされている PATH に設定します。これにより、ダイナミックリンカーは共有ライブラリを検索するディレクトリを認識できるようになります。
    Linux
    CODE
    $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<appd_iot_cpp_sdk_dir>/lib
    Mac
    CODE
    $ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:<appd_iot_cpp_sdk_dir>/lib
  4. プログラムを実行します。例:
    CODE
    $ ./main

IoT C++ インストゥルメンテーションのカスタマイズ(オプション)

 IoT C++ SDK を使用して、IoT C++ インストゥルメンテーションをさらにカスタマイズできます。最新の IoT C++ SDK ドキュメント、または以下に記載されている以前のバージョンを参照してください。

サンプル C++ アプリケーションの実行

サンプル C++ アプリケーションは、カスタム、ネットワークリクエスト、およびエラーイベントのサンプルデータを送信します。データは、スマート カー アプリケーションをモックし、使用状況情報、ネットワークパフォーマンス、およびエラーをキャプチャします。

サンプルアプリケーションを実行するには、「Sample Application using IoT C++ SDK」に記載されている手順に従います。