OneAgent metric API

You can use the local http://localhost:<port>/metrics/ingest API endpoint to push locally retrieved metrics to Dynatrace over a secure and authenticated channel. This endpoint is available only to local clients and cannot be reached from remote hosts.

Enable the OneAgent metric API

The OneAgent metric API comes with OneAgent version 1.201 by default. You only need to enable the OneAgent metric API at the environment or host level. Note that the host-level configuration overrides the environment configuration.

Enable at the environment level

1. In the Dynatrace menu, go to Settings > Monitoring > Monitored technologies.
2. In the list of supported technologies, search for the Dynatrace OneAgent StatsD, Pipe, HTTP Metric API entry.
3. Select Edit.
4. Turn on Enable Extensions Execution Controller on every host.
5. Turn on Enable local PIPE/HTTP metric API on every host.

Disable on selected hosts

When enabled at the environment level, you can disable ingestion for selected hosts.

1. In the Dynatrace menu, select Hosts, and select your host.
2. Open the browse menu (…) and select Settings.
3. In the Monitored technologies table, search for the PIPE/HTTP entry. You can sort by Type and look for the Infrastructure insights type.
4. Edit the entry:
   • Turn on Use host configuration.
   • Turn off Enable on this host.

Enable for a single host

1. In the Dynatrace menu, go to Settings > Monitoring > Monitored technologies.
2. In the list of supported technologies, search for the Dynatrace OneAgent StatsD, Pipe, HTTP Metric API entry.
3. Select Edit.
4. Turn off Extension Execution Controller.
5. In the Dynatrace menu, select Hosts, and select your host.
6. Open the browse menu (…) and select Settings.
7. In the Monitored technologies table, search for the Extensions Execution Controller entry. You can sort by Type and look for the Infrastructure insights type. Select Edit and turn on Use host configuration and Enable on this host.
8. Search for PIPE/HTTP. Select Edit and turn on Use host configuration and Enable on this host.

Topology awareness

Using the local API endpoint, the host ID and host name context are automatically added to each metric as dimensions. Learn how to enrich your metrics with other Dynatrace-specific dimensions and apply Dynatrace-AI causation details to your ingested data.

Metric format

Provided data points must follow the Metrics ingestion protocol.

The request consumes a plain/text payload with the charset=utf-8 character set. The payload is limited to 1,000 lines.

Example

With this curl command, you'll ingest the cpu.temperature metric assigned to the cpu=1 dimension. The metric will be automatically assigned to a respective host ID and host name.

curl --data "cpu.temperature,cpu=1 55" http://localhost:14499/metrics/ingest \
     -H "Content-Type: text/plain; charset=utf-8"

Successful response:

{
 "error": null,
 "linesValid": 1,
 "linesInvalid": 0
}

Communication port

The default metric ingestion port is 14499. If necessary, you can use oneagentctl command-line interface to check or change the port. Changing the metric ingestion port requires restart of OneAgent. Add –restart-service to the command to restart OneAgent automatically.

Check the ingestion port

Use the --get-extensions-ingest-port parameter to show the current local ingestion port, 14499 by default.

• Linux: ./oneagentctl --get-extensions-ingest-port
• Windows: .\oneagentctl.exe --get-extensions-ingest-port

Set a custom ingestion port

Use the --set-extensions-ingest-port=<arg> parameter to set a custom local ingestion port.

• Linux: ./oneagentctl --set-extensions-ingest-port=14499 --restart-service
• Windows: .\oneagentctl.exe --set-extensions-ingest-port=14499 --restart-service

Configure proxy

Configure your host proxy to allow localhost traffic going to the metric ingestion port, 14499 by default.

Note that changing the port for the OneAgent metric API also affects scripting integration and Telegraf.