psTerminalPerfCounter

In the previous article I gave a quick rundown of the history and inner workings of Windows Performance Counters, now comes the hands-on part. The basis is release 0.4.1, which is all about visualization and data export. New additions: CSV export, a terminal GUI replacing the text-based view, and HTML export via PSWriteHTML. Sounds exciting… and it is 🙂 I figure you see it the same way, otherwise you wouldn’t still be reading. 🙂

Installation

Installing a PowerShell module, nothing special

# Install psTerminalPerfcounter
Install-Module psTerminalPerfCounter

# List Cmdlets
Get-Command -Module psTerminalPerfCounter

# Install PSWriteHtml, required for HTML Export
Install-Module PSWriteHtml

Basic Structure, Counter Configs

psTerminalPerfCounter works with configuration files that describe the counter sets and their configuration: counter IDs, instances (whether, for example, all CPU cores or only core 3 and 4 should be monitored), value conversion, units, and the color coding of the graphs via the so-called ColorMap, which however is only supported by the legacy visualization.

Counter configs can be stored in any path and called from there. Alternatively, paths can be registered, which allows calling them simply by the config name. The default path is the config folder within the module itself, which already ships with a few predefined configs.

# List all registered paths
Get-tpcConfigPaths

# Add custom path
Add-tpcConfigPath -Path 'C:\tpcConfig'

# List all Counterconfigs and details in all paths
Test-tpcAvailableCounterConfig

Single Server Monitoring

The fastest method is a single server, local or remote.

# Use CPU Config locally
Start-tpcMonitor -Configname CPU
Start-tpcMonitor -Confipath 'C:\Users\labadmin\Documents\PowerShell\Modules\psterminalperfcounter\0.4.0\Config\tpc_CPU.json'

# Use CPU Config remote
Start-tpcMonitor -Computername 'dev-node1' -Configname CPU
Start-tpcMonitor -Computername 'dev-node1' -Confipath 'C:\Users\labadmin\Documents\PowerShell\Modules\psterminalperfcounter\0.4.0\Config\tpc_CPU.json'

# Use CPU Config rmeote with different credentials
Start-tpcMonitor -Computername 'dev-node1' -Credentials $(Get-Credential) -Configname CPU

Since the legacy visualization reaches its limits at the latest with multi-server environments, I use the -TUI switch for this hands-on.

# Use CPU Config locally with TUI
Start-tpcMonitor -Configname CPU -TUI

Multi Server Monitoring

Multi-server monitoring also works via configuration files, although while writing these lines it occurs to me: why did I never think of simply running a counter config against a server list? Onto the backlog with that. Anyway, in the environment configuration you can define any number of servers with different configs. Since I recently still had trouble making the sparklines in the TUI scrollable, they are disabled in the multi-server view.

# Start multi server monitoring
Start-tpcEnvironmentMonitor -EnvConfigPath 'C:\tpcConfig\ENV_SERVER_EXAMPLE.json' -TUI

LAB-NODE03 is a German installation in this case

The Duration column shows the time the function needed on each server to collect all values. The final timestamp of the entire data set is always defined by the slowest server, as only this way is a homogeneous time series possible. A variance of, in this case, 1.3 seconds cannot be avoided here.

That’s all there is to running it, since this module only provides the framework. The actual life comes with the counter configs. Let’s now take a look at how these are created.

Creating Counter Configs

In the beginning there is the performance counter. Before we can write the configuration, we need the counter IDs instead of the localized names. For that there is Get-tpcPerformanceCounterInfo, which works in both directions: counter path to ID and vice versa.

# List all counter and counter objects containing 'processor time'
Get-tpcPerformanceCounterInfo -ComputerName 'dev-node1' -SearchTerm 'processor time'

The last two columns are important. There are single-instance counters with only one value, but also multi-instance counters like the Processor counter set, where each instance corresponds to a core, or the total (_Total).

In the same way you can use the cmdlet to find out which counter is hidden behind a composite ID.

# Show counter name of composite ID
Get-tpcPerformanceCounterInfo -ComputerName 'dev-node1' -SearchTerm '238-6'

Or on a German system

Let’s also take counters that are not present by default on a Windows system: SQL Server. DEV22A in this case is the first instance on the system.

# "Out-String -Stream" converts PowerShell's internal formatting objects into actual strings line by 
# line, enabling string operations like `Select-String` to work on them.

Get-tpcPerformanceCounterInfo -ComputerName 'dev-node1' -SearchTerm 'dev22a' | 
		Out-String -Stream | 
		Select-String "lookup"

Let’s take Page lookups/sec for testing –> 12222-12272

Get-tpcPerformanceCounterInfo -ComputerName 'dev-node1' -SearchTerm 'dev22a' | 
		Out-String -Stream | 
		Select-String "log flushes"

And log flush/sec on the TempDB instance –> 12352-12446

The minimal config then looks like this. Some values are missing for the SQL Server counters, but that is not SQL Server specific, it shows that most fields receive defaults. Details on this can be found in the docs in the repo. Also worth mentioning: for CPU I use "counterInstance": "1|2", which automatically creates two counters, and for the page lookups the conversion by 1000 so that the numbers stay readable.\

{
	"name": "CPU and Sql Server Page Usage",
	"description": "CPU Usage",
	"counters": [
		{
			"title": "CPU Usage",
			"unit": "%",
			"conversionFactor": 1,
			"conversionExponent": 1,
			"conversionType": "D",
			"format": "table",
			"counterID": "238-6",
			"counterSetType": "MultiInstance",
			"counterInstance": "0|1",
			"colorMap": {
				"20": "Green",
				"50": "Yellow",
				"70": "RED"
			}
		},
		{
			"title": "Sql DEV22A Page Lookups/s",
			"unit": "#K",
			"conversionFactor": 1000,
			"conversionExponent": 1,
			"conversionType": "D",
			"counterID": "12222-12272",
			"counterSetType": "SingleInstance",
			"counterInstance": ""
		},
		{
			"title": "Sql DEV22A TempDB Log Flushes/s",
			"unit": "#",
			"counterID": "12352-12446",
			"counterSetType": "MultiInstance",
			"counterInstance": "tempdb"
		}

	]
}

Then save the whole thing in a registered path with the prefix tpc_NAME.json and off we go.

Monitoring an Environment with an Environment File

No magic here either. Config names or paths can be specified. A function that is not yet fully documented is the use of SecretVaults: via the PowerShell connectors, credentials can be loaded from almost all common solutions, which also gives non-admins the ability to monitor systems.

[
    {
        "name": "SQL_ENVIRONMENT_001",
        "description": "SQL Server Environment Production",
        "interval": 2,
        "secretvaultname": "SecretStore",
        "credentialname": "integrated",
        "servers": [
            {
                "computername": "DEV-NODE1",
                "comment": "Sql Server Node A Production",
                "counterConfig": [
                    "SQLDEMO"
                ]
            },
            {
                "computername": "DEV-NODE2",
                "comment": "Sql Server Node B Production",
                "counterConfig": [
                    "C:\Users\devadmin\Desktop\tpc_SQLDEMO.json"
                ]
            }
        ]
    }
]

# without TUI
Start-tpcEnvironmentMonitor -EnvConfigPath "C:\Users\devadmin\Desktop\ENV_SERVER_EXAMPLE2.json"

Data Export

CSV

To reuse the time series, you can export to CSV. Caution, currently still a known bug: the export is comma-separated, so values containing a comma get split as well, fixed in 0.4.1.

# -CsvPath is default desktop
	Start-tpcEnvironmentMonitor -EnvConfigPath "C:\Users\devadmin\Desktop\ENV_SERVER_EXAMPLE2.json" -ExportCsv

HTML Report

An alternative visualization as HTML, useful when I want to pass on a time series without bothering with Excel or other tools. Grouping can be done by counter or by server, depending on whether, with multiple servers, I want to see all counters of one server in a single chart, or one specific counter across multiple servers. Details on this can be found in the docs in the repo.

To note: the HTML contains a rolling data set bound to the maximum number of samples. The more samples, the more sluggish the HTML becomes. For large time series, better use CSV.

# -HTMLPath is default desktop
	Start-tpcEnvironmentMonitor -EnvConfigPath "C:\Users\devadmin\Desktop\ENV_SERVER_EXAMPLE2.json" -ExportHTML

That’s it as a quick start, more details on the individual functions can be found, as always, in the docs and the README in the repository.

The post psTerminalPerfCounter – Performance Counter in Terminal – HowTo first appeared on DBA von Nebenan.

psTerminalPerfCounter

It has been almost a year now since I started developing psTerminalPerfCounter. Proud of the „graphical“ implementation, language independence via a 3rd-party lib and the holy grail of the time: classes in PowerShell.

None of it survived:

• Graphical implementation? Nice and colorful, but…
  • Sluggish as a rock in multi-server environments
  • Dynamic and scalable? Nope
  • Reimplemented as a TUI (BETA)
    
• Multi-language via 3rd-party lib
  • Turns out it all works directly through the Windows registry, stumbled across it by accident
    
