This guide assumes that you have configured Database Monitoring and are using APM. Connecting APM and DBM injects APM trace identifiers into DBM data collection, which allows for correlation of these two data sources. This enables product features showing database information in the APM product, and APM data in the DBM product.

Before you begin

Supported databases

Postgres, MySQL, SQL Server, Oracle, MongoDB

Supported Agent versions

7.46+

Data privacy

Enabling SQL comment propagation results in potentially confidential data (service names) being stored in the databases which can then be accessed by other third parties that have been granted access to the database.

APM tracer integrations support a Propagation Mode, which controls the amount of information passed from applications to the database.

• full mode sends full trace information to the database, allowing you to investigate individual traces within DBM. This is the recommended solution for most integrations.
• service mode sends the service name, allowing you to understand which services are the contributors to database load.
• disabled mode disables propagation and does not send any information from applications.

* Full propagation mode on Aurora MySQL requires version 3.

** Full propagation mode on Oracle is only supported when using Java.

Supported application tracers and drivers

* CommandType.StoredProcedure not supported

** Full mode SQL Server for Java/.NET:

• The instrumentation executes a SET context_info command when the client issues a query, which makes an additional round-trip to the database.
• Prerequisites:
  • Agent version 7.55.0 or greater
  • Java tracer version 1.39.0 or greater
  • .NET tracer version 3.3 or greater

*** Full mode Oracle for Java:

• The instrumentation overwrites V$SESSION.ACTION.
• Prerequisite: Java tracer 1.45 or greater

**** Service/Full mode MongoDB for Node.js:

• Prerequisite:
  • Node.js tracer 5.37.0 or greater

***** Service/Full mode MongoDB for Python:

• Prerequisite:
  • Python tracer 3.5.0 or greater

Setup

For the best user experience, ensure the following environment variables are set in your application:

DD_SERVICE=(application name)
DD_ENV=(application environment)
DD_VERSION=(application version)

Datadog recommends setting the obfuscation mode to obfuscate_and_normalize for Agent versions 7.63 and higher. Add the following parameter in the apm_config section of your APM Agent configuration file:

  sql_obfuscation_mode: "obfuscate_and_normalize"

go get github.com/DataDog/dd-trace-go/v2 # 2.x

import (
   "database/sql"
   "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
   sqltrace "github.com/DataDog/dd-trace-go/contrib/database/sql/v2"
)

import (
	"database/sql"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
   sqltrace "github.com/DataDog/dd-trace-go/contrib/database/sql/v2"
)

func main() {
	// The first step is to set the dbm propagation mode when registering the driver. Note that this can also
	// be done on sqltrace.Open for more granular control over the feature.
	sqltrace.Register("postgres", &pq.Driver{}, sqltrace.WithDBMPropagation(tracer.DBMPropagationModeFull))

	// Followed by a call to Open.
	db, err := sqltrace.Open("postgres", "postgres://pqgotest:password@localhost/pqgotest?sslmode=disable")
	if err != nil {
		log.Fatal(err)
	}

	// Then, we continue using the database/sql package as we normally would, with tracing.
	rows, err := db.Query("SELECT name FROM users WHERE age=?", 27)
	if err != nil {
		log.Fatal(err)
	}
	defer rows.Close()
}

# Start the Java Agent with the required system properties
java -javaagent:/path/to/dd-java-agent.jar -Ddd.dbm.propagation.mode=full -Ddd.integration.jdbc-datasource.enabled=true -Ddd.service=my-app -Ddd.env=staging -Ddd.version=1.0 -jar path/to/your/app.jar

public class Application {
    public static void main(String[] args) {
        try {
            Connection connection = DriverManager
                    .getConnection("jdbc:postgresql://127.0.0.1/foobar?preferQueryMode=simple", "user", "password");
            Statement stmt = connection.createStatement();
            String sql = "SELECT * FROM foo";
            stmt.execute(sql);
            stmt.close();
            connection.close();
        } catch (SQLException exception) {
            //  exception logic
        }
    }
}

source 'http://rubygems.org'
gem 'datadog' # Use `'ddtrace', '>= 1.8.0'` if you're using v1.x

# Depends on your usage
gem 'mysql2'
gem 'pg'

require 'mysql2'
require 'ddtrace'

Datadog.configure do |c|
	c.service = 'billing-api'
	c.env = 'production'
	c.version = '1.3-alpha'

	c.tracing.instrument :mysql2, comment_propagation: ENV['DD_DBM_PROPAGATION_MODE']
end

client = Mysql2::Client.new(:host => "localhost", :username => "root")
client.query("SELECT 1;")

pip install "ddtrace>=1.9.0"

pip install psycopg2

pip install pymongo

import psycopg2

POSTGRES_CONFIG = {
    "host": "127.0.0.1",
    "port": 5432,
    "user": "postgres_user",
    "password": "postgres_password",
    "dbname": "postgres_db_name",
}

# connect to postgres db
conn = psycopg2.connect(**POSTGRES_CONFIG)
cursor = conn.cursor()
# execute sql queries
cursor.execute("select 'blah'")
cursor.executemany("select %s", (("foo",), ("bar",)))

from pymongo import MongoClient

# Connect to MongoDB
client = MongoClient('mongodb://localhost:27017/')
db = client['test_database']
collection = db['test_collection']

# Insert a document
collection.insert_one({"name": "test", "value": 1})

# Query documents
results = collection.find({"name": "test"})
for doc in results:
    print(doc)

npm install dd-trace@^3.17.0

// This line must come before importing any instrumented module.
const tracer = require('dd-trace').init();

const pg = require('pg')
const tracer = require('dd-trace').init({ dbmPropagationMode: 'full' })

const client = new pg.Client({
	user: 'postgres',
	password: 'postgres',
	database: 'postgres'
})

client.connect(err => {
	console.error(err);
	process.exit(1);
});

client.query('SELECT $1::text as message', ['Hello world!'], (err, result) => {
	// handle result
})

Explore the APM Connection in DBM

Attribute active database connections to the calling APM services

Break down active connections for a given host by the upstream APM services making the requests. You can attribute load on a database to individual services to understand which services are most active on the database. Pivot to the most active upstream service’s service page to continue the investigation.

Filter your database hosts by the APM services that call them

Quickly filter the Database List to display only the database hosts that your specific APM services depend on. Easily identify if any of your downstream dependencies have blocking activity that may impact service performance.

View the associated trace for a query sample

When viewing a Query Sample in Database Monitoring, if the associated trace has been sampled by APM, you can view the DBM Sample in the context of the APM Trace. This allows you to combine DBM telemetry, including the explain plan and historical performance of the query, alongside the lineage of the span within your infrastructure to understand if a change on the database is responsible for poor application performance.

Explore the DBM Connection in APM

Visualize the downstream database hosts of APM services

On the APM page for a given service, view the direct downstream database dependencies of the service as identified by Database Monitoring. Quickly determine if any hosts have disproportionate load that may be caused by noisy neighbors. To view a service’s page, click on the service in the Software Catalog to open a details panel, then click View Service Page in the panel.

Identify potential optimizations using explain plans for database queries in traces

View historical performance of similar queries to those executed in your trace, including sampled wait events, average latency, and recently captured explain plans, to contextualize how a query is expected to perform. Determine if the behavior is abnormal and continue the investigation by pivoting to Database Monitoring for additional context about the underlying database hosts.

Further Reading

Additional helpful documentation, links, and articles:

Seamlessly correlate DBM and APM telemetry to understand end-to-end query performanceBLOG