# Configuration

Central Repository can download data from remote instances in two ways:

1. Linked Server
2. SQL Server Integration Services (SSIS)

Both methods do a FULL load of the relatively small `meta*` tables and delta loads of the `logger*` tables that contain the actual performance data. Whilst SSIS is a performance optimised engine and may perform faster, there is no noticable performance advantage of using either method and both perform in a similar way when pulling remote data. The advantage of using Linked Server is that it does not require SSIS and can be run on a SQL Server Express Edition with jobs invoked via Windows Scheduled Tasks instead of the SQL Agent.

> Linked Server approach is build programatically and therefore easier to develop and maintain. It contains a number of improvements over the SSIS method, such as message logging to a table, automatic table import without the explicit declaration (SSIS requires meta data refresh which slows down the development) and force full load of the header tables if missing keys are detected.

## Add Remote Instance

In order for the central respository to know which remote instances to collect data from, they must be defined in `[dbo].[sqlwatch_config_sql_instance]`

This can be achieved by directly inserting data into the table, or by executing a stored procedure:

```sql
exec [dbo].[usp_sqlwatch_config_repository_add_remote_instance]
    @sql_instance --sql instance name,
    @hostname --hostname, if different to the @sql_instance, for example this could be in IP if no DNS records present,
    @sql_port --non standard sql port, leave NULL for the default 1433,
    @sqlwatch_database_name --name of the SQLWATCH database,
    @environment --name of the environment (DEV,PROD,QA or anything) - this is for the user convinience,
    @linked_server_name --name of the linked server, a new LS will be created if not exists. If you prefer to use existing LS, leave this blank and manually update [linked_server_name] in [dbo].[sqlwatch_config_sql_instance]. If you are using SSIS, leave NULL. 
    @rmtuser --username for the linked server authentication, leave NULL for default Windows Auth or when using SSIS,
    @rmtpassword --password for the linked server authentication, leave NULL for default Windows Auth or when using SSIS,
```