• Classes in PowerShell? Very bad decision.
  • Not practical, instances aren’t easily serializable, methods get lost, parallel remoting with runspaces barely doable
  • Rebuild in C#

With the current release 0.4.1, all the features I had in my backlog are implemented for now. Since I will be lacking the time for this project over the next few months, this is a good moment to write a HowTo, because the README.md in the repo can be a bit challenging at times… as it seems 🙂 But before we get to the hands-on, let’s first talk a little about the technology and history of performance counters.

History

Windows performance counters have been around since NT 3.1 (1993), back then I didn’t even own a computer. At the time, Microsoft needed a standardized way to expose system states without every application having to implement its own monitoring mechanisms. But that also meant scraping measurement values out of the registry and calculating deltas yourself.

Windows 2000 added the Performance Data Helper (PDH) as a convenient high-level API, which shaped access to performance counters the way we know it today. At the same time, WMI was introduced, making performance data accessible through an object-oriented interface. CIM just wasn’t proprietary enough and a bit too compatible 😛

Windows Vista brought the revised Provider V2 model: instead of a DLL that was loaded by the system into a foreign process (error-prone, provider crash = crash of the querying process), providers now register as standalone executables or services. That is the model still in use today.

Structure and Function

Metadata in the registry

All known counters are registered under HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib. That’s where the name, description and a numeric index number per counter live, separated by language (subkey 009 for English, 007 for German, etc.).

# List available language packs (counter IDs)
Get-ChildItem "HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib"

Providers deliver the raw data

Every component (kernel, drivers, services like IIS or SQL Server, the .NET runtime) can register its own counters. The provider waits passively and only delivers data once someone queries it. There is no permanent collection service running in the background.

# List all services that have a Performance subkey

Get-ChildItem "HKLM:\SYSTEM\CurrentControlSet\Services" |
    Where-Object { Test-Path "$($_.PSPath)\Performance" } |
    ForEach-Object {
        $perf = Get-ItemProperty "$($_.PSPath)\Performance"
        [PSCustomObject]@{
            Service      = $_.PSChildName
            FirstCounter = $perf.'First Counter'
            LastCounter  = $perf.'Last Counter'
            Library      = $perf.Library
        }
    } | Format-Table -AutoSize

APIs for applications (CONSUMER)

• PDH (Performance Data Helper): The convenient API that returns values already formatted (e.g. percentages calculated, intervals taken into account). Get-Counter in PowerShell uses PDH.
• PerfLib / registry directly: Faster, but raw. WMI uses this path internally.

Structure

\Processor(_Total)\% Processor Time
└─ Object: „Processor“
└─ Instance: „_Total“ (sum of all cores)
└─ Counter: „% Processor Time“

Microsoft’s Tools

The grandfather: PerfMon

The Performance Monitor has been Microsoft’s official tool since the NT days and, for what it was built for, it is still excellent: interactive, graphical deep-dive analysis of individual systems, with recording via Data Collector Sets, CSV export via relog and basic remoting. The limits show up the moment you want to scale, automate or simply work in the terminal. Portable configuration files, keeping an eye on multiple servers at once or a structured console workflow are not its strengths.

The newcomer: Windows Admin Center

Microsoft’s browser-based management interface also comes with a performance view, cleaner than Perfmon and without a local installation on the managed system. For a quick look at CPU, memory and network that’s perfectly fine. Two things limit its practical value though: first, WAC requires a central installation, just quickly firing it up on a client or at a customer’s site isn’t an option. Second, the counter selection is based, as everywhere, on the localized PDH API, which makes workspaces not really portable.

The evergreen: Get-Counter

Get-Counter is the PowerShell equivalent for console use and therefore the most flexible of the three tools, as long as you’re up for some fiddling willing to get your hands dirty. Counters can be queried directly, repeated in a loop and sent down the pipeline. Remoting works via the -ComputerName parameter. The problem is the same as everywhere: the counter paths are language-dependent, a script written on a German system fails on an English one. On top of that, Get-Counter returns raw data. Formatting, thresholds, history visualization and structured output are entirely manual work. For one-off queries and quick checks it’s ideal, for reproducible, multi-language environments it quickly hits its limits.

# Query CPU, memory and disk counters every 5 seconds, format output as table
$counters = @(
    '\Processor(_Total)\% Processor Time',
    '\Memory\Available MBytes',
    '\PhysicalDisk(_Total)\Disk Bytes/sec'
)

# German Counternames
# $counters = @( 
#	'\Processor(_Total)\% Processor Time', 
#	'\Memory\Available MBytes', 
#	'\PhysicalDisk(_Total)\Disk Bytes/sec' 
# )

Get-Counter -Counter $counters -SampleInterval 5 -Continuous | ForEach-Object {
    $sample = $_.CounterSamples

    [PSCustomObject]@{
        Timestamp       = $_.Timestamp
        'CPU %'         = [math]::Round(($sample | Where-Object Path -like '*processor*').CookedValue, 1)
        'RAM frei (MB)' = [math]::Round(($sample | Where-Object Path -like '*available*').CookedValue, 0)
        'Disk B/s'      = [math]::Round(($sample | Where-Object Path -like '*disk bytes*').CookedValue, 0)
    } | Format-Table -AutoSize
}

The path to language independence

As you can see, language dependence is a big problem across all implementations. And it’s not even necessary. Under the hood, every counter object and every counter has a unique ID. Take a look at the screenshots above, there’s always a First and Last Counter. So \Processor(_Total)\Processor Time (%) –> \238(_Total)\6 .

# Read counter ID/name mapping from registry (English - key 009, German - key 007)
Get-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\009' -Name Counter |
		Select-Object -ExpandProperty Counter | Select-Object -First 20

That’s it. The counter object and the path just need to be translated once and I’ve got my language-independent counter path. Before execution it gets translated on the target system and then Get-Counter -Counter <TRANSLATION> is run. In psTerminalPerfCounter this is handled by the cmdlet get-tpcPerformanceCounterInfo

https://dbavonnebenan.de/psterminalperfcounter-counter-in-terminal-handson_en/

The post Windows Performance Counters: How the OS Monitors Itself first appeared on DBA von Nebenan.

What awaits you here?

• Windows Server Failover Cluster Deployment with Extended AD and DNS Permissions
• Identity Management: Group Managed Service Accounts (gMSA)
• Kerberos and Service Principal Names (SPN)
• Local Security Policies
• Background knowledge on why configurations are done the way they are

Intro

Who hasn’t been there? Before you can even start installing SQL Server, you’ve either repetitively clicked through pages of bad GUIs or, if available, juggled a loose collection of scripts to semi-automatically set up all dependencies and best practices.

Even worse is the case when, as a consultant, you don’t have Domain Admin access (which is how it should be) and you have to guide the customer — who may have never done this before — via Teams & Co. If this isn’t already a planned installation with knowledge transfer, something like this creates pain.

Accordingly, I’ve now gathered all my loose scripts and developed a function for each topic area that automates all these tasks and logs them for archival purposes. Thanks also to Claude for the support. Nobody reviews and documents code better than Claude.

Now you might ask: Aren’t there dbatools and DSC? Sure, I like using those too. But transparent, traceable scripts without framework overhead convey knowledge better — especially when aspiring DBAs lack the big-picture perspective. Operating SQL Server starts at the bare metal, goes through storage, Windows Server, Active Directory, and ends at a Certificate Authority. And for critical infrastructure companies or small mid-sized businesses with 3 clusters, I don’t want to start a fundamental discussion about dbatools or DSC right from the beginning.

Let’s start with a production-ready Windows Server Failover Cluster — including CNO/VCO permissions, DNS registration, and quorum configuration. Everything repeatable, everything logged, everything traceable.

The Lab Scenario

To make the steps tangible, the following environment and naming conventions are used

• Nodes
  • LAB-NODE01 (192.168.100.12)
  • LAB-NODE02 (192.168.100.13)
• Cluster Name
  • MSSQL-CL-01 (192.168.100.14)
• SQL Instance
  • LAB22A
• Domain
  • lab.local
• Service Accounts Group Managed Service Accounts (gMSA)
  • g-LAB22A-oltp
  • g-LAB22A-agnt

Windows Server Failover Cluster Deployment

The WSFC forms the foundation for AlwaysOn Availability Groups. The script manages the entire lifecycle from feature installation to witness configuration.

Feature Installation & Cluster Creation

First, the Failover-Clustering feature is installed on the individual nodes and the cluster is created. An important aspect of automation is the Cluster Name Object (CNO): It needs write permissions in DNS and Active Directory to be able to automatically create listener records later.

.\cluster_manageSQLCluster.ps1 `
    -Operation InstallFeature `
    -Nodes "LAB-NODE01","LAB-NODE02" `
    -LogPath "C:\Temp\Cluster_Feature_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Afterwards, the cluster is created. The script additionally sets the corresponding permissions in AD and DNS.

.\cluster_manageSQLCluster.ps1 `
    -Operation CreateCluster `
    -ClusterName "MSSQL-CL-01" `
    -Nodes "LAB-NODE01","LAB-NODE02" `
    -StaticIP "192.168.100.14" `
    -DnsDomain "lab.local" `
    -TargetOU "OU=lab_computer,DC=lab,DC=local" `
    -LogPath "C:\Temp\Cluster_Create_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

