Metric scripting integration

Early Adopter

You can use the dynatrace_ingest tool to push locally retrieved metrics to Dynatrace over a secure and authenticated channel. The tool is available to local clients only and cannot be reached from remote hosts.

Enable scripting integration

Scripting integration comes with OneAgent version 1.201+ by default. You only need to enable scripting integration at the environment or local host level. Note that the host-level configuration overrides the environment configuration.

Binary location

The tool location depends on whether or not you've customized the OneAgent installation using the <INSTALL_PATH> parameter:

  • Linux or AIX:
    <INSTALL_PATH>/agent/tools, by default /opt/dynatrace/oneagent/agent/tools
  • Docker-based deployment
    <INSTALL_PATH>/agent/tools, by default /opt/dynatrace/oneagent/agent/tools
    Note that this path will differ for a volume-based deployment.
  • Windows:
    <INSTALL_PATH>\agent\tools, by default %PROGRAMFILES%\dynatrace\oneagent\agent\tools

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

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

Topology awareness

Using the dynatrace_ingest based scripting integration, the host ID and host name context are added to each metric as dimensions automatically. For more information, see Metric ingestion. Note that we're already working on more automatic metric enrichments.

Metric format

Provided data points must follow the Metrics ingestion protocol.


The basic usage is:

dynatrace_ingest [Options] [Metrics]

Both [Options] and [Metrics] are optional. The syntax of metrics passed to the [Metrics] arguments must comply with the Metrics ingestion protocol.

There two basic ways to pass metrics with dynatrace_ingest: (1) by piping another process output to dynatrace_ingest, or (2) using the call arguments.

Piping process output

When metrics are omitted, dynatrace_ingest expects them to be passed via standard input. Each line is treated as one metric. This enables you to pipe metrics to dynatrace_ingest from the output of other processes. For example:

echo host.process_count `ps aux | wc -l` | dynatrace_ingest

Call arguments

When using call arguments instead of standard input to pass metrics, pass each metric as a separate argument. For example, to pass two metrics using a single command:

dynatrace_ingest 'cpu.temperature,cpu=1 55'  'cpu.temperature,cpu=2 45'

Command line options

-v [ --verbose ]
Prints logs to standard output

-p [ --port ] arg (=14499)
Sets custom port for communication with the OneAgent Extensions Execution Controller (EEC) module. If you change the default EEC port (14499), you must instruct dynatrace_ingest to use the new port. For more information on setting a custom EEC port, see Communication port

-h [ --help ]
Prints help message and quit