Información general

Sigue esta guía para migrar entre las principales versiones de los SDKs de navegador RUM y los SDKs de logs de navegador. Consulta la documentación del SDK para obtener información detallada sobre sus características y capacidades.

De v4 a v5

V5 introduce los siguientes cambios y más:

• Nuevas configuraciones y valores predeterminados de privacidad para Session Replay
• Recopilación automática de señales de frustración
• Métricas de rendimiento actualizadas
• APIs y parámetros del SDK actualizados

Ten en cuenta los siguientes cambios más recientes al actualizar tu SDK. Los cambios están agrupados por área de impacto.

General

Parámetros de inicialización del SDK

Acción a realizar: sustituir los parámetros obsoletos por los nuevos parámetros equivalentes en v5. Los antiguos nombres de parámetros ya no están disponibles en v5.

APIs públicas

Acción a realizar: sustituir las APIs obsoletas por las nuevas APIs equivalentes. Las APIs antiguas ya no están disponibles en v5.

Dominios de entrada

La V5 envía datos a dominios de entrada distintos de los de las versiones anteriores.

Acción a realizar: actualiza cualquier entrada connect-src de la Política de seguridad de contenido (CSP) para utilizar el nuevo dominio.

Eventos de confianza

Para evitar recopilar datos incorrectos o ilegítimos, v5 solo escucha eventos generados por acciones del usuario, ignorando eventos creados por scripts. Consulta eventos de confianza para más detalles.

Acción a realizar: si dependes de algún evento programático y deseas que el SDK lo tenga en cuenta, añádele el atributo __ddIsTrusted, como se indica a continuación:

const click = new Event('click')
click.__ddIsTrusted = true
document.dispatchEvent(click)

Acción a realizar: si dependes en gran medida de eventos programáticos, por ejemplo, en un entorno de test de interfaz de usuario automatizado, puedes permitir todos los eventos no fiables configurando allowUntrustedEvents: true.

Tipo de devolución beforeSend

Las funciones de devolución de llamadas beforeSend deben devolver un valor booleano:

beforeSend(event: any, context?: any) => boolean

La implementación no ha cambiado. Si no se devuelve ningún valor, no se descarta el evento.

Acción a realizar: asegúrate de que beforeSend devuelve true para mantener el evento y false para descartarlo. Esto resuelve los errores de compilación de TypeScript relacionados.

Session Replay

Enmascaramiento de Session Replay

El ajuste predeterminado de enmascaramiento de Session Replay defaultPrivacyLevel ha cambiado de mask-user-input a mask. Esto oculta todos los datos de las grabaciones de Session Replay por defecto, haciendo que las grabaciones sean menos sensibles a la vista. Para más información, consulta Opciones de privacidad del navegador de Session Replay.

Acción a realizar: si deseas ver más datos sin enmascarar en Session Replay, como contenido HTML no confidencial o texto introducido por el usuario, configura defaultPrivacyLevel como mask-user-input o allow.

Grabación automática de sesiones muestreadas para Session Replay

Las sesiones que se muestrean para Session Replay con sessionReplaySampleRate se graban automáticamente al inicio de la sesión. Esto significa que no tienes que llamar al método startSessionReplayRecording() para capturar una grabación. En otras palabras, no se perderá accidentalmente ninguna grabación.

Acción a realizar: si quieres seguir utilizando el comportamiento de grabación antiguo y personalizar cuándo se inicia la grabación, configura startSessionReplayRecordingManually en true.

Solo se paga por Session Replay cuando la sesión captura una grabación

En versiones anteriores del SDK, las sesiones se determinan como sesiones de Session Replay a través del mecanismo de muestreo. En v5, las sesiones solo se cuentan como sesiones de Session Replay si se captura una grabación durante la sesión. Esto facilita el seguimiento del uso de Session Replay.

No es necesaria ninguna acción: este comportamiento entra en vigor automáticamente en v5.

Frecuencia de muestreo predeterminada de Session Replay

En v5, el valor predeterminado de sessionReplaySampleRate es 0 en lugar de 100. Si no incluyes una frecuencia de muestreo, no se registra ninguna repetición.

Acción a realizar: para utilizar Session Replay, establece una frecuencia de muestreo explícitamente con sessionReplaySampleRate: 100 (u otra frecuencia de muestreo).

RUM

Integración de APM

Para fomentar la compatibilidad y el uso de OpenTelemetry, se han modificado los tipos de propagadores por defecto para incluir tracecontext además de datadog.