File Share Witness (Quorum)

For a 2-node cluster, a witness is mandatory to avoid split-brain scenarios. Here, a file share on the domain controller (\\LAB-DC\quorum$) is used.

Manual Intermediate Step
The Cluster Computer Object (MSSQL-CL-01$) requires Full Control at both the share and NTFS permission level of the witness path (\\LAB-DC\quorum$). This must be ensured before running the following command.

.\cluster_manageSQLCluster.ps1 `
    -Operation SetWitness `
    -ClusterName "MSSQL-CL-01" `
    -WitnessShare "\\LAB-DC\quorum$" `
    -LogPath "C:\Temp\Cluster_Witness_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Microsoft Cmdlets Used

The script primarily uses the FailoverClusters module

• New-Cluster
  • Creates the cluster, adds the nodes, and sets the management IP
• Set-ClusterQuorum
  • Configures the witness mode (here: File Share Witness)
• Install-WindowsFeature
  • Installs the RSAT tools and the cluster service

Identity Management: gMSA

Using standard users as service accounts can lead to expired passwords and downtime. The recommended method for SQL Server is Group Managed Service Accounts (gMSA). Here, the Key Distribution Service (KDS) of Active Directory handles password rotation; nobody needs to know the password.

KDS Root Key

Before the first gMSA can be created, a KDS Root Key must exist once per forest. If a key already exists, the creation will be skipped.

.\security_createGMSA.ps1 `
    -InitializeKDS `
    -LogPath "C:\Temp\KDS_Init.log"

gMSA Creation

Instead of assigning servers directly to a gMSA, it is best practice to create a security group (SQL_LAB_CL01) that contains the computer accounts of the cluster nodes. In addition to setting up the actual gMSA, this script can also create the security groups and handle the assignments. And always keep the descriptions of AD objects well-maintained.

.\security_createGMSA.ps1 `
    -AccountName @( `
        @("g-LAB22A-oltp", "SQL Server Engine Account for LAB22A"), `
        @("g-LAB22A-agnt", "SQL Server Agent Account for LAB22A") ) `
    -SecurityGroupName "SQL_LAB_CL01" `
    -SecurityGroupDescription "SQL Server Cluster CL01 gMSA Group" `
    -ServerNames "LAB-NODE01","LAB-NODE02" `
    -CreateSecurityGroup `
    -SecurityGroupOU "OU=lab_secgrp,DC=lab,DC=local" `
    -PasswordIntervalDays 90 `
    -LogPath "C:\Temp\gMSA_Creation_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

After this step, a restart of the nodes is required for the new group membership to take effect.

Local Registration

After creation, the gMSAs must be registered locally on the nodes. The following script can be used for this purpose.

# Required for local setup (Local Admin)
Add-WindowsFeature -Name RSAT-AD-PowerShell

$gMSAs = @(
    'g-LAB22A-oltp',
    'g-LAB22A-agnt'
)

foreach ($gMSA in $gMSAs) {

    if (Test-ADServiceAccount -Identity $gMSA -ErrorAction SilentlyContinue) {
        try {
            Install-ADServiceAccount -Identity $gMSA -ErrorAction Stop
            Write-Host "$gMSA installed" -ForegroundColor Green
        } catch {
            Write-Host "$gMSA - Installation error: $($_.Exception.Message)" -ForegroundColor Red
        }
    } else {
        Write-Host "$gMSA does not exist" -ForegroundColor Yellow
    }
}

After this step, a restart of the nodes is required for the new group membership to take effect.

Microsoft Cmdlets Used

The script primarily uses the ActiveDirectory module

• Add-KdsRootKey
  • Creates the root key for the Group Key Distribution Service
• New-ADServiceAccount
  • Creates the gMSA object in AD
• Set-ADServiceAccount
  • Configures which computers (PrincipalsAllowedToRetrieveManagedPassword) are allowed to read the password

Kerberos and Service Principal Names (SPN)

A gMSA does not have the right to write its own SPNs in AD by default. When the SQL service starts, the registration often fails, leading to NTLM fallbacks. Even though I prefer to set SPNs in a controlled and manual manner, the automatic registration must be technically possible to avoid fallbacks.

The script solves this problem by granting the gMSA the rights in AD to manage its own SPNs, in addition to creating the SPNs. It sets ACLs on the nodes for Read, Write, and Validated write on the servicePrincipalName attribute.

.\security_setSqlSpn.ps1 `
    -ServiceAccount "LAB\g-LAB22A-oltp" `
    -InstanceName "LAB22A" `
    -Port 51101 `
    -Hostnames "LAB-NODE01","LAB-NODE02" `
    -Domain "lab.local" `
    -IsGMSA `
    -SetADPermissions `
    -LogPath "C:\Temp\SPN_AlwaysOn_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Microsoft Cmdlets Used

On one hand, setspn.exe is used for SPN management, and on the other hand, the ActiveDirectory module is used again to verify accounts and extract SIDs.

Since none of the modules can manipulate Active Directory permissions, the .NET Framework System.DirectoryServices is used directly for this purpose, which provides various classes to completely turn AD inside out.

Local Security Policies

As everywhere in IT, SQL Server should also follow the PoLP, which is why no service account gets local administrator privileges. For SQL Server to still run flawlessly and performantly, the service account needs specific rights in the operating system („User Rights Assignment“). Anyone who has done this manually a few times will be very happy about this solution. This must be executed locally on the respective node.

# ===== Set Engine Permissions for gMSA =====

    .\security_setSqlLocalSec.ps1 `
        -ServiceAccount "g-LAB22A-oltp$" `
        -ServiceType "engine" `
        -IsGMSA `
        -LogPath "C:\Temp\LAB22A_Engine_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

# ===== Set Agent Permissions for gMSA =====

    .\security_setSqlLocalSec.ps1 `
        -ServiceAccount "g-LAB22A-agnt$" `
        -ServiceType "agent" `
        -IsGMSA `
        -LogPath "C:\Temp\LAB22A_Agent_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Microsoft Cmdlets Used

Since PowerShell has no native cmdlets for editing local security policies, the Windows tool secedit.exe is used and its export is manipulated.

Summary

With these four building blocks, the foundation for a SQL Server installation has been laid. It wasn’t just an installation that was performed, but a valid, documented configuration that considers identity (gMSA), network (DNS/SPN), and OS performance. In the next step, the actual SQL Server instance can be installed.

Also check out the linked MD files — they contain background information on best practices and further articles from Microsoft

The post Automate SQL Server HA: AD, SPN, and Cluster Setup first appeared on DBA von Nebenan.

• Changelog
• Documentation

Intro

Windows Performance Counters are absolutely powerful, but when I need something quick or monitoring tailored to a specific problem, I get frustrated fast. Usually I fall back on other options – PowerShell native Get-Counter, CIM, or existing monitoring solutions at my clients. But that’s never truly ad-hoc either, and I’ve accepted it.

Recently I had the chance to join Uwe Ricken’s Performance Tuning Workshop at DataSaturday, and he clearly named Performance Counters as a must-have in every DBA’s toolkit. What I didn’t know until then: SQL Server creates individual counters like Compile/sec, AdHoc Queries/sec, etc.

The possibilities to visualize dependencies directly – endless. But how long should I sit there configuring that in Windows Performance Monitor, especially ad-hoc at a client site?

Uwe showed the capabilities in Windows Admin Center, which enables templates you can use flexibly across servers. For systems or environments where Admin Center is used strategically, definitely a great choice.
But two problems remain: As a consultant, I can’t install software at every client, and if Admin Center happens to be running, my English templates fail on German systems.

Still, I was so incredibly hooked by the template idea and the SQL Server possibilities that 4 weeks of after-work crunchtime were spinning in my head. So let me introduce my first module in the PowerShell Gallery:

psTerminalPerfCounter 0.1.0-preview A PowerShell module for displaying real-time graphs of Windows Performance Counters directly in the terminal console. This module provides an easy way to visualize system performance metrics without requiring external graphing tools or GUI applications by using templates and multilanguage support.

You’ll find all technical details and development status in the repository – I just want to show the different possibilities here.

Main Features

100% PowerShell

• no external dependencies

Terminal Graphics

• obviously it’s not a real engine, the more counters the choppier it gets, but it’s sufficient
• The foundation comes from Prateek Singh solution. Without finding this, I would have had to solve this problem first, for which I probably wouldn’t have had time. THANKS!!!

Configuration Templates

• every output element is controlled via configuration files
• flexible, portable

Data Output Customization

• each counter in the configuration file can use its own output
  • Table, Graph, or Both
• arbitrary axis scaling in steps and max values
• arbitrary value coloring based on user-defined ColorMap per counter
• value conversion via configuration file (Byte -> KB -> MB -> GB)

Language Independent

• configuration files are based on counter IDs, not paths
  • portable, regardless of system language translation from ID to counter path happens at runtime
  • no external dependencies
