> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traversal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynatrace

> Connect Dynatrace to pull entities, problems, metrics, logs, traces, and Grail data during investigations.

Connecting Dynatrace lets Traversal pull entities, Davis-detected problems, metrics, events, logs, and traces during investigations so it can correlate symptoms across your services and produce grounded root-cause explanations.

## What Traversal reads

* **Entities and topology** — host, service, process, and application entities, plus their dependency relationships
* **Problems** — Davis-detected problems and their evidence
* **Metrics** — time-series data and dimensional metadata
* **Events** — deployment events and other point-in-time signals
* **Logs** — classic log queries and Grail (DQL) log queries
* **Spans / Traces** — APM spans and trace context
* **Settings** — read-only access to configuration objects (e.g. anomaly-detection rules)

## Authentication

Traversal talks to Dynatrace through two complementary API surfaces, and you can connect **either, or both at the same time**:

| Surface                     | Host                   | Authentication               | Covers                                                          |
| --------------------------- | ---------------------- | ---------------------------- | --------------------------------------------------------------- |
| **Classic Environment API** | `*.live.dynatrace.com` | API token (`dt0c01...`)      | Entities, problems, events, classic metrics, classic logs, SLOs |
| **Platform / Grail**        | `*.apps.dynatrace.com` | OAuth 2.0 client credentials | DQL queries against logs, events, spans, metrics, and bizevents |

<Note>
  **Pick what fits your tenant:**

  * **Dynatrace Managed / self-hosted** — Classic API only (Grail is SaaS-only).
  * **SaaS, Grail-only** — OAuth client only. Problems and entities are still reachable via DQL.
  * **SaaS, mid-migration or both surfaces in use** — provide both. Traversal automatically routes each query to the right surface.
</Note>

You only need to fill in the section(s) for the surface(s) you want to connect; leave the other section empty. Traversal's connection check exercises every credential you provide and reports per-surface pass/fail, so you'll see exactly which half is working if one side is misconfigured.

## Setup

