DQL Smartscape: consulta la topología con smartscapeNodes, smartscapeEdges y traverse

DQL Smartscape: consulta la topología con smartscapeNodes, smartscapeEdges y traverse, y enriquece logs y métricas con consultas verificadas.
DQL Smartscape : interroger la topologie avec smartscapeNodes, smartscapeEdges et traverse

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 type en mayúsculas (HOST, K8S_NAMESPACE, AWS_EC2_INSTANCE…) y un identificador de Smartscape con la forma ENTITY_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.start y lifetime.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.

Ejemplo de la documentación DQL: smartscapeNodes PROCESS filtrado por el binario envoy, traverse runs_on hacia HOST con fieldsKeep name, y luego fields process_name y host_name, con la sintaxis de traverse y sus dos direcciones
Source : docs.dynatrace.com

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.

Equivalencias documentadas entre entidades clásicas y Smartscape on Grail: smartscapeNodes asterisco, smartscapeNodes HOST en lugar de fetch dt.entity.host, smartscapeEdges asterisco, dt.smartscape en lugar de dt.entity, getNodeName y getNodeField en lugar de entityName y entityAttr
Source : docs.dynatrace.com

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_on en backward para 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 oculto references, 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

  1. Ejecuta smartscapeNodes "*" | fields type | dedup type: deben aparecer los tipos esperados. Si no, comprueba el permiso storage:smartscape:read.
  2. Antes de un traverse, lista las aristas reales: smartscapeEdges "*" | filter source_type == "PROCESS" | summarize by:{type, target_type}, edges = count(). Un resultado vacío tras traverse suele deberse a una dirección invertida.
  3. Amplía el período si falta un nodo: un nodo cuyo lifetime.end es 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 fieldsKeep para 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 tabla smartscape, 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.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
DQL fonction in() : filtrer sur une liste, un tableau ou une sous-requête

Función in de DQL: filtrar por una lista, un array o una subconsulta

Next Post
Formation observabilité gratuite : le chemin complet, des signaux aux SLO

Formación en observabilidad gratuita: el camino completo, de las señales a los SLO

Related Posts