oneagentctl and API cheat sheet: OneAgent tags, properties, host group, network and modes

1. Using oneagentctl #

On the host.

Where to find it #

oneagentctl is installed with OneAgent: /opt/dynatrace/oneagent/agent/tools/oneagentctl on Linux, C:\Program Files\dynatrace\oneagent\agent\tools\oneagentctl.exe on Windows. It runs with administrator rights.

Common mistake: Forgetting the restart: changes to host group, network zone, server or mode only apply after OneAgent restarts; add --restart-service. Already instrumented processes must also be restarted for some changes.

2. Tags and properties #

Organise and filter.

Commands to know #

oneagentctl --set-host-tag=role=webserver --set-host-tag=env=prod
oneagentctl --get-host-tags
oneagentctl --remove-host-tag=role

oneagentctl --set-host-property=owner=team-shop
oneagentctl --get-host-properties
oneagentctl --remove-host-property=owner

To tag many entities without logging in to hosts, use the tags API with an entity selector:

curl -X POST "$DT_URL/api/v2/tags?entitySelector=type(HOST),hostGroupName(\"shop-prod\")" \
  -H "Authorization: Api-Token $DT_TOKEN" -H "Content-Type: application/json" \
  -d '{"tags":[{"key":"team","value":"shop"}]}'

Good to know: Tags set through the API are manual tags on the entity; tags and properties set with oneagentctl are sent by the agent. For a fleet, prefer automatic tagging rules or host properties set at installation.

3. Host group, network and server #

Grouping and communication.

Commands to know #

oneagentctl --set-host-group=shop-prod --restart-service
oneagentctl --get-host-group
oneagentctl --set-network-zone=paris.dc1 --restart-service
oneagentctl --get-network-zone
oneagentctl --set-proxy=proxy.example.com:3128 --restart-service
oneagentctl --set-server=https://<activegate>:9999/communication --set-tenant=<id> --set-tenant-token=<token> --restart-service

Remotely, remote configuration management changes the host group or network zone of a batch of agents:

curl -X POST "$DT_URL/api/v2/oneagents/remoteConfigurationManagement" \
  -H "Authorization: Api-Token $DT_TOKEN" -H "Content-Type: application/json" \
  -d '{"entities":["HOST-0123456789ABCDEF"],"operations":[{"operation":"set","attribute":"hostGroup","value":"shop-prod"}]}'

Common mistake: Using remote configuration for tags or properties: it only handles specific attributes (host group, network zone). For tags, use the tags API.

Good practice: Choose the host group at installation time: it is used to group process groups and for per-group configuration, and changing it later creates new entities.

4. Mode, identity and costs #

Advanced settings.

Commands to know #

oneagentctl --set-monitoring-mode=infra-only --restart-service   # fullstack | infra-only | discovery
oneagentctl --set-host-name=web-01
oneagentctl --set-host-id-source="ip-addresses;namespace=prod"
oneagentctl --set-auto-update-enabled=true

# cost allocation (DPS licensing)
oneagentctl --set-host-property=dt.cost.costcenter=CC123 --set-host-property=dt.cost.product=shop

SLOs are managed with the API v2 (/api/v2/slo): see SLOs in Dynatrace.

Variables for containers #

On Kubernetes, these settings go through the Dynatrace Operator and the DynaKube resource: see Dynatrace Operator on Kubernetes.