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

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

ANSI-C アプリケーションがある場合、またはプラットフォームが Linux x86 でない場合は、AppDynamics のアカウント担当者にお問い合わせください。

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"   
  ....
{
CPP

SDK の初期化

次に示すように、SDK とデバイスの構成を入力パラメータとして指定し、関数 appd_iot_init_sdk を呼び出すことにより、C++ SDK を初期化する必要があります。SDK の構成は、アプリケーションキー、ログレベル、および EUM コレクタ URL のパラメータを取得します。SDK は EUM コレクタ URL を使用して EUM サーバにデータを送信します。デバイス構成には、一意のデバイスを識別するための情報が含まれています。

各地域の EUM コレクタ URL については、「Cisco AppDynamics SaaS Domains and IP Ranges」を参照してください。EUM コレクタ URL が指定されていない場合は、デフォルトの SaaS コレクタ URL が使用されます。

#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);
}
CPP

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

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);

  ...
}
CPP

イベントの追加と送信

さまざまなタイプのイベントを理解するために、 以下のセクションに示すスマートカー 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();
}
CPP

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

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();
}
CPP

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();
}
CPP

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

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

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

  1. AppDynamics HTTP ヘッダー ADRUM と ADRUM_1 をビジネスアプリケーションに対するネットワークリクエストの一部として設定します。

    /* 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);
    CPP

  2. コールは、ビジネストランザクションを関連付けるための情報を含む応答ヘッダー（つまり、 ADRUM_*）を返します。これらの BT 応答ヘッダーを出力する場合は、次のように表示されます。

    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
    CPP

  3. EUM サーバに送信するネットワークイベントに、次の BT 応答ヘッダーを追加します。

    /* 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();
    CPP

  4. コントローラ UI では、関連するビジネストランザクションを [Device Details] ダイアログで確認できます。 

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

  1. プログラムをコンパイルします。ドライバファイルが次の場合の例を次に示します。main.cpp:

    $ g++ -c main.cpp -I<appd_iot_sdk_dir>/include
    BASH

  2. アプリケーションのオブジェクトコードを使用し、AppDynamics IoT C++ SDK ライブラリをリンクするバイナリを作成します。

    $ g++ main.o <appd_iot_sdk_dir>/lib/libappdynamics_iot.so -o main
    BASH 
    $ g++ main.o <appd_iot_sdk_dir>/lib/libappdynamics_iot.dylib -o main
    BASH


    手順 1 と 2 を次の 1 つの手順に組み合わせることができます。

    $ g++ main.cpp -o main -I<appd_iot_cpp_sdk_dir>/include -L<appd_iot_cpp_sdk_dir>/lib -lappdynamics_iot
    BASH

  3. 環境変数 DYLD_LIBRARY_PATH を SDK ライブラリがインストールされている PATH に設定します。これにより、ダイナミックリンカーは共有ライブラリを検索するディレクトリを認識できるようになります。

    $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<appd_iot_cpp_sdk_dir>/lib
    BASH 
    $ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:<appd_iot_cpp_sdk_dir>/lib
    BASH

  4. プログラムを実行します。例： 

    $ ./main
    BASH

コントローラ UI でのインストゥルメンテーションの確認

「IoT アプリケーションがコントローラにデータをレポートしたことの確認」を参照してインストゥルメンテーションを確認します。 

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

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

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

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

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