Skip to content
CA Application Performance Management - 10.7
Documentation powered by DocOps

Configure the Standalone EPAgent RESTful Interface

Last update April 13, 2018

You can configure the Standalone EPAgent HTTP RESTful interface to submit metrics gathered from your application or environment. The HTTP RESTful Interface can operate in conjunction with your existing Standalonen 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 Standalone 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 Standalone EPAgent REST Interface can process GZIP compressed JSON metric data.

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/metricFeed

Method: POST

Header : "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"

Error Codes

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 introscope.agent.metricClamp= property to the IntroscopeEPAgent.properties 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

Examples

Sample HTTP POST calls using cURL:

curl -i -H "Content-type: application/json" -X POST http://my-host-name:8080/apm/metricFeed  -d '{ metrics : [{type : "PerIntervalCounter", name : "MyTest|RESTFul|PerIntervalCounter|Test1:Count", value : "123"}] }'
curl -i -H "Content-type: application/json" -X POST http://my-host-name:8080/apm/metricFeed  -d '{ metrics : [{type : "LongCounter", name : "MyTest|RESTFul|LongCounter|Test2:Count", value : "456"}] }

Was this helpful?

Please log in to post comments.