--- name: dtctl description: Use dtctl CLI tool for querying observability data in Dynatrace via DQL (logs, metrics, traces, ...) and to manage Dynatrace platform resources (workflows, dashboards, notebooks, SLOs, settings, buckets, lookup tables). license: Apache-2.0 --- # dtctl Command Reference ## Syntax ```bash dtctl [name\/id] [flags] ``` **Verbs:** get, describe, create, edit, apply, delete, exec, query, logs, wait, history, restore, share\/unshare **Key Resources:** workflow (wf), dashboard (dash), notebook (nb), slo, bucket (bkt), lookup (lkup), settings, analyzer (az), copilot (cp) **Global Flags:** - `--context` - Switch environment - `-o, --output` - json|yaml|table|wide|csv|chart|sparkline|barchart - `--dry-run` - Preview without executing - `--plain` - Machine-readable output ## Setup ```bash # Configure context dtctl config set-context prod --environment "https:\/\/abc.apps.dynatrace.com" --token-ref prod-token --safety-level readonly dtctl config set-credentials prod-token --token "dt0s16.YOUR_TOKEN" dtctl config use-context prod # Safety levels: readonly | readwrite-mine | readwrite-all | dangerously-unrestricted ``` ## Common Commands ### Workflows ```bash dtctl get workflows --mine dtctl edit workflow dtctl apply -f workflow.yaml --set env=prod dtctl exec workflow --wait --timeout 10m dtctl logs wfe --follow dtctl history workflow ``` ### Dashboards\/Notebooks ```bash dtctl get dashboards --mine dtctl edit dashboard dtctl share dashboard --user user@example.com --access read-write dtctl history dashboard dtctl restore dashboard 3 ``` ### DQL Queries ```bash dtctl query "fetch logs | filter status='ERROR' | limit 100" dtctl query -f query.dql --set host=h-123 --set timerange=2h dtctl query "timeseries avg(dt.host.cpu.usage)" -o chart dtctl wait query "fetch spans | filter test_id == 'test-123'" --for=count=1 --timeout 5m ``` **Wait conditions:** count=N, count-gte=N, count-gt=N, count-lte=N, count-lt=N, any, none **Template syntax in .dql files:** ```dql fetch logs | filter host.name = "{{.host}}" | filter timestamp > now() - {{.timerange | default "1h"}} ``` ### Lookup Tables ```bash dtctl create lookup -f data.csv --path \/lookups\/grail\/pm\/errors --lookup-field code dtctl get lookups dtctl get lookup \/lookups\/grail\/pm\/errors -o csv > backup.csv # Use in DQL dtctl query "fetch logs | lookup [load '\/lookups\/grail\/pm\/errors'], lookupField:status_code" ``` ### Settings API ```bash dtctl get settings-schemas | grep openpipeline dtctl get settings --schema builtin:openpipeline.logs.pipelines dtctl edit setting dtctl apply -f config.yaml --set env=prod ``` ### SLOs ```bash dtctl get slos dtctl describe slo dtctl exec slo -o json dtctl apply -f slo.yaml ``` ### Davis AI ```bash dtctl get analyzers dtctl exec analyzer dt.statistics.GenericForecastAnalyzer --query "timeseries avg(dt.host.cpu.usage)" -o chart dtctl exec copilot "What caused the CPU spike?" dtctl exec copilot nl2dql "show error logs from last hour" ``` ## Template Variables ```bash # In YAML files: {{.variable}} or {{.variable | default "value"}} dtctl apply -f workflow.yaml --set environment=prod --set owner=team-a ``` ## Troubleshooting ```bash dtctl auth whoami # Check auth dtctl auth can-i create workflows # Check permissions dtctl config set-credentials --token "dt0s16.NEW_TOKEN" dtctl --help # Command help ``` **Name resolution:** Use IDs instead of names if ambiguous (`dtctl get dashboards` to find ID) **Safety blocks:** Adjust context safety level or switch context **Permissions:** Check token scopes at https:\/\/github.com\/dynatrace-oss\/dtctl\/blob\/main\/docs\/TOKEN_SCOPES.md