|
| 1 | +--- |
| 2 | +title: Live Debugger |
| 3 | +further_reading: |
| 4 | +- link: "/dynamic_instrumentation/" |
| 5 | + tag: "Documentation" |
| 6 | + text: "Dynamic Instrumentation" |
| 7 | +- link: "/dynamic_instrumentation/expression-language/" |
| 8 | + tag: "Documentation" |
| 9 | + text: "Dynamic Instrumentation Expression Language" |
| 10 | +- link: "/dynamic_instrumentation/sensitive-data-scrubbing/" |
| 11 | + tag: "Documentation" |
| 12 | + text: "Sensitive Data Scrubbing" |
| 13 | +- link: "/dynamic_instrumentation/symdb/" |
| 14 | + tag: "Documentation" |
| 15 | + text: "Autocomplete and Search (Preview)" |
| 16 | +- link: "/tracing/error_tracking/execution_replay" |
| 17 | + tag: "Documentation" |
| 18 | + text: "Execution Replay" |
| 19 | +--- |
| 20 | + |
| 21 | +{{< beta-callout-private url="https://www.datadoghq.com/product-preview/live-debugger/" >}} |
| 22 | + Live Debugger is in Limited Preview. Request access to join the waiting list. |
| 23 | + <br> |
| 24 | + To submit questions, feedback, or requests related to Live Debugger, fill out <a href="https://docs.google.com/forms/d/e/1FAIpQLSdM9SV4fxrM_OvQ2CtI7CMl7evN0jasFb6X1QiPAbW6dPTQVQ/viewform?usp=header">this form</a> with details. |
| 25 | + <br> |
| 26 | + For time-sensitive issues, contact <a href="https://www.datadoghq.com/support/">Datadog support</a>. |
| 27 | +{{< /beta-callout-private >}} |
| 28 | + |
| 29 | +## Overview |
| 30 | + |
| 31 | +With Live Debugger, you can debug running applications in real time, without redeploying code or interrupting service. Powered by Datadog's [Dynamic Instrumentation][1], Live Debugger uses logpoints—auto-expiring, "non-breaking breakpoints"—to collect information from running applications without pausing execution. This makes it ideal for investigating issues in environments where traditional debugging methods aren't practical. |
| 32 | + |
| 33 | +## Key capabilities |
| 34 | + |
| 35 | +Live Debugger provides: |
| 36 | + |
| 37 | +- **Real-time inspection** of variable states, method arguments, and execution paths in running code. |
| 38 | +- **Non-invasive data collection** that captures debugging information without stopping applications or degrading performance. |
| 39 | +- **Code instrumentation** with logpoints that can be added anywhere in your code, including third-party libraries. |
| 40 | +- **Auto-expiring logpoints** that are automatically deactivated after a set time (default: 48 hours). |
| 41 | +- **Conditional logging** based on user-defined criteria to capture data only when specific conditions are met. |
| 42 | +- **Built-in [sensitive data scrubbing][3]** to prevent exposure of personal information, passwords, and secrets. |
| 43 | + |
| 44 | +## Getting started |
| 45 | + |
| 46 | +### Prerequisites |
| 47 | + |
| 48 | +1. All [Dynamic Instrumentation prerequisites][16] are met. |
| 49 | +1. You have [created a logs index][19] to store debugging information. |
| 50 | +1. (Recommended) You have enabled [Source Code Integration][20] to view and select specific code locations when adding logpoints. |
| 51 | + |
| 52 | +### Setup Live Debugger |
| 53 | + |
| 54 | +Enable and disable Live Debugger on a service using one of the following methods: |
| 55 | + |
| 56 | +#### One-click enablement (recommended) #### |
| 57 | + |
| 58 | +<div class="alert alert-info">Only users with the following permissions can use one-click enablement: <b>Org Management, APM Remote Configuration Read, APM Remote Configuration Write</b>.</div> |
| 59 | + |
| 60 | +1. Select the service and environment on the [Live Debugger Settings][18] page. |
| 61 | +1. Check that all prerequisites are met as indicated on the Settings page. |
| 62 | +1. Click "Enable" or "Disable": |
| 63 | + - "Enable" to allow users to create Debug Sessions on the selected service and environment. |
| 64 | + - "Disable" to deactivate active Debug Sessions and prevent users from creating more. |
| 65 | + |
| 66 | +**Note**: No service restart is required for changes to take effect. Admins and security contacts receive email notifications when services are enabled or disabled. |
| 67 | + |
| 68 | +#### Manual enablement #### |
| 69 | +1. Select the service and environment on the [Live Debugger Settings][18] page. |
| 70 | +1. Follow the instructions to enable Live Debugger. |
| 71 | +1. Restart the service before using Live Debugger. |
| 72 | + |
| 73 | + |
| 74 | +## Live Debugger and Dynamic Instrumentation |
| 75 | +Due to shared underlying technology, Live Debugger and Dynamic Instrumentation are always enabled or disabled together on the same service and environment. |
| 76 | + |
| 77 | +Like Live Debugger, Dynamic Instrumentation allows users to create logpoints (in addition to supporting other custom instrumentation like spans, span tags, and metrics). However, Live Debugger logpoints expire automatically after a set time period, while Dynamic Instrumentation logpoints remain active until manually deactivated. |
| 78 | + |
| 79 | +When you enable or disable Live Debugger, the same action applies to Dynamic Instrumentation for that service and environment. When disabled, all data capture stops from both active Debug Session logpoints and dynamic instrumentations. |
| 80 | + |
| 81 | +## Using Live Debugger |
| 82 | + |
| 83 | +### Creating and using a Debug Session |
| 84 | + |
| 85 | +Debug Sessions let you inspect your code at runtime with auto-expiring logpoints. To create and use a Debug Session: |
| 86 | + |
| 87 | +1. Start a Debug Session from one of the following: |
| 88 | + - On the [Live Debugger page][14], click **Create Debug Session**. |
| 89 | + - (Requires Code Origins feature) In the [Trace Explorer][22], click on a trace to open the side panel, find the Code Origin section, and click **Start Debug Session**. |
| 90 | +2. Add the first logpoint to start the session. |
| 91 | +3. Add, remove, and modify logpoints within the session. |
| 92 | + |
| 93 | +Debug Sessions automatically expire after 48 hours. You can manually disable and re-enable both sessions and individual logpoints at any time. |
| 94 | + |
| 95 | + |
| 96 | +### Creating logpoints |
| 97 | + |
| 98 | +Logpoints are "non-breaking breakpoints" that specify where in the code to capture information, what data to include, and under what conditions. To add a logpoint for debugging: |
| 99 | + |
| 100 | +1. Go to the [Live Debugger page][14]. |
| 101 | +2. Click **Create Debug Session**. |
| 102 | +3. Choose your service, environment, and select where in your code to place the first logpoint. |
| 103 | +4. Define a logpoint message template using the [Dynamic Instrumentation expression language][2]. |
| 104 | +5. (Optional) Enable "Capture Variables" to collect all execution context (this feature is rate-limited to 1 execution per second). |
| 105 | +6. (Optional) Define a condition for when the logs should be emitted. |
| 106 | + |
| 107 | +**Note:** Some feature limitations may apply depending on the service's runtime language. Review the [runtime language-specific documentation][17] for more details. |
| 108 | + |
| 109 | +### Protecting sensitive data |
| 110 | + |
| 111 | +Live Debugger data might contain sensitive information, especially when using the "Capture Variables" option. To protect this data: |
| 112 | + |
| 113 | +1. Use the built-in [sensitive data scrubbing][3] mechanisms. |
| 114 | +2. Use [Sensitive Data Scanner][15] to identify and redact sensitive information based on regular expressions. |
| 115 | + |
| 116 | +## Impact on performance and billing |
| 117 | + |
| 118 | +Enabling Live Debugger and Dynamic Instrumentation on a service does not trigger data capture or impact performance. Data capture only occurs when there are active Debug Sessions or dynamic instrumentations on that service. |
| 119 | + |
| 120 | +**Performance impact**: Datadog's agent-driven instrumentation ensures minimal impact on application performance; sampling logic, rate limits, and built-in budgets prevent runaway data capture. |
| 121 | + |
| 122 | +**Pricing impact**: Logs captured by Datadog are all billed the same way, whether they are generated from Live Debugger or logger lines in your source code. With Live Debugger, the logpoints automatically expire after the set time period, limiting unnecessary data accumulation and costs. Monitor your [Datadog Plan & Usage page][21] for any unexpected increases after utilizing a new feature. |
| 123 | + |
| 124 | +## Limitations |
| 125 | + |
| 126 | +The following constraints apply to Live Debugger usage and configuration: |
| 127 | + |
| 128 | +- **Language support:** Live Debugger is available for the same runtime languages as [Dynamic Instrumentation][1], including: Java, Python, .NET, PHP (preview), Node.js (preview), Ruby (preview). |
| 129 | +- **Configuration scope:** Live Debugger and Dynamic Instrumentation are enabled or disabled together for the same service and environment. |
| 130 | +- **Rate limits:** |
| 131 | + - Logpoints with variable capture: Limited to 1 execution per second. |
| 132 | + - Logpoints without variable capture: Limited to 5000 executions per second, per service instance. |
| 133 | +- **Session duration:** Debug Sessions automatically expire after 48 hours by default. |
| 134 | + |
| 135 | +## Further Reading |
| 136 | + |
| 137 | +{{< partial name="whats-next/whats-next.html" >}} |
| 138 | + |
| 139 | +[1]: /dynamic_instrumentation/ |
| 140 | +[2]: /dynamic_instrumentation/expression-language/ |
| 141 | +[3]: /dynamic_instrumentation/sensitive-data-scrubbing/ |
| 142 | +[4]: /agent/ |
| 143 | +[5]: /agent/remote_config/ |
| 144 | +[6]: https://github.com/DataDog/dd-trace-java |
| 145 | +[7]: https://github.com/DataDog/dd-trace-py |
| 146 | +[8]: https://github.com/DataDog/dd-trace-dotnet |
| 147 | +[9]: https://github.com/DataDog/dd-trace-js |
| 148 | +[10]: https://github.com/DataDog/dd-trace-rb |
| 149 | +[11]: https://github.com/DataDog/dd-trace-php |
| 150 | +[12]: /getting_started/tagging/unified_service_tagging/ |
| 151 | +[13]: https://app.datadoghq.com/dynamic-instrumentation/setup |
| 152 | +[14]: https://app.datadoghq.com/debugging/sessions |
| 153 | +[15]: /dynamic_instrumentation/sensitive-data-scrubbing/#redact-based-on-variable-values-with-sensitive-data-scanner |
| 154 | +[16]: /dynamic_instrumentation/#prerequisites |
| 155 | +[17]: /dynamic_instrumentation/enabling |
| 156 | +[18]: https://app.datadoghq.com/debugging/settings |
| 157 | +[19]: /dynamic_instrumentation/#create-a-logs-index |
| 158 | +[20]: /integrations/guide/source-code-integration/ |
| 159 | +[21]: https://app.datadoghq.com/account/billing |
| 160 | +[22]: https://app.datadoghq.com/apm/traces |
0 commit comments