AppDynamics IoT Device API

Base URL: /eumcollector/iot/v1, Version: 4.5.2

API for IoT devices to communicate with AppDynamics

Schemes: https

Summary

Path	Operation	Description
/application/{appKey}/beacons	POST	Post beacons
/application/{appKey}/enabled	GET	Check if AppKey is enabled
/application/{appKey}/validate-beacons	POST	Validate beacons

Paths

Post beacons

POST /application/{appKey}/beacons

Post beacons from your IoT device to this endpoint. This accepts Content-Encoding gzip and identity. If Content-Encoding header is not specified, identity is assumed.

application/json

The beacons for all devices being reported. A single beacon can hold upto 200 events of each event type (CustomEvent, NetworkRequestEvent, and ErrorEvent). Often you will have only one beacon if your IoT device can directly transmit to the AppDynamics endpoint. You would have multiple beacons if you have more than 200 events of an event type from a single device, or more than one device sending beacons via an intermediate hub.

Beacon


appKey	Application Key for your AppDynamics App	path	string

202 Accepted: Beacons queued for ingestion. This does not mean that the beacon is valid.
400 Bad Request: The request was malformed. Likely due to an invalid Content-Encoding.
402 Payment Required: The IoT license associated with this app key is expired
403 Forbidden: This application is disabled or non-existent, this agent should stop sending beacons. Your IoT device may want to check the endpoint periodically, since you may have re-enabled the application through your AppDynamics Controller
429 Too Many Requests: This application is over its license limit, stop sending beacons until the next calendar month.

Check if AppKey is enabled

GET /application/{appKey}/enabled

Checks if the supplied AppKey is valid and enabled. This can be used by apps after being disabled to easily check if the agent should get re-enabled.

application/json


appKey	Application Key for your AppDynamics App	path	string

200 OK: App key is enabled
403 Forbidden: This application is disabled or non-existent, you should stop sending beacons.

Validate beacons

POST /application/{appKey}/validate-beacons

Post beacons for validation. These beacons do not get ingested. This endpoint should be used only for debug purposes during development.

application/json

The beacons to validate

Beacon


appKey	Application Key for your AppDynamics App	path	string

200 OK: Beacons are valid
400 Bad Request: The request was malformed and could not be read. This could be from an invalid encoding or unreadable json. The reason will be in the response body.

ValidationError
402 Payment Required: The IoT license associated with this app key is expired
403 Forbidden: This application is disabled or non-existent, you should stop sending beacons.
422 Unprocessable Entity: One or more beacons are invalid

ValidationError
429 Too Many Requests: This endpoint is rate limited. You can call it at least once per minute per app key, but any more and you may get this response code.

Schema definitions

Beacon: object

All of the event data from one device. At least one event should be populated in one of the event arrays, if all of those arrays are empty, this beacon is meaningless.

deviceInfo: DeviceInfo
versionInfo: VersionInfo
customEvents: object[]: The custom events from this device.

CustomEvent
networkRequestEvents: object[]: The network request events from this device.

NetworkRequestEvent
errorEvents: object[]: The error events from this device.

ErrorEvent

CustomEvent:

An event that doesn't fit into the other event definitions. All of the analytics tools will still be available, but some widgets will not be automatically generated for these events. In addition to the 'timestamp' property, you must specify the 'eventType' property, which describes the type of this event for the 'deviceType', and the 'eventSummary' property, which is a human readable summary of the event.

Event

eventType: string (1 to 24 chars): The type of this event. Cannot contain the pipe character '|'. Valid Examples: "Temperature Reading", "Motion Detected",
eventSummary: string (1 to 64 chars): The summary of this event. Appears in the Activity stream. Should be human readable and informative to someone reading through events looking for a specific one. Valid Examples: "Door closed", "Light turned on", "Switch to gear 4"

object

DeviceInfo: object

deviceName: string (up to 80 chars): Human readable name of the device. This is not required and does not need to be unique. Valid Examples: "Thermostat in room 1302", "Vehicle 1532312"
deviceType: string (1 to 24 chars): Type of the device. Cannot contain the pipe character '|'. Valid Examples: "Thermostat", "Wind Turbine", "Camera"
deviceId: string (1 to 128 chars): Unique ID for this device. Valid Examples: "1877837d-66a9-4bfb-b6e8-6dd4ac62ea38", "CA 5UMH719"

ErrorEvent:

An error event. Use this event to report errors and issues that you want to monitor. The only required fields are 'timestamp' and 'name'. AppDynamics will group errors based on many heuristics, but if you only include the minimum of 'name', then that is all that we can group on. Providing more information allows AppDynamics to group more intelligently.

Event

name: string (1 to 64 chars): The name of the error. This should be a short human readable name. Valid Examples: "SIGINT", "NullPointerException"
message: string (1 to 2048 chars): A longer description of the error. Valid Examples: "Tried to call open() before socket was initialized", "Max heap memory exceeded"
stackTraces: object[] (up to 32 chars): The StackTraces at the time of this error. The StackTrace that contained the error is the most important one, so be sure to populate errorStackTraceIndex if you include multiple StackTraces.

