Metric scripting integration

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

Topology awareness

Using the dynatrace_ingest based scripting integration, the host ID and host name context are added to each metric as dimensions automatically. 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.

Usage

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

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.