Elysia Tools
Navegación
Workflow Playbook
Inventaría atributos antiguos, migra convenciones semánticas, comprueba la propagación y revisa una traza real antes de publicar cambios de instrumentación.
Temas
Esta guía está dirigida a quien mantiene un servicio y actualiza sus convenciones semánticas OpenTelemetry, no a quien investiga un incidente abierto. Guarda un registro anterior al cambio, la configuración de instrumentación o del Collector y una petición que cruce al menos dos servicios. Elimina secretos y datos personales. Con structured-log-analyzer identifica los atributos actuales; si el registro está en logfmt, logfmt-to-json-structured-log-bridge ayuda a revelar comillas, conversiones de tipo y claves duplicadas. No conviertas un JSON ya estructurado por rutina. Para decidir qué datos pueden circular entre equipos, consulta pii-log-redaction.
Ejecuta otel-semantic-convention-migration-tool sobre una copia de código, reglas del Collector o consultas de paneles. Anota versión de origen y destino, diferencias, atributos eliminados y campos sin asignación. Su resultado es un borrador, no una actualización de producción. http.target, por ejemplo, puede necesitar una separación consciente entre ruta y consulta en lugar de un reemplazo literal. Valida esos casos con las personas responsables y despliega únicamente el cambio revisado. Comprueba también los paneles: un contador de atributos renombrados no detecta consultas que todavía usan nombres antiguos.
Entrega ejemplos de traceparent, tracestate, baggage y cabeceras OTLP a opentelemetry-w3c-traceparent-tracestate-baggage-and-otlp-protobuf-headers-propagation-validator. En el salto siguiente debe mantenerse el identificador de traza y cambiar el identificador de span. Esa comprobación no prueba que se hayan emitido spans. Decodifica una exportación posterior con distributed-trace-decoder-waterfall-visualizer y compara servicios, parentesco, errores y duración con la petición prevista. Registra los tramos ausentes sin deducirlos de cabeceras correctas.
Si hay un objetivo de latencia, usa api-latency-budget-planner para contrastar los tiempos observados con las asignaciones por etapa. Una traza indica dónde se consumió tiempo; no equivale a un P99 medido. Conserva junto a la decisión las versiones, el inventario comparado, el resultado de cabeceras, la exportación y los campos pendientes. Si el objetivo real es resolver una incidencia o repetir cargas de una API, cambia a observability-debugging o api-request-replay-and-debugging, respectivamente.
Guía de flujo de trabajo
Analiza un registro depurado anterior al cambio. Convierte logfmt a JSON solo cuando haga falta para ver valores entre comillas y claves repetidas.
Reescribe atributos admitidos desde v1.20, revisa diferencias y reglas propuestas, y separa campos eliminados o no asignados para decisión manual.
Comprueba traceparent, tracestate, baggage y cabeceras OTLP en un salto representativo, incluida la continuidad de traza y el cambio de span.
Decodifica una exportación JSON OTel, Jaeger o Zipkin posterior y contrasta servicios, relaciones, errores y tiempos con la ruta prevista.
Convierte logfmt cuando las comillas o claves duplicadas ocultan campos; analiza directamente JSON si ya contiene atributos tipados.
Aplica los nombres propuestos solo tras revisar los atributos eliminados o sin correspondencia, como http.target, antes de modificar reglas del Collector.
Valida cabeceras para continuidad de contexto, comprueba los spans emitidos en la traza y usa un presupuesto de latencia solo si existe un objetivo.
Si existe un objetivo, sitúa los tiempos de cada span frente a las asignaciones acordadas y documenta los tramos excedidos.