Adds both query_config and query_config_file to mssql integration

CHANGELOG.md

@@ -108,7 +108,7 @@ v0.38.0 (2023-11-21)
 
 - Allow agent to start with `module.git` config if cached before. (@hainenber)
 
-- Adds new optional config parameter `query_config_path` to `mssql` integration to allow for custom metrics (@StefanKurek)
+- Adds new optional config parameters `query_config_file` and `query_config` to `mssql` integration to allow for custom metrics (@StefanKurek)
 
 ### Bugfixes
 

component/prometheus/exporter/mssql/mssql.go

@@ -2,13 +2,15 @@ package mssql
 
 import (
 	"errors"
+	"fmt"
 	"os"
 	"time"
 
 	"github.com/grafana/agent/component"
 	"github.com/grafana/agent/component/prometheus/exporter"
 	"github.com/grafana/agent/pkg/integrations"
 	"github.com/grafana/agent/pkg/integrations/mssql"
+	"github.com/grafana/agent/pkg/util"
 	"github.com/grafana/river/rivertypes"
 	config_util "github.com/prometheus/common/config"
 )
@@ -37,11 +39,12 @@ var DefaultArguments = Arguments{
 
 // Arguments controls the mssql exporter.
 type Arguments struct {
-	ConnectionString   rivertypes.Secret `river:"connection_string,attr"`
-	MaxIdleConnections int               `river:"max_idle_connections,attr,optional"`
-	MaxOpenConnections int               `river:"max_open_connections,attr,optional"`
-	Timeout            time.Duration     `river:"timeout,attr,optional"`
-	QueryConfigPath    string            `river:"query_config_path,attr,optional"`
+	ConnectionString   rivertypes.Secret         `river:"connection_string,attr"`
+	MaxIdleConnections int                       `river:"max_idle_connections,attr,optional"`
+	MaxOpenConnections int                       `river:"max_open_connections,attr,optional"`
+	Timeout            time.Duration             `river:"timeout,attr,optional"`
+	QueryConfigFile    string                    `river:"query_config_file,attr,optional"`
+	QueryConfig        rivertypes.OptionalSecret `river:"query_config,attr,optional"`
 }
 
 // SetToDefault implements river.Defaulter.
@@ -63,17 +66,17 @@ func (a *Arguments) Validate() error {
 		return errors.New("timeout must be positive")
 	}
 
-	if a.QueryConfigPath != "" {
-		_, err := os.Stat(a.QueryConfigPath)
+	if a.QueryConfigFile != "" {
+		_, err := os.Stat(a.QueryConfigFile)
 
 		if err == nil {
 			return nil
 		}
 
 		if errors.Is(err, os.ErrNotExist) {
-			return errors.New("query_config_path must be a valid path of a YAML config file")
+			return errors.New("query_config_file must be a valid path of a YAML config file")
 		} else {
-			return errors.New("query_config_path file has issues")
+			return fmt.Errorf("query_config_file file has issues: %w", err)
 		}
 	}
 
@@ -86,6 +89,7 @@ func (a *Arguments) Convert() *mssql.Config {
 		MaxIdleConnections: a.MaxIdleConnections,
 		MaxOpenConnections: a.MaxOpenConnections,
 		Timeout:            a.Timeout,
-		QueryConfigPath:    a.QueryConfigPath,
+		QueryConfigFile:    a.QueryConfigFile,
+		QueryConfig:        util.RawYAML(a.QueryConfig.Value),
 	}
 }

component/prometheus/exporter/mssql/mssql_test.go

@@ -20,7 +20,7 @@ func TestRiverUnmarshal(t *testing.T) {
 	max_idle_connections = 3
 	max_open_connections = 3
 	timeout = "10s"
-    query_config_path = "` + goodQueryPath + `"`
+    query_config_file = "` + goodQueryPath + `"`
 
 	var args Arguments
 	err := river.Unmarshal([]byte(riverConfig), &args)
@@ -31,7 +31,7 @@ func TestRiverUnmarshal(t *testing.T) {
 		MaxIdleConnections: 3,
 		MaxOpenConnections: 3,
 		Timeout:            10 * time.Second,
-		QueryConfigPath:    goodQueryPath,
+		QueryConfigFile:    goodQueryPath,
 	}
 
 	require.Equal(t, expected, args)
@@ -65,7 +65,7 @@ func TestArgumentsValidate(t *testing.T) {
 				MaxIdleConnections: 1,
 				MaxOpenConnections: 0,
 				Timeout:            10 * time.Second,
-				QueryConfigPath:    goodQueryPath,
+				QueryConfigFile:    goodQueryPath,
 			},
 			wantErr: true,
 		},
@@ -76,7 +76,7 @@ func TestArgumentsValidate(t *testing.T) {
 				MaxIdleConnections: 0,
 				MaxOpenConnections: 1,
 				Timeout:            10 * time.Second,
-				QueryConfigPath:    goodQueryPath,
+				QueryConfigFile:    goodQueryPath,
 			},
 			wantErr: true,
 		},
