“Monitoring tells you whether a system is working, observability lets you ask why it isn’t working.”
— Baron Schwartz
Summary
This note narrows from the SQL VM host agent to the SQL Server check itself: the agent already runs on the host, but the actual database telemetry only appears once the sqlserver.d/conf.yaml file defines the target instance, credentials, and collection behavior for the engine-level metrics.
Configuration contract
Shows the integration config file and the connection parameters that tell the host agent how to reach the local SQL Server instance.
Separates engine-monitoring configuration from the broader host-agent bootstrap so each layer stays easy to reason about.
Built-in metric surface
Lists the built-in SQL Server metrics that Datadog collects out of the box, such as connections, waits, buffer pool indicators, and other server-health counters.
Makes clear where the default integration is sufficient and where custom queries are needed later.
Verification workflow
Uses the agent status output and related checks to confirm that the SQL integration is running and reporting rather than merely installed on disk.
Keeps the verification step local first so configuration errors are caught before dashboard queries are debugged.
Restart discipline
Covers the required restart after config edits and the follow-up validation path that proves the change was actually loaded.
When to use: the agent is already present on the SQL VM and the next task is to enable or adjust SQL Server telemetry itself.
Glossary
SQL Server integration
The Datadog check that connects to SQL Server and emits engine-specific metrics through the local agent.
It matters here because host installation alone does not create database observability.
Service telemetry layer
The host agent is the transport; the SQL integration is the domain-specific collector.
sqlserver.d/conf.yaml
The Datadog integration file that defines how the SQL Server check should connect and what it should collect.
It matters here because this file is the real contract between the agent and the database engine.
Integration owns behavior
If SQL metrics are wrong or missing, this file is the first place to inspect.
instance block
The config section that describes one monitored SQL Server target with its host, port, and credentials.
It matters here because Datadog can only collect from instances that are explicitly declared.
Explicit targets
A running agent never guesses database endpoints; every monitored instance must be named in config.
built-in metrics
The default metrics a Datadog integration emits without any custom query extension.
It matters here because the note separates native coverage from the later custom metric work.
Default before custom
Use built-in metrics first, then add custom queries only for gaps that matter operationally.
service check
A Datadog status signal that reports whether a check can reach and evaluate a target successfully.
It matters here because an integration can fail before it ever produces meaningful metrics.
Health of the collector
A red service check tells you the monitoring path is broken even before charts go blank.
agent status output
The local diagnostic report that lists configured checks, recent runs, and collection errors.
It matters here because it confirms whether the SQL integration loaded and executed after a config change.
Trust local diagnostics first
Dashboards lag and filters mislead; the host status output is the first source of truth.
restart requirement
The need to restart the Datadog Agent after editing integration config files.
It matters here because changes on disk do not become active until the running agent reloads them.
Config is not live by default
A correct file with no restart looks exactly like a bad configuration from the dashboard side.
custom query extension
The optional Datadog mechanism for adding SQL queries that emit extra metrics beyond the built-in set.
It matters here because the note positions custom queries as an extension point, not part of the baseline integration contract.
Extend after baseline
First make the default check healthy, then layer on custom metrics for deadlocks, login breakdowns, or other project-specific views.
Integration Config File
Written to /etc/datadog-agent/conf.d/sqlserver.d/conf.yaml:
Minimal config (integration only, no custom queries)
SQL Server 2022 uses a self-signed certificate by default. Without TrustServerCertificate=yes, the ODBC driver will refuse to connect. Do not use this in production environments with real certificates — instead, configure a proper certificate and remove this setting. See server-configuration for the full SQL Server instance setup including certificate and network configuration.
Production Certificate Setup
Provision a CA-signed certificate for SQL Server, configure it in SQL Server Configuration Manager, then remove TrustServerCertificate=yes from connection_string. This ensures the ODBC driver validates the certificate and the connection is genuinely encrypted.
Built-in SQL Server Metrics Collected by Datadog
The integration automatically collects these metric groups from SQL Server DMVs:
Metric
Description
sqlserver.stats.connections
Total active connections
sqlserver.stats.batch_requests
Batch requests per second (overall throughput)
sqlserver.stats.lock_waits
Lock waits per second — correlates with wait types like LCK_M_*
sqlserver.buffer.cache_hit_ratio
Buffer cache hit ratio (%) — target > 99%
sqlserver.buffer.page_life_expectancy
Seconds a page stays in buffer pool — target > 300
sqlserver.buffer.checkpoint_pages
Checkpoint pages flushed per second
sqlserver.buffer.pool_size
Buffer pool size in pages
Buffer Cache Hit Ratio
Should stay above 99%. Drops below 95% indicate memory pressure — SQL Server is reading from disk instead of RAM. See essential-dba-queries for DMV queries to diagnose memory pressure.
Page Life Expectancy
Higher is better. Drops below 300 seconds indicate memory pressure and frequent page evictions from the buffer pool.
Missing VIEW SERVER STATE permission
If the dd_agent SQL login lacks VIEW SERVER STATE permission, the Datadog agent connects successfully but returns zero values for most metrics (connections, buffer pool, waits). The agent logs no error — it simply reports 0 for every DMV-backed metric. Always verify with SELECT HAS_PERMS_BY_NAME(null, null, 'VIEW SERVER STATE') from the dd_agent session.
Fix: Grant VIEW SERVER STATE
Connect as sa and run: GRANT VIEW SERVER STATE TO dd_agent;. Restart the Datadog agent, then verify with sudo datadog-agent check sqlserver — metric values should now be non-zero.
Verifying the SQL Server Integration
# Check SQL Server integration statussudo datadog-agent check sqlserver# Check integration status in the full status outputsudo datadog-agent status | grep -A 10 "Integrations" | grep -A 5 "sqlserver"
Expected: Status: OK with metric counts listed.
Restarting After SQL Server Config Changes
# Restart the agent to pick up config changessudo systemctl restart datadog-agent# Wait a few seconds, then verifysudo datadog-agent check sqlserver 2>&1 | grep -i "error|ok|instance"
YAML Tabs
YAML does not allow tab characters. If the config file was edited in an editor that inserted tabs, the agent will silently fail to load it. Check with:
sudo cat -A /etc/datadog-agent/conf.d/sqlserver.d/conf.yaml | head -40
Tabs appear as ^I. Replace all with spaces.
Fix: Replace Tabs with Spaces
Run sudo sed -i 's/\t/ /g' /etc/datadog-agent/conf.d/sqlserver.d/conf.yaml to replace all tab characters with two spaces. Re-verify with cat -A, then restart the agent with sudo systemctl restart datadog-agent.