Tres servicios llamados unknown_service:python, trazas imposibles de asociar a un pod, atributos de negocio invisibles en las consultas: la mayoría de las decepciones tras una primera ingesta OTLP vienen de los atributos. Definir bien los atributos OpenTelemetry Dynatrace usa para construir sus entidades es la diferencia entre un mapa de servicios legible y un montón de spans huérfanos.
Objetivo: al terminar este tutorial, tus servicios OTel llevan los atributos de recurso estándar, el Collector los enriquece con el contexto de Kubernetes y del host, y sabes comprobar qué atributos se almacenan realmente y se pueden consultar. El contenido sirve para Dynatrace SaaS (Grail, DQL) y Dynatrace Managed. La gestión de los atributos de span difiere entre ambos: se señala en el paso correspondiente.
Para la arquitectura del Collector, consulta el Collector de OpenTelemetry en Kubernetes.
El problema: datos sin identidad
Un span sin un service.name correcto no se asocia a ningún servicio útil. Un span sin atributos de Kubernetes no lleva al pod que ha fallado. Durante un incidente, el equipo de guardia pierde minutos adivinando «quién» ha producido el dato, y el MTTR se resiente. Los atributos de recurso responden a esa pregunta de una vez por todas.
Requisitos previos
- Aplicaciones instrumentadas con un SDK de OpenTelemetry (por ejemplo el agente de OpenTelemetry para Java).
- Un Collector
otelcol-contribo una distribución que incluyak8sattributes,resourcedetection,resourceytransform. En las versiones recientes del Collector contrib,k8sattributesyresourcedetectionse llamank8s_attributesyresource_detection; los nombres antiguos, usados a continuación, se siguen aceptando como alias obsoletos. - Un token de Dynatrace con los scopes de ingesta OTLP (trazas, métricas, logs).
Recurso o span: dos niveles de atributos
- Atributos de recurso: describen al emisor y valen para toda la telemetría de un proceso. Ejemplos:
service.name,service.version,deployment.environment,k8s.pod.name,host.name. - Atributos de span: describen una operación. Ejemplos:
http.request.method,db.system,order.id.
Regla simple: lo que no cambia durante la vida del proceso va en el recurso. Así, las trazas, las métricas y los logs comparten las mismas claves, lo que hace posible la correlación.
Configurar los atributos OpenTelemetry Dynatrace paso a paso
Paso 1: definir los atributos de recurso en la aplicación
# extrait d'un Deployment Kubernetes
env:
- name: OTEL_SERVICE_NAME
value: "checkout"
- name: POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: OTEL_RESOURCE_ATTRIBUTES
value: "service.version=2.3.0,service.namespace=shop,deployment.environment=prod,k8s.pod.name=$(POD_NAME)"
Líneas críticas: OTEL_SERVICE_NAME prevalece sobre un service.name colocado en OTEL_RESOURCE_ATTRIBUTES. La sintaxis $(POD_NAME) la resuelve Kubernetes, siempre que la variable se declare antes. Nota: las convenciones semánticas recientes renombran deployment.environment como deployment.environment.name; elige una clave y mantenla en todas partes.
Paso 2: enriquecer en el Collector
El Collector añade lo que la aplicación desconoce: namespace, nodo, workload, nube.
processors:
k8sattributes:
auth_type: serviceAccount
passthrough: false
extract:
metadata:
- k8s.namespace.name
- k8s.deployment.name
- k8s.pod.name
- k8s.pod.uid
- k8s.node.name
pod_association:
- sources:
- from: resource_attribute
name: k8s.pod.uid
- sources:
- from: connection
resourcedetection:
detectors: [env, system]
timeout: 2s
override: false
resource:
attributes:
- key: k8s.cluster.name
value: "prod-eu-1"
action: upsert
k8sattributes exige un ServiceAccount con los permisos get, list y watch sobre pods, namespaces y ReplicaSets. override: false impide que la detección sobrescriba valores ya definidos por la aplicación.
Paso 3: enriquecimiento de Dynatrace en los hosts con OneAgent
Si OneAgent se ejecuta en el host, puede proporcionar archivos de enriquecimiento con atributos como dt.entity.host, que asocian la telemetría de OTel a las entidades descubiertas por OneAgent. La ruta y el formato de estos archivos se describen en la documentación de Dynatrace (apartado sobre el enriquecimiento de datos de OpenTelemetry): compruébalos para tu versión en lugar de escribirlos a fuego en el código. Sin OneAgent, la identidad depende únicamente de los atributos de los pasos 1 y 2.
Paso 4: limpiar los atributos sensibles e inútiles
Elimina los datos personales y los atributos de alta cardinalidad antes de exportar:
processors:
transform/clean:
error_mode: ignore
trace_statements:
- context: span
statements:
- delete_key(attributes, "user.email")
- replace_pattern(attributes["url.full"], "token=[^&]+", "token=***")
batch: {}
service:
pipelines:
traces:
receivers: [otlp]
processors: [k8sattributes, resourcedetection, resource, transform/clean, batch]
exporters: [otlphttp/dynatrace]
Paso 5: entender la allow-list de atributos de span
Dynatrace no trata todos los atributos de span de la misma forma según el despliegue:
- Dynatrace Managed (y SaaS sin almacenamiento de spans en Grail): los atributos de span personalizados deben autorizarse explícitamente en los ajustes del entorno (una lista de atributos permitidos en la sección de monitorización de servicios del lado del servidor; la etiqueta exacta depende de la versión). Un atributo que no está en la lista no se conserva. También existen opciones de enmascaramiento.
- Dynatrace SaaS con Grail: los atributos se almacenan, por lo general, junto con los spans y se pueden consultar con DQL, sujetos a las reglas de procesamiento y de enmascaramiento configuradas (OpenPipeline, ajustes de privacidad).
El comportamiento exacto evoluciona: consulta la página de la documentación de Dynatrace dedicada a los atributos de span para tu entorno. Los atributos de recurso estándar sirven, en ambos casos, para identificar el servicio.
Cómo comprobar que funciona
- En el Collector: añade temporalmente el exportador
debugconverbosity: detailedy lee los atributos de recurso en los logs del Collector. - Dynatrace SaaS: comprueba la presencia de los atributos en un notebook:
fetch spans, from: now() - 30m | filter service.name == "checkout" | fields start_time, span.name, service.version, k8s.namespace.name, k8s.pod.name | limit 20Una columna vacía indica un atributo no definido o no conservado.
- Dynatrace Managed: abre una traza distribuida del servicio y consulta los atributos del span; un atributo personalizado ausente debe añadirse primero a la lista de permitidos.
- Nombre del servicio: si aparece
unknown_service, el proceso no está leyendoOTEL_SERVICE_NAME.
Buenas prácticas
- Un nombre de servicio estable y único por componente; la versión en
service.version, nunca en el nombre. - Los mismos atributos de recurso en trazas, métricas y logs, para pasar de una señal a otra (consulta logs de OpenTelemetry con trace_id).
- Ningún identificador de usuario ni valor de alta cardinalidad en los atributos de recurso.
- Filtra tus SLO por
deployment.environmentpara no mezclar pruebas y producción (consulta SLO de OpenTelemetry con DQL). - Documenta la convención de atributos del equipo: menos toil con cada servicio nuevo.
Preguntas frecuentes
¿Por qué aparece mi servicio dos veces?
A menudo porque coexisten dos valores de service.name, o porque OneAgent y el SDK de OTel instrumentan el mismo proceso. Armoniza el nombre y revisa los duplicados.
¿Hay que poner un prefijo a mis atributos de negocio?
Sí, un espacio de nombres propio (shop.order.id) evita colisiones con las convenciones semánticas actuales y futuras.
¿Funciona el procesador k8sattributes fuera de Kubernetes?
No. Fuera de Kubernetes, usa resourcedetection con los detectores adecuados (sistema, nube) y el procesador resource.
Conclusión
Los atributos de recurso son la identidad de tu telemetría. Defínelos en la aplicación, enriquécelos en el Collector, límpialos antes de exportar y comprueba lo que conserva Dynatrace, tanto en SaaS como en Managed. Referencias: las convenciones semánticas de recurso y la documentación de Dynatrace sobre OpenTelemetry.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión.