Associer la fonctionnalité Database Monitoring aux traces

Database Monitoring n'est pas pris en charge pour ce site.

Ce guide part du principe que vous avez configuré Database Monitoring et que vous utilisez APM. Associer APM à DBM permet d’injecter les identifiants de trace APM dans les données DBM afin de mettre en corrélation ces deux sources de données. Vous pourrez ainsi visualiser les informations sur les bases de données dans la solution APM, et les données APM dans la solution DBM.

Avant de commencer

Bases de données prises en charge
Postgres, MySQL, SQL Server, Oracle
Versions de l’Agent prises en charge
7.46+
Confidentialité des données
L’activation de la propagation des commentaires SQL entraîne le stockage de données potentiellement confidentielles (noms des services) dans les bases de données ; ces données sont alors accessibles aux tierces parties ayant accès à la base de données.

Les intégrations du traceur APM prennent en charge un mode de propagation qui contrôle la quantité d’informations transmises depuis les applications vers la base de données.

  • Le mode full envoie les informations complètes d’une trace à la base de données, ce qui vous permet d’analyser des traces individuelles au sein de DBM. Il s’agit de la solution recommandée pour la plupart des intégrations.
  • Le mode service envoie le nom du service, ce qui vous permet d’identifier les services contribuant à la charge de la base de données. Il s’agit du seul mode pris en charge pour les applications SQL Server.
  • Le mode disabled désactive la propagation et ne transmet aucune information provenant des applications.

SQL Server et Oracle ne prennent pas en charge le mode de propagation full en raison du comportement de mise en cache des instructions, qui peut entraîner des problèmes de performance lors de l’ajout du contexte complet d’une trace.

DD_DBM_PROPAGATION_MODEPostgresMySQLSQL ServerOracle
full
service

Pilotes et traceurs d’application pris en charge

LangageBibliothèque ou FrameworkPostgresMySQLSQL ServerOracle
Go : dd-trace-go >= 1.44.0
database/sqlmode service uniquementmode service uniquement
sqlxmode service uniquementmode service uniquement
Java : dd-trace-java >= 1.11.0
jdbcmode service uniquementmode service uniquement
Ruby : dd-trace-rb >= 1.8.0
pg
mysql2
Python : dd-trace-py >= 1.9.0
psycopg2
.NET : dd-trace-dotnet >= 2.35.0
Npgsql *
MySql.Data *
MySqlConnector *
ADO.NET *mode service uniquement
PHP : dd-trace-php >= 0.86.0
pdo
MySQLi
Node.js : dd-trace-js >= 3.17.0
postgres
mysql
mysql2

* CommandType.StoredProcedure n’est pas pris en charge

Configuration

Pour garantir une expérience utilisateur optimale, assurez-vous que les variables d’environnement suivantes sont définies dans votre application :

