diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml index b50ecdb5347..578ac55891d 100644 --- a/config/_default/menus/main.en.yaml +++ b/config/_default/menus/main.en.yaml @@ -4635,6 +4635,11 @@ menu: parent: dbm identifier: dbm_setup_architecture weight: 2 + - name: Azure SQL Configurations + url: database_monitoring/architecture/azure_sql/ + parent: dbm_setup_architecture + identifier: dbm_architecture_azure_sql + weight: 1 - name: Setting Up Postgres url: database_monitoring/setup_postgres/ parent: dbm diff --git a/content/en/database_monitoring/architecture/azure_sql.md b/content/en/database_monitoring/architecture/azure_sql.md new file mode 100644 index 00000000000..6d38ce37b9f --- /dev/null +++ b/content/en/database_monitoring/architecture/azure_sql.md @@ -0,0 +1,286 @@ +--- +title: Azure SQL Configurations +description: Configure Azure SQL instance scoping for Database Monitoring across SQL Database, Managed Instance, and Elastic Pool deployment types. +further_reading: +- link: "/database_monitoring/architecture/" + tag: "Documentation" + text: "DBM Setup Architectures" +- link: "/database_monitoring/setup_sql_server/" + tag: "Documentation" + text: "Setting up SQL Server" +--- + +## Overview + +Each check instance in the Datadog Agent configuration creates one Database Monitoring (DBM) instance. Azure SQL is a family of three deployment types, each using the SQL Server check but with different behavior. + + + + + + + + + + + + + + + + + + + + + + + + + + +
Deployment typeDatabase AutodiscoveryNotes
sql_databaseNot supportedOne config entry per database required
managed_instanceSupportedBehaves like on-premises SQL Server
Elastic poolNot supportedElastic pool is a billing unit only; databases connect like sql_database
+ +The `$azure_name` template variable strips `.database.windows.net` from the host. For example: `myserver.database.windows.net` → `myserver`. + +## Azure SQL Database + +Azure SQL Database requires one config entry per database. `database_autodiscovery` is not supported for this deployment type. The Agent can only connect to one database per check instance. + +**Scenario**: Logical server `myserver.database.windows.net` with three databases: + +| Database | Notes | +|---|---| +| `app_db` | Production application database | +| `analytics_db` | Analytics workload | +| `audit_db` | Audit records | + +### Option 1: Database level (recommended) + +
Use database-level scoping ($azure_name-$database). This is the only option that delivers full DBM data for Azure SQL Database. Update the config manually when databases are added or removed.
+ +Based on the example scenario above, this counts as three DBM instances. + +```yaml +instances: + - host: myserver.database.windows.net + username: datadog + password: "" + dbm: true + database: app_db + azure: + deployment_type: sql_database + fully_qualified_domain_name: myserver.database.windows.net + database_identifier: + template: "$azure_name-$database" # → "myserver-app_db" + + - host: myserver.database.windows.net + username: datadog + password: "" + dbm: true + database: analytics_db + azure: + deployment_type: sql_database + fully_qualified_domain_name: myserver.database.windows.net + database_identifier: + template: "$azure_name-$database" # → "myserver-analytics_db" + + - host: myserver.database.windows.net + username: datadog + password: "" + dbm: true + database: audit_db + azure: + deployment_type: sql_database + fully_qualified_domain_name: myserver.database.windows.net + database_identifier: + template: "$azure_name-$database" # → "myserver-audit_db" +``` + +### Option 2: Logical server level + +
Use logical server level only if per-database DBM data is not required. Query samples and explain plans are not collected at this scope.
+ +One entry connected to `master` covers server-level metadata only. + +Based on the example scenario above, this counts as one DBM instance. + +```yaml +instances: + - host: myserver.database.windows.net + username: datadog + password: "" + dbm: true + database: master + azure: + deployment_type: sql_database + fully_qualified_domain_name: myserver.database.windows.net + database_identifier: + template: "$azure_name" # → "myserver" +``` + +## Azure SQL Managed Instance + +Azure SQL Managed Instance uses engine edition 8, which supports `database_autodiscovery` and behaves like on-premises SQL Server. + +**Scenario**: Managed instance `myinstance.a1b2c3d4e5f6.database.windows.net` with three databases: + +| Database | Notes | +|---|---| +| `app_db` | Production application database | +| `analytics_db` | Analytics workload | +| `audit_db` | Audit records | + +### Option 1: Instance level (recommended) + +
Use instance-level scoping ($azure_name). One entry with database_autodiscovery: true requires no manual updates as databases are added or removed.
+ +One entry with `database_autodiscovery: true` covers all databases automatically. + +Based on the example scenario above, this counts as one DBM instance. + +```yaml +instances: + - host: myinstance.a1b2c3d4e5f6.database.windows.net + username: datadog + password: "" + dbm: true + database_autodiscovery: true + azure: + deployment_type: managed_instance + fully_qualified_domain_name: myinstance.a1b2c3d4e5f6.database.windows.net + database_identifier: + template: "$azure_name" # → "myinstance" +``` + +With managed identity authentication: + +```yaml +instances: + - host: myinstance.a1b2c3d4e5f6.database.windows.net + dbm: true + database_autodiscovery: true + azure: + deployment_type: managed_instance + fully_qualified_domain_name: myinstance.a1b2c3d4e5f6.database.windows.net + managed_identity: + client_id: "" + identity_scope: "https://database.windows.net/.default" + database_identifier: + template: "$azure_name" +``` + +### Option 2: Database level + +
Use database-level scoping only if different teams own different databases and need isolated DBM views, or if billing requires per-database cost attribution.
+ +One entry per database. Use only if different teams own different databases and need isolated DBM views, or if billing requires per-database cost attribution. + +Based on the example scenario above, this counts as three DBM instances. + +```yaml +instances: + - host: myinstance.a1b2c3d4e5f6.database.windows.net + username: datadog + password: "" + dbm: true + database: app_db + azure: + deployment_type: managed_instance + fully_qualified_domain_name: myinstance.a1b2c3d4e5f6.database.windows.net + database_identifier: + template: "$azure_name-$database" # → "myinstance-app_db" + database_metrics: + instance_metrics: + enabled: false # prevent duplicate instance-level metrics across entries +``` + +## Azure SQL Elastic Pools + +Elastic pools are a resource allocation unit only. They are not visible at the connection layer. Each database in a pool connects exactly like a standalone Azure SQL Database. Pool-level metrics are available through the Datadog Azure Monitor integration, not the SQL Server check. + +**Scenario**: Logical server `myserver.database.windows.net` with five databases across two elastic pools: + +| Database | Pool | +|---|---| +| `app_db` | ElasticPool1 | +| `analytics_db` | ElasticPool1 | +| `audit_db` | ElasticPool1 | +| `reports_db` | ElasticPool2 | +| `exports_db` | ElasticPool2 | + +### Option 1: Per-database with pool tags (recommended) + +
Use per-database scoping with pool:<name> tags ($azure_name-$database). Per-database is the only viable approach. Elastic pools are invisible to the connection layer. Tags provide pool grouping for dashboards and monitors.
+ +Add a `pool:` tag to each entry to enable filtering across a pool in dashboards and monitors. + +Based on the example scenario above, this counts as five DBM instances. + +```yaml +instances: + - host: myserver.database.windows.net + username: datadog + password: "" + dbm: true + database: app_db + azure: + deployment_type: sql_database + fully_qualified_domain_name: myserver.database.windows.net + tags: + - "pool:ElasticPool1" + database_identifier: + template: "$azure_name-$database" # → "myserver-app_db" + + - host: myserver.database.windows.net + username: datadog + password: "" + dbm: true + database: analytics_db + azure: + deployment_type: sql_database + fully_qualified_domain_name: myserver.database.windows.net + tags: + - "pool:ElasticPool1" + database_identifier: + template: "$azure_name-$database" # → "myserver-analytics_db" + + - host: myserver.database.windows.net + username: datadog + password: "" + dbm: true + database: reports_db + azure: + deployment_type: sql_database + fully_qualified_domain_name: myserver.database.windows.net + tags: + - "pool:ElasticPool2" + database_identifier: + template: "$azure_name-$database" # → "myserver-reports_db" + + # Repeat for remaining databases with the appropriate pool tag +``` + +### Option 2: Per-database, no pool grouping + +
Use this option if pool grouping in dashboards and monitors is not required.
+ +Based on the example scenario above, this counts as five DBM instances. + +```yaml +instances: + - host: myserver.database.windows.net + username: datadog + password: "" + dbm: true + database: app_db + azure: + deployment_type: sql_database + fully_qualified_domain_name: myserver.database.windows.net + database_identifier: + template: "$azure_name-$database" # → "myserver-app_db" + + # Repeat for remaining databases +``` + +{{< partial name="whats-next/whats-next.html" >}}