Dynatrace¶
Clarity Transform reads observed topology from the Dynatrace Environment API v2: host-to-host connections and service-to-service calls, each endpoint already resolved to a named host and process rather than a bare address.
Where to find it¶
Go to Discover → Integrations, then select the Dynatrace card. The card's category label is Observability. The integration's page has the Endpoints and History tabs; Integrations describes the page, its grid and its row actions.
Why we do this¶
Beyond host-to-host connectivity, distributed tracing knows which services call which other services. That is an application-level dependency map derived from live tracing, and it is something no purely network-level source can produce.
What we collect¶
- Host-to-host network connections, with both ends named
- Service-to-service call relationships from distributed tracing
- The process at each endpoint, which is what makes the evidence attributable
Connections between processes on the same host are discarded, since they describe nothing about dependencies between machines.
What it adds¶
Two things it provides. Process-level attribution, so a conversation is recorded as one piece of software calling another rather than one address reaching another. And service-level dependencies, which is the application map itself rather than the network evidence it is usually inferred from.
Coverage equals OneAgent deployment
Dynatrace sees what it monitors. An unmonitored host is invisible to this source entirely, including its traffic to monitored ones, so a partial OneAgent rollout produces a partial map. That is worth establishing early, because the quality of this source makes it tempting to treat as complete.
What is deliberately not inferred¶
- No metrics or measurement data. The token scope is topology only, deliberately.
- No log data, traces or user session data.
- No application code or configuration.
- Nothing is written to Dynatrace.
- Same-host process connections are discarded, as above.
What we require¶
An API token with the entities.read scope and nothing else. No metrics scope, because what is read is the topology graph rather than measurement data.
- Interface: the Dynatrace Environment API v2
- Connectivity: HTTPS on TCP 443, to either the SaaS tenant address or an ActiveGate where API traffic is routed through one
- Token: created for this purpose rather than reused, so it can be revoked independently
Verification before handover¶
- Confirm the token authenticates and carries the right scope. Call the entities endpoint. A scope error rather than an authentication error means the token is valid but was created with the wrong scopes, which is the more common of the two.
- Confirm the address is the one Clarity should use. Where an ActiveGate routes API traffic, the endpoint is the ActiveGate rather than the tenant. Using the tenant address directly may be blocked outbound even though the token is correct.
- Confirm the entities returned cover what you expect. Compare the host count against the known estate. A gap here is OneAgent coverage rather than permission, and it is better established now than assumed later.
Configuring the endpoint¶
On the integration's Endpoints tab, select the add icon (Create New Integration Endpoints). The Create new entry form opens with these fields, in this order:
| Field | Value |
|---|---|
| Name | A name for the endpoint |
| End Point | The tenant address, or the ActiveGate where one routes API traffic |
| Credential | A credential with the API token as its Password |
| Job Schedule | A five-field cron expression, for example 0 2 * * * (daily) |
| Enabled | Ticked. The box is unticked when the form opens |
The help texts: End Point "FQDN or IP Address of management system for technology e.g. vCenter, Nutanix Prism"; Credential "Credentials can be configured under Settings/Identity and Access Management/Credentials."; Job Schedule "Cron schedule – Use five fields: 〈mm〉 〈hh〉 〈day-of-month〉 〈month〉 〈weekday〉".
The Credential list offers the credentials stored under Settings → Identity & Access Management → Credentials, so create the credential there first.
No field is marked as required. Technology is set by the card and is hidden in the form. Select Save to create the endpoint, or Cancel to close the form. The edit icon opens the same fields as Edit entry.
Removing the access¶
Revoke the API token in Dynatrace. Because it was created for this purpose and carries one scope, revoking it affects nothing else. Then, in Clarity, remove the endpoint (select its row on the Endpoints tab, then Remove selected) or clear its Enabled box, and remove the credential under Settings → Identity & Access Management → Credentials.
Troubleshooting¶
| Symptom | Cause |
|---|---|
| A scope error rather than an authentication error | The token is valid but was created without entities.read. Scopes cannot be added to an existing token on some versions; create a new one. |
| Cannot reach the tenant address | An ActiveGate routes API traffic in this environment. Use the ActiveGate address as the endpoint. |
| Fewer hosts than expected | OneAgent is not deployed on them. This source sees only what it monitors. |
| Service relationships missing although hosts are present | Distributed tracing is not enabled for those processes, so the service layer has nothing to report. |