The IoT Java SDK can be included in IoT Java applications running on an edge device like gateways, points of sale, car infotainment centers. This getting started will show you how to install the Java SDK and instrument your IoT application.
Follow the steps below to get your EUM App Key and instrument your IoT C/C++ apps.
This Java SDK differs from the AppDynamics Java Agent in that it is a very lightweight library specially designed for lower-end devices. A lot of flexibility is also built into the way event information can be extended and the instrumentation code configured as well as controlled.
Check the Requirements
Before you get started, make sure you meet the following requirements:
A device running one of the following version of Java Runtime:
Java SE 7
Java SE Embedded 7
Java SE 8
Java SE Embedded 8
- HTTPS interface to send beacons to the EUM Server
- EUM App Key
- EUM Collector URL (only for on-prem deployments)
Get the IoT Java SDK
If you're using the IntelliJ IDE, add the file
lib/appd-iot-sdk.jar to your project by following the instructions given in Working with module dependencies. Confirm that the JAR file shows up under External Projects in your IntelliJ project.
Upgrade the IoT Java SDK
From the root directory of your clone of the IoT Java SDK from GitHub:
- Update the repository:
$ git pull origin master
- Follow the instructions given in Build the SDK to rebuild the IoT Java SDK.
Add the SDK Dependencies to the Gradle Configuration
Add the following to your
Add the Instrumentation Code
Import the IoT SDK
In your application file, add the
import statement that includes the Java IoT SDK:
Configure the IoT Java Agent
Configure the instrumentation by providing the EUM App Key and the URL to the EUM Collector. If the EUM Collector URL is not specified, the default SaaS Collector URL is used.
Set Device Info
You are required to set the name and ID for devices. The name should consist of a short string that identifies the type and model of the device, such as "EV Model 3" or "Thermostat Model Star7". The device ID must be a unique identifier for the device, such as a UUID, the VIN number of a car, or the MAC address of the device.
The example code below sets the device ID to a random UUID and the name to "Smart Shelf".
Set Version Info
You can set the versions for the firmware, hardware, OS, and software as shown below.
Initialize the Agent
To initialize the agent, pass the
AgentConfiguration object, the
DeviceInfo object, and the
VersionInfo object to the
Build and Run the Application
Use your favorite Java IDE or CLI environment to build and run the application. Note that the AppDynamics IoT Java SDK needs to be the in build and runtime classpath.
For instructions on adding libraries to the classpath:
For instructions to build and run the app:
- IntelliJ: Building and Running the Application
- Eclipse: Running your programs
- Gradle: Building Java Projects with Gradle
Add and Send Events
The following sections will show you how to create and send the supported events: Custom, Network Request, and Error.
Create a Basic Custom Event
A Custom event can be used to report any performance, device, or business logic data. It is the most general, configurable and flexible data type available.
The Custom event builder takes two required parameters.
- Event Type: A short human-readable description of the event, such as "FL Pressure Drop".
- Description: A string describing the event, such as "Front Left Tire Pressure Drop".
To make reporting this event meaningful, it is recommended that you provide a timestamp and at least one kind of datatype.
Create a basic custom event.
Additional information can be added to the
CustomEvent. For details, see the
CustomEventclass in the latest Java IoT SDK documentation.
Add the custom event to the instrumentation (this adds it to the in-memory buffer).
Send all the events to the EUM Server. This is a blocking call, so the application can send it on a separate thread as shown above.
Send a Network Event
Report a Network Request Event using the
HttpRequestTrackerclass. This call automatically adds an event to the in-memory buffer, so you need to explicitly import the class.
Send all the events to the EUM Server. This is a blocking call. The application can send it on a separate thread. The recommendation is to batch a number of events together before calling the
Send an Error Event
Report an Error Event using the API.
Send all the events to the EUM Server. This is a blocking call. The application can send it on a separate thread.
Verify the Instrumentation in the Controller UI
See Confirm the IoT Application Reported Data to the Controller to verify the instrumentation.
Correlate Business Transactions with Network Requests (Optional)
To correlate business transactions (BTs) with network requests, you need to have instrumented 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.
Make a network request that includes the AppDynamics HTTP request headers
ADRUM_1to one of your business applications:
The call will return response headers that contain information for correlating business transaction. If you were to print these BT response headers, you would see something like the following:
Send a beacon containing the BT response headers to the EUM Server:
In the Controller UI, you should be able to view the correlated business transaction in the Device Details dialog.
Enable Logging for the SDK (Optional)
The IoT Java SDK uses the Simple Logging Facade for Java (SLF4J) as the logging framework. You can use your favorite logging engine that is compatible with SLF4J.
If no binding is found on the classpath, then SLF4J will default to a no-operation implementation and display console messages like the following:
To use the
java.util.logging engine, add the following line to the
To see all the debug messages from the library, append the following line to the bottom of the file
Customize the IoT Java Instrumentation (Optional)
You can further customize the IoT Java instrumentation using the IoT Java SDK. See the latest IoT Java SDK documentation or the previous versions listed below:
Run the Sample Java Application
The sample Java 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.
Troubleshooting the IoT Java SDK
This section provides instructions for debugging common issues.
Unable to Link the IoT Java Agent
If you are getting the following error when trying to link the IoT Java Agent, it's because of a dependency on
To correct the problem, you need to remove the dependency that you added to enable logging. Thus, remove the line specifying the group
org.slf4j shown below from