DQL Smartscape designa los comandos que consultan la topología almacenada en Grail: smartscapeNodes para las entidades, smartscapeEdges para las relaciones y traverse para pasar de un nodo a sus vecinos. Durante un incidente, responden con una sola consulta a preguntas que antes exigían varias pantallas: ¿en qué hosts se ejecuta este proceso?, ¿qué servicios pertenecen a este namespace?, ¿qué volúmenes están asociados a estas instancias?
Esta guía presenta el modelo (nodos, aristas, duración de vida), la sintaxis exacta de los tres comandos y de las funciones de enriquecimiento, y después consultas de operación. Todas las sintaxis citadas proceden de las páginas «DQL Smartscape commands» y «Smartscape on Grail» de la documentación oficial, consultadas en octubre de 2026.
Smartscape on Grail es una funcionalidad de Dynatrace SaaS. Dynatrace Managed no tiene Grail ni DQL; allí la topología se consulta en el Smartscape clásico y mediante el selector de entidades de la API. Si DQL es nuevo para ti, empieza por los comandos DQL comentados.
El modelo de DQL Smartscape: nodos, aristas, duración de vida
- Nodos: cada entidad tiene un campo
typeen mayúsculas (HOST,K8S_NAMESPACE,AWS_EC2_INSTANCE…) y un identificador de Smartscape con la formaENTITY_TYPE-000000000000007B, comparable a una cadena de texto. - Aristas: una relación tiene un tipo (
runs_on,calls,belongs_to…) y une dos nodos. Las aristas estáticas, derivadas de la configuración, heredan la duración de vida del nodo; las aristas dinámicas, derivadas de las señales (un servicio que llama a otro según las trazas), se registran en un instante dado. - Duración de vida: un nodo no tiene una única marca de tiempo sino dos campos,
lifetime.startylifetime.end. Una consulta solo ve los nodos cuya duración de vida se solapa con su período.
Tres puntos de la documentación que conviene recordar: un período de consulta que empieza hace menos de 15 minutos se amplía automáticamente a 15 minutos; la retención es de 35 días; los datos de Smartscape están incluidos en la licencia DPS, sin coste de consulta adicional. El permiso necesario es storage:smartscape:read, que cubre smartscapeNodes, smartscapeEdges, getNodeName() y getNodeField().
Paso a paso: consultar la topología
Paso 1 — Listar los tipos de nodo presentes
smartscapeNodes "*"
| fields type
| dedup type
El parámetro type acepta un tipo exacto sin comillas (HOST), una lista entre llaves ({ HOST, PROCESS }) o un patrón entre comillas con * ("*EC2*"). Un patrón admite como máximo 64 comodines, y dos comodines consecutivos (**) no son compatibles. Los parámetros opcionales from, to y timeframe fijan el período.
Paso 2 — Filtrar nodos
smartscapeNodes HOST
| fields id, type
| limit 10
Cada nodo tiene un campo tags. Las etiquetas de la nube y de Kubernetes se almacenan allí de forma distinta a como están en los logs: la documentación da, por ejemplo, aws.tags.team, que pasa a ser tags:aws[team], y las labels de pod o de workload, que pasan a ser tags:k8s.labels[*].
Paso 3 — Consultar las aristas
smartscapeEdges "*"
| filter source_type == "K8S_POD"
| summarize by:{type, target_type}, edges = count()
Cada arista expone type, source_id, source_type, target_id y target_type. Esta consulta de la documentación elabora el inventario de las relaciones que parten de los pods; para la sintaxis de la agrupación, consulta DQL group by.
Paso 4 — Recorrer la topología con traverse
Sintaxis documentada:
traverse edgeType, …, targetType, … [, direction] [, fieldsKeep: field, …] [, nodeId]
direction vale forward (por defecto) o backward. traverse sigue a un comando smartscapeNodes y lee el identificador del nodo de origen en el campo id, salvo que nodeId designe otro. Devuelve los nodos de destino con un campo dt.traverse.history: un array de registros, uno por recorrido, que contiene por defecto id, edge_type y direction, más los campos listados en fieldsKeep.

