dynatrace-control

name	dynatrace-control
description	Manage Dynatrace environments using dtctl - install/update the CLI, configure authentication with OS keyring tokens, and run kubectl-style operations (get/describe/edit/apply/delete/query/exec) for workflows, dashboards, notebooks, DQL, SLOs, settings, buckets, lookups, OpenPipeline, and Davis AI. Use when the user wants to control Dynatrace resources via dtctl.

Dynatrace Control with dtctl

Operate dtctl, the kubectl-style CLI for Dynatrace. This skill teaches core dtctl command patterns and operations.

Skill Initialization

CRITICAL: When this skill is loaded, IMMEDIATELY run these commands to display the current context:

# Show current context
dtctl config current-context

# Show context details  
dtctl config describe-context $(dtctl config current-context) --plain

# Show authenticated user
dtctl auth whoami --plain

This displays:

• Current context name and environment URL
• Safety level (readonly, readwrite-mine, readwrite-all, dangerously-unrestricted)
• Authenticated user identity (name, email, UUID)

Prerequisites

If dtctl is not installed or not working, see references/troubleshooting.md for installation and setup.

Resources & Commands

Available Resources

dtctl manages these resource types. Before using a resource, read its reference doc to understand field names, JSON structure, and filtering patterns.

Resource	Aliases	Reference Documentation
analyzer	analyzers	analyzers.md - Davis AI analyzers
app	apps	apps.md - Applications
bucket	bkt	buckets.md - Data buckets
copilot-skill	copilot-skills	copilot-skills.md - Davis CoPilot skills
dashboard	dash	dashboards.md - Dashboards (use .name NOT .title)
edgeconnect	ec	edgeconnect.md - EdgeConnect
function	functions, fn, func	functions.md - App Engine functions
group	groups	groups.md - User groups
intent	intents	- App intents

Command Verbs

Verb	Description	Example
get	List resources	dtctl get workflows --mine
describe	Show resource details	dtctl describe workflow <id>
edit	Edit resource interactively	dtctl edit dashboard <id>
apply	Create/update from file	dtctl apply -f workflow.yaml --set env=prod
delete	Delete resource	dtctl delete workflow <id>
exec	Execute workflow/function/analyzer/copilot	dtctl exec workflow <id>
query	Run DQL query	dtctl query "fetch logs | limit 10"
logs	Print resource logs	dtctl logs workflow-execution <id>
wait	Wait for conditions	dtctl wait query "fetch logs" --for=any
history	Show document history	dtctl history dashboard <id>
restore	Restore document version	dtctl restore dashboard <id> --version 3
share	Share document	dtctl share dashboard <id> --user [e-mail]
unshare	Remove sharing	dtctl unshare dashboard <id> --user [e-mail]
find	Discover resources	dtctl find intents --data trace.id=abc
open	Open in browser	dtctl open intent <app/intent> --data key=value
diff	Compare resources

For detailed command usage, see:

• references/commands.md - All command patterns and examples
• references/copilot.md - Davis CoPilot commands
• references/functions.md - Function execution
• references/analyzers-usage.md - Analyzer execution

Key Concepts for AI Agents

Output Modes

# Machine-readable formats (use these for AI agents)
-o json          # JSON output
-o yaml          # YAML output
-o csv           # CSV output
-o chart         # ASCII chart (for time series)
-o sparkline     # ASCII sparkline (for time series)
-o barchart      # ASCII bar chart (for time series)

# Human-readable formats
-o table         # Table format (default)
-o wide          # Wide table with more columns

# Always use --plain flag for AI consumption
--plain          # Strips colors and prompts, best for parsing

For AI agents, always use: dtctl <command> -o json --plain

Template Variables

In YAML/DQL files, use Go template syntax:

# workflow.yaml
title: "{{.environment}} Deployment"
owner: "{{.team}}"
trigger:
  schedule:
    cron: "{{.schedule | default "0 0 * * *"}}"

# query.dql
fetch logs
| filter host.name == "{{.host}}"
| filter timestamp > now() - {{.timerange | default "1h"}}

Execute with: dtctl apply -f file.yaml --set environment=prod --set team=platform

Authentication & Permissions

# Check current user and permissions
dtctl auth whoami --plain

Quick Reference: DQL Queries

# Inline query
dtctl query "fetch logs | filter status == \"ERROR\" | limit 100" -o json --plain

# Query from file with variables
dtctl query -f query.dql --set host=h-123 --set timerange=2h -o json --plain

# Wait for query results
dtctl wait query "fetch spans | filter test_id='test-123'" --for=count=1 --timeout 5m

# Query with chart output
dtctl query "timeseries avg(dt.host.cpu.usage)" -o chart --plain

For more DQL patterns, load the dt-dql-essentials skill.

Common Issues

Name resolution ambiguity:

• If a name matches multiple resources, dtctl will fail
• Solution: Use IDs instead of names
• Find ID: dtctl get <resource> -o json --plain | jq -r '.[] | "\(.id) | \(.name)"'

Permission denied:

• Check token scopes: https://github.com/dynatrace-oss/dtctl/blob/main/docs/TOKEN_SCOPES.md
• Check safety level: dtctl config describe-context $(dtctl config current-context) --plain

Context/safety blocks:

• Destructive operations may be blocked by safety level
• Switch context: dtctl config use-context <name>
• Adjust safety level when creating context

Additional Resources

• Troubleshooting: references/troubleshooting.md
• Multi-tenant setup: references/config-management.md
• All commands: references/commands.md
• CLI help: dtctl --help, dtctl <command> --help

Safety Reminders

• Use --plain for machine/AI consumption
• Confirm context + safety level before destructive ops; prefer get/describe first
• Use --mine flag to filter resources you own
• For multi-tenant work, see references/config-management.md