• I had no idea this was possible with Windows built-in tools. Here too I stumbled across a blog at PowerShell.ONE by chance. Again, a big THANKS!!! My original solution had multiple language variants (DE, EN, FR, ES) which would be set by reading system locale.

Demo with CPU Configuration

# Install module with required dependency (GripDevJsonSchemaValidator)
Install-Module -Name psTerminalPerfCounter -AllowPrerelease

# Import the module
Import-Module psTerminalPerfCounter

# Start Default Cpu Configuration
Start-tpcMonitor -ConfigName CPU

When loading the configuration, counter IDs are translated to counter paths and tested

If successful, the first samples are collected so a graph can be displayed

Thats IT!

Within 10 seconds, 2 Performance Counters running, no installation, no language issues.

Demo Counter Translation

# Translate ID -> Path
Get-tpcPerformanceCounterInfo 238-6

# Search Counter -> Including ID
Get-tpcPerformanceCounterInfo "Queue"

Output is heavily truncated since the ResultSet is enormous

# Search Counter -> Including ID
Get-tpcPerformanceCounterInfo "Processor Queue"

What’s next?

The foundation works, the planned feature list is long, and what I really need for SQL Server is still far off. I hope I haven’t solved a problem that doesn’t exist, but this module simply addresses all the issues I’ve always had with Performance Counters, as mentioned above.

Furthermore, this is my first larger project that I’m developing publicly, so GitHub might not always meet expected standards. I’m always happy about feedback and suggestions.

The post psTerminalPerfCounter – SpeedUp your Performance Counters in Terminal first appeared on DBA von Nebenan.

What’s available here?

• DISKSPD Templates and Wrapper
• How can I display the latencies of individual database files?
• Long-term analysis of latencies with snapDiskLatency

Intro

Currently, I’m involved in a code review at a client. We’re examining not only the application but also all interfaces. This naturally includes the SQL Server landscape, which I set up at the beginning of the year.

The result was more findings in my direction than expected, and I immediately felt challenged. I was able to refute most of it, some topics were the client’s responsibility, and one topic caught my interest purely out of curiosity.

Read- and Write Latencies of TempDB ( and every other DB )

Background

The client doesn’t operate their own data center, so they’re dependent on the hoster, who unfortunately isn’t very communicative. Therefore, I had to get a picture of the totally overcommitted hardware through various other means and challenge the hoster. This was also the reason why I was quite precisely informed about what the hoster’s hosts and storage systems were capable of delivering.

That’s why I was very surprised that 32ms Write Latency was listed as a finding. No question, that’s a bad value for AllFlash NVMe, but it just stood there in the report without differentiation or deeper analysis. Just the statement „bad storage.“ So I unpacked my tools, took another look at it, and also developed a new solution that I want to share with you.

DISKSPD

Repo: perf_diskspeed/DISKSPD
Microsoft: https://github.com/microsoft/diskspd

With DISKSPD, you should always start on unknown systems; often a large portion of problems is hidden here. At this client, for example, a DB with high workload was running on spindles, with latencies in the .2 percentile of 15 seconds latency, plus 14MB throughput. I don’t need to worry about indexes etc. anymore.

To quickly get results, I built a wrapper for DISKSPD that always executes 3 standard tests:

• SQL Server Workload
• Random 64KB Workload
• Sequential 64KB Workload

The files are stored separately in the _Output subfolder and thus provide quite good hints about storage problems. Now these were, as expected, great values that correspond to NVMe storage. So let’s continue to SQL Server and see what it tells us. welche NVMe Storage entsprechen. Also weiter zu Sql Server und wir schauen mal was uns dieser so sagt.

sys.dm_io_virtual_file_stats

SQL Server provides a view where all file metrics are cleanly listed.

select * from sys.dm_io_virtual_file_stats(null,null)

• Microsoft Learn

Based on this, I built an analysis script that gives me more info and I can also draw further conclusions like ReadWrite Ratio, probable IOPS based on the number of operations, and also quantities. This allows you to build storage systems quite well for specific workloads.

And this value also showed me 32ms Write Latency of the TempDB. Then I started wondering, how does this value even arise?

Basic Calculation

SQL Server measures I/O latency through simple division of cumulative wait times by the number of operations:

-- Read Latency in ms
io_stall_read_ms / num_of_reads = durchschnittliche Read-Latenz

-- Write Latency in ms  
io_stall_write_ms / num_of_writes = durchschnittliche Write-Latenz

That’s it!!! And now it should be clear that the point-in-time use of this DMV is not really meaningful, on the contrary. The values can, as with the review company that specializes in such processes, lead to false conclusions and action recommendations. Scary.

If the storage system had a hard hiccup since the start of SQL Server, the metrics are contaminated. According to my research, you can’t flush these, only by taking the DB offline, which I usually avoid in productive environments.

After a few more rounds in my head, the solution came quite quickly. These are all snapshot values, I just need the delta between two values and I have real values. And I can also put the whole thing in a time series and have a long-term analysis. Mindblowing

Google also quickly showed corresponding solutions that I used as a base idea. Thanks to Paul Randal ( sqlskills.com )

For analyzing a complete week, this is also not suitable. So I extended the whole thing to a long-term analysis with persistent table.

The Solution –> snapDiskLatency

Repo: perf_diskspeed/snapDiskLatency

What does snapDiskLatency do?

The problem is well-known – the standard DMV sys.dm_io_virtual_file_stats shows cumulative values since SQL Server startup. One single storage hiccup weeks ago and the latency values are no longer representative.

This solves the problem with two simple stored procedures:

The first collects the raw data from the DMV hourly and writes it to a permanent table. Why hourly? Shorter intervals lead to unreliable delta calculations – too little I/O between snapshots makes the values inaccurate. However, this can be individually adjusted since the agent triggers the procedure.

The second does the delta calculations between snapshots and creates the result. Thus, real latency values are generated for defined time periods, without historical hiccups, which can then be compared with other metrics.

Here we see, for example, in the TRUNCATE TABLE an outlier (NVMe is also underlying here). On the LAB system there’s no load, DOXIS is just a table with 2 columns and was artificially worked with workload.

The Result

Instead of possibly contaminated values:

• Average latencies per interval
• Read/Write ratios
• Breakdown by database and file type

Setup

Create Agent Job, run hourly, done. The complete instructions are in the README, copy & paste & enjoy

Diagrams

Since every good proprietary database monitoring tool does this and presents it graphically, I want to at least show one possibility in Excel in the result. For this, the result of the DataSource or Copy must be pivoted and you can easily recognize your daily peaks.

The post Measuring SQL Server Disk Latency Correctly – snapDiskLatency first appeared on DBA von Nebenan.

I’ve always used PowerShell following the same pattern, that’s roughly how my learning path followed the PowerShell Best Practices.

• Quick and Dirty one-liners in the console, nowadays Terminal
• Gradually, those one-liners evolved into PowerShell scripts with better organized one-liners
• Variables came along, then functions, reusability increased
• Functions became modules, persistent data storage in JSON and technologically that was the end for a while
• The last highlight was threading and runspaces

I’ve been operating on these last two levels for quite a long time now, of course getting more efficient and generally my PowerShell knowledge became broader.

During this development, however, I noticed a problem: I’m a very organized person, at least in my professional environment 😉, and so should my code be, structured. I don’t think much of Clean Code, comments are just important at certain points, for me, for others, for my customers. Besides comments, structure is also important – what good do comments do me in a ‚bucket of chars‘? I also love symmetrical code, yeah go ahead and laugh, but it immediately makes clear what’s a variable, what’s an assignment and what’s the value. When I see something like this…

$userInfo = @{
   Name = $varSurename
   Address = $varStreet
   Data = $varRandomLongVar
}

$configSettings = @{
   ServerName = 'localhost'
   Port = 5432
   Database = 'mydb'
   Timeout = 30
}

$employee = @{
   Personal = @{
       FirstName = $varSurename
       LastName = 'Doe'
       Street = $varStreet
   }
   Work = @{
       Department = 'IT'
       Position = 'Developer'
   }
}

… my insides turn outward 🤣 Maybe it’s also a disease. This is a normal writing style that’s considered clean, I know, but it should look like this …

$userInfo = @{
   Name 	= $varSurename
   Address 	= $varStreet
   Data 	= $varRandomLongVar
}

$configSettings = @{
   ServerName 	= 'localhost'
   Port 		= 5432
   Database 	= 'mydb'
   Timeout 		= 30
}

$employee = @{
   Personal = @{
       FirstName 	= $varSurename
       LastName 	= 'Doe'
       Street 		= $varStreet
   }
   Work 	= @{
       Department 	= 'IT'
       Position 	= 'Developer'
   }
}

$users = @(
   @{ Name = 'Alice'; 		Role = 'Admin' }
   @{ Name = $varSurename; 	Role = 'User' }
)

Anyway, that’s not what this is about. It’s basically the case that structure and order gradually decrease in larger projects and classes play exactly into this topic. But why only now? Classes have existed since PowerShell 5.0.

AI Assisted Coding

