Skip to content

Commit 8a5bb96

Browse files
committed
docs(debugger): update setup requirements and reorganize documentation
- Update tracer version requirements: - In-App: Python ≥3.1.0, Java ≥1.48.0, .NET ≥3.29.0 - Env Var: Add Node.js ≥5.39.0, Ruby ≥2.9.0, PHP ≥1.5.0; update Python to ≥2.2.0, Java to ≥1.34.0, .NET to ≥2.54.0 - Add "Create a logs index" section with exclusion filter configuration steps - Add "Link your source code" section for Source Code Integration - Minor copy improvements for clarity - Reorder and remove unused references These changes align Live Debugger current product capabilities and provide clear setup guidance for all supported languages with less reliance on the Dynamic Instrumentation documentation.
1 parent b35f504 commit 8a5bb96

File tree

1 file changed

+58
-57
lines changed

1 file changed

+58
-57
lines changed

content/en/tracing/live_debugger/_index.md

Lines changed: 58 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ further_reading:
1919
text: "Sensitive Data Scrubbing"
2020
- link: "/dynamic_instrumentation/symdb/"
2121
tag: "Documentation"
22-
text: "Autocomplete and Search (Preview)"
22+
text: "Autocomplete and Search"
2323
- link: "/error_tracking/backend/exception_replay"
2424
tag: "Documentation"
2525
text: "Exception Replay"
@@ -44,44 +44,49 @@ Live Debugger provides:
4444
- **Dynamic logpoint placement** anywhere in your codebase, including in third-party libraries.
4545
- **Auto-expiring logpoints** that deactivate automatically after a configurable duration.
4646
- **Conditional data capture** based on user-defined expressions, so information is collected only when specific conditions are met.
47-
- **Built-in [sensitive data scrubbing][3]** to help prevent exposure of personal data, secrets, and credentials.
47+
- **Built-in [sensitive data scrubbing][1]** to help prevent exposure of personal data, secrets, and credentials.
4848

49-
## Getting started
49+
## Requirements & Setup
5050

51-
### Prerequisites
51+
Live Debugger supports Python, Java, .NET, Ruby, Node.js, and PHP. It requires the [Datadog Agent][2], an
52+
[APM-instrumented application][3], and [Remote Configuration][4]. You can enable it for an individual service either in-app, or by
53+
setting an environment variable.
5254

53-
1. All [Dynamic Instrumentation prerequisites][16] are met.
54-
1. You have [created a logs index][19] to store debugging information.
55-
1. (Recommended) You have enabled [Source Code Integration][20] to view and select specific code locations when adding logpoints.
55+
The enablement method depends on your tracer version, see the table below for details.
5656

57-
### Setup Live Debugger
57+
| | By Service<br>(In-App) | By Service<br>(Env Var) |
58+
|---|---|---|
59+
| **How to Enable** | Settings page | Environment variables |
60+
| **Agent Version** | v7.49.0+ | v7.49.0+ |
61+
| **Minimum Tracer Versions** | [Python][5] ≥ 3.1.0<br>[Java][6] ≥ 1.48.0<br>[.NET][7] ≥ 3.29.0 | [Python][5] ≥ 2.2.0<br>[Java][6] ≥ 1.34.0<br>[.NET][7] ≥ 2.54.0<br>[Node.js][8] ≥ 5.39.0<br>[Ruby][9] ≥ 2.9.0<br>[PHP][10] ≥ 1.5.0 |
5862

59-
Enable and disable Live Debugger on a service using one of the following methods:
63+
To enable Live Debugger in-app, navigate to the Live Debugger **Settings** page, select the desired service, and toggle
64+
it to **Enabled**.
6065

61-
#### One-click enablement (recommended) ####
66+
If in-app enablement isn't available, follow the instructions below for your target language:
6267

63-
<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>
68+
{{< partial name="dynamic_instrumentation/dynamic-instrumentation-languages.html" >}}
6469

65-
1. Select the service and environment on the [Live Debugger Settings][18] page.
66-
1. Check that all prerequisites are met as indicated on the Settings page.
67-
1. Click "Enable" or "Disable":
68-
- "Enable" to allow users to create Debug Sessions on the selected service and environment.
69-
- "Disable" to deactivate active Debug Sessions and prevent users from creating more.
70+
<div class="alert alert-info">
71+
<b>Why DI instructions?</b>
72+
Live Debugger is built on <a href="/tracing/dynamic_instrumentation/">Dynamic Instrumentation (DI)</a>, so its
73+
setup instructions and limitations also apply here.
74+
</div>
7075

71-
**Note**: No service restart is required for changes to take effect. Admins and security contacts receive email notifications when services are enabled or disabled.
76+
### Create a logs index
7277

73-
#### Manual enablement ####
74-
1. Select the service and environment on the [Live Debugger Settings][18] page.
75-
1. Follow the instructions to enable Live Debugger.
76-
1. Restart the service before using Live Debugger.
78+
Live Debugger generates logs that are sent to Datadog and appear alongside your application logs.
7779

80+
If you use [Exclusion filters][11], ensure Live Debugger logs are not filtered:
7881

79-
## Live Debugger and Dynamic Instrumentation
80-
Due to shared underlying technology, Live Debugger and Dynamic Instrumentation are always enabled or disabled together on the same service and environment.
82+
1. Create a logs index and [configure it][12] to the desired retention with **no sampling**.
83+
2. Set the filter to match on the `source:dd_debugger` tag. All Dynamic Instrumentation logs have this source.
84+
3. Ensure that the new index takes precedence over any other with filters that match that tag, because the first match wins.
8185

