Configure the EPAgent RESTful Interface
apmdevops97
You can configure the EPAgent HTTP RESTful interface to submit metrics gathered from your application or environment. The HTTP RESTful Interface can operate in conjunction with your existing EPAgent metric gathering solutions. Including stateful and stateless plugins, network socket listener, and the HTTP method using GET with query parameters.
To enable the REST interface to your EPAgent, configure introscope.epagent.config.httpServerPort in the IntroscopeEPAgent.properties file. The REST interface receives metric data using HTTP POST calls with payloads of metric data in JSON syntax. In addition, the EPAgent REST Interface can process GZIP compressed JSON metric data.
To run the EPAgent RESTful interface, you must first install the CA APM Service Pack 9.7.1 or later.
Contents
2
Types
Metric
{"type" : "<a supported metric type>","name" : "<a unique metric name (including path but excluding host|process|agent)>","value" : "<the metric value>"}}
Valid Metric Data Types
The type attribute of a metric must be one of the following:
PerIntervalCounter
The value is a rate per interval. The metrics are aggregated over time by adding up the values. The sum of values is kept by a counter. At the end of the 15-second interval, the value of the counter is reported. After that, the counter is reset to zero.
Use this data type whenever you need to report on the rate at which something is occurring, like for example “errors per interval”.
IntCounter/LongCounter
Reports the integer or long value sent to the metric, and keeps reporting that value over every subsequent 15-second interval, until a new value is supplied.
This data type can be useful in the context of reporting queue depth, threads available, or similar gauge-like, tally metrics.
IntAverage/LongAverage
Calculates and reports the averages (integer or long) for the timings you supply to the metric. As the IntAverage/LongAverage receives your measurements, it keeps a running count and a running average of your results. At the end of each 15-second interval, it reports the count of measurements, the mean of all measurements, the fastest measurement, and the slowest measurement.
Use this data type to calculate response times, like “average latency time in milliseconds”.
IntRate
The value is a per-second integer rate. IntRate divides the value(s) you supply by 15. It assumes a
per second
rate when looking at live data. For a 15 second interval, the remainder (14 or less) will be truncated. When aggregated over multiple time periods, the weighted average is used as the aggregated value.Use this data type in the context of “queries per second”, for example.
StringEvent
Reports string values, like a process ID or a startup command line. This metric data type introduces a considerable overhead in terms of memory and bandwidth, so use it sparingly. Reporting log entries as string events is not recommended.
Timestamp
This data type generates successively increasing timestamps. The value is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC (Unix Epoch Time).
Note that reporting timestamps is generally unnecessary, as performance metrics are all automatically timestamped on receipt to APM.
Metric Feed
{"host" : "<agent hostname>", (Optional. If set, it must match that in IntroscopeEPAgent.properties)"process" : "<agent process name>", (Optional. If set, it must match that in IntroscopeEPAgent.properties)"agent" : "<agent name>", (Optional. If set, it must match that in IntroscopeEPAgent.properties)"metrics" : [{"type" : "<type>", "name" : "<name>", "value" : "<value>"},{"type" : "<type>", "name" : "<name>", "value" : "<value>"},{"type" : "<type>", "name" : "<name>", "value" : "<value>"}
MetricFeedResponse
{"errorCode" : (Only included when errors processing metric feed bundle occur)"errorMessage" : "One or more metric specifications were invalid", (Only included when errors processing metric feed bundle occur)"invalidCount" : 2, (Only included when count > 0)"validCount" : 1"metricErrors" : [{"metricName" : "<metric name>", "metricErrorCode" : "<error code>", "metricErrorMsg" : "<error message>", "metricErrorIndex" : <the index of the erroneous metric in the submitted metric list>},{"metricName" : "<metric name>", "metricErrorCode" : "<error code>", "metricErrorMsg" : "<error message>", "metricErrorIndex" : <the index of the erroneous metric in the submitted metric list>}] (metricErrors only included when there are errors processing one or more metrics)}
URIs
Metric Feed URI
URL:
http://<EPA Host>:<EPA HTTP Port>/apm/metricFeedMethod:
POSTHeader :
"Content-Type:application/json"HTTP Success Response Code:
200 (OK) {"validMetricCount" : <number of successfully submitted metrics>}
GZIP Compression
To enable GZIP compression, you gzip the entire HTTP payload and include the following HTTP header:
Header :
"Content-Encoding:gzip"Payload Errors
Code | Message | Notes |
1000 | Invalid Request. A valid request must have a Content-Type header. The only supported value is application/json. A valid request must have a valid json payload containing a MetricFeed object. A valid request may have a Content-Encoding header. Supported encodings are gzip, x-gzip, and identity. A valid request may specify a charset in the Content-Type header. The specified charset must be supported by the installed java implementation. | |
1001 | Invalid JSON | Input is not parse-able as JSON |
1010 | One or more metric specifications were invalid | Response will contain per-metric errors for each of the invalid metrics, limited to the first 100. |
Per Metric Errors
Code | Message | Notes |
1011 | Invalid metric name | Name = (MetricName) | (ResourceSegments “:” MetricName) Where: ResourceSegments = (ResourceName) | (ResourceSegments “|” ResourceName) MetricName = Sequence of any Unicode character other than “|” or “:”, without trailing spaces ResourceName = Sequence of any Unicode character other than “|” or “:” |
1012 | Invalid metric type | Valid types are: LongAverage, IntAverage, LongCounter, IntCounter, IntRate, StringEvent, TimeStamp, PerIntervalCounter |
1013 | Invalid metric value | Typically seen when a value does not match the specified type, such as "hello world" as value for an IntCounter. |
1014 | Metric clamp exceeded | Metric could not be created because the default metric clamp of 5000 was reached. You can override this default value by adding the property to the file and configuring a custom clamp value. Note that processing more metrics will result in a higher resources usage by the EPAgent process. |
HTTP Response Codes
Code | Message | Notes |
200 | Success | Output includes the number of valid metric submitted |
400 | Invalid request | Maps to error codes 1000 and 1001 above |
409 | Partial success | Maps to error code 1010 above with individual metric errors for each erroneous metric submitted (up to clamping limit) |
415 | Invalid encoding | When a Content-Encoding header other than gzip or Identity is submitted with the metric bundle |