Use clientes de rastreamento open source para relatar dados e analisar exceções - Managed Service for OpenTelemetry: Central de Documentação do Alibaba Cloud

Quando sua aplicação lança exceções, o Managed Service for OpenTelemetry as detecta nos dados de rastreamento e agrega os resultados na página Exceptions. Isso oferece visibilidade sobre os tipos de erro, stack traces e rastreamentos afetados. Com a instrumentação automática (agentes OpenTelemetry ou SkyWalking), as exceções são capturadas sem alterações no código. Para instrumentação manual, este tópico explica como registrar exceções em spans para cada protocolo de rastreamento compatível.

Pré-requisitos

Antes de começar, verifique se você tem:

Um cliente de rastreamento open source configurado para relatar dados de rastreamento ao Managed Service for OpenTelemetry. Para instruções de configuração, consulte Descrição da conexão.

Como o Managed Service for OpenTelemetry detecta exceções

O mecanismo de detecção depende do protocolo de rastreamento que sua aplicação utiliza:

Protocolo	Local de armazenamento das exceções	Gatilho de detecção
OpenTelemetry	Atributos de evento em um span	Presença do atributo `exception.type`
OpenTracing (Jaeger, Zipkin, SkyWalking)	Campos de log em um span	Campo `event` defina como `"error"` e presença do campo `error.kind`

Após a detecção, as exceções aparecem na página Exceptions com stack traces completos, se fornecidos.

Registre exceções com OpenTelemetry

As convenções semânticas do OpenTelemetry para exceções definem como os dados de exceção se associam aos spans. O Managed Service for OpenTelemetry verifica os seguintes atributos de evento:

Atributo	Obrigatório	Descrição
`exception.type`	Sim	Nome da classe da exceção. Aciona a detecção da exceção.
`exception.message`	Não	Texto da mensagem da exceção.
`exception.stacktrace`	Não	String completa do stack trace. Exibido na página Exceptions.

Use o SDK (recomendado)

Os SDKs do OpenTelemetry fornecem um método recordException que preenche esses atributos automaticamente a partir do objeto de exceção capturado.

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

O método recordException cria um evento de span com exception.type, exception.message e exception.stacktrace preenchidos a partir da exceção capturada.

Nota

Os exemplos nesta página usam o SDK do OpenTelemetry para Java. O método recordException está disponível em todas as linguagens dos SDKs do OpenTelemetry. Consulte a documentação do OpenTelemetry para uso específico de cada linguagem.

Use instrumentação automática

Se sua aplicação utilizar um agente ou framework OpenTelemetry com instrumentação automática, as exceções serão capturadas e relatadas sem necessidade de alterações no código. O Managed Service for OpenTelemetry detecta os dados da exceção e os exibe na página Exceptions.

Registre exceções com OpenTracing

As convenções semânticas do OpenTracing armazenam dados de exceção em campos de log do span. O Managed Service for OpenTelemetry verifica os seguintes campos de log:

Campo de log	Obrigatório	Descrição
`event`	Sim	Deve ser defina como `"error"`. Aciona a detecção da exceção.
`error.kind`	Sim	Nome da classe da exceção.
`message`	Não	Texto da mensagem da exceção.
`stack`	Não	String completa do stack trace. Exibido na página Exceptions.

Jaeger e Zipkin: use o SDK do OpenTracing

O exemplo Java a seguir registra exceções em spans usando o SDK do 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;
}

Pontos importantes neste exemplo:

Tags.ERROR.set(span, Boolean.TRUE) marca o span como um span de erro.
O campo event recebe o valor de Tags.ERROR.getKey(), que resulta em "error".
O campo stack captura o stack trace completo por meio de StringWriter e PrintWriter.

SkyWalking: captura automática de exceções

Os agentes do SkyWalking utilizam instrumentação não intrusiva para capturar exceções automaticamente. Nenhuma alteração de código é necessária. Na maioria dos casos, o agente registra os dados da exceção e os relata ao Managed Service for OpenTelemetry, onde aparecem na página Exceptions.

Visualize e analise dados de exceção

Depois que sua aplicação relata exceções, o Managed Service for OpenTelemetry agrega os dados na página Exceptions. Abra o console para revisar:

Tipos de exceção e contagem de ocorrências
Stack traces de cada exceção
Spans e rastreamentos afetados

Utilize esses dados para identificar erros recorrentes, acompanhar tendências de exceções e priorizar correções com base na frequência e no impacto.

Para obter detalhes sobre as capacidades de análise, consulte Análise de exceções.