Of course I was an early adopter of all the AI chatbots and was amazed at what ChatGPT could already do 2 years ago. Of course the code, regardless of language, was unusable, but definitely useful for knowledge generation. As the quality progressed, the code got better and the solution approaches became more and more interesting.

At some point, classes started appearing in the suggestions and I consistently ignored them 😝. Through my C# journeys, I knew that classes are simply the standard, but you should fundamentally know what you want to do with them in the project to design them cleanly. And I didn’t want to make that effort.

The New Project

It was time to adapt a 4-year-old solution to new requirements, as is sometimes the case. Since my knowledge doesn’t stand still either, after briefly skimming through the code, I decided:

I’M NOT TOUCHING THIS ANYMORE, THIS ALL HAS TO BE NEW!!

Now I was in the relaxed position that everything was available for the solution:

• Program flow chart
• Function descriptions
• Programmatic solution of the required functions at the lowest level
• 4 years of lessons learned

So I only had to worry about orchestrating all the steps and decided to give classes a chance. In theory, this is namely the cleanest and most structured way to code.

The result hasn’t completely changed my way of coding, but it has sustainably changed it – but more on that later.

Conclusion After 5 Weeks in the Project

Classes in PowerShell are so incredibly simple, so structured, so beautiful❤️. Of course the use case has to fit, since the implementation initially requires more structure, but when that’s given, there will be no way around classes for me anymore.

Why This Article, Aren’t There Enough Already?

There are some articles about classes in PowerShell and object orientation, but still this topic is hardly covered in a classic tutorial. It’s always the functions and you have to know about this topic to find it. So I’m simply writing another article, also in german this time, to maybe reach one or the other additionally, because…

Background Info on PowerShell Classes – OOP Since Version 5.0

Classes have existed in PowerShell since PowerShell 5.0, so 2016… and I only learned about them a year ago 🤦‍♂️. PowerShell classes bring object-oriented programming concepts to PowerShell and thus also have all the basic features of a class.

• Properties: Properties are strongly typed and support most validation attributes like [ValidateNotNull()], [ValidateRange()], etc.
• Methods: Methods are functions bound to an object and must explicitly define the return type
• Constructors: Enable initialization of objects with specific values
• Inheritance: Allows creating new classes from existing classes and extending their functionality

A class, after loading, is its own data type – more on that later.

And How Does This Work Now?

I still remember how I struggled with OOP many years ago and it’s generally assumed that rather admins than full-blood software developers initially deal with PowerShell. So I’ll try to keep it totally simple.

I’ll take a fictional module that queries server properties via remoting and evaluates them locally, a classic admin task.

ATTENTION: Of course this example is very constructed and not necessarily practical, but in my opinion it shows the relationships quite well.

This PowerShell classes tutorial shows you the most important concepts for object-oriented programming with PowerShell.

Properties

A class has a firmly defined set of properties at all times. This cannot be changed at runtime, but must be described in the definition of the class.

The Class

class Server {
# All Possible properties for the Server class
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem
# -------------------------------------------
}

Constructors

A constructor creates the instance of a class. The class can receive default values, or the constructor expects parameters. In our case, a server name makes sense. So I give the property ServerName a value directly when loading.

class Server {
# All Possible properties for the Server class
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem
# -------------------------------------------

    # Constructor
    Server([string]$name) {
        $this.ServerName = $name
    }
}

Now we have a class, but how do we get a server in there? By loading the class into a variable and preferably also dynamically for all servers.

class Server {
# All Possible properties for the Server class
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem
# -------------------------------------------

    # Constructor
    Server([string]$name) {
        $this.ServerName = $name
    }
}

$serverlist = @('Server1','Server2','Server3')

foreach ( $server in $serverlist ) {
    
    # Create a new Server object for each server name
    New-Variable -Name "obj_$server" -Value ([Server]::new($server)) -Force

}

Methods

Methods make classes really interesting in my opinion. Methods are the functions with which I can manipulate properties of classes or generate RETURNS based on arguments that I add to the call. Here I already specify the type of return in the method definition. VOID thus logically creates no return.

class Server {
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem

    Server([string]$name) {
        $this.ServerName = $name
    }

    [void] GetServerInfo() {

        try {

            $osInfo = Invoke-Command -ComputerName $this.ServerName -ScriptBlock {
                Get-CimInstance Win32_OperatingSystem | Select-Object Caption, LastBootUpTime
            } -ErrorAction Stop

            $this.IP = Invoke-Command -ComputerName $this.ServerName -ScriptBlock {
                (Get-NetIPAddress -AddressFamily IPv4 | Where-Object {$_.IPAddress -notlike '169.*'} | Select-Object -First 1).IPAddress
            } -ErrorAction Stop

            $this.OperatingSystem = $osInfo.Caption
            $this.LastBootTime    = $osInfo.LastBootUpTime
            $this.Status          = "Online"

        } catch {

            $this.Status = "Offline"

        }
    }
}

$serverlist = @('Server1','Server2','Server3')

foreach ($server in $serverlist) {
    New-Variable -Name "obj_$server" -Value ([Server]::new($server)) -Force
}

$obj_Server1.GetServerInfo()
$obj_Server2.GetServerInfo()
$obj_Server3.GetServerInfo()

Here I’ve inserted the method GetServerInfo(), which now collects the information about the server. I don’t need to pass an argument or start a cmdlet, since the instance (server name) of the class (Server) has inherited everything. I don’t need external functions, variables or anything else, everything is available in the class. ❤️ Following an example from the LAB:

And Now, Where’s the Benefit?

Of course this isn’t the most optimal use case, but it’s understandable. One possibility would be to create a logging class. Here from my project:

class PatchLogger {
     [string]        $ServerName
     [string]        $LogPathServer
     [string]        $LogLevel = 'INFO'
     [hashtable]     $LogTargets
     [bool]          $ConsoleOutput
     [bool]          $StreamOutput
     [string]        $VerbosePreference
     [string]        $DebugPreference

     # Constructor
     PatchLogger(	[string]$LogPathServer,
					[string]$ServerName,
					[string]$MessageFile,
					[string]$ErrorFile,
					[string]$VerboseFile,
					[string]$DebugFile,
					[string]$SqlServerFile,
					[bool]$ConsoleOutput 	= $true,
					[bool]$StreamOutput 	= $false) {
					
          $this.LogPathServer   = $LogPathServer
          $this.ServerName      = $ServerName
          $this.ConsoleOutput   = $ConsoleOutput
          $this.StreamOutput    = $StreamOutput
          $this.LogTargets      = @{
               Main           = $MessageFile
               Error          = $ErrorFile
               Verbose        = $VerboseFile
               Debug          = $DebugFile
               SqlServer      = $SqlServerFile
          }

          $this.VerbosePreference = $Global:VerbosePreference
          $this.DebugPreference   = $Global:DebugPreference

          if ( -not (Test-Path $this.LogPathServer) ) {
               New-Item -Path $this.LogPathServer -ItemType Directory -Force | Out-Null
          }
    }
	
}

An instance of the class is loaded directly into the variable $PatchLogger when the module loads, and from now on I can start right away with $PatchLogger.Info($message). How? Such a short command with such a complex class? Let’s get to the last thing, which in my opinion is the advantage par excellence: Overloading.

Overloading

Overloading means nothing other than the number of arguments I pass to a method. Based on the number, the engine can distinguish which method is used, since I can have several with the same name. The technical term would be Method Overloading.

The added value lies in the fact that I don’t have to work with BoundParams, Switch or IF loops like with functions. When a helper method is called with only one argument, the missing arguments are filled in internally and the main method is called.

Let’s take the example $PatchLogger.Info($message)

# Hauptmethode
[hashtable] WriteLog([string]$Level, [string]$Message, [string]$MessageCode, [int]$Severity, [string]$Target, [bool]$ReturnObject) {...}

# Helfermethode
[hashtable] Info([string]$Message) {
      return $this.WriteLog('INFO', $Message, $null, 0, 'Main', $true)
}

# Helfermethode 2
[hashtable] Info([string]$Message, [string]$MessageCode) {
      return $this.WriteLog('INFO', $Message, $MessageCode, 0, 'Main', $true)
}

What will be most needed in a large module? A simple message to the main log, without message code and frills. So the helper method calls the main method with the default values that do exactly that.

Let’s look at helper method 2. This expects 2 arguments, namely a MessageCode. Now I can write a registered message with $PatchLogger.Info(„Process XY completed“,“I0002″).

Of course I can also implement all this with functions, but I don’t think it’s as structured and pretty.

class PatchLogger {
     [string]        $ServerName
     [string]        $LogPathServer
     [string]        $LogLevel = 'INFO'
     [hashtable]     $LogTargets
     [bool]          $ConsoleOutput
     [bool]          $StreamOutput
     [string]        $VerbosePreference
     [string]        $DebugPreference