@@ -87,18 +87,18 @@ func TestArgumentsValidate(t *testing.T) {
 				MaxIdleConnections: 1,
 				MaxOpenConnections: 1,
 				Timeout:            0,
-				QueryConfigPath:    goodQueryPath,
+				QueryConfigFile:    goodQueryPath,
 			},
 			wantErr: true,
 		},
 		{
-			name: "invalid query_config_path",
+			name: "invalid query_config_file",
 			args: Arguments{
 				ConnectionString:   rivertypes.Secret("test"),
 				MaxIdleConnections: 1,
 				MaxOpenConnections: 1,
 				Timeout:            0,
-				QueryConfigPath:    "doesnotexist.YAML",
+				QueryConfigFile:    "doesnotexist.YAML",
 			},
 			wantErr: true,
 		},
@@ -109,7 +109,7 @@ func TestArgumentsValidate(t *testing.T) {
 				MaxIdleConnections: 1,
 				MaxOpenConnections: 1,
 				Timeout:            10 * time.Second,
-				QueryConfigPath:    goodQueryPath,
+				QueryConfigFile:    goodQueryPath,
 			},
 			wantErr: false,
 		},
@@ -131,7 +131,7 @@ func TestConvert(t *testing.T) {
 	goodQueryPath, _ := filepath.Abs("../../../../pkg/integrations/mssql/collector_config.yaml")
 	riverConfig := `
 	connection_string = "sqlserver://user:pass@localhost:1433"
-	query_config_path = "` + goodQueryPath + `"`
+	query_config_file = "` + goodQueryPath + `"`
 	var args Arguments
 	err := river.Unmarshal([]byte(riverConfig), &args)
 	require.NoError(t, err)
@@ -143,7 +143,7 @@ func TestConvert(t *testing.T) {
 		MaxIdleConnections: DefaultArguments.MaxIdleConnections,
 		MaxOpenConnections: DefaultArguments.MaxOpenConnections,
 		Timeout:            DefaultArguments.Timeout,
-		QueryConfigPath:    goodQueryPath,
+		QueryConfigFile:    goodQueryPath,
 	}
 	require.Equal(t, expected, *res)
 }

docs/sources/flow/reference/components/prometheus.exporter.mssql.md

@@ -12,7 +12,8 @@ title: prometheus.exporter.mssql
 # prometheus.exporter.mssql
 
 The `prometheus.exporter.mssql` component embeds
-[sql_exporter](https://github.com/burningalchemist/sql_exporter) for collecting stats from a Microsoft SQL Server.
+[sql_exporter](https://github.com/burningalchemist/sql_exporter) for collecting stats from a Microsoft SQL Server and exposing them as
+Prometheus metrics.
 
 ## Usage
 
@@ -27,20 +28,32 @@ prometheus.exporter.mssql "LABEL" {
 The following arguments can be used to configure the exporter's behavior.
 Omitted fields take their default values.
 
-| Name                   | Type       | Description                                                       | Default | Required |
-| ---------------------- | ---------- | ----------------------------------------------------------------- | ------- | -------- |
-| `connection_string`    | `secret`   | The connection string used to connect to an Microsoft SQL Server. |         | yes      |
-| `max_idle_connections` | `int`      | Maximum number of idle connections to any one target.             | `3`     | no       |
-| `max_open_connections` | `int`      | Maximum number of open connections to any one target.             | `3`     | no       |
-| `timeout`              | `duration` | The query timeout in seconds.                                     | `"10s"` | no       |
-| `query_config_path`    | `string`   | The location of a custom query to prometheus metric config file.  |         | no       |
+| Name                   | Type       | Description                                                         | Default | Required |
+| ---------------------- | ---------- | ------------------------------------------------------------------- | ------- | -------- |
+| `connection_string`    | `secret`   | The connection string used to connect to an Microsoft SQL Server.   |         | yes      |
+| `max_idle_connections` | `int`      | Maximum number of idle connections to any one target.               | `3`     | no       |
+| `max_open_connections` | `int`      | Maximum number of open connections to any one target.               | `3`     | no       |
+| `timeout`              | `duration` | The query timeout in seconds.                                       | `"10s"` | no       |
+| `query_config_file`    | `string`   | MSSQL query to prometheus metric configuration file path.           |         | no       |
+| `query_config`         | `string`   | MSSQL query to prometheus metric configuration as an inline string. |         | no       |
 
 [The sql_exporter examples](https://github.com/burningalchemist/sql_exporter/blob/master/examples/azure-sql-mi/sql_exporter.yml#L21) show the format of the `connection_string` argument:
 
 ```conn
 sqlserver://USERNAME_HERE:PASSWORD_HERE@SQLMI_HERE_ENDPOINT.database.windows.net:1433?encrypt=true&hostNameInCertificate=%2A.SQL_MI_DOMAIN_HERE.database.windows.net&trustservercertificate=true
 ```
 
+Either `query_config_file` or `query_config` can be specified.
+The `query_config_file` argument points to a YAML file defining which MSSQL queries map to custom Prometheus metrics.
+The `query_config` argument must be a YAML document as string defining which MSSQL queries map to custom Prometheus metrics.
+`query_config` is typically loaded by using the exports of another component. For example,
+
+- `local.file.LABEL.content`
+- `remote.http.LABEL.content`
+- `remote.s3.LABEL.content`
+
+See [sql_exporter](https://github.com/burningalchemist/sql_exporter#collectors) for details on how to create a configuration file.
+
 ## Blocks
 
 The `prometheus.exporter.mssql` component does not support any blocks, and is configured
@@ -103,12 +116,12 @@ Replace the following:
 [scrape]: {{< relref "./prometheus.scrape.md" >}}
 
 ## Custom metrics
-It is possible to retrieve custom prometheus metrics for a mssql instance using the optional `query_config_path` parameter.
+You can use the optional `query_config_file` or `query_config` parameters to retrieve custom Prometheus metrics for a MSSQL instance.
 
-This parameter should point to a YAML config file defined [here](https://github.com/burningalchemist/sql_exporter#collectors). If it does, it will use the new config to query your mssql instance and create whatever metrics are defined.
-If you want additional metrics on top of the default provided ones, the default config should be used as a base.
+If either of these are defined, they will use the new configuration to query your MSSQL instance and create whatever Prometheus metrics are defined.
+If you want additional metrics on top of the default metrics, the default configuration must be used as a base.
 
-The default config file used by this integration is as follows:
+The default configuration used by this integration is as follows:
 ```
 collector_name: mssql_standard
 

docs/sources/static/configuration/integrations/mssql-config.md

@@ -10,7 +10,7 @@ title: mssql_config
 
 # mssql_config
 
-The `mssql_configs` block configures the `mssql` integration, an embedded version of [`sql_exporter`](https://github.com/burningalchemist/sql_exporter) that lets you collect [Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server) metrics.
+The `mssql_config` block configures the `mssql` integration, an embedded version of [`sql_exporter`](https://github.com/burningalchemist/sql_exporter) that lets you collect [Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server) metrics.
 
 It is recommended that you have a dedicated user set up for monitoring an mssql instance.
 The user for monitoring must have the following grants in order to populate the metrics:
@@ -19,12 +19,24 @@ GRANT VIEW ANY DEFINITION TO <MONITOR_USER>
 GRANT VIEW SERVER STATE TO <MONITOR_USER>
 ```
 
+## Quick configuration example
+
+To get started, define the MSSQL connection string in Grafana Agent's integration block:
+
+```yaml
+metrics:
+  wal_directory: /tmp/wal
+integrations:
+  mssql:
+    enabled: true
+    connection_string: "sqlserver://[user]:[pass]@localhost:1433"
+```
 
 Full reference of options:
 
 ```yaml
-  # Enables the mssql integration, allowing the Agent to automatically
-  # collect metrics for the specified mssql instance.
+  # Enables the MSSQL integration, allowing the Agent to automatically
+  # collect metrics for the specified MSSQL instance.
   [enabled: <boolean> | default = false]
 
   # Sets an explicit value for the instance label when the integration is
@@ -34,7 +46,7 @@ Full reference of options:
   [instance: <string>]
 
   # Automatically collect metrics from this integration. If disabled,
-  # the mssql integration is run but not scraped and thus not
+  # the MSSQL integration is run but not scraped and thus not
   # remote-written. Metrics for the integration are exposed at
   # /integrations/mssql/metrics and can be scraped by an external
   # process.
@@ -64,32 +76,39 @@ Full reference of options:
   # Exporter-specific configuration options
   #
 
-  # The connection_string to use to connect to the mssql instance.
+  # The connection_string to use to connect to the MSSQL instance.
   # It is specified in the form of: "sqlserver://<USERNAME>:<PASSWORD>@<HOST>:<PORT>"
   connection_string: <string>
 
-  # The maximum number of open database connections to the mssql instance.
+  # The maximum number of open database connections to the MSSQL instance.
   [max_open_connections: <int> | default = 3]
 
-  # The maximum number of idle database connections to the mssql instance.
+  # The maximum number of idle database connections to the MSSQL instance.
   [max_idle_connections: <int> | default = 3]
 
-  # The timeout for scraping metrics from the mssql instance.
+  # The timeout for scraping metrics from the MSSQL instance.
   [timeout: <duration> | default = "10s"]
 
-  # The file path for a YAML config file which allows for custom queries/metrics
-  # for the mssql instance
-  [query_config_path: <string>]
-
+  # Path to a YAML configuration file with custom Prometheus metrics and MSSQL queries.
+  # This field has precedence to the config defined in the query_config block.
+  # See https://github.com/burningalchemist/sql_exporter#collectors for more details how to specify your configuration file.
+  [query_config_file: <string>]
+
+  # Embedded MSSQL query configuration for custom MSSQL Prometheus metrics.
+  # You can specify your metrics and queries here instead of in an external configuration file.
+  # See https://github.com/burningalchemist/sql_exporter#collectors for more details how to specify your metric configurations.
+  query_config: 
+    [- <metrics> ... ]
+    [- <queries> ... ]]
 ```
 
 ## Custom metrics
-It is possible to retrieve custom prometheus metrics for a mssql instance using the optional `query_config_path` parameter.
+You can use the optional `query_config_file` or `query_config` parameters to retrieve custom Prometheus metrics for a MSSQL instance.
 
-This parameter should point to a YAML config file defined [here](https://github.com/burningalchemist/sql_exporter#collectors). If it does, it will use the new config to query your mssql instance and create whatever metrics are defined.
-If you want additional metrics on top of the default provided ones, the default config should be used as a base.
+If either of these are defined, they will use the new configuration to query your MSSQL instance and create whatever Prometheus metrics are defined.
+If you want additional metrics on top of the default metrics, the default configuration must be used as a base.
 
-The default config file used by this integration is as follows:
+The default configuration used by this integration is as follows:
 ```
 collector_name: mssql_standard