Atributos OpenTelemetry Dynatrace: service.name, enriquecimiento y allow-list

Atributos OpenTelemetry Dynatrace: define service.name, enriquece con k8sattributes, gestiona la allow-list de spans y comprueba en SaaS y en Managed.
Attributs OpenTelemetry Dynatrace : service.name, enrichissement et allow-list

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-contrib o una distribución que incluya k8sattributes, resourcedetection, resource y transform. En las versiones recientes del Collector contrib, k8sattributes y resourcedetection se llaman k8s_attributes y resource_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

  1. En el Collector: añade temporalmente el exportador debug con verbosity: detailed y lee los atributos de recurso en los logs del Collector.
  2. 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 20
    

    Una columna vacía indica un atributo no definido o no conservado.

  3. 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.
  4. Nombre del servicio: si aparece unknown_service, el proceso no está leyendo OTEL_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.environment para 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.

Total
0
Shares
Leave a Reply

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

Previous Post
Tail sampling OpenTelemetry avant Dynatrace : maîtriser coûts et volume de traces

Tail sampling OpenTelemetry antes de Dynatrace: controla costes y volumen de trazas

Next Post
Superviser collector OpenTelemetry : sa télémétrie interne dans Dynatrace (SaaS et Managed)

Monitorizar collector OpenTelemetry: su telemetría interna en Dynatrace (SaaS y Managed)

Related Posts