Unified Exception Monitoring and Reporting with ASM and JavaAgent

Preface

In daily development, various errors and unexpected exceptions inevitably appear; if not handled promptly, they can cause further issues. This article introduces a set of best‑practice guidelines and demonstrates how the Zz platform elegantly achieves unified exception monitoring and reporting.

Exception Introduction

2.1 Understanding Exceptions

An exception occurs when an unexpected situation prevents normal program execution. When an exception happens, three key questions must be answered: where did it occur, who should handle it, and how to handle it.

2.2 Classification of Java Exceptions

All Java exceptions inherit from Throwable and are divided into Error (fatal, e.g., StackOverflowError , OutOfMemoryError ) and Exception . Exceptions are further split into checked (must be declared or caught) and unchecked (runtime exceptions that inherit from RuntimeException ).

2.3 Exception Handling Process

2.4 Principles of Throwing and Catching Exceptions

Do not use exceptions when unnecessary.

Throw exceptions with descriptive messages.

Handle all exceptions that can be dealt with.

Ignore an exception only with a justified reason.

2.5 Understanding try/catch/finally

The try block must be paired with catch and/or finally . catch handles the thrown exception, while finally always executes for resource cleanup. Certain situations (e.g., code never entering try , infinite loops, System.exit() ) prevent finally from running.

Exception Handling Practices

3.1 Best Practices

Define business‑meaningful exceptions and reuse existing ones (e.g., DubboTimeoutException instead of generic RuntimeException ).

Avoid return statements inside finally .

Catch specific exception subclasses rather than Exception or Throwable .

Never swallow an exception without handling; always consider future code changes.

Do not use exceptions for control flow.

Place resource‑release logic in finally , possibly delegating to utility methods.

3.2 Zz Exception Monitoring Practice

Typical catch‑block code:

public String doSomething(String arg) {
    try {
        return method1(arg);
    } catch (Exception e) {
        log.error("call method1 error msg={}", e.getMessage());
        // alarm logic
    } finally {
        // close resource
    }
    return null;
}

All catch blocks perform similar logging and alarm actions, which can be unified using AOP or, more transparently, bytecode enhancement.

3.3 Implementing Unified Reporting with ASM + JavaAgent

JavaAgent uses the premain method to attach a transformer during class loading:

public static void premain(String arg, Instrumentation inst) {
    LOG.info("******** AgentApplication.premain executing, String Param: {} ********", arg);
    inst.addTransformer(new CustomClassFileTransformer(), true);
    LOG.info("******** AgentApplication premain executed ********");
}

The CustomClassFileTransformer checks whether a class needs enhancement and, if so, uses ASM to modify its bytecode:

@Override
public byte[] transform(ClassLoader loader, String className, Class
classBeingRedefined,
                        ProtectionDomain protectionDomain, byte[] classfileBuffer) {
    if (!needEnhance(className)) {
        return classfileBuffer;
    }
    try {
        ClassReader cr = new ClassReader(className);
        ClassWriter cw = new ClassWriter(ClassWriter.COMPUTE_MAXS);
        CustomClassVisitor classVisitor = new CustomClassVisitor(cw);
        cr.accept(classVisitor, ClassReader.EXPAND_FRAMES);
        return cw.toByteArray();
    } catch (IOException e) {
        LOG.warn("desc=CustomClassFileTransformer.transform, className:{} Exception:{}", className, e);
    }
    return classfileBuffer;
}

The visitor injects handling logic at each catch block line number:

@Override
public void visitTryCatchBlock(Label start, Label end, Label handler, String type) {
    exceptionHandlers.add(handler);
    super.visitTryCatchBlock(start, end, handler, type);
}

@Override
public void visitLineNumber(int line, Label start) {
    if (exceptionHandlers.contains(start)) {
        ExceptionProcessor.injectHandleLogic(this, className, methodName, line);
    }
    super.visitLineNumber(line, start);
}

The injected logic calls a static processor that records class, method, and line information and reports it via the monitoring system:

public static
void process(T exception, String className, String methodName, int lineNumber) {
    try {
        className = className.replace(File.separator, ".");
        String itemName = generateItemNameAfterFilter(exception.getClass().getSimpleName(), className, methodName);
        if (StringUtil.isEmpty(itemName)) {
            return;
        }
        ZzMonitor.sumWithAlarm(itemName, 1, String.valueOf(lineNumber), true);
    } catch (RuntimeException e) {
        LOG.error("desc=ExceptionProcessor.process error", e);
    }
}

Finally, package the agent with Maven Shade Plugin and run the application with the -javaagent flag:

-javaagent:./lib/auto-monitor-alarm-1.0.0.jar

The result is a non‑intrusive, automatically instrumented exception monitoring solution that improves early detection and reduces manual error‑handling code.

Conclusion

By combining JavaAgent and ASM , we can enhance methods at the bytecode level to capture exception locations and report them, helping developers quickly locate and address runtime issues, thereby improving code quality and system stability.