![\[dbo\].\[sqlwatch\_config\_sql\_instance\]](https://560149426-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LamHUpIpVXoBUUDZZpO%2F-Lx2FmcVi7BdMTy2Mxtd%2F-Lx2FxaF7HkNH0pMEQJJ%2Fimage.png?alt=media\&token=6e33a37a-5531-4d47-855b-404906896847)

## Linked Server

In order to invoke collection via Linked Server, a linked server object to the SQLWATCH database on each monitored instance must be created. This can be achieved by executing stored procedure:`[dbo].[usp_sqlwatch_user_repository_create_linked_server]`

### Create all required linked servers

The procedure can create all required linked servers as per the `[linked_server_name]` column in `[dbo].[sqlwatch_config_sql_instance]` table:

```sql
exec [dbo].[usp_sqlwatch_config_repository_create_linked_server]
    @rmtuser --optional user name for the remote instance (same for all) or blank to use default windows auth,
    @rmtpassword --optional password for the remote instance (same for all) or blank to use default windows auth
```

### Create specific linked server

Alternatively, it can create only specific linked server. This is the default bahavior when executing `[dbo].[usp_sqlwatch_user_repository_add_remote_instance]`

```sql
exec [dbo].[usp_sqlwatch_config_repository_create_linked_server]
    @sql_instance --name of the existing sql instance in [dbo].[sqlwatch_config_sql_instance],
    @linked_server --optional, name of the required linked server. if blank a default name will be created,
    @rmtuser --optional user name for the remote instance (same for all) or blank to use default windows auth,
    @rmtpassword --optional password for the remote instance (same for all) or blank to use default windows auth
```

{% embed url="https://docs.microsoft.com/en-us/sql/relational-databases/linked-servers/create-linked-servers-sql-server-database-engine" %}

### Create remote collector jobs

Linked Server collector can be multithreaded and there is no limit on the number of threads providing the performance of the central repository is adequate. The linked server approach creates a table based queue of all remote objects to import with the required dependency (i.e. meta tables first, the logger tables) in `[dbo].[sqlwatch_meta_repository_import_queue]`

The queue can be then processed by executing stored procedure:`exec [dbo].[usp_sqlwatch_repository_remote_table_import]`

To increase the number of import threads schedule the above procedure multiple times.

To create default repository agent jobs, please execute the below procedure:

```sql
exec [dbo].[usp_sqlwatch_config_repository_create_agent_jobs]
    @threads = --number of thread jobs to create
```

This will result in the following jobs to be created:

1. A single enqueuing job that creates list of remote objects to pull data from (`[dbo].[sqlwatch_meta_repository_import_queue]`) and umltimately controls how often they are processed.&#x20;
2. A single or multiple import jobs, depending on the `@threads` variable that will process the import queue. These jobs can run every 1 minute and will process any outstanding items in the queue table.&#x20;

![Example of @threads = 8](https://560149426-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LamHUpIpVXoBUUDZZpO%2F-Lx288IKa_ZaFIZt86X1%2F-Lx2FeKFbCZXv5ssUG3q%2Fimage.png?alt=media\&token=b0e7e368-7e1b-4eac-b952-57c396c6ab6f)

### Execution

Each thread registers itself in the threads table `[dbo].[sqlwatch_meta_repository_import_thread]` which contains the name of the SQL Agent Job currently running the thread

![\[dbo\].\[sqlwatch\_meta\_repository\_import\_thread\]](https://560149426-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LamHUpIpVXoBUUDZZpO%2F-Lx2IRicXEyMew0VrGn9%2F-Lx2JGtju9DdB55G8xgN%2Fimage.png?alt=media\&token=0b8a5c13-da1e-4d1f-9ea4-f10ee264fb3f)

Import status of each object can be seen in the `[dbo].[sqlwatch_meta_repository_import_status]` table:

![](https://560149426-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LamHUpIpVXoBUUDZZpO%2F-Lx2L-Nwi8etJpI6ZajT%2F-Lx2LBsSL763Ni8v1QDb%2Fimage.png?alt=media\&token=165b3d35-3983-4f79-89f3-65b2d4b950de)

## SSIS

### Package Configuration

To configure SSIS package, navigate to the Project in the **Integration Services Catalogs**:

![](https://560149426-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LamHUpIpVXoBUUDZZpO%2F-LvS9VSyWhuXNz7YKPhd%2F-LvSAZ4Sxiu7DOv6eWrJ%2Fimage.png?alt=media\&token=02d370a6-8829-4929-b9e6-310887338311)

{% hint style="info" %}
You can apply configuration to the project, or individual packages. The project will contain the collection of all configuration options from child packages.
{% endhint %}

{% embed url="https://docs.microsoft.com/en-us/sql/integration-services/catalog/ssis-catalog" %}

### Control package

The control package `control_import.dtsx` is responsible for orchestrating multi-threaded data collection and execution of the Worker Package `import_remote_data.dtsx`

![](https://560149426-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LamHUpIpVXoBUUDZZpO%2F-LrVU0YCsyyp89XGJX7r%2F-LrVV7a5LVbPw1vmqWK9%2Fimage.png?alt=media\&token=c9c0ca11-c1a1-4743-b509-d8a075ee1fc4)

#### Parameters

**number\_of\_parallel\_collectors**\
Number of threads for parallel collection. If this is set to > 1, then multiple servers will be collected in parallel, in addition to each collector data flow being run in parallel, according to the `MaxConcurrentExecutables` parameter. Be careful as running parallel collectors may be slower than single thread. Make sure central repository can sustain the workload. Maximum allowed parallel threads are 8.

**repository\_database**\
Name of the database where the central repository is. Default SQLWATCH.

**repository\_instance\_name**\
Name of the SQL Server instance where the central repository is hosted.

**repository\_password**\
SQL Password to access central repository or blank for Windows authentication.

**repository\_user\_name**\
SQL User to access central repository or blank for Windows authentication.

### Worker Package

The worker package `import_remote_data.dtsx` is responsible for the actual data collection from remote instances into the central repository.

![](https://560149426-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LamHUpIpVXoBUUDZZpO%2F-LrVWLMNThaalszQJxlm%2F-LrVWaeUDDim7lZ9q1kt%2Fimage.png?alt=media\&token=29d9f014-107e-419b-b7a1-059b9f9fc7b4)

#### Parameters

**last\_snapshot\_offset\_minutes**\
Offset in minutes to increase delta time slice. By default only data since last snapshot will be collected from the remote instance. We may increase this and go further beyond that to cover any gaps. Behind the scenes this translates to `[snapshot_time] > dateadd(minute,-@last_snapshot_offset_minutes,[last_snapshot_time])`

{% hint style="warning" %}
Not currently used, reserved for future use
{% endhint %}

**remote\_instance\_name**\
SQL Instance to collect data from. This parameters is passed from the control package during run time.

**remote\_password**\
SQL Password for the remote instance or blank for Windows authentication.

**remote\_user\_name**\
SQL User for the remote instance or blank for Windows authentication.

{% hint style="info" %}
In the current implementation it is not possible to specify different accounts for accessing remote instances. This means that when using SQL Authentication all instances must have the same SQL User and Password. When using Windows authentication this is usually not a problem as the SSIS runs under a context of one the SQL agent or proxy account
{% endhint %}

**repository\_database**\
Name of the database where the central repository is. Default SQLWATCH.

**repository\_instance\_name**\
Name of the SQL Server instance where the central repository is hosted.

**repository\_password**\
SQL Password to access central repository or blank for Windows authentication.

**repository\_user\_name**\
SQL User to access central repository or blank for Windows authentication.

### Execution

### Central repository collector

The package does delta loads of the `logger*` tables and full loads of the `meta*` tables. Meta tables are relatively small and should not contain more than a few hundred rows. Logger tables can be quite big and thanks to delta loads, the more often the package runs, the less data it pulls with every run.

There is no predefined agent job for the SSIS based repository collector due to variety of environments and folder names in SSISDB. Once the package has been deployed onto the preferred Integration Services Server and configured please crate agent job with the schedule as you please.

When scheduling the `dtsx`, the control package should be called from the agent job:

![](https://560149426-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LamHUpIpVXoBUUDZZpO%2F-LrivaqDt8NAwHXamy-O%2F-LrivnYQrxLHEf4H-CHu%2Fimage.png?alt=media\&token=c3b39f69-31a9-4db6-951a-adf341f72796)