     # Constructor
     PatchLogger([string]$LogPathServer, [string]$ServerName, [string]$MessageFile, [string]$ErrorFile, [string]$VerboseFile, [string]$DebugFile, [string]$SqlServerFile, [bool]$ConsoleOutput = $true, [bool]$StreamOutput = $false) {
          $this.LogPathServer   = $LogPathServer
          $this.ServerName      = $ServerName
          $this.ConsoleOutput   = $ConsoleOutput
          $this.StreamOutput    = $StreamOutput
          $this.LogTargets      = @{
               Main           = $MessageFile
               Error          = $ErrorFile
               Verbose        = $VerboseFile
               Debug          = $DebugFile
               SqlServer      = $SqlServerFile
          }

          $this.VerbosePreference = $Global:VerbosePreference
          $this.DebugPreference   = $Global:DebugPreference

          if ( -not (Test-Path $this.LogPathServer) ) {
               New-Item -Path $this.LogPathServer -ItemType Directory -Force | Out-Null
          }
     }

     [void] UpdatePreferences([string]$VerbosePreference, [string]$DebugPreference) {
          $this.VerbosePreference = $VerbosePreference
          $this.DebugPreference   = $DebugPreference
     }

     # Central WriteLog method - all other methods call this one
     [object] WriteLog([string]$Level, [string]$Message, [string]$MessageCode, [int]$Severity, [string]$Target, [bool]$ReturnObject) {

          $timestamp          = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
          $severityText       = if ($Severity -ne 9999) { "S$Severity" } else { "" }
          $messageCodeText    = if ($MessageCode) { " $MessageCode" } else { "" }

          $paddedLevel        = "{0,-9}" -f "[$Level]"

          $additionalInfo     = "$severityText$messageCodeText"
          $logEntry           = if ( $level -eq 'BLANK' ) {
                                   ""
                                } elseif ( $Level -notin @('VERBOSE','DEBUG') -and -not [string]::IsNullOrEmpty($additionalInfo) ) {
                                   "[$timestamp] $paddedLevel [$($this.ServerName)] $Message ($additionalInfo)"
                                } else {
                                   "[$timestamp] $paddedLevel [$($this.ServerName)] $Message"
                              }

          $targetFile = $this.LogTargets[$Target]
          if ( $targetFile ) {
               try {
                    Add-Content -Path $targetFile -Value $logEntry -Encoding UTF8

                    $verboseFile = $this.LogTargets['Verbose']
                    if ( $verboseFile -and $Level -ne 'VERBOSE' ) {
                         Add-Content -Path $verboseFile -Value $logEntry -Encoding UTF8 # for unbroken verbose stream
                    }

               } catch {
                    Invoke-ScriptError $_
               }
          }

          if ( $this.ConsoleOutput ) {
               switch ( $Level ) {
                    'ERROR'        { Write-Host $logEntry -ForegroundColor Red }
                    'WARNING'      { Write-Host $logEntry -ForegroundColor Yellow }
                    'INFO'         { Write-Host $logEntry -ForegroundColor Green }
                    'BLANK'        { Write-Host $logEntry}
                    'VERBOSE'      {
                         if ( $this.VerbosePreference -ne 'SilentlyContinue' ) {
                              Write-Host $logEntry -ForegroundColor Cyan
                         }
                    }
                    'DEBUG'        {
                         if ( $this.DebugPreference -ne 'SilentlyContinue' ) {
                              Write-Host $logEntry -ForegroundColor Magenta
                         }
                    }
               }
          }

          # PowerShell streams for integration - only if explicitly enabled
          if ( $this.StreamOutput ) {
               switch ($Level) {
                    'ERROR'   { Write-Error       $Message -ErrorAction Continue }
                    'WARNING' { Write-Warning     $Message }
                    'VERBOSE' { Write-Verbose     $Message }
                    'DEBUG'   { Write-Debug       $Message }
               }
          }

          # Return object only when requested
          if ( $ReturnObject ) {
               return @{
                    HasError    = $Level -eq 'ERROR'
                    HasWarning  = $Level -eq 'WARNING'
                    MessageCode = if ( $MessageCode ) { $MessageCode } else { $null }
                    Message     = $Message
                    Severity    = $Severity
                    Level       = $Level
                    Target      = $Target
               }
          }

          return $null
     }

     # BLANK Line
     [void] BlankLine() {
          $this.WriteLog('BLANK', '', $null, 0, 'Main', $false)
     }

     # INFO Methods - standard return hashtable
     [hashtable] Info([string]$Message) {
          return $this.WriteLog('INFO', $Message, $null, 0, 'Main', $true)
     }

     [hashtable] Info([string]$Message, [string]$MessageCode) {
          return $this.WriteLog('INFO', $Message, $MessageCode, 0, 'Main', $true)
     }

     # INFO NoReturn
     [void] InfoNoReturn([string]$Message) {
          $this.WriteLog('INFO', $Message, $null, 0, 'Main', $false)
     }

     [void] InfoNoReturn([string]$Message, [string]$MessageCode) {
          $this.WriteLog('INFO', $Message, $MessageCode, 0, 'Main', $false)
     }

     # WARNING Methods - standard return hashtable
     [hashtable] Warning([string]$Message) {
          return $this.WriteLog('WARNING', $Message, $null, 1, 'Main', $true)
     }

     [hashtable] Warning([string]$Message, [string]$MessageCode) {
          return $this.WriteLog('WARNING', $Message, $MessageCode, 1, 'Main', $true)
     }

     # WARNING NoReturn
     [void] WarningNoReturn([string]$Message) {
          $this.WriteLog('WARNING', $Message, $null, 1, 'Main', $false)
     }

     [void] WarningNoReturn([string]$Message, [string]$MessageCode) {
          $this.WriteLog('WARNING', $Message, $MessageCode, 1, 'Main', $false)
     }

     # ERROR Methods - standard return hashtable
     [hashtable] Error([string]$Message) {
          return $this.WriteLog('ERROR', $Message, $null, 2, 'Error', $true)
     }

     [hashtable] Error([string]$Message, [string]$MessageCode) {
          return $this.WriteLog('ERROR', $Message, $MessageCode, 2, 'Error', $true)
     }

     # ERROR NoReturn
     [void] ErrorNoReturn([string]$Message) {
          $this.WriteLog('ERROR', $Message, $null, 2, 'Error', $false)
     }

     [void] ErrorNoReturn([string]$Message, [string]$MessageCode) {
          $this.WriteLog('ERROR', $Message, $MessageCode, 2, 'Error', $false)
     }

     # VERBOSE & DEBUG - NoReturn
     [void] Verbose([string]$Message) {
          $this.WriteLog('VERBOSE', $Message, $null, 0, 'Verbose', $false)
     }

     [void] Debug([string]$Message) {
          $this.WriteLog('DEBUG', $Message, $null, 0, 'Debug', $false)
     }

     # Step/SQL/AG Methods - NoReturn
     [void] StepStart([int]$Step, [string]$StepName) {
          $this.BlankLine()
          $message = "========================= STEP $Step START: $StepName ========================="
          $this.WriteLog('INFO', $message, $null, 9999, 'Main', $false)
     }

     [void] StepEnd([int]$Step, [string]$StepName, [bool]$Success) {
          $status   = if ( $Success ) { "SUCCESS" } else { "FAILED" }
          $message  = "========================= STEP $Step END: $StepName - $status ========================="
          $this.WriteLog('INFO', $message, $null, 9999, 'Main', $false)
          $this.BlankLine()
     }

}

Summary

PowerShell classes revolutionize how you structure larger projects. Available since PowerShell 5.0, they offer object-oriented programming with properties, methods, constructors, and method overloading. The initial extra effort pays off through clean, maintainable code – especially for modules and more complex function collections.

The most important advantages at a glance:

• Strongly typed properties with validation
• Encapsulated functionality through methods
• Elegant overloading instead of complex parameter logic and a structure that remains understandable even after months

For daily-doing scripts, the classic approach remains more practical, but as soon as reusability and structure become important, there’s no way around classes for me anymore. 🫡

The post PowerShell Classes for Beginners – Structured Code Instead of Function Chaos first appeared on DBA von Nebenan.

Anyway. If you’re a bit further along in the topic and already know that the pronunciation isn’t „SQL“ but „sequel“ , you should fundamentally question these posts, as they mostly generalize.

This was also the case in a post about the top 3 SQL mistakes that „everyone“ makes. And here we are, getting to the point.

LinkedIn

The same happened with Vedran Kesegic, who gave the hint that TRUNCATE is apparently rollback-capable when encapsulated in a transaction. Then Carsten Saastamoinen-Jakobsen jumped in and things got wild. So wild that the whole topic hooked me so much that I did a deep dive into it. Furthermore, so much knowledge dropped in this exchange that it would be a shame if it disappeared in a comment section.

What to expect here

I compared the exchange and looked at the core statements. I also texted separately with both of them a bit more, and Carsten gave me excerpts from one of his publications where the topic is covered technically.

Technically speaking, both agree, even if they don’t say it . But what was really wild in the end was the question:

I can say it upfront. This question is an philosophical one. I was able to form an opinion based on my research, more on that later, but basically it’s up to everyone to decide for themselves.

The Discussion – DML or DDL ?

Vedran Kesegic

Core Position: TRUNCATE is DDL

„TRUNCATE modifies internal system tables sys.sysallocunits and sys.sysrowsets. DELETE modifies indexes and stats“

