Getting started

Install the app in your Dynatrace environment and open your first live diagram.

Requirements

• A Dynatrace SaaS environment on the platform with AppEngine, where you are allowed to install custom apps.
• For the people who use the app: permissions for the scopes listed below (DQL access to entities, events and the data your KPIs query).
• To deploy, either a GitHub account (GitHub Codespaces, nothing to install — next section) or Node.js 20.19 or later and npm on your machine (steps 1 to 5).

Deploy from GitHub Codespaces

The repository includes a dev container: a codespace starts with Node.js and every dependency installed. You provide two values — your environment URL and a platform token — and run one command.

1. Create a platform token

Go to My platform tokens, select Platform token, give it a name and an expiration date, choose your environment and add these scopes:

• app-engine:apps:install
• app-engine:apps:run
• app-engine:apps:delete

Select Generate and copy the token — it is shown only once. A platform token works within the permissions of its user, so that user must be allowed to install apps in the environment. See Platform tokens in the Dynatrace documentation.

2. Create the codespace

Use the button above, or Code › Codespaces › Create codespace on main in the repository. The first time, the creation page asks for two recommended secrets:

GitHub stores them as Codespace user secrets of your own GitHub account — not in the repository — with access to this repository, and passes them to the codespace as environment variables. From then on the creation page only shows them as Associated with repository and reuses them; the deploy step below lets you use other values anyway. Other people who open a codespace from the repository are asked for their own values. While the codespace starts, npm ci installs the dependencies, and the terminal shows where the app will be deployed.

3. Deploy

In the codespace terminal:

npm run deploy:token

It asks for the environment URL and the platform token, showing your saved values: press Enter to keep them, or type another environment's URL and token to deploy there (nothing is saved). scripts/deploy.sh then builds the app and installs it in that environment (it takes precedence over app.config.json), authenticating with the token instead of a browser sign-in, and prints the link to the app. Extra arguments go to dt-app deploy, e.g. npm run deploy:token -- --dry-run; --yes skips the questions (CI).

Where the saved values are

In your account, not in the repository: your avatar › Settings › Codespaces › Codespace user secrets (github.com/settings/codespaces). Repository › Settings › Secrets › Codespaces stays empty — and should: secrets there would be shared by everyone who opens a codespace from the repository.

Deploying to another environment

You don't have to delete anything — pick one:

Without secrets you can also copy .env.example to .env (ignored by git) or export the values:

export DT_APP_ENVIRONMENT_URL=https://<environment-id>.apps.dynatrace.com
export DT_APP_PLATFORM_TOKEN=<your-platform-token>
npm run deploy:token

1. Clone and install

git clone https://github.com/Edunzz/dynatrace_apps_custom_diagram_creator.git
cd dynatrace_apps_custom_diagram_creator
npm install

2. Point it to your environment

Open app.config.json and set your environment URL. The app id my.custom.diagram.creator can stay as it is; change it only if you want to install two copies side by side.

{
  "environmentUrl": "https://<your-environment-id>.apps.dynatrace.com/",
  "app": {
    "id": "my.custom.diagram.creator",
    "version": "0.10.1"
  }
}

3. Run it locally (optional)

The development server opens your browser, asks you to sign in with SSO and proxies every platform call with your permissions.

npm run start

4. Deploy

Build and install the app in the environment from app.config.json. The first deploy opens the browser to sign in with SSO; to use a platform token instead, run npm run deploy:token as described in Deploy from GitHub Codespaces.

npm run deploy

5. Open your first diagram

Open https://<your-environment-id>.apps.dynatrace.com/ui/apps/my.custom.diagram.creator. The first time the app opens it creates the lookup table /lookups/custom-diagram-creator/diagrams with the sample diagram Sample – EasyTrade trading platform — the EasyTrade demo application end to end, which lights up in environments that run EasyTrade — and shows a "Diagram storage created" notification.

Environments that already have diagrams receive a new sample once; a sample you delete doesn't come back. The samples of earlier versions (Online Banking and Platform signals) are removed from the list, unless someone saved them since they were added.

Open the sample, switch to Edit and click any component to see the floating toolbar, or double-click it to open its editor. The user guide walks through every feature.

App scopes

The app asks for these scopes when it is installed, so its queries can read every kind of telemetry in Grail. Scopes are the upper limit: each user still needs the matching IAM permissions to see the data.

Troubleshooting