Dynamic Instrumentation
Join the Beta!
Dynamic Instrumentation is in private beta. Fill out this form if you would like to
access it.
Request AccessDynamic Instrumentation lets you capture data from your live applications without needing to do any code changes or redeployment.
Getting started
Requirements
Dynamic Instrumentation requires the following:
Note: debugger_read
and debugger_write
permissions are required to access the Dynamic Instrumentation page. For more information about roles and on how to assign roles to users, see Role Based Access Control.
Create a logs index
Dynamic Instrumentation logs are sent to Datadog and they appear alongside your application logs.
If you use Exclusion filters, ensure Dynamic Instrumentation logs are not filtered:
- Create a logs index and configure it to the desired retention with no sampling.
- Set the filter to match on
source:dd_debugger
(all Dynamic Instrumentation logs have this source). - Ensure that the new index takes precedence over any other with filters that match that tag, because the first match wins.
Enable Dynamic Instrumentation
To enable Dynamic Instrumentation on a service, select its runtime and follow the setup instructions:
Explore Dynamic Instrumentation
Dynamic Instrumentation can help you understand what your application is doing at runtime. By adding a Dynamic Instrumentation probe you are exporting additional data from your application, without the need to do any code change or redeployment.
Creating a probe
Both log and metric probes require the same initial setup:
- Go to the Dynamic Instrumentation page.
- Click Create Probe in the top right, or click the three dot context menu on a service and select Add a probe for this service.
- If not prefilled, choose a service from the list.
- If not prefilled, choose runtime, environment and version.
- In the source code, specify where to set the probe by selecting either a class and method or a source file and line.
If you set up Source Code Integration for your service, autocomplete shows suggestions for the selecting a file and displays the file’s code so you can choose the line.
Creating a log probe
A log probe emits a log when it executes.
If you enable Capture method parameters and local variables
on the log probe, it also captures the following values from the execution context and adds them to the log event:
- method arguments
- local variables
- class fields
- the call stack
- exceptions
You can see the captured values in the Datadog UI.
Because capturing this data is performance-intensive, it is enabled on only one instance of your service that matches the probe’s environment and version settings. Probes with capture enabled are rate limited to execute once per second.
Log probes without extra data capturing are enabled on all service instances that match the specified environment and version. They are rate limited to execute at most 5000 times per second, on each service instance.
For more information, read How Dynamic Instrumentation Works.
To create a log probe:
- Complete the generic probe setup (choose service, environment, version, and probe location).
- Select Log as the probe type.
- Define a log message template. You can use the Dynamic Instrumentation expression language to reference values from the execution context.
- Optionally enable extra data capturing from the probe.
- Optionally define a condition using the Dynamic Instrumentation expression language. The log is emitted when the expression evaluates to true.
Creating a metric probe
A metric probe emits a metric when it executes.
Metric probes are automatically enabled on all service instances that match the configured environment and version.
You can use the Dynamic Instrumentation expression language to reference numeric values from the context, such as a variable, a class field, or an expression that yields a numeric value.
For more information, read How Dynamic Instrumentation Works.
To create a metric probe:
- Complete the generic probe setup (choose service, environment, version, and probe location).
- Select Metric as the probe type.
- Specify a name for the metric, which will be prefixed with
dynamic.instrumentation.metric.probe.
. - Select a metric type (count, gauge, or histogram).
- Choose the value of the metric using the Debugger expression language. For count metrics this is optional, and if you omit it, every invocation increments the count by one.
Further Reading
Additional helpful documentation, links, and articles: