diff --git a/docs/DynamicInstrumentation.md b/docs/DynamicInstrumentation.md index 32e1325a473..3daf2c27680 100644 --- a/docs/DynamicInstrumentation.md +++ b/docs/DynamicInstrumentation.md @@ -1,5 +1,34 @@ # Dynamic Instrumentation +## Instrumentable Code + +Instrumentation can be installed on lines containing executable code and +the final lines of a method (which does not contain executable code). +The following example Ruby method is annotated with which lines can be +targeted by dynamic instrumentation: + + def foo(param) # No (*1) + rv = if param == 1 # Yes + 'yes' # Yes + else # No + 'no' # Yes + end # No (*2) + rv # Yes + end # Yes (*3) + +Note that the method definition line (*1) is executable and can be targeted +if you wish to instrument the method definition, but if you want to instrument +the defined method, you must set the line probe on a line inside of the +method and not on the method definition line itself. + +Note that only the "end" that ends a method definition is specially handled +(*3); other "end" lines, such as (*2), are not instrumentable. + +Dynamic instrumentation is not currently able to report when line probes target +non-executable lines. Setting line probes on non-executable lines will succeed +(the UI will report that the code is instrumented, if the referenced file +is loaded and tracked), but no events will be emitted. + ## Expression Language `dd-trace-rb` supports Dynamic Instrumentation expression language for