ID de entidad de Dynatrace: encuéntralo en un Notebook, con la API entitySelector o en DQL

ID de entidad de Dynatrace: encuéntralo con la API entities y un entitySelector preciso, en DQL desde un Notebook, y evita las trampas de nombre y ventana.
ID entité Dynatrace : le trouver dans un Notebook, par l'API entitySelector ou en DQL

El ID de entidad de Dynatrace es la clave que reclaman casi todas las automatizaciones: scope de un objeto de Settings, filtro de un SLO, selector de una alerta, parámetro de un módulo de Terraform o Monaco. Un nombre de host o de servicio no basta: cambia, se repite de un entorno a otro y no es único. El ID, en cambio, designa una entidad precisa, por ejemplo SERVICE-1125C375A187D27A.

Encontrarlo debería llevar diez segundos. En la práctica, se pierde a menudo tiempo copiando un identificador equivocado, recuperando cincuenta resultados en lugar de uno, o escribiendo una consulta que solo funciona en una plataforma. Menos toil aquí significa runbooks más fiables y automatizaciones que no se rompen al primer cambio de nombre.

Esta guía cubre tres métodos: la API Monitored entities v2 con un entitySelector (Managed y SaaS), DQL en un Notebook (solo SaaS, Grail) y el paso de uno a otro con classicEntitySelector().

Qué es un ID de entidad de Dynatrace

Cada objeto monitorizado (host, proceso, servicio, aplicación, test sintético…) es una entidad, con un tipo y un identificador. El ID tiene la forma TIPO-IDENTIFICADOR: HOST-…, SERVICE-…, HTTP_CHECK-…, SYNTHETIC_TEST-…. El nombre mostrado (displayName en la API, entity.name en DQL) es una etiqueta; lo que esperan las API es el ID.

Ejemplo concreto: para declarar key requests mediante la API de Settings, el campo scope debe contener el ID del servicio, y la documentación remite precisamente a la llamada GET entities list para encontrarlo.

Requisitos previos

  • Para la API: un token con el scope entities.read. Un error 401 o 403 en este punto es cuestión de resolución de problemas de tokens de API.
  • URL base: https://{tu-dominio}/e/{id-entorno} en Managed, https://{id-entorno}.live.dynatrace.com en SaaS. A través de un ActiveGate: https://{dominio-activegate}:9999/e/{id-entorno}.
  • Para DQL (SaaS): el permiso storage:entities:read.

Método 1 — La API y el entitySelector (Managed y SaaS)

Paso 1 — Buscar por tipo y por nombre

La llamada GET /api/v2/entities exige uno de dos criterios: el tipo (type("…")) o el ID (entityId("…")). Después se añade el nombre:

curl -s -G "$DT_URL/api/v2/entities" \
  -H "Authorization: Api-Token $DT_TOKEN" \
  --data-urlencode 'entitySelector=type("SERVICE"),entityName.equals("AuthenticationService")' \
  --data-urlencode 'from=now-7d'

Tres detalles importan:

  • entityName("…") a secas hace un CONTAINS, insensible a mayúsculas por defecto. entityName.equals("…") exige igualdad, entityName.startsWith("…") un prefijo, entityName.in("a","b") una lista. Para una comparación sensible a mayúsculas: caseSensitive(entityName.equals("…")).
  • Sin from, la búsqueda abarca los tres últimos días (now-3d). Una entidad apagada la semana pasada no aparece: amplía la ventana.
  • Si el valor contiene un paréntesis o una coma, ponlo entre comillas.
Respuesta JSON de GET /api/v2/entities tomada de la documentación: totalCount 52, pageSize 50, nextPageKey y dos entidades SERVICE con entityId, displayName, lastSeenTms y serviceTechnologyTypes

La respuesta contiene totalCount, pageSize (50 por defecto) y, si quedan resultados, un nextPageKey. Para la página siguiente, pasa únicamente nextPageKey: la documentación obliga a omitir entonces todos los demás parámetros.

Paso 2 — Afinar cuando el nombre no basta

¿Varios servicios llevan el mismo nombre (uno por entorno de pruebas, uno por clúster)? Combina los criterios; solo se devuelven las entidades que cumplen todos:

# par tag
type("SERVICE"),entityName.equals("checkout"),tag("env:prod")
# par management zone
type("SERVICE"),entityName.equals("checkout"),mzName("Payments")
# par relation : les services qui tournent sur un hôte donné
type("SERVICE"),fromRelationships.runsOnHost(type("HOST"),entityName.equals("web-01"))
# en excluant
type("HOST"),not(tag("Infrastructure:Linux"))

Para saber qué propiedades y relaciones expone un tipo, llama a GET /api/v2/entityTypes/{type} y fíjate en properties, fromRelationships y toRelationships. El parámetro fields añade campos a la respuesta, por ejemplo fields=+lastSeenTms,+properties.serviceTechnologyTypes.

Paso 3 — Extraer el ID limpiamente