82-
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.
86+
### Link your source code
8387

84-
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.
88+
If you enable the Datadog Source Code Integration, you can debug code directly through
89+
Live Debugger.
8590

8691
## Using Live Debugger
8792

@@ -92,8 +97,8 @@ When you enable or disable Live Debugger, the same action applies to Dynamic Ins
9297
A Debug Session lets you inspect running code using auto-expiring logpoints. To create and use a Debug Session:
9398

9499
1. Start a Debug Session from one of the following locations:
95-
- On the [Live Debugger page][14], click **Create Debug Session**.
96-
- (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**.
100+
- On the [Live Debugger page][13], click **Create Debug Session**.
101+
- (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**.
97102
2. Add a logpoint to begin collecting diagnostic data.
98103
3. Add, remove, or modify logpoints as needed during the session.
99104

@@ -103,35 +108,34 @@ Debug Sessions expire automatically. You can also manually disable or re-enable
103108

104109
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:
105110

106-
1. Go to the [Live Debugger page][14].
111+
1. Go to the [Live Debugger page][13].
107112
2. Click **Create Debug Session**.
108113
3. Choose your service, environment, and select where in your code to place the first logpoint.
109-
4. Define a logpoint message template using the [Dynamic Instrumentation expression language][2].
114+
4. Define a logpoint message template using the [expression language][15].
110115
5. (Optional) Enable "Capture Variables" to collect all execution context (this feature is rate-limited to 1 execution per second).
111116
6. (Optional) Define a condition for when the logs should be emitted.
112117

113-
**Note:** Some feature limitations may apply depending on the service's runtime language. Review the [runtime language-specific documentation][17] for more details.
118+
**Note:** Some feature limitations may apply depending on the service's runtime language. Review the [runtime language-specific documentation][16] for more details.
114119

115120
### Protecting sensitive data
116121

117122
Live Debugger data might contain sensitive information, especially when using the "Capture Variables" option. To protect this data:
118123

119-
1. Use the built-in [sensitive data scrubbing][3] mechanisms.
120-
2. Use [Sensitive Data Scanner][15] to identify and redact sensitive information based on regular expressions.
124+
1. Use the built-in [sensitive data scrubbing][1] mechanisms.
125+
2. Use [Sensitive Data Scanner][17] to identify and redact sensitive information based on regular expressions.
121126

122127
## Impact on performance and billing
123128

124-
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.
129+
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.
125130

126131
**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.
127132

128-
**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.
133+
**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.
129134

130135
## Limitations
131136

132137
The following constraints apply to Live Debugger usage and configuration:
133138

134-
- **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).
135139
- **Configuration scope:** Live Debugger and Dynamic Instrumentation are enabled or disabled together for the same service and environment.
136140
- **Rate limits:**
137141
- Logpoints with variable capture: Limited to 1 execution per second.
@@ -141,25 +145,22 @@ The following constraints apply to Live Debugger usage and configuration:
141145

142146
{{< partial name="whats-next/whats-next.html" >}}
143147

144-
[1]: /dynamic_instrumentation/
145-
[2]: /dynamic_instrumentation/expression-language/
146-
[3]: /dynamic_instrumentation/sensitive-data-scrubbing/
147-
[4]: /agent/
148-
[5]: /remote_configuration
149-
[6]: https://github.com/DataDog/dd-trace-java
150-
[7]: https://github.com/DataDog/dd-trace-py
151-
[8]: https://github.com/DataDog/dd-trace-dotnet
152-
[9]: https://github.com/DataDog/dd-trace-js
153-
[10]: https://github.com/DataDog/dd-trace-rb
154-
[11]: https://github.com/DataDog/dd-trace-php
155-
[12]: /getting_started/tagging/unified_service_tagging/
156-
[13]: https://app.datadoghq.com/dynamic-instrumentation/setup
157-
[14]: https://app.datadoghq.com/debugging/sessions
158-
[15]: /dynamic_instrumentation/sensitive-data-scrubbing/#redact-based-on-variable-values-with-sensitive-data-scanner
159-
[16]: /dynamic_instrumentation/#prerequisites
160-
[17]: /dynamic_instrumentation/enabling
161-
[18]: https://app.datadoghq.com/debugging/settings
162-
[19]: /dynamic_instrumentation/#create-a-logs-index
163-
[20]: /integrations/guide/source-code-integration/
164-
[21]: https://app.datadoghq.com/account/billing
165-
[22]: https://app.datadoghq.com/apm/traces
148+
[1]: /dynamic_instrumentation/sensitive-data-scrubbing/
149+
[2]: /agent/
150+
[3]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/
151+
[4]: /tracing/guide/remote_config
152+
[5]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/python/
153+
[6]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/java/
154+
[7]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/dotnet-core
155+
[8]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs/
156+
[9]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/ruby/
157+
[10]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/php
158+
[11]: /logs/log_configuration/indexes/#exclusion-filters
159+
[12]: /logs/log_configuration/indexes/#add-indexes
160+
[13]: https://app.datadoghq.com/debugging/sessions
161+
[14]: https://app.datadoghq.com/apm/traces
162+
[15]: /dynamic_instrumentation/expression-language/
163+
[16]: /dynamic_instrumentation/enabling
164+
[17]: /dynamic_instrumentation/sensitive-data-scrubbing/#redact-based-on-variable-values-with-sensitive-data-scanner
165+
[18]: https://app.datadoghq.com/account/billing
166+
[19]: /dynamic_instrumentation/

0 commit comments

Comments
 (0)