DD_SERVICE=(nom de l'application)
DD_ENV=(environnement de l'application)
DD_VERSION=(version de l'application)

Mettez à jour les dépendances de votre application afin d’inclure dd-trace-go@v1.44.0 ou une version ultérieure :

go get gopkg.in/DataDog/dd-trace-go.v1@v1.44.0

Mettez à jour votre code afin d’importer le package contrib/database/sql :

import (
   "database/sql"
   "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
   sqltrace "gopkg.in/DataDog/dd-trace-go.v1/contrib/database/sql"
)

Activez la fonctionnalité de propagation de Database Monitoring via l’une des méthodes suivantes :

  1. Variable d’environnement : DD_DBM_PROPAGATION_MODE=full

  2. Utilisation de code pendant l’enregistrement du pilote :

    sqltrace.Register("postgres", &pq.Driver{}, sqltrace.WithDBMPropagation(tracer.DBMPropagationModeFull), sqltrace.WithServiceName("my-db-service"))
    
  3. Utilisation de code sur sqltrace.Open :

    sqltrace.Register("postgres", &pq.Driver{}, sqltrace.WithServiceName("my-db-service"))
    
    db, err := sqltrace.Open("postgres", "postgres://pqgotest:password@localhost/pqgotest?sslmode=disable", sqltrace.WithDBMPropagation(tracer.DBMPropagationModeFull))
    if err != nil {
        log.Fatal(err)
    }
    

Exemple complet :

import (
    "database/sql"
    "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
    sqltrace "gopkg.in/DataDog/dd-trace-go.v1/contrib/database/sql"
)

func main() {
    // La première étape consiste à définir le mode de propagation DBM lors de l'enregistrement du pilote. Notez qu'il est également
    // possible de le faire sur sqltrace.Open pour avoir un contrôle plus granulaire sur la fonctionnalité.
    sqltrace.Register("postgres", &pq.Driver{}, sqltrace.WithDBMPropagation(tracer.DBMPropagationModeFull))

    // On appelle ensuite Open.
    db, err := sqltrace.Open("postgres", "postgres://pqgotest:password@localhost/pqgotest?sslmode=disable")
    if err != nil {
        log.Fatal(err)
    }

    // Puis on utilise le package database/sql comme d'habitude, avec tracing.
    rows, err := db.Query("SELECT name FROM users WHERE age=?", 27)
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()
}

Suivez les instructions d’instrumentation du tracing Java et installez la version 1.11.0 de l’Agent ou une version ultérieure.

Vous devez également activer l’instrumentation jdbc-datasource.

Activez la fonctionnalité de propagation de DBM à l’aide de l’une des méthodes suivantes :

  • Définissez la propriété système dd.dbm.propagation.mode=full
  • Définissez la variable d’environnement DD_DBM_PROPAGATION_MODE=full

Exemple complet :

# Lancez l'Agent Java avec les propriétés système requises
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 chemin/vers/votre/app.jar

Testez la fonctionnalité dans votre application :

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
        }
    }
}

Remarque : les instructions préparées ne sont pas prises en charge en mode full, et tous les appels de l’API JDBC qui utilisent des instructions préparées entraînent automatiquement le passage en mode service. Étant donné que la plupart des bibliothèques Java SQL utilisent des instructions préparées par défaut, cela signifie que la plupart des applications Java sont limitées au mode service.

Dans votre Gemfile, installez la version 1.8.0 de dd-trace-rb ou une version ultérieure :

source 'https://rubygems.org'
gem 'ddtrace', '>= 1.8.0'

# Selon votre utilisation
gem 'mysql2'
gem 'pg'

Activez la fonctionnalité de propagation de Database Monitoring via l’une des méthodes suivantes :

  1. Variable d’environnement : DD_DBM_PROPAGATION_MODE=full

  2. Option comment_propagation (par défaut : ENV['DD_DBM_PROPAGATION_MODE']), pour mysql2 ou pg :

     Datadog.configure do |c|
         c.tracing.instrument :mysql2, comment_propagation: 'full'
         c.tracing.instrument :pg, comment_propagation: 'full'
     end
    

Exemple complet :

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;")

Mettez à jour les dépendances de votre application afin d’inclure dd-trace-py>=1.9.0 :

pip install "ddtrace>=1.9.0"

Installez psycopg2 (Remarque : l’association de DBM et APM n’est pas prise en charge pour les clients MySQL) :

pip install psycopg2

Activez la fonctionnalité de propagation de Database Monitoring via la variable d’environnement suivante :

  • DD_DBM_PROPAGATION_MODE=full

Exemple complet :


import psycopg2

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

# connexion à la base de données postgres
conn = psycopg2.connect(**POSTGRES_CONFIG)
cursor = conn.cursor()
# exécution des requêtes sql
cursor.execute("select 'blah'")
cursor.executemany("select %s", (("foo",), ("bar",)))
Afin de pouvoir utiliser cette fonctionnalité, l'instrumentation automatique doit être activée pour votre service .NET.

Suivez les instructions relatives au tracing .NET Framework ou celles relatives au tracing .NET Core afin d’installer le package d’instrumentation automatique et d’activer le tracing pour votre service.

Vérifiez que vous utilisez une bibliothèque client compatible, par exemple Npgsql.

Activez la fonctionnalité de propagation de Database Monitoring en définissant la variable d’environnement suivante :

  • Pour Postgres et MySQL : DD_DBM_PROPAGATION_MODE=full
  • Pour SQL Server : DD_DBM_PROPAGATION_MODE=service
Afin de pouvoir utiliser cette fonctionnalité, l'extension du traceur doit être activée pour votre service PHP.

