DEV Community

Cover image for Dynatrace App Toolkit: build your first app step by step
Span Observer
Span Observer

Posted on Originally published at span.observer

Dynatrace App Toolkit: build your first app step by step

Your team needs a view that no standard screen provides: one that joins teams, services and a home-grown DQL query. The operational decision is easy to state. Either you keep a dashboard and screenshots pasted into a wiki, or you build a small app that lives inside your environment. The Dynatrace App Toolkit is the command-line tool that makes the second option affordable. This article takes it the opposite way round from the documentation: first what to decide before writing code, then the minimal loop that gets an app running.

It applies to Dynatrace SaaS only (addresses ending in apps.dynatrace.com); Managed is not covered. span.observer did not deploy an app to write this piece: commands and options come from the developer documentation and the vendor’s post, linked below, and no output is made up.

The vendor’s post presents App Toolkit 1.0 as a single toolchain: create, develop and deploy, add app functions and update packages, all from one binary, dt-app. Keep that idea in mind; the rest follows from it.

Dynatrace App Toolkit: do you really need an app?

Before opening a terminal, put three questions to the team. They save you from maintaining code for nothing.

  • Would a dashboard do? If the view is a set of DQL tiles, stay with a dashboard: no code, no release cycle.
  • Who maintains the app? An app has a version, dependencies and an owner. Name that person before the first line of code, as for any service.
  • What data will it read? The app’s scopes are declared in its configuration: the fewer you ask for, the shorter the security review.

If the answer leans towards an app (custom interface, navigation, presentation logic), move on to the setup. For the queries behind your future pages, the article on advanced DQL techniques is a good base.

Prerequisites to check before running the command

The App Toolkit page lists precise requirements. Here they are as read in the documentation:

  • Node.js 24 installed locally (check with node --version);
  • your environment address, in the form https://{environment-id}.apps.dynatrace.com/, which you can copy from the browser address bar;
  • network access to dt-cdn.net, registry.npmjs.org, your environment and github.com (for templates);
  • free ports: 3000 to 3005 for the dev server, 30000 for local execution of app functions, 5343 for SSO authentication (the toolkit tries the next port if it is busy).

On a corporate workstation the network line is the one that fails first: ask for the four hosts to be opened before losing an hour on an installation error.

Creating the app: the minimal loop

The « First app in 5 minutes » tutorial gives this path. These are the steps in the order I would run them.

  1. In your editor’s terminal, run npx dt-app@latest create.
  2. Name the app, for example my-first-app, then enter the environment address (the command may prefill it if you are already signed in).
  3. Move into the folder: cd my-first-app.
  4. Start the local server: npx dt-app dev. The app opens in the browser.
  5. Open ui/app/pages/Home.tsx, change the text of the Heading element to « My first app » and save: the browser refreshes on its own.

Terminal listing the dt-app commands: node --version, create, cd, dev, deploy --dry-run and deploy

This image is an assembly of commands taken from the documentation, not a recorded session. Mind the browser detail: the documentation says Chrome 142 or later asks for permission to connect to devices on your local network; if the page stays blank, look for that prompt first.

What the vendor’s post stresses is the speed of the loop. It reports rebuilds dropping from about 2.7 seconds to 0.05 seconds thanks to change detection (only modified components are rebuilt and checked), and incremental type checking that only revisits changed files and their dependencies. Those figures are the vendor’s; span.observer has not measured them.

Reading the generated folder and the configuration

Version 1.x of the toolkit separates the interface from app functions. The workspace described in the documentation looks like this:

Layout of an App Toolkit 1.x workspace: ui folder with main.tsx and tsconfig.json, documents folder, app.config.json file and .dt-app/logs folder

The file to know is app.config.json (or app.config.ts). At the top level, environmentUrl is required. Under app, the documentation requires id (lowercase, dot-separated namespace), name, version, description and scopes.

Example app.config.json with environmentUrl, then app holding id, name, version, description and empty scopes

The example above is built from the documented fields with placeholder values: the environment ID abc12345 does not exist and your scopes depend on what the app will read. The version field deserves a team rule: bump it on every deployment, it is your rollback reference.

Deploying without surprises: dry run, then deploy

The dev server shares nothing. For colleagues to see the app, you must deploy it. npx dt-app deploy builds and deploys to the configured environment. Two useful options, according to the documentation:

  • --dry-run creates a distributable .zip archive in out/ without deploying: this is the check to make before a first production release;
  • --skip-build reuses an existing build, handy when a pipeline has already built the app.

To remove the app, dt-app uninstall exists too, with its own --dry-run. What the documentation I read does not detail is the exact interactive sign-in flow and what appears in the environment after deployment. I therefore do not describe it; follow the « deploy your app » guide on the developer site.

Automating: the part that matters for on-call

The post stresses a point useful to SRE teams: every command can run in scripts or pipelines, with arguments and options on the command line instead of interactive prompts. The documentation gives the levers: the --non-interactive option, and environment variables. DT_APP_PLATFORM_TOKEN skips the default authentication flow; DT_APP_OAUTH_CLIENT_ID and DT_APP_OAUTH_CLIENT_SECRET automate SSO token retrieval, which helps in continuous integration. These secrets must never enter the repository: keep them in your CI tool’s vault.

Two more maintenance commands: dt-app update updates packages, and dt-app migration execute helps move between versions (options --from and --to). Schedule an update each quarter rather than doing it in an emergency. If you already manage your platform as code, the logic matches Terraform for alerts and dashboards: the app becomes a versioned artefact like the others. And to understand how the data behind your pages is identified, see the article on the entity ID.

Best practices

  • One named owner and one repository per app, with code review as for any service.
  • Minimal scopes, reviewed with every new page.
  • A deploy --dry-run before any production release, and the version bumped.
  • CI secrets kept out of the repository; DT_APP_DISABLE_TELEMETRY=1 exists if your policy forbids the toolkit’s telemetry.
  • Start with one simple page that reads a single DQL query, then extend.

Frequently asked questions

Which Node.js version does the Dynatrace App Toolkit need?

The documentation states Node.js 24. Check it with node --version before running npx dt-app@latest create.

Does the toolkit work with Dynatrace Managed?

The sources I read refer to apps.dynatrace.com environments, so SaaS. Nothing was verified for Managed: this article does not claim it.

Can the commands run in CI without interaction?

Yes, according to the documentation: the --non-interactive option and the DT_APP_OAUTH_CLIENT_ID and DT_APP_OAUTH_CLIENT_SECRET variables are meant for this. Test with --dry-run first.

Conclusion

Building a Dynatrace app is a maintenance decision before it is a technical one. If the answer is yes, the create, dev, deploy --dry-run, deploy loop fits in five commands. For the official detail, read the vendor’s post on App Toolkit 1.0 and the developer documentation.

span.observer is an independent community blog, not affiliated with Dynatrace LLC. Trademarks belong to their owners. Tools change fast: check commands and options against the official documentation.


Originally published on span.observer. French version: https://span.observer/fr/dynatrace-app-toolkit-demarrer-pas-a-pas/.

Top comments (0)