Tu Collector de OpenTelemetry está en marcha, pero no llega nada a Dynatrace. En sus logs se repite una sola línea: 401 Unauthorized o 403 Forbidden. Nueve de cada diez veces, el culpable es el token de API de Dynatrace: formato de cabecera incorrecto, scope ausente, token caducado o enviado al entorno equivocado.
Esta resolución de problemas sale cara en guardia (on-call): mientras se busca, las trazas, las métricas y los logs se pierden, y los SLO calculados sobre ellos dejan de ser fiables. Un diagnóstico metódico reduce ese tiempo a unos minutos y baja el MTTR de los incidentes de ingesta.
Objetivo de este tutorial: identificar en menos de diez minutos por qué se rechaza una petición, sea para la ingesta OTLP o para la API v2. El contenido vale para Dynatrace SaaS y Dynatrace Managed; las diferencias de URL y de tokens se señalan en cada paso.
401 o 403: lo que dice realmente el código
Los dos códigos no cuentan la misma historia. Distinguirlos evita dar vueltas en círculo.
| Código | Significado | Causas frecuentes |
|---|---|---|
| 401 | El llamante no está autenticado | Cabecera ausente o mal formada, token revocado, caducado, mal copiado o perteneciente a otro entorno |
| 403 | El llamante está autenticado pero no tiene permiso | Scope ausente en el token, token desactivado según los casos, restricción en el entorno |
| 404 | La URL no corresponde a nada | Identificador de entorno incorrecto, ruta /e/<env-id> olvidada en Managed |
Quédate con la regla: un 401 se arregla en el token o en la cabecera, un 403 se arregla en los scopes. El contenido exacto del mensaje de error que llega en el cuerpo de la respuesta suele ayudar a decidir: léelo siempre.
Requisitos previos
- Un entorno Dynatrace SaaS o Managed, y derecho a gestionar tokens (el permiso de entorno adecuado).
curlyjqen un equipo que alcance el entorno (o el ActiveGate).- El token que quieres probar en una variable de entorno, nunca en claro en un archivo versionado.
- Un segundo token de acceso válido para el paso de verificación: la llamada de lookup acepta un token clásico de cualquier scope (o un token de plataforma con
api-tokens:tokens:read).
Solucionar problemas de un token de API de Dynatrace paso a paso
Paso 1: verificar la URL del entorno
Antes de acusar al token, comprueba la dirección. Los formatos difieren según el despliegue:
# Dynatrace SaaS
export DT_URL="https://<env-id>.live.dynatrace.com"
# Dynatrace Managed (cluster)
export DT_URL="https://<votre-domaine>/e/<env-id>"
# Via un Environment ActiveGate (SaaS ou Managed)
export DT_URL="https://<activegate>:9999/e/<env-id>"
export DT_API_TOKEN="dt0c01.XXXX.YYYY"
Un token creado en el entorno A no funciona en el entorno B. En Managed con varios entornos, es la primera causa de 401 con la que nos encontramos.
Paso 2: comprobar el formato de la cabecera
La API de entorno espera el esquema Api-Token, no Bearer:
curl -s -o /dev/null -w "%{http_code}\n" \
-H "Authorization: Api-Token ${DT_API_TOKEN}" \
"${DT_URL}/api/v2/metrics?pageSize=1"
Líneas críticas: la palabra Api-Token seguida de un espacio y después el token completo. Un token clásico empieza por dt0c01. y contiene dos puntos de separación. Si la cadena está truncada (copia desde un terminal estrecho, salto de línea en un secret de Kubernetes), obtendrás un 401.
En SaaS, los tokens de plataforma y los clientes OAuth que usan las aplicaciones y la API de la plataforma se envían con Bearer. La API OTLP acepta las dos familias, cada una con su esquema y sus scopes (openpipeline:traces:ingest, etc., para un token de plataforma). No los mezcles: un token de plataforma enviado con Api-Token será rechazado. Comprueba qué tipo de credencial espera cada API en la página de autenticación de la documentación.
Paso 3: leer los scopes reales del token
La API v2 permite consultar los metadatos de un token sin mostrarlo en la interfaz. La llamada se hace con el segundo token, y el token que se inspecciona va en el cuerpo:
curl -s -X POST "${DT_URL}/api/v2/apiTokens/lookup" \
-H "Authorization: Api-Token ${DT_ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-d "{\"token\": \"${DT_API_TOKEN}\"}" | jq '{name, enabled, expirationDate, scopes}'
La respuesta indica si el token está activo, su fecha de caducidad y la lista de sus scopes. Tres casos frecuentes:
enabled: false: alguien lo ha desactivado, a menudo tras una alerta de filtración de un secreto;expirationDatesuperada: el token ha caducado y hay que crear uno nuevo;- falta el scope esperado: es la explicación de tu 403.
Paso 4: hacer coincidir scope y llamada
Cada punto de acceso exige un scope concreto. Estas son las correspondencias más habituales; comprueba el nombre exacto en la pantalla de creación del token, que muestra tanto la etiqueta como el identificador técnico:
| Uso | Punto de acceso | Scope |
|---|---|---|
| Trazas OTLP | /api/v2/otlp/v1/traces |
openTelemetryTrace.ingest |
| Métricas OTLP | /api/v2/otlp/v1/metrics |
metrics.ingest |
| Logs OTLP | /api/v2/otlp/v1/logs |
logs.ingest |
| Lectura de entidades | /api/v2/entities |
entities.read |
| Lectura de problemas | /api/v2/problems |
problems.read |
| Objetos de configuración | /api/v2/settings/objects |
settings.read / settings.write |
Trampa clásica: un Collector que envía trazas, métricas y logs con un único token que solo tiene openTelemetryTrace.ingest. Las trazas pasan, los otros dos pipelines devuelven 403. El Collector exporta entonces solo una parte de la telemetría, lo que es más difícil de detectar que una caída total.
Paso 5: corregir la configuración del Collector
Una configuración limpia del exportador, con el token inyectado por variable de entorno:
exporters:
otlphttp/dynatrace:
endpoint: "${env:DT_URL}/api/v2/otlp"
headers:
Authorization: "Api-Token ${env:DT_API_TOKEN}"
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp/dynatrace]
metrics:
receivers: [otlp]
processors: [cumulativetodelta, batch]
exporters: [otlphttp/dynatrace]
logs:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp/dynatrace]
Líneas críticas: endpoint termina en /api/v2/otlp (el exportador añade /v1/traces, /v1/metrics y /v1/logs); la cabecera usa el esquema Api-Token. Para el detalle del Collector, consulta la guía de instalación del Collector de OpenTelemetry para Dynatrace.
En Kubernetes, crea el secret sin un salto de línea parásito:
kubectl create secret generic dynatrace-otlp \
--from-literal=DT_API_TOKEN="${DT_API_TOKEN}" \
-n observability
Evita echo "$TOKEN" | base64 en un manifiesto: echo añade un salto de línea final, que se codifica con el resto, y el token recibido pasa a ser inválido.
Cómo comprobar que funciona
- Repite la llamada del paso 2: el código esperado es
200. - Envía una traza de prueba mínima al punto de acceso OTLP; la API OTLP de Dynatrace solo acepta protobuf binario (no JSON); un cuerpo protobuf vacío basta para probar la autenticación:
curl -s -o /dev/null -w "%{http_code}\n" -X POST \ -H "Authorization: Api-Token ${DT_API_TOKEN}" \ -H "Content-Type: application/x-protobuf" \ --data-binary "" \ "${DT_URL}/api/v2/otlp/v1/traces"Un código de la familia 2xx confirma la autenticación y el scope; un 401 o un 403 te devuelve a los pasos 2 a 4.
- En los logs del Collector, los errores de exportación deben desaparecer:
kubectl logs deploy/otel-collector -n observability | grep -iE "401|403"ya no devuelve nada. - En SaaS, una consulta DQL confirma la llegada de los datos:
fetch spans, from:now()-15m | summarize count(), by:{service.name}. En Managed, abre la vista de servicios o de trazas distribuidas y busca el servicio emisor.
Si faltan datos aunque la autenticación pase, el problema está en otra parte: consulta trazas de OpenTelemetry ausentes en Dynatrace.
Buenas prácticas
- Un token por uso: un token de ingesta para el Collector y otro para la automatización. Una filtración solo expone entonces un perímetro reducido.
- El mínimo privilegio: añade solo los scopes necesarios. Un token de ingesta no tiene ningún motivo para poder escribir ajustes.
- Una fecha de caducidad y una rotación planificada, con una alerta antes del vencimiento en lugar de una caída el día D.
- Un nombre explícito: equipo, uso y fecha en el nombre del token. El lookup se vuelve legible al instante.
- Monitorizar la ingesta: una alerta sobre la caída del volumen recibido detecta un token caducado antes que los usuarios. Consulta monitorizar el Collector de OpenTelemetry.
- En Managed, ten presente la separación entre tokens de entorno y tokens de la API de Cluster, detallada en la automatización con la API de Cluster.
Preguntas frecuentes
¿Puedo añadir un scope a un token existente?
Según la versión, la interfaz permite modificar ciertos tokens, pero el valor secreto no se vuelve a mostrar nunca. Lo más seguro sigue siendo crear un token nuevo con los scopes correctos, desplegarlo y revocar después el antiguo.
¿Por qué obtengo 401 con un token que funciona en curl?
Compara la cadena que recibe realmente la aplicación: comillas de más en un archivo YAML, salto de línea final en un secret, variable de entorno sin resolver (el Collector envía entonces literalmente ${env:DT_API_TOKEN}). Activa temporalmente los logs de depuración del cliente para comprobar la cabecera, sin conservarlos nunca en producción.
¿Funciona un token de Managed tras migrar a SaaS?
No. Los tokens están ligados a su entorno. Tras una migración, vuelve a crear los tokens en el entorno SaaS y actualiza cada cliente que los use.
Conclusión
Un 401 se resuelve en el token o en la cabecera, un 403 en los scopes y un 404 en la URL. Con la llamada de prueba y el lookup del token, el diagnóstico cabe en unos pocos comandos. Añade una rotación planificada y una alerta sobre el volumen ingerido: la próxima caducidad dejará de ser un incidente.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de su propietario. Los nombres de scopes y de pantallas evolucionan: compruébalos en la documentación oficial de tu versión.