„DML writes data (rows in user tables), while DDL writes metadata (rows in system tables, data that describes other/user objects). Truncate happens to write metadata (system tables) and thus is classified as DDL.“

Technical Arguments

• Uses SCH-M (Schema Modification) lock
• Modifies system metadata tables
• Microsoft documentation classifies it as DDL
• Logs page deallocations, not row deletions

Key Statement

„TRUNCATE modifies internal system tables sys.sysallocunits and sys.sysrowsets. DELETE modifies indexes and stats – see attached“

Carsten Saastamoinen-Jakobsen

Core Position: TRUNCATE is DML

„It is not an argument to call TRUNCATE a DDL statement because a certain lock is used! When statements are categorized, it must be based on what happens and not how a given database system solves the task.“

„We may have to recognize that a previous error categorization should not continue to call TRUNCATE a DDL, but recognize that it is a DML.“

Logical Arguments

• Data is deleted, structure is preserved
• No table definition changes occur
• Follows semantic rules of data manipulation
• Can delete only some partitions (not all data)

Key Statement

„I say that MS is right in the documentations because they are not telling that TRUNCATE is as DDL, because they know that TRUNCATE is a DML!“

NOTE Gabriel
I think this is really a bit questionable because the documentation is absolutely clear on this point –> DDL (microsoft.com)

Quote from publication

„As of version 2016, it is possible to delete only some of the data in a table with TRUNCATE, so it is even more cor­rect to call it manipulation than definition, because it is changing some of the data but not changing the structure.“

Points of Agreement

• TRUNCATE can be rolled back in a transaction
  • general demo at sqlauthority.com
  • deep dive demo sqlshack.com
• TRUNCATE is a logged operation
• TRUNCATE is faster than DELETE for large datasets
• Both understand the technical implementation

Core Disagreement

• Classification criteria
  • Implementation details
• Authority
  • Vendor documentation (Vedran) vs. Logical reasoning (Carsten)
• Perspective
  • How it works internally (Vedran) vs. What it does functionally (Carsten)

My 50 Cent

So as you can see, technically it fits, but how do you view the whole thing? Maybe it’s good that I’m not preloaded with as much knowledge as both of them because from my perspective it’s quite clear: DDL!!

Contrary to Carsten’s statement that no system tables are changed, Vedran’s statement is absolutely correct. See why…

… and of course because MS says it’s DDL ( microsoft.com )

And partitioning is DML… I don’t know, here too it’s at least system columns that define the partitioning.

How TRUNCATE works

I’d like to say I’ll describe it simply, but that’s just my normal description. The topic is really complex

1 – TRUNCATE Command Initiated

TRUNCATE TABLE dbo.MyTable;

• First action: Acquire SCH-M (Schema Modification) lock on entire table
• Effect: Table is completely locked – no reads, no writes, nothing

2 – Identify Extents

• DEEP DIVE Extents –> microsoft.com
• SQL Server reads IAM pages
• Lists all extents belonging to the table
• Still holding: SCH-M lock on table

3- Lock Individual Extents

• Places X (Exclusive) locks on each extent
• These are regular data locks, NOT schema locks
• Now holding:
  • SCH-M lock on table (prevents access)
  • X locks on extents (marks them for deallocation)

4 – Log the Operation

• Writes to transaction log: „Deallocate extents 8:8, 8:16, etc.“
• Still holding: Both lock types

5a – If COMMIT

• Updates IAM – marks extents as free
• Releases all X locks on extents
• Releases SCH-M lock on table
• Table is accessible again

5b – If ROLLBACK

• Discards deallocation markers
• Releases all X locks on extents
• Releases SCH-M lock on table
• Everything unchanged

Why Two Different Lock Types?

SCH-M Lock:

• „Nobody touch this table AT ALL“
• Typical for DDL operations
• Prevents even metadata queries

X Locks on Extents:

• „These specific data blocks are being modified“
• Typical for data operations
• Ensures extents aren’t reused until commit/rollback by other sessions

My humble Opinion

Given this knowledge, the case is actually clear for me, but how do you see it? Indeed, here no user data is being manipulated; instead, system-level assignments are being adjusted. Consequently, I’ll allow myself, despite my new half-knowledge, to make the following comparison:

„I also don’t say I’m deleting text in a Word document when I quick format the disk and only delete the block allocation.“

Yes, I think that’s a nice comparison… Case closed, now a few technically interesting aspects and solutions

Technical Part, Hacks and How2

… practical, not technical

TRUNCATE with Survivor Table (Temporary Table)

Data that is still required is simply moved to a temporary table and retrieved after TRUNCATE

-- Step 1: Create temp table with rows to keep
	SELECT * INTO #SurvivorRows 
	FROM 
		MyTable 
	WHERE
		DateColumn >= '2024-01-01'

-- Step 2: Truncate the entire table
	TRUNCATE TABLE MyTable

-- Step 3: Re-insert survivor rows
	INSERT INTO MyTable
	SELECT * FROM #SurvivorRows

-- Step 4: Clean up
	DROP TABLE #SurvivorRows

TRUNCATE with PARTITION option (2016++)

Since SQL Server 2016 (every edition) it is possible to specify partitions or ranges of partitions

-- Truncate specific partitions
	TRUNCATE TABLE MyPartitionedTable 
	     WITH (PARTITIONS (2, 4 TO 6))

-- Check partition status
	SELECT 
		 partition_number
		,rows 
	FROM
		sys.partitions 
	WHERE 
		OBJECT_NAME(OBJECT_ID) = 'MyPartitionedTable'

TRUNCATE is always a transaction…

…. and must be considered during RESTORING. Carsten illustrated this whole thing very nicely in his publication. I’m just describing it, that has to suffice at this point

Even though we only write TRUNCATE TABLE, SQL Server still uses BEGIN and COMMIT TRANSACTION, which of course is recorded in the TLog. Accordingly, during a POINT IN TIME RECOVERY, the data in the table remains available until the TLog with the corresponding TRANSACTION is restored, or the time of the TRUNCATE transaction has been exceeded.

So you can also restore the data

Continuously read Transaction log file data with fn_dblog and fn_dump_dblog

Vedran wrote in one of his posts that there’s an undocumented function where you can read log records at runtime. There’s also a very cool article about this on sqlshack.com

NOT recommended for production but only for test / education.

Finally

Let’s get to my initially mentioned point that all these SQL Server tips from randoms should be questioned. Because the statement that truncate is not rollback safe is simply wrong. The path to this realization was long for me, initiated by the conversation between Vedran and Carsten. I really learned a lot left and right, which I also wanted to record here again for posterity.

In the end, it doesn’t matter whether it’s DDL or DML. In the general SQL Server standard, for example, it’s described as DML, most RDBMSs in dialect with DDL. We’ll just agree on DDL and that’s it. Much more exciting is what happens under the hood.

Best comment from Vedran

„Or you are trying to argue with SQL Certified Master about SQL? Good luck Mr :)“

Links from the text

Full Conversation

The post TRUNCATE TABLE – DDL vs DML – deep dive in operations and practical tips first appeared on DBA von Nebenan.

The Extended Events were quickly set up, „Remote Procedure Call Starting“ shows me a statement without a fully qualified table name. The target object is in the database under the db_owner schema. Welllll, that’s already questionable, but OK. Why not keep it as dbo?

Anyway, the behavior at this point was really incomprehensible to me since everything was configured correctly: Default schema of the user, db_owner on the DB. And the SysAdmin. I had noticed that, but well, customer’s decision. I’ll note things like this in a session, but won’t change anything to avoid endangering grown dependencies.

After searching for a long time, I almost gave up, referred to the vendor and ended the call. Unfortunately, I can’t let go of stuff like this, so I fired up the lab, rebuilt the environment and lo and behold, found the error.

The problem is the SysAdmin role. It directly maps the login to the dbo user of the database – regardless of whether the actual user exists or not, thus inheriting dbo’s default schema. Mindblowing, didn’t know that. 🙂

SysAdmin Role InActive

SysAdmin Role Active

DECLARE @IsSysAdmin INT
SELECT @IsSysAdmin = IS_SRVROLEMEMBER('sysadmin')


SELECT SYSTEM_USER AS CurrentLoginName;

SELECT 
    'Current User'  AS Info,
    USER_NAME()     AS Username,
    SCHEMA_NAME()   AS CurrentSchema,
    CASE WHEN @IsSysAdmin = 1 THEN 'Yes' ELSE 'No' END 
                    AS IsSysAdmin


SELECT 
    'Default Schema'        AS Info,
    dp.name                 AS Username,
    dp.default_schema_name AS DefaultSchema
FROM 
    sys.database_principals dp
WHERE 
    dp.name = USER_NAME()


SELECT 
    'DB Role Membership'    AS Info,
    USER_NAME()             AS Username,
    r.name                  AS RoleName
FROM 
    sys.database_principals u
JOIN 
    sys.database_role_members m ON u.principal_id = m.member_principal_id
JOIN 
    sys.database_principals r ON m.role_principal_id = r.principal_id
WHERE 
    u.name = USER_NAME()

