Registre y analice excepciones con clientes de rastreo de código abierto - Managed Service for OpenTelemetry

Cuando su aplicación genera excepciones, Managed Service for OpenTelemetry las detecta en los datos de rastreo y agrupa los resultados en la página Exceptions. Esto le permite visualizar los tipos de error, las pilas de llamadas y los traces afectados. Con la instrumentación automática (agentes de OpenTelemetry o SkyWalking), las excepciones se capturan sin modificar el código. Para la instrumentación manual, esta página explica cómo registrar excepciones en los spans de cada protocolo de rastreo compatible.

Requisitos previos

Antes de empezar, compruebe que cuenta con lo siguiente:

Un cliente de rastreo de código abierto configurado para enviar datos de rastreo a Managed Service for OpenTelemetry. Para ver las instrucciones de configuración, consulte Connection description

Cómo detecta excepciones Managed Service for OpenTelemetry

El mecanismo de detección depende del protocolo de rastreo que utilice su aplicación:

Protocolo	Dónde se almacenan las excepciones	Condición de detección
OpenTelemetry	Atributos de evento en un span	Presencia del atributo `exception.type`
OpenTracing (Jaeger, Zipkin, SkyWalking)	Campos de registro en un span	Campo `event` establecido como `"error"` y presencia del campo `error.kind`

Una vez detectadas, las excepciones aparecen en la página Exceptions con las pilas de llamadas completas, siempre que se hayan proporcionado.

Registre excepciones con OpenTelemetry

Las convenciones semánticas de OpenTelemetry para excepciones definen cómo se adjuntan los datos de excepción a los spans. Managed Service for OpenTelemetry busca los siguientes atributos de evento:

Atributo	Obligatorio	Descripción
`exception.type`	Sí	Nombre de la clase de la excepción. Activa la detección de excepciones.
`exception.message`	No	Texto del mensaje de la excepción.
`exception.stacktrace`	No	Cadena completa de la pila de llamadas. Se muestra en la página Exceptions.

Use el SDK (recomendado)

Los SDK de OpenTelemetry proporcionan el método recordException, que llena estos atributos automáticamente a partir del objeto de excepción capturado.

Span span = myTracer.startSpan("spanName");
try {
    // Business logic
} catch (Throwable e) {
    span.recordException(e);
    throw e;
} finally {
    span.end();
}

El método recordException crea un evento de span con los campos exception.type, exception.message y exception.stacktrace llenados a partir de la excepción capturada.

Nota

Los ejemplos de esta página utilizan el SDK de OpenTelemetry para Java. El método recordException está disponible en todos los lenguajes de los SDK de OpenTelemetry. Consulte la documentación de OpenTelemetry para conocer el uso específico de cada lenguaje.

Use la instrumentación automática

Si su aplicación utiliza un agente de OpenTelemetry o un framework con instrumentación automática, las excepciones se capturan y se envían sin modificar el código. Managed Service for OpenTelemetry detecta los datos de excepción y los muestra en la página Exceptions.

Registre excepciones con OpenTracing

Las convenciones semánticas de OpenTracing almacenan los datos de excepción en los campos de registro del span. Managed Service for OpenTelemetry busca los siguientes campos de registro:

Campo de registro	Obligatorio	Descripción
`event`	Sí	Debe establecerse como `"error"`. Activa la detección de excepciones.
`error.kind`	Sí	Nombre de la clase de la excepción.
`message`	No	Texto del mensaje de la excepción.
`stack`	No	Cadena completa de la pila de llamadas. Se muestra en la página Exceptions.

Jaeger y Zipkin: use el SDK de OpenTracing

A continuación se muestra un ejemplo en Java que registra excepciones en los spans mediante el SDK de OpenTracing:

public static void test() {
    Tracer tracer = GlobalTracer.get();
    Span span = tracer.buildSpan("spanName").start();

    try (Scope scope = tracer.activateSpan(span)) {
        // Business logic
    } catch (Exception e) {
        onException(e, span);
    } finally {
        span.finish();
    }
}

public static void onException(Throwable throwable, Span span) {
    if (span != null) {
        Tags.ERROR.set(span, Boolean.TRUE);
        if (throwable != null) {
            span.log(errorLogs(throwable));
        }
    }
}

private static Map<String, Object> errorLogs(Throwable throwable) {
    Map<String, Object> errorLogs = new HashMap<>();
    errorLogs.put("event", Tags.ERROR.getKey());
    errorLogs.put("error.object", throwable);
    errorLogs.put("error.kind", throwable.getClass().getName());
    String message = throwable.getCause() != null
        ? throwable.getCause().getMessage()
        : throwable.getMessage();
    if (message != null) {
        errorLogs.put("message", message);
    }
    StringWriter sw = new StringWriter();
    throwable.printStackTrace(new PrintWriter(sw));
    errorLogs.put("stack", sw.toString());
    return errorLogs;
}

Puntos clave de este ejemplo:

La instrucción Tags.ERROR.set(span, Boolean.TRUE) marca el span como un span de error.
El campo event toma el valor de Tags.ERROR.getKey(), que se resuelve como "error".
El campo stack captura la pila de llamadas completa mediante StringWriter y PrintWriter.

SkyWalking: captura automática de excepciones

Los agentes de SkyWalking utilizan una instrumentación no intrusiva para capturar excepciones automáticamente. No es necesario modificar el código. En la mayoría de los casos, el agente registra los datos de excepción y los envía a Managed Service for OpenTelemetry, donde aparecen en la página Exceptions.

Consulte y analice los datos de excepciones

Una vez que su aplicación envía las excepciones, Managed Service for OpenTelemetry agrupa los datos en la página Exceptions. Abra la consola para revisar lo siguiente:

Tipos de excepciones y cantidad de ocurrencias
Pilas de llamadas de cada excepción
Spans y traces afectados

Utilice esta información para identificar errores recurrentes, dar seguimiento a las tendencias de excepciones y priorizar las correcciones según la frecuencia y el impacto.

Para conocer las capacidades de análisis detallado, consulte Exception analysis.