StackTrace
errorStackTraceIndex: integer , { x ∈ ℤ | x ≥ 0 }: The index into the stackTraces array that caused the error. This is not required, but if there is more than one stackTrace, then it is highly recommended. If empty, the default is 0. If outside of the range of the stackTraces array, it is defaulted to 0.
severity: string , x ∈ { alert , critical , fatal }: The severity of the error. "alert" means that there was an error that didn't cause any issues. "critical" means that there was an error that caused issues. "fatal" means that there was an error that killed your app. The default is "critical"

object

Event: object

The base definition that all event objects inherit from. This includes a timestamp, duration, and some additional typed property maps.

timestamp: integer (int64): The start time of this event in milliseconds epoch time.
duration: integer (int64) , { x ∈ ℤ | x ≥ 0 }: The duration of this event in milliseconds. If unpopulated, the duration is assumed to be 0.
stringProperties: object: A map of the string properties of this event. There cannot be more than 16 string properties per event. Entry keys have a max length of 24 characters. Entry values have a max length of 128 characters. Entry keys cannot contain the pipe character '|'. Valid Examples: { "username": "john.doe" }
longProperties: object: A map of the long properties of this event. There cannot be more than 16 long properties per event. Entry keys have a max length of 24 characters. Entry keys cannot contain the pipe character '|'. Valid Examples: { "buttonId": 123 }
booleanProperties: object: A map of the boolean properties of this event. There cannot be more than 16 boolean properties per event. Entry keys have a max length of 24 characters. Entry keys cannot contain the pipe character '|'. Valid Examples: { "error": false }
doubleProperties: object: A map of the double properties of this event. There cannot be more than 16 double properties per event. Entry keys have a max length of 24 characters. Entry keys cannot contain the pipe character '|'. Valid Examples: { "Fahrenheit": 98.2 }
datetimeProperties: object: A map of the datetime properties of this event, in millisecond epoch time. There cannot be more than 16 datetime properties per event. Entry keys have a max length of 24 characters. Entry keys cannot contain the pipe character '|'. Valid Examples: { "bootTime": 1487119625012 }

object

NetworkRequestEvent:

A network request event. Should always populate timestamp, duration, url, and either networkError or statusCode. Other fields are included for ease of use.

Event

url: string (1 to 2048 chars): The URL of the request. Must be a valid URL. Valid Example: "http://www.appdynamics.com"
statusCode: integer: The HTTP response status code returned. Should be defined if the 'networkError' is not defined. Valid Example: 200
networkError: string (1 to 1024 chars): If a network error occured (such as socket timeout), which caused the network request to fail without response/status. Valid Example: "Connection Interrupted", "ERR_NAME_NOT_RESOLVED"
requestContentLength: integer (int64) , { x ∈ ℤ | x ≥ 0 }: The length in bytes of the http request body. Valid Example: 5432
responseContentLength: integer (int64) , { x ∈ ℤ | x ≥ 0 }: The length in bytes of the http response body. Valid Example: 6123
responseHeaders: object: HTTP response headers provided as a list of {"key": ["values"]} pairs. To enable BT correlation, add the headers {"ADRUM": "isAjax:true"} and {"ADRUM_1": "isMobile:true"} to your HTTP request. Attach all the response headers which will include BT headers in case your backend application is instrumented with AppDynamics APM Agent.

object

StackFrame: object

A platform agnostic view of a single stack frame. It is likely that you will not be able to populate all of the fields here.

symbolName: string (up to 128 chars): The symbol of the frame. For C, this is the method name. For Java, this is the class name and method name. Valid Examples: "malloc()", "Utils.openFile()", "[Application load]"
packageName: string (up to 256 chars): The package that contains the symbol. For C, this is the library or executable. For Java, this is the package of the class. Valid Examples: "CoreFoundation", "com.my.app", "libFoo.so"
filePath: string (up to 4096 chars): The path to the file that contains the symbol. Can be just the file name Valid Examples: "Main.java", "Util.c", "/home/code/myproject/src/foo.c"
lineNumber: integer: The line number of the code in the symbol. Valid Examples: 42, 138
absoluteAddress: integer (int64): The absolute address of the instruction.
imageOffset: integer (int64): The offset of the instruction from the start of the image
symbolOffset: integer (int64): The offset of the instruction from the start of the symbol

StackTrace: object

A set of stack frames

thread: string (1 to 32 chars): The name of the thread that this stack trace was on. Examples: "0", "Main-1", "UI", "Network Processor"
runtime: string , x ∈ { native , java , python , javascript , .net , node.js }: The runtime of the stack trace. This is purely used to format the UI nicely. By default this is "native", so no need to populate it if you are happy with that format.
stackFrames: object[]: All of the stack frames in this stack trace.

StackFrame

ValidationError: object

message: string[]: A human readable description of the validation error.

string

VersionInfo: object

hardwareVersion: string (1 to 80 chars): The hardware version of this device. Valid Example: "Board Rev. 13A"
firmwareVersion: string (1 to 80 chars): The firmware version of this device. Valid Example: "123.5.31"
softwareVersion: string (1 to 80 chars): The software version of the embedded application being monitored. Valid Example: "9.1.3"
operatingSystemVersion: string (1 to 80 chars): The operating system version of this device. Valid Example: "Linux 13.4"