curl -s -G "$DT_URL/api/v2/entities" \
  -H "Authorization: Api-Token $DT_TOKEN" \
  --data-urlencode 'entitySelector=type("HOST"),entityName.startsWith("web-")' \
  | jq -r '.entities[] | "\(.entityId)\t\(.displayName)"'

¿Ya tienes un ID y quieres comprobar a qué corresponde? GET /api/v2/entities/{entityId} devuelve el detalle de la entidad, con el mismo scope entities.read.

Límites que conviene tener presentes: un selector tiene como máximo 2000 caracteres y solo apunta a un tipo de entidad por petición. Las entidades eliminadas (tests sintéticos, aplicaciones, custom devices…) se excluyen por defecto; deletedEntities.include() las vuelve a incluir.

Método 2 — DQL en un Notebook (SaaS)

En Dynatrace SaaS, abre un Notebook y escribe fetch dt.entity.: el autocompletado propone los tipos de entidad. Cada registro contiene por defecto el ID y el nombre.

fetch dt.entity.service
| filter entity.name == "AuthenticationService"
| fields id, entity.name

Para descubrir los campos disponibles de un tipo, describe dt.entity.service da la lista. Para filtrar según relaciones, la documentación recomienda reutilizar un selector clásico, más rápido y más completo que los expand/lookup en DQL nativo (limitados a 100 IDs por tipo y por registro):

fetch dt.entity.host
| filter in(id, classicEntitySelector("type(host),toRelationship.isProcessOf(type(PROCESS_GROUP_INSTANCE),softwareTechnologies(JAVA))"))
| fields id, entity.name

Dos advertencias propias de Grail. Primero, Grail no aplica las management zones: quien tenga storage:entities:read ve todas las entidades. Después, desde la versión 1.334, la documentación anuncia una transición hacia el nuevo almacenamiento Smartscape y desaconseja las consultas de entidades clásicas; el modelo Smartscape on Grail se consulta con smartscapeNodes, por ejemplo smartscapeNodes HOST | fields id, type | limit 10. Prueba tus consultas sobre ese modelo antes de fijarlas en un dashboard. Para otras consultas del día a día, consulta las consultas DQL de operación.

Método 3 — En Managed: quedarse en la API

Dynatrace Managed no tiene ni Grail ni DQL. El método documentado sigue siendo la API v2 con el entitySelector: misma sintaxis, mismo scope, misma paginación, con la URL https://{tu-dominio}/e/{id-entorno}/api/v2/entities. El mismo selector sirve después en los SLO, en el metric selector y en las API de configuración, lo que lo convierte en una inversión rentable. El panorama de los endpoints está en las API de Dynatrace Managed.

Buenas prácticas

  • Busca con entityName.equals en lugar de entityName a secas: el CONTAINS por defecto trae homónimos parciales.
  • Comprueba siempre totalCount: un script que espera un resultado debe fallar si recibe dos.
  • Guarda el ID en tu configuración como código, pero conserva al lado el selector que lo produjo para poder regenerarlo.
  • Da al token de búsqueda únicamente el scope entities.read, sin permiso de escritura.

Cómo comprobar que funciona

Repite la llamada con el selector entityId("…") y el ID obtenido: la respuesta debe contener exactamente una entidad, con el displayName esperado y un lastSeenTms reciente. En DQL, fetch dt.entity.service | filter id == "SERVICE-…" debe devolver un único registro. Si no vuelve nada, amplía la ventana de tiempo: puede que la entidad no se haya visto en tres días.

Referencias oficiales: Entity selector y Query monitored entities in Grail.

Preguntas frecuentes

¿Por qué la API no encuentra una entidad que aún veo en un informe antiguo?

Sin el parámetro from, la búsqueda se limita a los tres últimos días. Añade from=now-30d y, para ciertos tipos (tests sintéticos, aplicaciones), deletedEntities.include().

¿Puedo pedir hosts y servicios en la misma llamada?

No, un selector apunta a un solo tipo por petición. Haz dos llamadas, o pasa por una relación (fromRelationships, toRelationships) para obtener el tipo vecino.

¿Filtran las management zones los resultados de DQL?

No. La documentación precisa que Grail no aplica los filtros de management zone a las entidades; es el permiso storage:entities:read el que da acceso al conjunto.

Conclusión

Un buen reflejo: buscar el ID con la API y un selector preciso, comprobar que vuelve un solo resultado y reutilizar ese mismo selector en todos los lugares donde Dynatrace lo acepta. En SaaS, DQL y classicEntitySelector() hacen de puente con los Notebooks, sin perder de vista la transición hacia Smartscape on Grail.

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Las sintaxis y los límites pueden evolucionar según la versión y la plataforma (SaaS o Managed): comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión.

Total
0
Shares
Leave a Reply

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

Previous Post
Key requests Dynatrace : marquer une requête clé et l'utiliser pour alerter

Key requests Dynatrace: marcar una solicitud clave y usarla para alertar

Next Post
Dynatrace Synthetic Recorder, emplacements privés et MFA : le monitoring synthétique avancé

Dynatrace Synthetic Recorder, ubicaciones privadas y MFA: la monitorización sintética avanzada

Related Posts