The IoT C++ SDK provides APIs to instrument C++ applications running on connected devices such as industrial or home gateways, points of sale, smart TVs or car infotainment systems. This getting started will show you how to install the C++ SDK and instrument your IoT application.
Follow the steps below to get your EUM App Key and instrument your IoT C/C++ apps.
If you have ANSI-C application or if your platform is not Linux x86, please contact your AppDynamics account representative.
Learn About the C/C++ SDK
You should know that the C++ SDK:
- Operates within the application thread and doesn’t spawn any new threads.
- Keeps all the event data in memory and doesn’t persist on disk.
- Provides an API to register for the network interface.
- Uses application's HTTPS stack to communicate with the EUM Server.
- Provides an API to fetch SDK log messages. Application developers have to manage logs by writing the log messages to
stderror to a log file.
- Uses the open-source json-c library that is statically linked.
- Makes synchronous blocking API calls that are not thread-safe. Application developers are responsible for making thread-safe calls.
Check the Requirements
Before you get started, make sure you meet the following requirements:
- GNU C++ Compiler (g++) version 4.2 for 32/64-bit architectures
- Any Linux distribution based on glibc 2.20+
- HTTPS stack for sending beacons to the EUM Cloud
- EUM App Key
- EUM Collector URL (only for on-prem deployments)
Get the IoT C++ SDK
Upgrade the IoT C++ SDK
From the root directory of your clone of the IoT C++ SDK from GitHub:
- Update the repository:
$ git pull origin master
- Follow the instructions given in Installation to rebuild the IoT C++ SDK.
Install the C++ SDK in Your Application
The C++ SDK is packaged as a tar zip file and contains the following:
include- directory containing headers for the public API for use with the C++ SDK
lib- the directory containing the shared object files for the C++ SDK
Add the SDK Headers
Copy or move the
include directory, which contains the SDK header files into your application directory, and include it in your code to access the SDK APIs.
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.
Register Network Interface
The SDK needs an HTTPS interface to send events to the EUM Server. The application developer has to provide callback functions for the SDK to execute the HTTPS request. Refer to Run the Sample Application for a sample network interface implementation using
Add and Send Events
To understand the different types of events, you will work with the sample smart car IoT application given in the sections below.
Custom event to capture technical stats of a "SmartCar".
Network Request Events
Network Request event to capture the performance of an HTTPS call to get weather information.
The Error event below is used to capture Bluetooth errors in the SmartCar app.
Correlate Business Transactions with Network Requests (Optional)
To correlate business transactions (BTs) with network requests, you need to instrument a business application and enabled business transactions in the Controller UI. See Correlate Business Transactions for IoT Monitoring to learn more.
The steps below show you how to get the BT response headers and use them to correlate the BT with an IoT Network Request event.
Set the AppDynamics HTTP headers
ADRUM_1as part of a network request to your business application.
The call will return response headers (i.e.,
ADRUM_*) that contain information for correlating the business transaction. If you were to print these BT response headers, you would see something like the following:
Add these BT response headers to the network event that you send to the EUM Server:
In the Controller UI, you should be able to view the correlated business transaction in the Device Details dialog.
Compile and Run Your App with the SDK Library File
Compile your program. For example, if the driver file is
Create the binary with the object code of your application and linking AppDynamics IoT C++ SDK library.
You can combine steps 1 and 2 into one step as below:
Set the environment variable
PATHwhere the SDK library is installed. This will let dynamic linker know the directory to search for shared libraries.
Run your program. For example:
Verify the Instrumentation in the Controller UI
See Confirm the IoT Application Reported Data to the Controller to verify the instrumentation.
Customize the IoT C++ Instrumentation (Optional)
You can further customize the IoT C++ instrumentation using the IoT C++ SDK. See the latest IoT C++ SDK documentation or the previous versions listed below:
Run the Sample C++ Application
The sample C++ application sends sample data for Custom, Network Request, and Error events. The data mocks a smart car application, capturing usage information, network performance, and errors.
To run the sample app, follow the instructions given in Sample Application using IoT C++ SDK.