El sentido importa. Un proceso se ejecuta en un host: se parte del proceso y se sigue runs_on hacia delante. Para listar los servicios de un namespace, se parte del namespace y se remonta belongs_to hacia atrás:
smartscapeNodes K8S_NAMESPACE
| filter tags[`example.com/annotation`] == "my-annotation"
| traverse belongs_to, K8S_SERVICE, direction: backward
Varios tipos de arista y de destino se combinan entre llaves, como en este ejemplo oficial:
smartscapeNodes CONTAINER
| filter k8s.workload.kind == "daemonset"
| traverse {runs_on, belongs_to}, {HOST, K8S_CLUSTER}, fieldsKeep:name
| fields container_name = dt.traverse.history[0][name], node_name = name, node_type = type
Paso 5 — Enriquecer logs, spans y métricas
Las señales asociadas a un nodo llevan campos dt.smartscape.<type>. Dos funciones recuperan la información del nodo:
fetch bizevents
| fieldsAdd getNodeName(dt.smartscape.host)
timeseries avg(dt.host.cpu.idle), by:{ dt.smartscape.host }
| fieldsAdd getNodeField(dt.smartscape.host, "tags")
La documentación recomienda getNodeField en lugar de entityAttr. La siguiente imagen resume las equivalencias con el modelo de entidades clásico.

Los tipos de nodo a veces difieren del modelo clásico: CLOUD_APPLICATION_INSTANCE se llama K8S_POD en Smartscape on Grail. El campo id_classic da el identificador clásico correspondiente, cuando existe (entidades de Kubernetes, entidades básicas y servicios).
Consultas útiles en operación
- Radio de impacto: partir de un host caído y remontar
runs_onenbackwardpara listar lo que se ejecuta en él. - Inventario por equipo: filtrar los nodos por una etiqueta de propietario y recorrer hacia los recursos vinculados, como el ejemplo oficial de los volúmenes EC2 asociados a las instancias de un equipo.
- Recuento por host:
smartscapeNodes CONTAINER | summarize by:references[runs_on.host], count()usa el campo ocultoreferences, que expone las aristas estáticas desde el nodo de origen.
Estas consultas reducen el MTTR: la pregunta «¿qué depende de este componente?» obtiene una respuesta verificable, compartida en un Notebook, en lugar de una reconstrucción de memoria.
Cómo comprobar que la consulta es correcta
- Ejecuta
smartscapeNodes "*" | fields type | dedup type: deben aparecer los tipos esperados. Si no, comprueba el permisostorage:smartscape:read. - Antes de un
traverse, lista las aristas reales:smartscapeEdges "*" | filter source_type == "PROCESS" | summarize by:{type, target_type}, edges = count(). Un resultado vacío trastraversesuele deberse a una dirección invertida. - Amplía el período si falta un nodo: un nodo cuyo
lifetime.endes anterior al período no aparece.
Buenas prácticas
- Parte siempre del nodo más filtrado y luego recorre: menos nodos de entrada, resultado más legible.
- Conserva el nombre del nodo de origen con
fieldsKeeppara no perder el contexto. - Prefiere los tipos exactos a los patrones
"*"en las consultas de dashboard. - Protege los campos sensibles (por ejemplo
k8s.object) con un fieldset sobre la tablasmartscape, como describe la documentación. - Para la estrategia de conjunto, conecta estas consultas con tus consultas DQL de operación.
Preguntas frecuentes
¿Qué diferencia hay entre fetch dt.entity.host y smartscapeNodes HOST?
fetch dt.entity.host lee el modelo de entidades clásico; smartscapeNodes HOST lee Smartscape on Grail. Solo este último permite consultar todos los tipos a la vez ("*"), todas las relaciones y recorrer la topología con traverse.
¿Se puede usar un selector de entidades en Smartscape on Grail?
No: la documentación indica que classicEntitySelector no es compatible allí. El recorrido se hace con traverse. Para filtrar por una lista de identificadores, consulta la función DQL in().
¿Cuánto tiempo se conserva la topología?
35 días. Los nodos cuyo lifetime.end supera esa duración se eliminan junto con sus aristas estáticas; las aristas dinámicas se limpian en el mismo plazo.
Conclusión
DQL Smartscape se resume en tres comandos: smartscapeNodes para encontrar, smartscapeEdges para inventariar las relaciones, traverse para seguir una dependencia. Con getNodeName y getNodeField para enriquecer las señales, la topología se convierte en un dato que se consulta, se verifica y se comparte, en lugar de un esquema que se mira. Para situar estas consultas en un enfoque más amplio, consulta observabilidad vs monitorización.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Las marcas citadas pertenecen a sus propietarios. La sintaxis de DQL evoluciona: comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión antes de usarla en producción.