Suivez les instructions relatives au tracing PHP afin d’installer le package d’instrumentation automatique et d’activer le tracing pour votre service.

Vérifiez que vous utilisez une bibliothèque client compatible, par exemple PDO.

Activez la fonctionnalité de propagation de Database Monitoring en définissant la variable d’environnement suivante :

  • DD_DBM_PROPAGATION_MODE=full

Installez le traceur dd-trace-js ou mettez-le à jour vers une version ultérieure à 3.17.0 (ou 2.30.0 en cas d’utilisation de la version 12 de Node.js en fin de vie) :

npm install dd-trace@^3.17.0

Mettez à jour votre code pour importer et initialiser le traceur :

// Cette ligne doit précéder l'importation des modules instrumentés.
const tracer = require('dd-trace').init();

Activez la fonctionnalité de propagation de Database Monitoring via l’une des méthodes suivantes :

  • En définissant la variable d’environnement suivante :

    DD_DBM_PROPAGATION_MODE=full
    
  • En configurant le traceur de façon à utiliser l’option dbmPropagationMode (par défaut : ENV['DD_DBM_PROPAGATION_MODE']):

    const tracer = require('dd-trace').init({ dbmPropagationMode: 'full' })
    
  • En activant le traceur uniquement au niveau de l’intégration :

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

Exemple complet :

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) => {
    // traitement du résultat
})

Explorer la connexion APM dans DBM

Attribuer les connexions de base de données actives aux services APM les appelant

Visualiser les connexions actives vers une base de données avec le service APM à l'origine de celles-ci.

Obtenez une vue détaillée des connexions actives pour un host donné selon les services APM en amont qui émettent les requêtes. Vous pouvez attribuer la charge d’une base de données à des services individuels afin d’identifier ceux qui sont les plus actifs sur la base de données. Basculez sur la page du service en amont le plus actif pour poursuivre l’examen des données.

Filtrer les hosts de votre base de données selon les services APM qui les appellent

Filtrez les hosts de votre base de données selon les services APM qui les appellent.

Filtrez rapidement la liste des bases de données afin d’afficher uniquement les hosts de base de données dont dépendent vos services APM spécifiques. Identifiez facilement si l’une de vos dépendances en aval connaît un blocage susceptible de nuire aux performances du service.

Consulter la trace associée à un échantillon de requête

Affichez un aperçu de la trace APM échantillonnée à partir de laquelle la requête inspectée a été générée.

Si vous consultez un échantillon de requête dans Database Monitoring et que la trace associée a été échantillonnée par APM, vous pouvez afficher l’échantillon de requête DBM dans le contexte de la trace APM. Procéder de la sorte permet de combiner les données de télémétrie DBM (notamment le plan d’exécution ainsi que les performances historiques de la requête) et l’historique de la span au sein de votre infrastructure afin de déterminer si une modification apportée à la base données est à l’origine des mauvaises performances de l’application.

Explorer la connexion DBM dans APM

Visualiser les hosts de base de données en aval des services APM

Visualisez les hosts de base de données en aval dont dépendent vos services APM à partir de la page Service.

Sur la page APM d’un service donné, consultez les dépendances de base de données directement en aval du service identifiées par Database Monitoring. Déterminez rapidement si des hosts présentent une charge disproportionnée pouvant être due à d’autres hosts sollicitant fortement la base de données. Pour afficher la page d’un service, cliquez sur le service de votre choix dans le Service Catalog pour ouvrir le volet des détails, puis cliquez sur View Service Page au sein de celui-ci.

Identifier de potentielles optimisations à l’aide des plans d’exécution pour les requêtes de base de données dans les traces

Identifiez les inefficacités à l'aide des plans d'exécution pour les requêtes de base de données au sein de traces.

Consultez les performances historiques de requêtes similaires à celles exécutées dans votre trace, notamment les événements d’attente échantillonnés, la latence moyenne et les plans d’exécution capturés récemment, afin d’apporter du contexte au comportement attendu d’une requête. Déterminez si le comportement est anormal et poursuivez l’examen en basculant sur Database Monitoring pour obtenir encore plus d’informations concernant les hosts de base de données sous-jacents.

Pour aller plus loin