diff --git a/content/en/tracing/live_debugger/_index.md b/content/en/tracing/live_debugger/_index.md index d66da396a42..4ef2cadce93 100644 --- a/content/en/tracing/live_debugger/_index.md +++ b/content/en/tracing/live_debugger/_index.md @@ -19,7 +19,7 @@ further_reading: text: "Sensitive Data Scrubbing" - link: "/dynamic_instrumentation/symdb/" tag: "Documentation" - text: "Autocomplete and Search (Preview)" + text: "Autocomplete and Search" - link: "/error_tracking/backend/exception_replay" tag: "Documentation" text: "Exception Replay" @@ -44,56 +44,65 @@ Live Debugger provides: - **Dynamic logpoint placement** anywhere in your codebase, including in third-party libraries. - **Auto-expiring logpoints** that deactivate automatically after a configurable duration. - **Conditional data capture** based on user-defined expressions, so information is collected only when specific conditions are met. -- **Built-in [sensitive data scrubbing][3]** to help prevent exposure of personal data, secrets, and credentials. +- **Built-in [sensitive data scrubbing][1]** to help prevent exposure of personal data, secrets, and credentials. -## Getting started +## Requirements & Setup -### Prerequisites +Live Debugger supports Python, Java, .NET, Ruby, Node.js, and PHP. It requires the [Datadog Agent][2], an +[APM-instrumented application][3], and [Remote Configuration][4]. You can enable it for an individual service either in-app, or by +setting an environment variable. -1. All [Dynamic Instrumentation prerequisites][16] are met. -1. You have [created a logs index][19] to store debugging information. -1. (Recommended) You have enabled [Source Code Integration][20] to view and select specific code locations when adding logpoints. +The enablement method depends on your tracer version, see the table below for details. -### Setup Live Debugger +| | By Service
(In-App) | By Service
(Env Var) | +|---|---|---| +| **How to Enable** | Settings page | Environment variables | +| **Agent Version** | v7.49.0+ | v7.49.0+ | +| **Minimum Tracer Versions** | [Python][5] ≥ 3.10.0
[Java][6] ≥ 1.48.0
[.NET][7] ≥ 3.29.0 | [Python][5] ≥ 2.2.0
[Java][6] ≥ 1.34.0
[.NET][7] ≥ 2.54.0
[Node.js][8] ≥ 5.39.0
[Ruby][9] ≥ 2.9.0
[PHP][10] ≥ 1.5.0 | -Enable and disable Live Debugger on a service using one of the following methods: +To enable Live Debugger in-app, navigate to the Live Debugger **Settings** page, select the desired service, and toggle +it to **Enabled**. -#### One-click enablement (recommended) #### +{{< img src="tracing/live_debugger/live_debugger_enablement.mp4" video="true" alt="Enabling Live Debugger through the setting page" style="width:90%" >}} -
Only users with the following permissions can use one-click enablement: Org Management, APM Remote Configuration Read, APM Remote Configuration Write.
+If in-app enablement isn't available, follow the instructions below for your target language: -1. Select the service and environment on the [Live Debugger Settings][18] page. -1. Check that all prerequisites are met as indicated on the Settings page. -1. Click "Enable" or "Disable": - - "Enable" to allow users to create Debug Sessions on the selected service and environment. - - "Disable" to deactivate active Debug Sessions and prevent users from creating more. +{{< partial name="dynamic_instrumentation/dynamic-instrumentation-languages.html" >}} -**Note**: No service restart is required for changes to take effect. Admins and security contacts receive email notifications when services are enabled or disabled. +
+Why DI instructions? +Live Debugger is built on Dynamic Instrumentation (DI), so its +setup instructions and limitations also apply here. +
-#### Manual enablement #### -1. Select the service and environment on the [Live Debugger Settings][18] page. -1. Follow the instructions to enable Live Debugger. -1. Restart the service before using Live Debugger. +### Create a logs index +Live Debugger generates logs that are sent to Datadog and appear alongside your application logs. -## Live Debugger and Dynamic Instrumentation -Due to shared underlying technology, Live Debugger and Dynamic Instrumentation are always enabled or disabled together on the same service and environment. +If you use [Exclusion filters][11], ensure Live Debugger logs are not filtered: -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. +1. Create a logs index and [configure it][12] to the desired retention with **no sampling**. +2. Set the filter to match on the `source:dd_debugger` tag. All Dynamic Instrumentation logs have this source. +3. Ensure that the new index takes precedence over any other with filters that match that tag, because the first match wins. -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. +### Link your source code + +If you enable the Datadog Source Code Integration, you can debug code directly through +Live Debugger. ## Using Live Debugger -
Try using Live Debugger from your JetBrains IDE! Click here to learn more.
+
+Rather debug in your IDE? +Try using Live Debugger directly from JetBrains! Click here to learn more.
### Creating and using a Debug Session A Debug Session lets you inspect running code using auto-expiring logpoints. To create and use a Debug Session: 1. Start a Debug Session from one of the following locations: - - On the [Live Debugger page][14], click **Create Debug Session**. - - (Requires the Code Origin feature) In the [Trace Explorer][22], open a trace, locate the Code Origin section in the side panel, and click **Start Debug Session**. + - On the [Live Debugger page][13], click **Create Debug Session**. + - (Requires the Code Origin feature) In the [Trace Explorer][14], open a trace, locate the Code Origin section in the side panel, and click **Start Debug Session**. 2. Add a logpoint to begin collecting diagnostic data. 3. Add, remove, or modify logpoints as needed during the session. @@ -103,35 +112,34 @@ Debug Sessions expire automatically. You can also manually disable or re-enable 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: -1. Go to the [Live Debugger page][14]. +1. Go to the [Live Debugger page][13]. 2. Click **Create Debug Session**. 3. Choose your service, environment, and select where in your code to place the first logpoint. -4. Define a logpoint message template using the [Dynamic Instrumentation expression language][2]. +4. Define a logpoint message template using the [expression language][15]. 5. (Optional) Enable "Capture Variables" to collect all execution context (this feature is rate-limited to 1 execution per second). 6. (Optional) Define a condition for when the logs should be emitted. -**Note:** Some feature limitations may apply depending on the service's runtime language. Review the [runtime language-specific documentation][17] for more details. +**Note:** Some feature limitations may apply depending on the service's runtime language. Review the [runtime language-specific documentation][16] for more details. ### Protecting sensitive data Live Debugger data might contain sensitive information, especially when using the "Capture Variables" option. To protect this data: -1. Use the built-in [sensitive data scrubbing][3] mechanisms. -2. Use [Sensitive Data Scanner][15] to identify and redact sensitive information based on regular expressions. +1. Use the built-in [sensitive data scrubbing][1] mechanisms. +2. Use [Sensitive Data Scanner][17] to identify and redact sensitive information based on regular expressions. ## Impact on performance and billing -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. +Enabling Live Debugger on a service does not trigger data capture or impact performance. Data capture only occurs when there are active Debug Sessions on that service. **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. -**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. +**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][18] for any unexpected increases after utilizing a new feature. ## Limitations The following constraints apply to Live Debugger usage and configuration: -- **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). - **Configuration scope:** Live Debugger and Dynamic Instrumentation are enabled or disabled together for the same service and environment. - **Rate limits:** - Logpoints with variable capture: Limited to 1 execution per second. @@ -141,25 +149,22 @@ The following constraints apply to Live Debugger usage and configuration: {{< partial name="whats-next/whats-next.html" >}} -[1]: /dynamic_instrumentation/ -[2]: /dynamic_instrumentation/expression-language/ -[3]: /dynamic_instrumentation/sensitive-data-scrubbing/ -[4]: /agent/ -[5]: /remote_configuration -[6]: https://github.com/DataDog/dd-trace-java -[7]: https://github.com/DataDog/dd-trace-py -[8]: https://github.com/DataDog/dd-trace-dotnet -[9]: https://github.com/DataDog/dd-trace-js -[10]: https://github.com/DataDog/dd-trace-rb -[11]: https://github.com/DataDog/dd-trace-php -[12]: /getting_started/tagging/unified_service_tagging/ -[13]: https://app.datadoghq.com/dynamic-instrumentation/setup -[14]: https://app.datadoghq.com/debugging/sessions -[15]: /dynamic_instrumentation/sensitive-data-scrubbing/#redact-based-on-variable-values-with-sensitive-data-scanner -[16]: /dynamic_instrumentation/#prerequisites -[17]: /dynamic_instrumentation/enabling -[18]: https://app.datadoghq.com/debugging/settings -[19]: /dynamic_instrumentation/#create-a-logs-index -[20]: /integrations/guide/source-code-integration/ -[21]: https://app.datadoghq.com/account/billing -[22]: https://app.datadoghq.com/apm/traces +[1]: /dynamic_instrumentation/sensitive-data-scrubbing/ +[2]: /agent/ +[3]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/ +[4]: /tracing/guide/remote_config +[5]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/python/ +[6]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/java/ +[7]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/dotnet-core +[8]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs/ +[9]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/ruby/ +[10]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/php +[11]: /logs/log_configuration/indexes/#exclusion-filters +[12]: /logs/log_configuration/indexes/#add-indexes +[13]: https://app.datadoghq.com/debugging/sessions +[14]: https://app.datadoghq.com/apm/traces +[15]: /dynamic_instrumentation/expression-language/ +[16]: /dynamic_instrumentation/enabling +[17]: /dynamic_instrumentation/sensitive-data-scrubbing/#redact-based-on-variable-values-with-sensitive-data-scanner +[18]: https://app.datadoghq.com/account/billing +[19]: /dynamic_instrumentation/ diff --git a/static/images/tracing/live_debugger/live_debugger_enablement.mp4 b/static/images/tracing/live_debugger/live_debugger_enablement.mp4 new file mode 100644 index 00000000000..bc16455f50e Binary files /dev/null and b/static/images/tracing/live_debugger/live_debugger_enablement.mp4 differ