This document is the consumer guide for onboarding a new application to Dynatrace through the Observability-as-Code repository.
The Payment application is the reference implementation. Application teams should not install Monaco on application servers. Monaco runs from the CI/CD agent and deploys configuration to Dynatrace SaaS.
The repository separates three concerns:
The data path and the configuration path are different:
DATA PATH
Java application -> OneAgent -> Environment ActiveGate -> Dynatrace SaaS
CONFIGURATION PATH
Git -> Azure DevOps -> Monaco -> Dynatrace SaaS APIs
Before opening an onboarding PR, collect the following information:
dev, test, qa, staging, or prod)The Observability Platform team owns Dynatrace credentials, Monaco execution, naming standards, ActiveGate connectivity and platform-wide policy.
Copy:
payment-onboarding/application-template.yaml
to a new file using this naming convention:
payment-onboarding/<application>-<environment>.yaml
Example for an Order application:
payment-onboarding/order-prod.yaml
Example content:
application: order
environment: prod
team: order-management
owner: order-platform
criticality: high
aws:
account_id: "123456789012"
region: eu-west-1
platform: ec2
runtime:
technology: java
service_name: order-service
hosts:
inventory_group: order_prod
dynatrace:
host_group: order-prod
network_zone: aws-prod-eu-west-1
management_zone: order-prod
tags:
application: order
environment: prod
team: order-management
criticality: high
monitoring:
oneagent: true
monitoring_mode: fullstack
logs: true
tracing: true
slo:
availability:
enabled: true
target: 99.9
warning: 99.95
timeframe: now-7d
maintenance:
enabled: false
name: order-prod-weekly-maintenance
timezone: Europe/Amsterdam
recurrence: weekly
day: Sunday
start: "02:00"
duration_minutes: 60
alerting:
profile: order-prod
severity: high
Do not put passwords, API tokens, platform tokens, SSH keys or OAuth secrets in the onboarding file.
Use stable names that survive host replacement and Auto Scaling.
Recommended conventions:
host group = <application>-<environment>
management zone = <application>-<environment>
network zone = <cloud>-<environment>-<region>
application tag = application:<application>
environment tag = environment:<environment>
team tag = team:<team>
criticality tag = criticality:<criticality>
Payment example:
host group = payment-prod
management zone = payment-prod
network zone = aws-prod-eu-west-1
application tag = application:payment
Do not use EC2 instance IDs, IP addresses or Dynatrace entity IDs as the reusable application identity.
From the Dynatrace directory:
python3 -m pip install -r scripts/requirements.txt
python3 scripts/validate-onboarding.py payment-onboarding/payment-prod.yaml
For another application:
python3 scripts/validate-onboarding.py payment-onboarding/order-prod.yaml
The same validation runs automatically in Azure DevOps.
The Payment reference playbook is:
ansible/install-oneagent.yaml
It installs OneAgent with:
host group = payment-prod
network zone = aws-prod-eu-west-1
mode = fullstack
host tags = application=payment, environment=prod, team=payments, criticality=critical
The OneAgent installer URL/token must come from pipeline secrets or an approved internal artifact repository.
For another application, copy the Payment playbook or convert it into your organization’s centrally-generated playbook and change only approved metadata. Do not create a new ActiveGate per application unless network/security architecture requires it. Applications in the same approved network zone can normally use the same highly available ActiveGate tier.
The role intentionally does not automatically change host groups on an already monitored host. A host-group change can affect process-group identity and monitored-service lifecycle. Treat host-group migration as a reviewed change.
Monaco uses three building blocks:
manifest.yaml
|
+--> project
|
+--> config.yaml
+--> JSON templates
The current Payment project is:
monaco/
├── manifest.yaml
└── payment/
├── config.yaml
├── auto-tag.json
├── management-zone.json
├── maintenance-window.json
└── slo.json
For a new application, create a sibling project:
monaco/order/
Copy the Payment project as a starting point and replace Payment-specific values with the new application’s approved values.
Then add the project to monaco/manifest.yaml:
projects:
- name: payment
path: payment
- name: order
path: order
Do not hardcode Dynatrace credentials in the manifest. The manifest reads the environment URL and platform token from environment variables supplied by the pipeline.
The Payment project creates an application:payment tag through builtin:tags.auto-tagging.
The reference rules use stable host-group and service-name selectors. For another application, verify the actual Dynatrace service name after OneAgent discovers the Java process and update the selector accordingly.
A production platform should prefer stable application metadata over names where possible. If your organization enriches processes/services with standardized metadata, build the automatic-tag rule from that metadata instead of brittle display names.
The Payment management zone is payment-prod and is built from the application tag.
This provides a reusable scope for application-specific views and related classic configuration. Management zones should not be treated as the only security mechanism for Grail data; use current Dynatrace IAM/data-access controls where data authorization is required.
The Payment example configures a weekly planned window:
Sunday 02:00-03:00 Europe/Amsterdam
The window references the management zone created by the same Monaco project. This is preferable to hardcoding a Dynatrace object ID because Monaco can resolve the reference during deployment.
If an application has no recurring maintenance requirement, omit/skip the maintenance configuration rather than creating a meaningless window.
The Payment reference SLO evaluates service availability for entities tagged:
application:payment
with:
target = 99.95
warning = 99.97
window = 7 days
Before production deployment, validate that the selected service(s) are correct and that the metric expression represents the application’s actual success definition. For payment systems, a business SLI based on successful payment transactions may be more meaningful than a generic HTTP success ratio.
The pipeline runs:
cd monaco
monaco deploy --dry-run manifest.yaml
This belongs on the Azure DevOps agent, not on the Payment EC2 server or ActiveGate server.
A dry run validates the Monaco manifest, project structure and configuration parameter resolution without applying the configuration.
Important: dry run is not a guarantee that every target Dynatrace API will accept every object. The production deploy still needs controlled credentials, target-environment validation and review.
After validation, the deployment stage runs:
monaco deploy manifest.yaml
The Azure pipeline uses a deployment job bound to:
dynatrace-production
Configure required approvers/checks on that Azure DevOps Environment. Do not fake approval by putting a password or manual flag in repository YAML.
Recommended flow:
Pull Request
|
v
Validate onboarding YAML
|
v
Validate Ansible
|
v
Monaco dry-run
|
v
Merge / controlled production run
|
v
Azure DevOps Environment approval
|
v
Monaco deploy
|
v
Post-deployment verification
Create the following outside Git:
Observability-Linux
The self-hosted Linux agent should have:
Create:
dynatrace-prod
with at least:
DT_ENV_URL = https://<environment>.apps.dynatrace.com
PLATFORM_TOKEN = <secret>
Keep PLATFORM_TOKEN secret.
For OneAgent installation, also provide secure pipeline variables such as:
DT_ONEAGENT_INSTALLER_URL
DT_ONEAGENT_INSTALLER_TOKEN
Create:
dynatrace-production
and configure approvals/checks for the Observability Platform team.
Before requesting review, confirm:
For Payment, the intended sequence is:
1. Deploy/verify Environment ActiveGate in aws-prod-eu-west-1
2. Confirm security-group connectivity from Payment EC2 to ActiveGate
3. Run onboarding validation
4. Run Ansible to install OneAgent
5. Verify payment-prod host group and aws-prod-eu-west-1 network zone
6. Restart the Java workload if required for full deep monitoring after initial install
7. Verify payment-service discovery in Dynatrace
8. Run Monaco dry-run
9. Review PR
10. Obtain production environment approval
11. Run Monaco deploy
12. Verify application:payment tag
13. Verify payment-prod management zone
14. Verify maintenance window
15. Verify SLO scope and data
Do not copy production credentials into development configuration. Extend manifest.yaml with separate environment groups and separate environment variables/tokens, for example:
development -> DT_DEV_ENV_URL / DEV_PLATFORM_TOKEN
production -> DT_ENV_URL / PLATFORM_TOKEN
Use separate Azure DevOps variable groups and protected Environments per lifecycle stage.
The Payment project is intentionally understandable rather than fully generated. For tens or hundreds of applications, the next step is to generate Monaco and Ansible inputs from the onboarding contract instead of manually copying projects.
A mature implementation can evolve toward:
application-onboarding.yaml
|
+--> schema validation
+--> generated OneAgent variables
+--> generated Monaco parameters
+--> policy checks
+--> approval
+--> deployment
Keep the onboarding YAML as the application team’s contract and keep Dynatrace implementation details owned by the Observability Platform team.