You can send metrics to the Machine Agent using its HTTP listener. You can report metrics through the Machine Agent by making HTTP calls to the Agent instead of piping to the Agent through sysout.

Activate the HTTP Listener

The HTTP listener is not enabled by default. To activate the HTTP listener, restart the Machine Agent and set the metric.http.listener system property to true. Optionally, you can specify the host and port for the listener with system properties.

The -D system properties are:

  • metric.http.listener: Required. Set to true.
  • metric.http.listener.port: Optional. Set to the port to be used, defaults to 8293.
  • metric.http.listener.host: Optional. This describes which interface to accept requests on. You can set it as follows:
    • If you do not specify the metric.http.listener.host, it defaults to localhost, which means requests are only accepted from localhost.
    • Set to 0.0.0.0 to accept on all interfaces (including from remote clients). Not a recommended configuration.*
    • Set to the IP address of the specific interface to accept requests on. Not a recommended configuration.*

*No authentication or authorization is performed and opening the listener service can introduce a potential security risk, allowing any user to connect to this service. If this configuration is used, customers are advised to introduce other mitigating controls (for example, firewalls, proxy service, network access lists) to limit access.

<machine_agent_home>/bin/machine-agent -Dmetric.http.listener=true -Dmetric.http.listener.port=<port_number> -Dmetric.http.listener.host=0.0.0.0
CODE

If starting the Agent by invoking the Machine Agent JAR, ensure that you place the options before the JAR name in your start up command. For example:

java -Dmetric.http.listener=true  -jar MACHINE_AGENT_HOME/machineagent.jar

Create Metrics

Use to post custom metrics to the Machine Agent for uploading to the Controller. Define one or more metrics in the body of the request as JSON data. 

URI

POST /api/v1/metrics

Metric Definition Fields

ParameterDescription
metricNameName for the metric as it will appear in the Controller UI.
aggregatorType

How the metrics should be aggregated. Options are:

  • AVERAGE: The average of all one-minute data points when adding it to the 10-minute or 60-minute granularity table.
  • SUM: The sum of all one-minute data points when adding it to the 10-minute or 60-minute granularity table.
  • OBSERVATION: Last reported one-minute data point in that 10-minute or 60-minute interval.
ValueA 64-bit integer value for the metric.

Format

POST /api/v1/metrics

 [

  {

    "metricName": "Custom Metrics|Test|MetricFromRESTClient1",

    "aggregatorType": "AVERAGE",

    "value": 10

  }

]
CODE

Create Events

Use to post custom events to the Machine Agent for uploading to the Controller. Define one or more events in the body of the request as JSON data.    

URI

POST /api/v1/events

Event Definition Fields

Parameter NameDescription
eventSeveritySeverity of the event, from INFO, WARN, ERROR.
typeA string describing the event subtype. The event will be of type CUSTOM, subtype will be the value of this parameter.
summaryMessageA summary of the event.
propertiesEvent properties. These properties are retrieved along with events by the Controller in a given query and provide a means for filtering the events. The maximum size of a key is 500 characters and the maximum size of a value is 5000 characters. The values can be a numeric or string value.
detailsArbitrary key-value details for the event; similar in constraints to properties but are retrieved in a separate call. Use this to store details that should only be retrieved when requested by the user, which avoids the expense of retrieving this data in the usual event calls.

Format

POST /api/v1/events
[
  {
    "eventSeverity": <event_severity>,
    "type": "<event_type>",
    "summaryMessage": "<event_summary>",
    "properties": {
      "<key>": {
        <user-specified_object>
      },...
    },
    "details": {
      "<key>": "<value>"
    }
  },
  {
    "eventSeverity": <event_severity>,
    "type": "<event_type>",
    "summaryMessage": "event_summary>",
    "properties": {
      "<key>": {
        <user-specified_object>
      },...
    },
    "details": {
      "<key>": "<value>"
    }
  },...
]
CODE


Legacy Machine Agent HTTP APIs

The following API endpoints are supported for backward compatibility, but are not extended or enhanced in future versions.

Upload Metrics

You can use GET or POST to upload metrics to the Metric Browser under Application Performance > Tier, where the tier is the one defined for the Machine Agent.

The format for GET is:

GET /machineagent/metrics
CODE

For example:

http://host:port/machineagent/metrics?name=Custom Metrics|Test|My Metric&value=42&type=average
XML

The format for POST is:

POST /machineagent/metrics
CODE

with header: 

Content-Type: application/xml
CODE

with body content:

<?xml version="1.0"?>
<request>
<metric name="[name of metric 1]", type="[aggregation type]", value="[value of metric 1]" />
<metric name="[name of metric 2]", type="[aggregation type]", value="[value of metric 2]" />
...
<metric name="[name of metric n]", type="[aggregation type]", value="[value of metric n]" />
</request> 
CODE

Example:

http://host:port/machineagent/metrics
XML

Example of body content: 

<request>
<metric name="Custom Metrics|Test|My Metric 1", type="AVERAGE", value="22" />
<metric name="Custom Metrics|Test|My Metric 2", type="SUM", value="98737" />
<metric name="Custom Metrics|Test|My Metric 3", type="CURRENT", value="93" />
</request>
CODE


Valid values for type are:

  • AVERAGE: Average of all one-minute data points when adding it to the 10-minute or 60-minute granularity table.
  • SUM: Sum of all one-minute data points when adding it to the 10-minute or 60-minute granularity table.
  • CURRENT: Last reported one-minute data point in that 10-minute or 60-minute interval.

Upload Events

Send events using HTTP GET requests to upload events to the Machine Agent. The format is:

GET /machineagent/event
CODE

For example: 

http://localhost:8293/machineagent/event?type=<event_type>&summary=<summary_text> 
XML

Event_type is one of the following:

  • error
  • info
  • warning