Module 3 of the Dynatrace Managed course shows how to deploy OneAgent on a host and when an ActiveGate is needed.
Course: Dynatrace Managed · Module 3/8 · Duration: ~45 min · Level: Beginner
Objectives:
- Install OneAgent on a Linux host and check its connection
- Choose the monitoring mode and the host group
- Understand when an ActiveGate is needed and which one to choose
- Know the options for Windows and Kubernetes
Prerequisites: module 2; a test cluster or environment; a Linux VM to monitor.
A cluster without agents shows nothing. This module teaches you how to deploy OneAgent and ActiveGate in a Dynatrace Managed environment: installing the agent on a host, the settings to decide from the outset, then the role of ActiveGates and the choice between their two Managed-specific variants.
Deploy OneAgent and ActiveGate: start with the agent on Linux
In the environment, the OneAgent deployment screen generates the download command and the required token for you. In essence, the command looks like this:
wget -O Dynatrace-OneAgent-Linux.sh \
"https://{your-domain}/e/{environment-id}/api/v1/deployment/installer/agent/unix/default/latest?arch=x86" \
--header="Authorization: Api-Token {token}"
sudo /bin/sh Dynatrace-OneAgent-Linux.sh \
--set-monitoring-mode=fullstack \
--set-host-group=test-orders
Three things to watch:
- The token grants the right to download the installer. Use the one generated by the deployment screen, do not store it in plain text in a repository, and note its expiry date.
- The monitoring mode: full-stack enables deep process monitoring (traces, services); an infrastructure-only mode exists for hosts where you only care about system metrics. This choice affects licence consumption.
- The host group (
--set-host-group) groups hosts that play the same role. It influences how Dynatrace groups processes and is the basis for the tagging rules in module 6. Decide on a naming convention before deploying at scale.
Check that the agent is working
Once installed, OneAgent runs as a system service. The oneagentctl tool lets you read and change its configuration afterwards:
systemctl status oneagent
sudo /opt/dynatrace/oneagent/agent/tools/oneagentctl --get-server
sudo /opt/dynatrace/oneagent/agent/tools/oneagentctl --get-host-group
In the interface, the host appears in the host list within a few minutes. Processes started before the installation are visible but not instrumented: restart them (application server, web server) to see their services and traces appear. This is the most common beginner’s mistake.
Options in detail, proxy cases and large-scale deployments are covered in Deploying OneAgent on Linux in a Managed environment.
Windows and Kubernetes
On Windows Server, the installer is used in graphical or silent mode with equivalent parameters; see Installing OneAgent on Windows Server in silent mode. On Kubernetes and OpenShift, you do not install it node by node: Dynatrace Operator and a DynaKube resource pointing to https://{your-domain}/e/{environment-id}/api handle the deployment, as explained in Kubernetes and OpenShift: connecting Dynatrace Operator to a Managed cluster.
What is an ActiveGate and when do you need one?
An ActiveGate is a Java component installed on a dedicated machine, acting as an intermediary between data sources and the cluster. By default it listens on port 9999. You need one in several situations:
- the OneAgents are in a network that cannot reach the cluster directly (DMZ, another site): the ActiveGate concentrates and relays their traffic;
- you want to monitor resources without an agent: cloud platforms, remote extensions, devices queried through an API;
- you want to run synthetic tests from a private location;
- you want to limit the number of flows crossing a firewall.
Environment ActiveGate or Cluster ActiveGate?
Managed distinguishes two types of ActiveGate:
| Environment ActiveGate | Cluster ActiveGate | |
|---|---|---|
| Attached to | One specific environment | The whole cluster |
| Typical uses | Routing agents from a network, extensions, cloud monitoring | Access from outside (agents outside the network, RUM data coming from the internet), private Synthetic locations |
| Installed from | The environment interface | The Cluster Management Console |
In practice: start with an Environment ActiveGate for your internal needs, and keep the Cluster ActiveGate for flows that come from outside the cluster’s network. The exact list of functions for each type changes between versions; the article ActiveGate in Managed: Environment ActiveGate or Cluster ActiveGate? details the criteria.
Network zones
When there are several ActiveGates across several sites, the OneAgent --set-network-zone option tells the agent which network zone to prefer. Agents in one datacenter then go through that datacenter’s ActiveGates. Not needed for a first test, but useful as soon as the infrastructure is distributed.
Hands-on exercise
Step 1 — Install OneAgent
From the deployment screen of your test environment, copy the Linux command, add a host group of your choice and run it on a VM. Expected result: the oneagent service active and the host visible in the host list with its group.
Step 2 — Instrument an application
Install a simple web server (nginx or Apache) or start a demo Java application, then restart it. Generate traffic with curl in a loop. Expected result: a web service appears, with requests and response times.
Step 3 — Read the configuration
Use oneagentctl --get-server and --get-host-group. Expected result: the address of the cluster or ActiveGate in use, and the group set in step 1.
Step 4 — Design the ActiveGate placement
On paper, draw your real network (sites, DMZ, internet access) and place the ActiveGates you need, specifying their type. Expected result: a diagram that justifies each ActiveGate with a specific flow.
Quiz
- Why does a service not appear after OneAgent is installed? a) The token has expired b) The process has not been restarted c) An ActiveGate is missing d) Full-stack mode is disabled by default
- What is the –set-host-group option for? a) Choosing the cluster b) Grouping hosts with the same role c) Setting the network zone d) Limiting the licence
- Which ActiveGate should you choose to receive data coming from the internet? a) Environment ActiveGate b) Cluster ActiveGate c) None d) A OneAgent in infrastructure mode
- How is OneAgent deployed on Kubernetes? a) By hand on each node b) With Dynatrace Operator and a DynaKube resource c) Through the CMC d) Through an ActiveGate
Answers
- b) Injection happens when the process starts; a process that predates the installation must be restarted.
- b) The host group brings together hosts that play the same role and is used by configuration rules.
- b) The Cluster ActiveGate handles flows from outside the cluster’s network.
- b) The Operator manages the agents’ lifecycle based on the DynaKube resource.
Further reading
- Deploying OneAgent on Linux in a Managed environment
- ActiveGate in Managed: Environment or Cluster?
- Connecting Dynatrace Operator to a Managed cluster
- Official Dynatrace Managed documentation (OneAgent and ActiveGate)
← Module 2: Managed cluster architecture and installation · Course overview · Module 4: Exploring the data →
Frequently asked questions
Do I need an ActiveGate to get started?
No. If the hosts can reach the cluster directly, OneAgent can connect to it without an intermediary. An ActiveGate becomes necessary to cross network zones, monitor without an agent or run private synthetic tests.
Does OneAgent restart my applications?
No. Installation does not stop any process. It is up to you to schedule the restart of the applications to be instrumented, ideally in a maintenance window.
Can the host group be changed after installation?
Yes, with oneagentctl, but the change can alter how processes are grouped and therefore the entity history. Settle the convention before mass deployment.
Your hosts are now sending data. Module 4 teaches you how to navigate it: from hosts to services, down to PurePath traces and the problems opened by Davis.
span.observer is an independent community blog, not affiliated with Dynatrace LLC. This course does not replace the official Dynatrace University training and certifications. Check features in the official documentation for your version.
2 comments