<Steps>
  <Step title="Choose which surface(s) to connect">
    <Tabs>
      <Tab title="Classic API (token)">
        Best for **Dynatrace Managed**, **self-hosted**, or any tenant where you only need entities, problems, events, classic metrics, classic logs, and SLOs. Works on every Dynatrace deployment.
      </Tab>

      <Tab title="Platform / Grail (OAuth)">
        Best for **SaaS-only** tenants that have moved to Grail for logs, events, spans, metrics, and bizevents. Required for DQL queries.
      </Tab>

      <Tab title="Both">
        Best for **SaaS tenants mid-migration** or any tenant using both surfaces in production. Traversal routes each query to the surface that owns the data, so you get the broadest coverage.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create a Classic API token (if connecting the Classic API)">
    1. In Dynatrace, open **Settings → Integration → Dynatrace API → Generate token**.
    2. Name it (e.g. `traversal`).
    3. Choose the read-only scopes you want to grant. Traversal will exercise whichever scopes the token carries; the more scopes you grant, the more data Traversal can use during investigations.

    **Minimum**:

    | Scope           | What it covers                                                             |
    | --------------- | -------------------------------------------------------------------------- |
    | `entities.read` | Required to connect. Powers entity-listing and service-dependency lookups. |

    **Recommended additions** — grant whichever your security policy allows:

    | Scope           | What it unlocks                                                                                                                                                                          |
    | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `problems.read` | Davis-detected problems (`/api/v2/problems`)                                                                                                                                             |
    | `metrics.read`  | Metric time-series queries (`/api/v2/metrics/query`)                                                                                                                                     |
    | `events.read`   | Events including deployments (`/api/v2/events`)                                                                                                                                          |
    | `releases.read` | Curated release lists (`/api/v2/releases`); only available on tenants where the Releases feature is enabled. Traversal falls back to events automatically when this scope isn't granted. |
    | `settings.read` | Settings 2.0 objects, including anomaly-detection rules (`/api/v2/settings/objects`)                                                                                                     |
    | `logs.read`     | Classic log queries                                                                                                                                                                      |
    | `slo.read`      | SLO definitions and status                                                                                                                                                               |
    | `traces.lookup` | Classic trace lookups                                                                                                                                                                    |

    <Note>
      Granting only `entities.read` is enough to connect, but Traversal won't have anything else to read. Grant the additional scopes for the data types you want surfaced during investigations.
    </Note>

    4. Click **Generate token** and copy the token immediately. Dynatrace shows it only once.
    5. Note your **Classic Environment URL** in the format `https://<env-id>.live.dynatrace.com`. The environment ID is the subdomain of your Dynatrace UI URL.

    <Note>
      For Dynatrace Managed deployments the URL format is `https://<your-domain>/e/<env-id>` instead. Traversal supports both.
    </Note>
  </Step>

  <Step title="Create a Platform OAuth client (if connecting Grail)">
    1. In Dynatrace, open **Account Management → Identity & access management → OAuth clients → Create client**.
    2. Name it (e.g. `traversal`) and choose which storage scopes to grant. Traversal queries whichever data types the token can read, so grant the storage scopes for the signals you want available during investigations.

    **Minimum**:

    | Scope  | What it covers                                                                                              |
    | ------ | ----------------------------------------------------------------------------------------------------------- |
    | *none* | No storage scopes are required to connect — you can save the integration first and grant data scopes later. |

    **Recommended additions** — grant whichever your security policy allows:

    | Scope                    | What it unlocks                                                                                         |
    | ------------------------ | ------------------------------------------------------------------------------------------------------- |
    | `storage:logs:read`      | Log records in Grail                                                                                    |
    | `storage:events:read`    | Event records in Grail (including deployment events)                                                    |
    | `storage:spans:read`     | Span records in Grail                                                                                   |
    | `storage:metrics:read`   | Metric records in Grail                                                                                 |
    | `storage:bizevents:read` | Business event records                                                                                  |
    | `storage:buckets:read`   | Storage bucket metadata; useful for letting Traversal discover which buckets exist before querying them |
    | `storage:system:read`    | System tables (e.g. `dt.system.tables`); useful for schema discovery                                    |

    <Note>
      You can save the integration with zero storage scopes if you want to set up authentication first and add data scopes later. Until you grant the relevant `storage:*:read` scopes, Traversal won't be able to read any data from Grail.
    </Note>

    3. Click **Create client** and copy the **Client ID**, **Client secret**, and **Account URN**. The secret is shown only once.
    4. Note your **Platform URL** in the format `https://<env-id>.apps.dynatrace.com`. The environment ID is the same as your Classic URL — only the host suffix differs (`.apps.` vs `.live.`).
  </Step>

  <Step title="Configure in Traversal">
    Go to **Company Knowledge → Integrations**, select **Dynatrace**, and fill in the section(s) for the surface(s) you're connecting:

    **Classic API**

    * **Classic Environment URL** — e.g. `https://abc12345.live.dynatrace.com`
    * **API Token** — the `dt0c01...` token from Step 2

    **Platform / Grail**

    * **Platform URL** — e.g. `https://abc12345.apps.dynatrace.com`
    * **OAuth Client ID** — starts with `dt0s02.`
    * **OAuth Client Secret** — the secret you copied
    * **Account URN** — format `urn:dtaccount:<uuid>`, found in **Account Management → Overview**

    Click **Save**. Traversal exercises every credential you provided and reports the result per surface — if you connected both, you'll see a separate pass/fail for Classic and Grail.
  </Step>
</Steps>

## Troubleshooting

* **Classic connection fails with an `entities.read` permission error** — `entities.read` is the only scope required to connect; other scopes are only needed for the corresponding queries. Re-generate the token with `entities.read` granted.
* **Integration saves but a specific Dynatrace query returns "no data" or a permission error** — the corresponding scope is likely not granted on the token (Classic) or OAuth client (Grail). Add the scope from the tables above and re-save the integration.
* **Classic URL pasted on the Platform host (or vice-versa)** — Traversal rejects URLs that mix the two surfaces. Use `*.live.dynatrace.com` for Classic and `*.apps.dynatrace.com` for Grail.
* **Grail OAuth connection fails with an SSO error** — check that all three of Client ID, Client Secret, and Account URN are correct. The Account URN must be the format `urn:dtaccount:<uuid>` from your Dynatrace Account Management page, not the environment ID.

## More information

* [Dynatrace API documentation](https://docs.dynatrace.com/docs/dynatrace-api)
* [Generate access tokens (Classic API)](https://docs.dynatrace.com/docs/manage/access-control/access-tokens)
* [Create OAuth clients (Platform)](https://docs.dynatrace.com/docs/manage/identity-access-management/access-tokens-and-oauth-clients)
* [Dynatrace Query Language (DQL)](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-query-language)