Acción a realizar: si aún no estás especificando el propagador deseado en el parámetro de inicialización allowedTracingUrls, configura tus encabezados de permisos de control y acceso del servidor para aceptar también el encabezado traceparent. Para más información, consulta Conectar RUM y trazas.

Campo Plan de sesión

En relación con los cambios en Session Replay, el campo session.plan solo está disponible para los eventos de sesión.

Acción a realizar: actualiza cualquier consulta de monitor o dashboard que hayas guardado para excluir el campo session.plan para eventos que no sean una sesión.

Las señales de frustración se recopilan automáticamente

Solo tienes que configurar trackUserInteractions: true para recopilar todas las interacciones del usuario, incluidas las señales de frustración. Ya no es necesario configurar el parámetro trackFrustrations por separado.

Acción a realizar: para rastrear las señales de frustración, configura trackUserInteractions: true. El parámetro trackFrustrations puede eliminarse.

La duración de los recursos se omite en las páginas congeladas

La recopilación de recursos omite las duraciones de los recursos que se prolongaron debido a que la página pasó a segundo plano, por ejemplo, cuando el usuario hace clic en otra pestaña mientras se carga la página.

No es necesaria ninguna acción: este comportamiento entra en vigor automáticamente en v5.

Recursos y seguimiento de tareas largas

Cuando se utiliza sessionReplaySampleRate en lugar de replaySampleRate o premiumSampleRate (ambos obsoletos), debes configurar recursos y tareas largas explícitamente.

Acción a realizar: para recopilar estos eventos, asegúrate de que trackResources y trackLongTasks están configurados en true.

Los nombres de los métodos de los recursos están en mayúsculas

Con el fin de evitar tener diferentes valores para el mismo nombre de método según el caso (POST vs post), los nombres de los métodos se envían ahora consistentemente en mayúsculas.

Acción a realizar: actualiza las consultas de monitor o dashboard para utilizar el campo resource.method con valores en mayúsculas.

Evento de acción beforeSend

La API beforeSend permite acceder a información contextual de los eventos recopilados (consulta Mejorar y controlar los datos RUM).

Con la introducción de las señales de frustración, un evento de acción puede asociarse a varios eventos DOM.

Junto con esta actualización, se ha eliminado el atributo context.event en favor del atributo context.events.

Acción a realizar: actualizar el código beforeSend para utilizar context.events en lugar de context.event.

beforeSend: (event, context) => {
  if (event.type === 'action' && event.action.type === 'click') {
    // acceso a eventos de navegador relacionados con el evento
    // antes, evento único: context.event
    // ahora, eventos múltiples: context.events
  }
}

beforeSend en periodos de primer plano

El atributo view.in_foreground_periods se calcula directamente desde el backend, no es enviado por el SDK.

Acción a realizar: elimina view.in_foreground_periods del código beforeSend. Si dependías de este atributo para un caso de uso específico, ponte en contacto con Soporte para obtener ayuda.

Entrada de rendimiento beforeSend

El atributo performanceEntry del contexto beforeSend se ha actualizado a partir de la representación JSON para incluir directamente el objeto de entrada de rendimiento.

Se ha eliminado el tipo exportado PerformanceEntryRepresentation en favor del tipo estándar PerformanceEntry.

Acción a realizar: en el código beforeSend, utiliza directamente el tipo PerformanceEntry en lugar del tipo PerformanceEntryRepresentation.

Logs

Eliminar el prefijo de error de la consola

Se ha suprimido el prefijo “console error:” en los mensajes de log. Esta información puede encontrarse en el atributo origin.

Acción a realizar: actualiza las consultas de monitor o dashboard que utilizan el prefijo "console error:" para utilizar @origin:console en su lugar.

Eliminar error.origin

Desde la introducción del atributo origin en todos los logs, error.origin era redundante y se ha suprimido.

Acción a realizar: actualiza las consultas de monitor o dashboard que utilicen error.origin para que utilicen origin en su lugar.

Desacoplar el registrador principal

Cuando el SDK recopila errores en tiempo de ejecución o logs de red, informe o consola, no añade el contexto específico al registrador principal (DD_LOGS.logger), y no utiliza el nivel o manejador establecido para ese registrador.

Acción a realizar: si confiaste en el nivel principal del registrador para excluir los logs de no registrador, utiliza los parámetros dedicados de la inicialización en su lugar.

Acción a realizar: si confiaste en el contexto del registrador principal para añadir contexto a los logs de no registrador, utiliza el contexto global en su lugar.

