[receiver/sqlserver] Enable direct connection to SQL Server instances (…

…#31915)

**Description:** <Describe what has changed.>
<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
This PR enables direct connection to SQL Server instances, and also
allows the SQL Server receiver to run on non-Windows platforms.

User-facing changes:
1. More (optional) configuration options. If the receiver wants to
connect directly to the SQL Server instance (rather than relying on
Windows Performance Counters), all of these options must be specified.
2. Add a new metric, `sqlserver.database_io.read_latency`. This is
disabled by default, and way randomly chosen as a single metric to try
to restrict this PR's size. I plan on following this PR up with more
metrics from the same query, as well as more queries and metrics.

Note: Existing users should see no change in functionality with this PR.
Using existing configurations with this PR should have no performance or
functional impact.

**Link to tracking Issue:** <Issue number if applicable>
Resolves
#30297

**Testing:** <Describe what testing was performed and which tests were
added.>
Tested on MacOS and Windows. Manual tested with direct connection to a
docker container on both platforms, as well as ran all tests in package.
Everything is passing.

**Working demo for testing:**
Docker container start command:
```
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=StrongPassw0rd" -p 1433:1433 -d mcr.microsoft.com/mssql/server:2022-latest
```
Collector config:
```
sqlserver:
 password: "StrongPassw0rd"
 port: 1433
 server: 0.0.0.0
 username: sa
 resource_attributes:
   sqlserver.instance.name:
     enabled: true
   sqlserver.computer.name:
     enabled: true
 metrics:
   sqlserver.database_io.read_latency:
     enabled: true
```

**Documentation:** <Describe the documentation added.>
Updated README

.chloggen/sqlserver_direct_connect.yaml

@@ -0,0 +1,30 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: sqlserverreceiver
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Enable direct connection to SQL Server
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [30297]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  Directly connecting to SQL Server will enable the receiver to gather more metrics
+  for observing the SQL Server instance. The first metric added with this update is
+  `sqlserver.database.io.read_latency`.
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

receiver/sqlserverreceiver/README.md

@@ -13,29 +13,45 @@
 [contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
 <!-- end autogenerated section -->
 
-The `sqlserver` receiver grabs metrics about a Microsoft SQL Server instance using the Windows Performance Counters.
-Because of this, it is a Windows only receiver.
+The `sqlserver` receiver grabs metrics about a Microsoft SQL Server instance. The receiver works by either using the
+Windows Performance Counters, or by directly connecting to the instance and querying it. Windows Performance Counters
+are only available when running on Windows.
 
 Make sure to run the collector as administrator in order to collect all performance counters for metrics. 
 
 ## Configuration
 
 The following settings are optional:
 - `collection_interval` (default = `10s`): The internal at which metrics should be emitted by this receiver.
+- `instance_name` (optional): The instance name identifies the specific SQL Server instance being monitored.
+  If unspecified, metrics will be scraped from all instances. If configured, the `computer_name` must also be set
+  when running on Windows.
+
+Direct connection options (optional, but all must be specified to enable):
+- `username`: The username used to connect to the SQL Server instance.
+- `password`: The password used to connect to the SQL Server instance.
+- `server`: IP Address or hostname of SQL Server instance to connect to.
+- `port`: Port of the SQL Server instance to connect to.
 
-To collect from a SQL Server with a named instance, both `computer_name` and `instance_name` are required. For a default SQL Server setup, these settings are optional.
+Windows-specific options:
 - `computer_name` (optional): The computer name identifies the SQL Server name or IP address of the computer being monitored.
-- `instance_name` (optional): The instance name identifies the specific SQL Server instance being monitored.
+  If specified, `instance_name` is also required to be defined. This option is ignored in non-Windows environments.
 
 Example:
 
 ```yaml
     receivers:
       sqlserver:
         collection_interval: 10s
+      sqlserver/1:
+        collection_interval: 5s
+        username: sa
+        password: securepassword
+        server: 0.0.0.0
+        port: 1433
 ```
 
-When a named instance is used, a computer name and a instance name must be specified.
+When a named instance is used on Windows, a computer name and a instance name must be specified.
 Example with named instance:
 
 ```yaml

receiver/sqlserverreceiver/documentation.md

@@ -178,6 +178,34 @@ Number of users connected to the SQL Server.
 | ---- | ----------- | ---------- |
 | {connections} | Gauge | Int |
 
+## Optional Metrics
+
+The following metrics are not emitted by default. Each of them can be enabled by applying the following configuration:
+
+```yaml
+metrics:
+  <metric_name>:
+    enabled: true
+```
+
+### sqlserver.database.io.read_latency
+
+Total time that the users waited for reads issued on this file.
+
+This metric is only available when the receiver is configured to directly connect to SQL Server.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
+| ---- | ----------- | ---------- | ----------------------- | --------- |
+| s | Sum | Double | Cumulative | true |
+
+#### Attributes
+
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| physical_filename | The physical filename of the file being monitored. | Any Str |
+| logical_filename | The logical filename of the file being monitored. | Any Str |
+| file_type | The type of file being monitored. | Any Str |
+
 ## Resource Attributes
 
 | Name | Description | Values | Enabled |

receiver/sqlserverreceiver/factory.go

@@ -38,8 +38,11 @@ func createDefaultConfig() component.Config {
 
 func setupQueries(cfg *Config) []string {
 	var queries []string
-	// TODO: Only add query if metrics are enabled
-	queries = append(queries, getSQLServerDatabaseIOQuery(cfg.InstanceName))
+
+	if cfg.MetricsBuilderConfig.Metrics.SqlserverDatabaseIoReadLatency.Enabled {
+		queries = append(queries, getSQLServerDatabaseIOQuery(cfg.InstanceName))
+	}
+
 	return queries
 }
 

receiver/sqlserverreceiver/factory_others_test.go

@@ -30,6 +30,7 @@ func TestCreateMetricsReceiverOtherOS(t *testing.T) {
 				cfg.Server = "0.0.0.0"
 				cfg.Port = 1433
 				cfg.InstanceName = "instanceName"
+				cfg.Metrics.SqlserverDatabaseIoReadLatency.Enabled = true
 				require.NoError(t, cfg.Validate())
 
 				require.True(t, directDBConnectionEnabled(cfg))

receiver/sqlserverreceiver/factory_test.go

@@ -87,6 +87,7 @@ func TestCreateMetricsReceiver(t *testing.T) {
 				cfg.Server = "0.0.0.0"
 				cfg.Port = 1433
 				require.NoError(t, cfg.Validate())
+				cfg.Metrics.SqlserverDatabaseIoReadLatency.Enabled = true
 
 				require.True(t, directDBConnectionEnabled(cfg))
 				require.Equal(t, "server=0.0.0.0;user id=sa;password=password;port=1433", getDBConnectionString(cfg))

receiver/sqlserverreceiver/internal/metadata/testdata/config.yaml

@@ -7,6 +7,8 @@ all_set:
       enabled: true
     sqlserver.batch.sql_recompilation.rate:
       enabled: true
+    sqlserver.database.io.read_latency:
+      enabled: true
     sqlserver.lock.wait.rate:
       enabled: true
     sqlserver.lock.wait_time.avg:
@@ -56,6 +58,8 @@ none_set:
       enabled: false
     sqlserver.batch.sql_recompilation.rate:
       enabled: false
+    sqlserver.database.io.read_latency:
+      enabled: false
     sqlserver.lock.wait.rate:
       enabled: false
     sqlserver.lock.wait_time.avg:

receiver/sqlserverreceiver/metadata.yaml

@@ -31,6 +31,15 @@ attributes:
     description: The page operation types.
     type: string
     enum: [read, write]
+  physical_filename:
+    description: The physical filename of the file being monitored.
+    type: string
+  logical_filename:
+    description: The logical filename of the file being monitored.
+    type: string
+  file_type:
+    description: The type of file being monitored.
+    type: string
 
 metrics:
   sqlserver.user.connection.count:
@@ -158,6 +167,16 @@ metrics:
     unit: "{transactions}/s"
     gauge:
       value_type: double
+  sqlserver.database.io.read_latency:
+    enabled: false
+    description: Total time that the users waited for reads issued on this file.
+    unit: "s"
+    sum:
+      monotonic: true
+      aggregation_temporality: cumulative
+      value_type: double
+    attributes: [physical_filename, logical_filename, file_type]
+    extended_documentation: This metric is only available when the receiver is configured to directly connect to SQL Server.
 
 tests:
   config: