btrace annotation简单翻译

最近研究btrace动态调试线上服务，无奈英文很差，于是乎想到把官方文档小小翻一下，正好学习英语，各位大神请轻拍。
    原文地址：https://kenai.com/projects/btrace/pages/UserGuide#btrace_anno。这篇文章可能一下子写不完，先挖个坑，每天填一点。
    每一段上面为原文，下面为译文。
   
Method Annotations

@com.sun.btrace.annotations.OnMethod annotation can be used to specify target class(es), target method(s) and "location(s)" within the method(s). An action method annotated by this annotation is called when the matching method(s) reaches specified the location. In OnMethod annotation, traced class name is specified by "clazz" property and traced method is specified by "method" property. "clazz" may be a fully qualified class name (likejava.awt.Component or a regular expression specified within two forward slashes. Refer to the samplesNewComponent.java and Classload.java. The regular expression can match zero or more classes in which case all matching classes are instrumented. For example /java\\.awt\\..+/ matches all classes in java.awt package. Also, method name can be a regular expression as well - matching zero or more methods. Refer to the sampleMultiClass.java. There is another way to abstractly specify traced class(es) and method(s). Traced classes and methods may be specified by annotation. For example, if the "clazz" attribute is specified as @javax.jws.WebServiceBTrace will instrument all classes that are annotated by the WebService annotation. Similarly, method level annotations may be used to specify methods abstractly. Refer to the sample WebServiceTracker.java. It is also possible to combine regular expressions with annotations - like @/com\\.acme\\..+/ matches any class that is annotated by any annotation that matches the given regular expression. It is possible to match multiple classes by specifying super type. i.e., match all classes that are subtypes of a given super type. +java.lang.Runnable matches all classes implementingjava.lang.Runnable interface. Refer to the sample SubtypeTracer.java.
@com.sun.btrace.annotations.OnMethod annotation 用于指定类、方法和方法内的“位置”。当一个与注解匹配的方法运行到指定的“位置”时，这个被注解的方法就会被调用。在OnMethod注解中，需要跟踪的类由"clazz" 定义，而方法则是“method”。"clazz"可以是一个全限定的类名，或者是一个用两个双斜线括起来的正则表达式。具体参照示例：NewComponent.java 和Classload.java.正则表达式能匹配0到多个类，所有匹配上的类都能跟踪到。例如 /java\\.awt\\..+/ 匹配所有java.awt 包下面的类. 同样的，方法名也可以用正则表达式描述。参照MultiClass.java示例. 还有其他的方式能精确的指定跟踪的类和方法--通过注解：例如，如果的你的"clazz" 属性指定为@javax.jws.WebService，BTrace 就会匹配所有用WebService注解修饰的类.类似的，"method"属性也可以这样配置来跟踪特定的某些方法.具体参照示例： WebServiceTracker.java. 用过注解跟踪的方式，同样可以使用正则表达式：比如 @/com\\.acme\\..+/. 也可通过通过制定超类或者接口来跟踪子类或者实现.比如 +java.lang.Runnable 可以跟踪到java.lang.Runnable 的所有实现类.参照示例： SubtypeTracer.java.
    
@com.sun.btrace.annotations.OnTimer annotation can be used to specify tracing actions that have to run periodically once every N milliseconds. Time period is specified as long "value" property of this annotation. Refer to the sampleHistogram.java
@com.sun.btrace.annotations.OnTimer 用于指定跟踪脚本每N毫秒就执行一次。N的值用value属性指定，为long型。参照：Histogram.java
@com.sun.btrace.annotations.OnError annotation can be used to specify actions that are run whenever any exception is thrown by tracing actions of some other probe. BTrace method annotated by this annotation is called when any exception is thrown by any of the other BTrace action methods in the same BTrace class.
@com.sun.btrace.annotations.OnError 用于指定当其他的btrace脚本运行时抛出异常后btrace应该执行的行为。也就是说如果btrace的脚本在运行过程中抛出了异常，那么被OnError修饰的方法就会执行。
@com.sun.btrace.annotations.OnExit annotation can be used to specify actions that are run when BTrace code calls "exit(int)" built-in function to finish the tracing "session". Refer to the sample ProbeExit.java.
@com.sun.btrace.annotations.OnExit 用于指定当btrace脚本退出是btrace应该执行的行为，也就是说，当btrace 脚本中调用了exit(int i)方法后，该注解修饰的方法就会执行。参照： ProbeExit.java
@com.sun.btrace.annotations.OnEvent annotation is used to associate tracing methods with "external" events send by BTrace client. BTrace methods annotated by this annotation are called when BTrace client sends an "event". Client may send an event based on some form of user request to send (like pressing Ctrl-C or a GUI menu). String value may used as the name of the event. This way certain tracing actions can be executed whenever an external event "fires". As of now, the command line BTrace client sends "events" whenever use presses Ctrl-C (SIGINT). On SIGINT, a console menu is shown to send an event or exit the client [which is the default for SIGINT]. Refer to the sampleHistoOnEvent.java
@com.sun.btrace.annotations.OnLowMemory annotation can be used to trace memory threshold exceed event. See sample MemAlerter.java
@com.sun.btrace.annotations.OnProbe annotation can be used to specify to avoid using implementation internal classes in BTrace scripts. @OnProbe probe specifications are mapped to one or more @OnMethod specifications by the BTrace VM agent. Currently, this mapping is done using a XML probe descriptor file [accessed by the BTrace agent]. Refer to the sample SocketTracker1.java and associated probe descriptor file java.net.socket.xml. When running this sample, this xml file needs to be copied in the directory where the target JVM runs (or fix probeDescPath option in btracer.bat to point to whereever the .xml file is).
Argument Annotations

@com.sun.btrace.annotations.Self annotation can be used to mark an argument to hold this (or self) value. Refer to the samples AWTEventTracer.java or AllCalls1.java
@com.sun.btrace.annotations.Self 标注一个变量用于保存 this (or self) 的值。参照 ：AWTEventTracer.java or AllCalls1.java
@com.sun.btrace.annotations.Return annotation can be used to mark an argument to hold the return value. Refer to the sample Classload.java
@com.sun.btrace.annotations.Return . 标注一个变量用于保存方法的返回值，参照： Classload.java
@com.sun.btrace.annotations.ProbeClassName (since 1.1) annotation can be used to mark an argument to hold the probed class name value. Refer to the sample AllMethods.java
@com.sun.btrace.annotations.ProbeClassName (since 1.1) 标注一个变量用于保存探测器类名。参照： AllMethods.java
@com.sun.btrace.annotations.ProbeMethodName (since 1.1) 标注一个变量用于保存探测器方法名。参照： WebServiceTracker.java
since 1.2 it accepts boolean parameter fqn to get a fully qualified probed method name
@com.sun.btrace.annotations.Duration annotation can be used to mark an argument to hold the duration of the method call in nanoseconds. The argument must be a long. Use with Kind.RETURN or Kind.ERROR locations.
@com.sun.btrace.annotations.Duration 用于记录被跟踪方法的执行时长，单位为纳秒。被修饰的参数必须是long型，配合Kind.RETURN 或者 Kind.ERROR 使用.
@com.sun.btrace.annotations.TargetInstance (since 1.1) annotation can be used to mark an argument to hold the called instance value. Refer to the sample AllCalls2.java
@com.sun.btrace.annotations.TargetMethodOrField (since 1.1) can be used to mark an argument to hold the called method name. Refer to the samples AllCalls1.java or AllCalls2.java
since 1.2 it accepts boolean parameter fqn to get a fully qualified target method name
Unannotated arguments

The unannotated BTrace probe method arguments are used for the signature matching and therefore they must appear in the order they are defined in the traced method. However, they can be interleaved with any number of annotated arguments. If an argument of type *AnyType[]* is used it will "eat" all the rest of the arguments in they order. The exact meaning of the unannotated arguments depends on the Location used:
Kind.ENTRY, Kind.RETURN- the probed method arguments
Kind.THROW - the thrown exception
Kind.ARRAY_SET, Kind.ARRAY_GET - the array index
Kind.CATCH - the caught exception
Kind.FIELD_SET - the field value
Kind.LINE - the line number
Kind.NEW - the class name
Kind.ERROR - the thrown exception
Field Annotations

@com.sun.btrace.annotations.Export annotation can be used with BTrace fields (static fields) to specify that the field has to be mapped to a jvmstat counter. Using this, a BTrace program can expose tracing counters to external jvmstat clients (such as jstat). Refer to the sample ThreadCounter.java
@com.sun.btrace.annotations.Property annotation can be used to flag a specific (static) field as a MBean attribute. If a BTrace class has atleast one static field with @Property attribute, then a MBean is created and registered with platform MBean server. JMX clients such as VisualVM, jconsole can be used to view such BTrace MBeans. After attaching BTrace to the target program, you can attach VisualVM or jconsole to the same program and view the newly created BTrace MBean. With VisualVM and jconsole, you can use MBeans tab to view the BTrace domain and check out it's attributes. Refer to the samples ThreadCounterBean.java and HistogramBean.java.
@com.sun.btrace.annotations.TLS annotation can be used with BTrace fields (static fields) to specify that the field is a thread local field. Please, be aware that you can not access such marked fields in other than @OnMethod handlers. Each Java thread gets a separate "copy" of the field. In order for this to work correctly the field type must be eitherimmutable (eg. primitives) or cloneable (implements Cloneable interface and overrides clone() method).These thread local fields may be used by BTrace programs to identify whether we reached multiple probe actions from the same thread or not. Refer to the samples OnThrow.java and WebServiceTracker.java
Class Annotations

@com.sun.btrace.annotations.DTrace annotation can be used to associate a simple one-liner D-script (inlined in BTrace Java class) with the BTrace program. Refer to the sample DTraceInline.java.
@com.sun.btrace.annotations.DTraceRef annotation can be used to associate a D-script (stored in a separate file) with the BTrace program. Refer to the sample DTraceRefDemo.java.
@com.sun.btrace.annotations.BTrace annotation must be used to designate a given Java class as a BTrace program. This annotation is enforced by the BTrace compiler as well as by the BTrace agent.