Add DBM auto_explain configuration #34146

jasonmp85 · 2026-01-26T21:18:01Z

What does this PR do? What is the motivation?

Adds a section about configuring auto_explain to the DBM PostgreSQL documentation.

Merge instructions

Going to use this preview to discuss language with team; after which I will mark this ready for merge, but not yet.

Merge readiness:

Ready for merge

Additional notes

This feature is in preview.

github-actions · 2026-01-26T21:21:56Z

Preview links (active after the `build_preview` check completes)

Modified Files

https://docs-staging.datadoghq.com/jason.petersen/add_auto_explain_docs/database_monitoring/setup_postgres/selfhosted

rtrieu

some minor feedback to comply with our style guide

content/en/database_monitoring/setup_postgres/selfhosted.md

databergs · 2026-01-26T22:11:47Z

content/en/database_monitoring/setup_postgres/selfhosted.md


+### Collecting plans with `auto_explain` (optional)
+
+By default, the agent will only gather `EXPLAIN` plans for a sampling of in-flight queries. These plans are of a more general nature, especially when application code uses prepared statements.


WDYT about linking to postgres EXPLAIN docs?

databergs · 2026-01-26T22:12:32Z

content/en/database_monitoring/setup_postgres/selfhosted.md

+
+By default, the agent will only gather `EXPLAIN` plans for a sampling of in-flight queries. These plans are of a more general nature, especially when application code uses prepared statements.
+
+To collect full `EXPLAIN ANALYZE` plans taken from all queries, you will need to use `auto_explain`, a first-party extension bundled with PostgreSQL available in all major providers. _Logging collection is a prerequisite to `auto_explain` collection_, so be sure to enable it before continuing.


Likewise wdyt about linking to PG docs for autoexplain?
https://www.postgresql.org/docs/current/auto-explain.html

databergs · 2026-01-26T22:15:42Z

content/en/database_monitoring/setup_postgres/selfhosted.md

+
+2. Change the `log_line_prefix` to enable richer event correlation
+   ```conf
+     log_line_prefix = '%m:%r:%u@%d:[%p]:%l:%e:%s:%v:%x:%c:%q%a:' # this pattern is required to ingest auto_explain plans


The "this is required" portion is truncated by the code snippet box. I'd pull it out into the step 2 text ( ...richer event correlation. This pattern is required to ...)

It also conflicts with the "Configure logging" section above:

Either pattern works; both contain the important things for correlation.

The "this is required" portion is truncated by the code snippet box

Yeah, I modeled that comment after the earlier log config line, which also had a trailing comment kind of far off to the right.

I've moved it into the step two text.

It also conflicts with the "Configure logging" section above:

I wasn't sure whether to address that. The logging section config is sufficient for sending and tagging PostgreSQL logs, but an explain plan needs more fields than are present there.

The auto_explain log config also is sufficient for sending and tagging PostgreSQL logs, so it's a functional superset. I didn't know whether to address this in text, or just implicitly imply this config supercedes the section above…

ethanperez · 2026-01-27T01:13:54Z

content/en/database_monitoring/setup_postgres/selfhosted.md

+To collect full `EXPLAIN ANALYZE` plans taken from all queries, you will need to use `auto_explain`, a first-party extension bundled with PostgreSQL available in all major providers. _Logging collection is a prerequisite to `auto_explain` collection_, so be sure to enable it before continuing.
+
+<div class="alert alert-danger">
+  <strong>Important:</strong> <code>auto_explain</code> produces logs lines that may contain sensitive information from your application, similar to the raw values that appear in non-obfuscated SQL. You can use the FIXME permission to control who can see the resulting plans, but the log lines themselves <i>will</i> be visible to all users within your Datadog org. Using <a href="//logs/guide/logs-rbac">RBAC for Logs</a> is one way to ensure these logs are only visible to the right users.


Not sure if this is preview docs thing, but this logs link doesn't work, it's not treated as relative

That's weird. @rtrieu how do I make a link to another docs page from within an HTML block (can't use markdown to generate the link)?

Oh, dur, I used a double slash by accident. Fixed.

Mostly linter stuff. Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com>

Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com>

databergs · 2026-01-27T19:44:13Z

This will include docs for RDS as well right?

Add DBM auto_explain configuration

0699f69

jasonmp85 requested review from a team as code owners January 26, 2026 21:18

Fix markdown use in HTML block

301609e

rtrieu self-requested a review January 26, 2026 21:56

rtrieu requested changes Jan 26, 2026

View reviewed changes

databergs reviewed Jan 26, 2026

View reviewed changes

ethanperez reviewed Jan 27, 2026

View reviewed changes

jasonmp85 and others added 2 commits January 27, 2026 11:21

Apply suggestions from code review

a84978b

Mostly linter stuff. Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com>

Apply suggestion from @rtrieu

b5c8898

Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com>

rtrieu approved these changes Jan 27, 2026

View reviewed changes

Add PostgreSQL links, fix relative doc link

e629270

jasonmp85 added 2 commits January 27, 2026 21:20

Add link to needed permission

4532ce0

Missing slash

89308a1

jasonmp85 merged commit 42b4287 into master Jan 28, 2026
16 checks passed

jasonmp85 deleted the jason.petersen/add_auto_explain_docs branch January 28, 2026 05:02

jasonmp85 mentioned this pull request Jan 30, 2026

Add auto_explain docs for rds #34232

Merged

1 task


		### Collecting plans with `auto_explain` (optional)

		By default, the agent will only gather `EXPLAIN` plans for a sampling of in-flight queries. These plans are of a more general nature, especially when application code uses prepared statements.


		By default, the agent will only gather `EXPLAIN` plans for a sampling of in-flight queries. These plans are of a more general nature, especially when application code uses prepared statements.

		To collect full `EXPLAIN ANALYZE` plans taken from all queries, you will need to use `auto_explain`, a first-party extension bundled with PostgreSQL available in all major providers. _Logging collection is a prerequisite to `auto_explain` collection_, so be sure to enable it before continuing.

Add DBM auto_explain configuration #34146

Add DBM auto_explain configuration #34146

Uh oh!

Conversation

jasonmp85 commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do? What is the motivation?

Merge instructions

Additional notes

Uh oh!

github-actions bot commented Jan 26, 2026

Preview links (active after the build_preview check completes)

Modified Files

Uh oh!

rtrieu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

databergs commented Jan 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jasonmp85 commented Jan 26, 2026 •

edited

Loading

Preview links (active after the `build_preview` check completes)