IoT C/C++ SDKでのアプリケーションのインストゥルメンテーション
IoT C++ SDK は、産業用またはホームゲートウェイ、POS、スマート TV、または車のインフォテインメント システムなど、接続されたデバイス上で実行されている C++ アプリケーションをインストゥルメント化する API を提供します。ここでは、C++ SDK をインストールし、IoT アプリケーションをインストゥルメント化する方法について説明します。
EUM アプリケーションキーを取得し、IoT C/C++ アプリケーションをインストゥルメント化するには、次の手順を実行します。
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 にアクセスするためにコードに含めます。
#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.
#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 を使用するネットワーク インターフェイスの実装例については、「サンプルアプリケーションの実行」を参照してください。
#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」の技術的な統計情報をキャプチャするカスタムイベント。
#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 コールのパフォーマンスをキャプチャして天気情報を取得するネットワーク リクエスト イベント。
#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 エラーをキャプチャするために使用されます。
#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 ネットワーク リクエスト イベントと関連付ける方法について説明します。
SDK ライブラリファイルを使用したアプリケーションのコンパイルおよび実行
コントローラ UI でのインストゥルメンテーションの確認
IoT アプリケーションがコントローラにデータをレポートしたことの確認IoT アプリケーションがコントローラにデータをレポートしたことの確認
IoT C++ インストゥルメンテーションのカスタマイズ(オプション)
IoT C++ SDK を使用して、IoT C++ インストゥルメンテーションをさらにカスタマイズできます。最新の IoT C++ SDK ドキュメント、または以下に記載されている以前のバージョンを参照してください。
サンプル C++ アプリケーションの実行
サンプル C++ アプリケーションは、カスタム、ネットワークリクエスト、およびエラーイベントのサンプルデータを送信します。データは、スマート カー アプリケーションをモックし、使用状況情報、ネットワークパフォーマンス、およびエラーをキャプチャします。
サンプルアプリケーションを実行するには、「Sample Application using IoT C++ SDK」に記載されている手順に従います。