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.
- Go to Settings and select Preferences > Extension Execution Controller.
- Turn on Enable Extension Execution Controller.
- Turn on Enable local HTTP Metric, Log and Event Ingest API.
- Go to Hosts or Hosts Classic (latest Dynatrace).
- Find and select your host to display the host overview page.
- In the upper-right corner of the host overview page, select More (…) > Settings.
- In the host settings, select Extension Execution Controller.
- Turn on Enable Extension Execution Controller.
- Go to Deployment Status and then select OneAgents.
- On the OneAgent deployment page, turn off Show new OneAgent deployments.
- Filter the table by
Host group
and select the host group you want to configure.This displays the OneAgent deployment page filtered by the selected host group. Each listed host has a Host group:The Host group property is not displayed when the selected host doesn't belong to any host group.
<group name>
link, where<group name>
is the name of the host group that you want to configure. - Select the host group name in any row.
As you have filtered by host group, all displayed hosts go to the same host group.
- In the host group settings, select Extension Execution Controller.
- Turn on Enable Extension Execution Controller.
Binary location
The tool location depends on whether or not you've customized the OneAgent installation using the <INSTALL_PATH>
parameter:
- Linux:
<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
Starting with OneAgent version 1.267+, AIX systems also support metric ingestion.
The default metric ingestion port is 14499
. If necessary, you can use the oneagentctl command 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, AIX:
./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, AIX:
./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 scripting integration also affects OneAgent REST API and Telegraf.