De v3 a v4

Con la versión v4 se han introducido varios cambios de última hora en el SDK del navegador RUM y logs.

Cambios

URLs de entrada

Las URLs a las que se envían los datos del SDK del navegador RUM han cambiado. Asegúrate de que tu Política de Seguridad de contenido está actualizada.

Compatibilidad mínima de la versión Typescript

El SDK de navegador RUM v4 no es compatible con TypeScript anterior a v3.8.2. Si utilizas TypeScript, asegúrate de que la versión es al menos v3.8.2.

Sintaxis de etiquetas

Los parámetros de inicialización version, env y service se envían como etiquetas (tags) a Datadog. El SDK del navegador RUM los depura levemente para asegurarse de que no generan múltiples etiquetas, e imprime una advertencia si esos valores no cumplen con la sintaxis de los requisitos de etiqueta.

Tipos de parámetros de inicialización más estrictos

Los tipos de TypeScript que representan parámetros de inicialización son más estrictos y pueden rechazar parámetros no compatibles previamente aceptados. Si obtienes errores de comprobación de tipos, asegúrate de que estás proporcionando parámetros de inicialización compatibles.

Prioridad de las opciones de privacidad

Cuando se especifican varias opciones de privacidad en el mismo elemento, Datadog aplica la opción más restrictiva para evitar la filtración inesperada de datos sensibles. Por ejemplo, si se especifican las clases dd-privacy-allow y dd-privacy-hidden en el mismo elemento, se oculta en lugar de permitirse.

Cálculo de nombres de acciones

Al calcular los nombres de las acciones, el SDK del navegador RUM elimina el texto de los elementos secundarios con el atributo data-dd-action-name del texto interior.

Por ejemplo, para el siguiente elemento container, donde anteriormente el nombre de acción calculado sería Container sensitive data, en v4, el nombre de acción calculado es Container:

<div id="container">
  Container
  <div data-dd-action-name="sensitive">sensitive data</div>
</div>

Eliminaciones

Campo _datadog_xhr de XHR

El SDK del navegador RUM utilizaba anteriormente una propiedad _datadog_xhr en los objetos XMLHttpRequest que representaba su estado interno. Esta propiedad se ha eliminado sin reemplazo, ya que no estaba destinada a ser utilizada externamente.

Parámetro de inicialización proxyHost

Se ha eliminado el parámetro de inicialización proxyHost. Utiliza en su lugar el parámetro de inicialización proxyUrl.

Compatibilidad de opciones de privacidad

Las opciones de privacidad input-ignored y input-masked ya no son válidas. En su lugar, utiliza la opción de privacidad mask-user-input.

Específicamente, reemplaza:

• Los nombres de clase dd-privacy-input-ignored y dd-privacy-input-masked con dd-privacy-mask-user-input
• Los valores de atributo dd-privacy="input-masked" y dd-privacy="input-ignored" con dd-privacy="mask-user-input"

De v2 a v3

El SDK del navegador v3 introduce Session Replay. Con esta importante actualización de la versión, se han introducido varios cambios de última hora en los SDK de navegador RUM y logs.

Cambios

Errores RUM

El SDK del navegador RUM ya no emite errores RUM para las llamadas XHR y Fetch fallidas. Estas solicitudes fallidas de red se siguen recopilando como recursos RUM, que contienen el atributo de código de estado.

Para seguir viendo las solicitudes de red fallidas como errores RUM, Datadog recomienda interceptar el recurso con la API beforeSend, comprobar la propiedad status_code y enviar manualmente un error con la API addError.

beforeSend: (event) => {
    if (event.type === 'resource' && event.resource.status_code >= 500) {
        datadogRum.addError(`${event.resource.method} ${event.resource.url} ${event.resource.status_code}`); // "GET https://www.example.com/ 504"
    }
}

Atributo de fuente de error RUM

El SDK del navegador RUM ya no permite especificar la fuente de un error recopilado con la API addError. Todos los errores recopilados con esta API tienen su atributo de fuente establecido en custom. La API addError acepta un objeto de contexto como segundo parámetro, que debe utilizarse para pasar contexto adicional sobre el error.

Eliminaciones

API RUM

Opciones de inicialización

Tipos TypeScript

Referencias adicionales

Más enlaces, artículos y documentación útiles:

Visualizar tus datos RUM en el ExplorerDOCUMENTACIÓN Utiliza Datadog Session Replay para ver en tiempo real los recorridos de los usuarios.BLOG