--------------------

-- select * from [customSchema].[userTable] <<<<< ALWAYS WORKING !!!!!

 select * from [userTable]

• Always use fully qualified object names, someday you’ll be glad you did. You can read this in many blogs.
• Always work according to POLP (Principle of Least Privilege), an app user shouldn’t have SysAdmin rights! 🙂

Gabriel, der DBAvonNebenan

The post SysAdmin Role ignores the Default User Schema – A confusing story first appeared on DBA von Nebenan.

SELECT 
    blocking_session_id   AS blocking_session,
    session_id            AS blocked_session,
    wait_time / 1000.0    AS waiting_sec,
    wait_type             AS waittype,
    resource_description  AS ressource
FROM 
    sys.dm_os_waiting_tasks
WHERE 
    blocking_session_id IS NOT NULL
ORDER BY 
    wait_time DESC

I also have a custom development that I will present in a later blog post, which better meets my individual requirements.

The Problem

Now I can display AdHoc blocks, but with deadlocks it gets more interesting. For this, the System Health Session must be checked, which is also volatile.

-- Query System Health Session for Deadlocks

SELECT
    event_data.value('(event/@timestamp)[1]', 'datetime2') AS DeadlockDateTime,
    event_data.query('.')                                  AS DeadlockGraph
FROM
(
    SELECT 
        CAST(target_data AS XML) AS target_data
    FROM 
        sys.dm_xe_session_targets AS st
    JOIN 
        sys.dm_xe_sessions AS s ON s.address = st.event_session_address
    WHERE
             s.name = 'system_health'
        AND st.target_name = 'ring_buffer'
) AS data
CROSS APPLY
    target_data.nodes('//RingBufferTarget/event[@name="xml_deadlock_report"]') AS XEventData(event_data)
ORDER BY 
    DeadlockDateTime DESC;

I encountered this problem with a client who was struggling enormously with deadlocks in a 3rd party application, but the support was a bit… let’s say reluctant. 😉

We had to report everything transparently to them so they would start finding a solution. Of course, query result sets can be considered transparent if you understand them or want to understand them. Unfortunately, the XML of Health Sessions or Extended Events are not exactly famous for being readable. Yet the client simply wanted the problem to be fixed.

So together we developed a reporting solution.

The Idea

With Extended Events I have XML data, and with PowerShell I can parse XML however I want, including into a report of my choice.

The Goal

We wanted a way, apart from SQL Server result sets, to overlay application problems with anomalies in the SQL Server metrics to quickly bring about solutions.

In the week after the solution went live, there were many, many „aha“ moments. From incorrectly configured ERP parameters to poor transaction handling.

The Way

Persistent Data

The most important thing is to persistently store blocking session and deadlock events. This works perfectly with Extended Events. There are two areas for this:

-- SNIPPET!!

ADD EVENT sqlserver.blocked_process_report(
    ACTION(sqlserver.client_app_name,
           sqlserver.client_hostname,
           sqlserver.database_name)
),
ADD EVENT sqlserver.xml_deadlock_report(
    ACTION(sqlserver.client_app_name,
           sqlserver.client_hostname,
           sqlserver.database_name)
)

The whole thing is configured in its own Extended Event and the recordings are already running. Nearly! We still need to configure SQL Server to treat Blocked Process as Extended Events.

EXEC sp_configure 'show advanced options', 1;
GO
RECONFIGURE;
GO
EXEC sp_configure 'blocked process threshold', '5'; -- 5 Secconds
RECONFIGURE
GO

Read Data

100% PowerShell

After the events are logged, they need to be evaluated. What immediately came to my mind were the dbatools with Read-DbaXEFile. The problem is that the currently written file cannot be read with it. You can imagine that blocking and deadlock events don’t occur in such masses that dozens of file rotations are performed within 24 hours. If they do, you definitely have a different problem than just reporting it . So we took the detour via SQL Server, since the current file can also be read here.

PowerShell + TSql

I still find it very difficult to read XML with queries, but THANKS to Brent Ozar, known to all of us, for the basic query I could build upon. At least I now had a result set for orientation and a separate XML for each event in the log.

-- Snippet
select
    *
FROM sys.fn_xe_file_target_read_file
   ('C:\temp\XEventSessions\blocked_process*.xel',
    'C:\temp\XEventSessions\blocked_process*.xem',
     null, null)
CROSS APPLY 
    (SELECT CAST(event_data AS XML) AS event_data) as xevents

Finalization with PowerShell

Since I finally had my XML event, I could parse it with PowerShell, transform it, and finally package it into a nice text report.

Sql Server Deadlock Analysis | Event Time: 2025-04-08T11:16:07.447
================================================================================

SQL STATEMENTS INVOLVED
--------------------------------------------------------------------------------

    Process ID:   process261b00cfc28
    SPID:         643
    Database:     DATABASENAME
    Query:        **DETAILED QUERY**

----------------------------------------

    Process ID:   process258294fbc28
    SPID:         650
    Database:     DATABASENAME
    Query:        **DETAILED QUERY**

----------------------------------------

VICTIM LIST
--------------------------------------------------------------------------------

    Process ID:   process261b00cfc28
    SPID:         643
    Database:     DATABASENAME


PROCESS LIST
--------------------------------------------------------------------------------

    Process ID:               process261b00cfc28
    SPID:                     643
    Isolation Level:          read uncommitted (1)
    Logical Reads:            700
    Wait Resource:            KEY: 6:72058005407662080 (fb04e1bc7788)
    Wait Time (ms):           2247
    Transaction:              user_transaction
    Last Transaction Started: 2025-04-08T11:16:07.447
    Client:                   'dbserver_dll <ID@APPSERVER:34784>'
    Hostname:                 APPSERVER
    User:                     USERNAME


EXECUTED SQL STATEMENT
----------------------------------------

    **DETAILED QUERY**


Process Details
================================================================================


    Process ID:               process258294fbc28
    SPID:                     650
    Isolation Level:          read uncommitted (1)
    Logical Reads:            1904
    Wait Resource:            KEY: 6:72057996178358272 (2a9726d2d061)
    Wait Time (ms):           2278
    Transaction:              user_transaction
    Last Transaction Started: 2025-04-08T11:16:07.330
    Client:                   'dbserver_dll <ID@APPSERVER:11664>'
    Hostname:                 APPSERVER
    User:                     USERNAME


EXECUTED SQL STATEMENT
----------------------------------------

    **DETAILED QUERY**


Process Details
================================================================================


RESOURCE LIST
--------------------------------------------------------------------------------

    Resource:
        Type:               keylock
        Database:           6
        Object:             DATABASENAME.dbo.tcprmp300100
        Index:              Itcprmp300100_1a
        Lock Mode:          X
        HOBT ID:            72058005407662080
        Associated Object ID: 72058005407662080

    Owners:
        Process ID:         process258294fbc28, Mode: X

    Waiting Processes:
        Process ID:         process261b00cfc28, Mode: U, Request Type: wait

================================================================================

    Resource:
        Type:               keylock
        Database:           6
        Object:             DATABASENAME.dbo.tcprrp011100
        Index:              Itcprrp011100_1a
        Lock Mode:          X
        HOBT ID:            72057996178358272
        Associated Object ID: 72057996178358272

    Owners:
        Process ID:         process261b00cfc28, Mode: X

    Waiting Processes:
        Process ID:         process258294fbc28, Mode: U, Request Type: wait

================================================================================

Implementation

It was requested to add the results to the daily report, which we had already implemented with PowerShell. Now, it’s not great to potentially attach 200 text files to an email every morning, so the PowerShell script returns a table showing how blocks and locks occurred in time period X, and if needed, one can proactively check the folder structure.

For dramatic effect and a quick overview, an Excel file is also generated. In this example, there was a nice collateral finding that the DWH jobs had serious problems 🙂

And just like that, we had a few reports that we could hand over to the vendor, and then things moved very quickly.

Die Ordner Struktur

_report/
├── text_reports/
│   └── YYYY/
│       └── MM/
│           └── DD/
│               ├── 20231120_123456_dbname_blocked.txt
│               ├── 20231120_123456_dbname_blocked.xml
│               └── 20231120_123456_dbname_deadlock.txt
└── excel_reports/
    └── BlockReport_20231120_123456.xlsx

Unfortunately, I experience again and again that application vendors think their customers are stupid and cannot operate the application. Stop doing that and believe your customers sometimes without 101% data, which you can only collect if you already have knowledge of the subject matter.

See Repository

The script has various parameters and options, details are in the README.MD. If you have questions, leave them in the comments or contact me.

Other

Erik Darling has also developed a solution to make Extended Events readable, in case other approaches are needed. (sp_HumanEvents)

Gabriel, der DBAvonNebenan

The post Reporting Blocks and Deadlocks: When the 3rd-Party Vendor Demands Evidence first appeared on DBA von Nebenan.

So I wrote a small PowerShell script that searches through MD files in the current folder for links, downloads them to the attachments folder, and dynamically replaces the links in the MD with local links.

The post Offline Images with Obsidian Website Clipper first appeared on DBA von Nebenan.