SQL Server 用 Azure 拡張機能のトラブルシューティング

2025-06-10

適用対象:SQL Server

この記事では、正しくインストールされていない、正しく実行されている、または Azure に接続されていない異常な拡張機能を識別する方法について説明します。

異常な拡張機能を特定する

Azure portal で組み込みの拡張機能の正常性ダッシュボードを使用する

Azure portal の組み込みの拡張機能の正常性ダッシュボードを使用して、SQL Server 用にデプロイされたすべての Azure 拡張機能の正常性を表示できます。

ヒント

このファイルを使用して、独自のカスタムダッシュボードを sql-server-samples GitHub リポジトリから作成します。 Arc 対応 SQL Server Health.json。

Azure Resource Graph を使用して異常な拡張機能のクエリを実行する

Azure Resource Graph を使用して、Azure Arc 対応サーバー上の SQL Server の Azure 拡張機能の状態を特定します。

ヒント

まだ慣れていない場合は、Azure Resource Graph について学習します。

このクエリは、サーバー上で拡張機能がインストールされているが正常ではない SQL Server のインスタンスを返します。

resources
| where type == "microsoft.hybridcompute/machines/extensions" 
| where properties.type in ("WindowsAgent.SqlServer", "LinuxAgent.SqlServer") 
| extend targetMachineName = tolower(tostring(split(id, '/')[8])) // Extract the machine name from the extension's id
| join kind=leftouter (
    resources
    | where type == "microsoft.hybridcompute/machines"
    | project machineId = id, MachineName = name, subscriptionId, LowerMachineName = tolower(name), resourceGroup , MachineStatus= properties.status , MachineProvisioningStatus= properties.provisioningState, MachineErrors = properties.errorDetails //Project relevant machine health information.
) on $left.targetMachineName == $right.LowerMachineName and $left.resourceGroup == $right.resourceGroup and $left.subscriptionId == $right.subscriptionId // Join Based on MachineName in the id and the machine's name, the resource group, and the subscription. This join allows us to present the data of the machine as well as the extension in the final output.
| extend statusExpirationLengthRange = 3d // Change this value to change the acceptable range for the last time an extension should have reported its status.
| extend startDate = startofday(now() - statusExpirationLengthRange), endDate = startofday(now()) // Get the start and end position for the given range.
| extend extractedDateString = extract("timestampUTC : (\\d{4}\\W\\d{2}\\W\\d{2})", 1, tostring(properties.instanceView.status.message)) // Extracting the date string for the LastUploadTimestamp. Is empty if none is found.
| extend extractedDateStringYear = split(extractedDateString, '/')[0], extractedDateStringMonth = split(extractedDateString, '/')[1], extractedDateStringDay = split(extractedDateString, '/')[2] // Identifying each of the parts of the date that was extracted from the message.
| extend extractedDate = todatetime(strcat(extractedDateStringYear,"-",extractedDateStringMonth,"-",extractedDateStringDay,"T00:00:00Z")) // Converting to a datetime object and rewriting string into ISO format because todatetime() does not work using the previous format.
| extend isNotInDateRange = not(extractedDate >= startDate and extractedDate <= endDate) // Created bool which is true if the date we extracted from the message is not within the specified range. This bool will also be true if the date was not found in the message.
| where properties.instanceView.status.message !contains "SQL Server Extension Agent: Healthy" // Begin searching for unhealthy extensions using the following 1. Does extension report being healthy. 2. Is last upload within the given range. 3. Is the upload status in an OK state. 4. Is provisioning state not in a succeeded state.
    or isNotInDateRange
    or properties.instanceView.status.message !contains "uploadStatus : OK"
    or properties.provisioningState != "Succeeded"
    or MachineStatus != "Connected"
| extend FailureReasons = strcat( // Makes a String to list all the reason that this resource got flagged for
        iif(MachineStatus != "Connected",strcat("- Machine's status is ", MachineStatus," -"),"") ,
        iif(MachineErrors != "[]","- Machine reports errors -", ""),
        iif(properties.instanceView.status.message !contains "SQL Server Extension Agent: Healthy","- Extension reported unhealthy -",""), 
        iif(isNotInDateRange,"- Last upload outside acceptable range -",""),
        iif(properties.instanceView.status.message !contains "uploadStatus : OK","- Upload status is not reported OK -",""), 
        iif(properties.provisioningState != "Succeeded",strcat("- Extension provisiong state is ", properties.provisioningState," -"),"") 
    )
| extend RecommendedAction = //Attempt to Identify RootCause based on information gathered, and point customer to what they should investigate first.
    iif(MachineStatus == "Disconnected", "Machine is disconnected. Please reconnect the machine.",
        iif(MachineStatus == "Expired", "Machine cert is expired. Go to the machine on the Azure portal for more information on how to resolve this issue.",
            iif(MachineStatus != "Connected", strcat("Machine status is ", MachineStatus,". Investigate and resolve this issue."),
                iif(MachineProvisioningStatus != "Succeeded", strcat("Machine provisioning status is ", MachineProvisioningStatus, ". Investigate and resolve machine provisioning status"),
                    iff(MachineErrors != "[]", "Machine is reporting errors. Investigate and resolve machine errors",
                        iif(properties.provisioningState != "Succeeded", strcat("Extension provisioning status is ", properties.provisioningState,". Investigate and resolve extension provisioning state."),
                            iff(properties.instanceView.status.message !contains "SQL Server Extension Agent:" and properties.instanceView.status.message contains "SQL Server Extension Agent Deployer", "SQL Server extension employer ran. However, SQL Server extension seems to not be running. Verify that the extension is currently running.",
                                iff(properties.instanceView.status.message !contains "uploadStatus : OK" or isNotInDateRange or properties.instanceView.status.message !contains "SQL Server Extension Agent: Healthy", "Extension reported as unhealthy. View FailureReasons and LastExtensionStatusMessage for more information as to the cause of the failure.",
                                    "Unable to recommend actions. Please view FailureReasons."
                                )
                            )
                        )
                    )
                )
            )
        )
    )
| project ID = id, MachineName, ResourceGroup = resourceGroup, SubscriptionID = subscriptionId, Location = ___location, RecommendedAction, FailureReasons, LicenseType = properties.settings.LicenseType, 
    LastReportedExtensionHealth = iif(properties.instanceView.status.message !contains "SQL Server Extension Agent: Healthy", "Unhealthy", "Healthy"),
    LastExtensionUploadTimestamp = iif(indexof(properties.instanceView.status.message, "timestampUTC : ") > 0,
        substring(properties.instanceView.status.message, indexof(properties.instanceView.status.message, "timestampUTC : ") + 15, 10),
        "no timestamp"),
    LastExtensionUploadStatus = iif(indexof(properties.instanceView.status.message, "uploadStatus : OK") > 0, "OK", "Unhealthy"),
    ExtensionProvisioningState = properties.provisioningState,
    MachineStatus, MachineErrors, MachineProvisioningStatus,MachineId = machineId,
    LastExtensionStatusMessage = properties.instanceView.status.message

考えられる問題を特定するには、RecommendedAction 列または FailureReasons 列の値を確認します。 RecommendedAction 列は、問題を解決するための最初の手順や、最初に確認すべき点の手掛かりを提供します。 FailureReasons 列には、リソースが異常と見なされた理由が一覧表示されます。最後に、エージェントによって最後に報告されたメッセージを確認するために、LastExtensionStatusMessage をチェックします。

トラブルシューティングガイド

推奨される操作	アクションの詳細
マシン証明書の有効期限が切れています。この問題を解決する方法の詳細については、Azure portal のコンピューターにアクセスしてください。	Azure に対する認証に使用される証明書の有効期限が切れたため、Arc 対応マシンを Arc に再オンボードする必要があります。 Azure portal で Arc マシンの状態が [期限切れ] になっています。ここでドキュメントに従ってエージェントをアンインストールし、ここで再オンボードします。再オンボードする場合は、ポータルで Arc 対応 SQL Server リソースを削除する必要はありません。自動オンボードが有効になっている (既定) 限り、SQL 拡張機能自動的に再インストールされます。
マシンが切断されています。コンピューターを再接続します。	Arc マシンは `state = Disconnected` 状態にあります。この状態には、さまざまな理由が考えられます。 Arc 接続されたマシンエージェントが停止、無効、または常にクラッシュするまたはエージェントと Azure の間の接続がブロックされます。 Arc に接続されたマシンサービス/デーモンの状態を調べて、それらが有効になっており、実行されていることを確認します。接続を確認します。詳細ログを使用してエージェントのトラブルシューティングを行います。
拡張機能が異常として報告された。エラーの原因の詳細については、FailureReasons と LastExtensionStatusMessage を参照してください。最後のアップロードは許容範囲外 (過去 3 日以内) です。	LastExtensionUploadTimestamp 列を確認します。タイムスタンプがない場合、インベントリや使用状況データは Azure に報告されません。 SQL 拡張機能から Azureへの接続のトラブルシューティングを行います。最後のアップロードが (過去 3 日以内に) 許容範囲外であり、 LastExtensionUploadStatus、 ExtensionProvisioningState、 MachineStatus など、それ以外のすべてが問題なく見える場合は、Azure Extension for SQL Server サービス/デーモンが停止される可能性があります。停止した理由を把握し、もう一度起動します。 LastExtensionStatusMessage で、問題に関するその他の手掛かりを確認します。
拡張機能のプロビジョニングの状態は失敗したです。拡張機能のプロビジョニング状態を調査して解決します。	SQL 拡張機能の初回インストールまたは更新に失敗しました。展開ツールと拡張機能のログ確認します。 LastExtensionStatusMessageの値を確認します。
アップロードの状態が報告されない OK	ダッシュボードの LastExtensionMessage 列を確認し、uploadStatus 値と uploadMessage 値を確認します (バージョンに応じて存在する場合)。 uploadStatus 値は通常、HTTP エラーコードです。エラーコードのトラブルシューティングに関するページを確認します。 uploadMessage には、より具体的な情報が含まれている場合があります。 SQL Server 接続の一般的な Azure 拡張機能のトラブルシューティング。
拡張機能のプロビジョニング状態が [更新中] であるまたは拡張機能のプロビジョニング状態が [作成中] であるまたは拡張機能のプロビジョニング状態が失敗または拡張機能のプロビジョニング状態が [削除中] である	特定の拡張機能がこれらの状態のいずれかに 30 分以上留まる場合は、プロビジョニングに問題がある可能性があります。拡張機能をアンインストールし、CLI またはポータルを使用して再インストールします。問題が解決しない場合は、展開者と拡張機能のログ確認。削除に失敗した場合は、エージェントをアンインストールし、必要に応じてポータルで Arc マシンリソースを削除してから、再デプロイしてみてください。ここでドキュメントに従ってエージェントをアンインストールし、ここで再オンボードします。

異常な拡張機能を特定する (PowerShell)

この例は PowerShell で実行されます。この例では、前のクエリと同じ結果が返されますが、PowerShell スクリプトを使用します。

# PowerShell script to execute an Azure Resource Graph query using Azure CLI
# where the extension status is unhealthy or the extension last upload time isn't in this month or the previous month.

# Requires the Az.ResourceGraph PowerShell module

# Login to Azure if needed
#az login

# Define the Azure Resource Graph query
$query = @"
resources
| where type == "microsoft.hybridcompute/machines/extensions" 
| where properties.type in ("WindowsAgent.SqlServer", "LinuxAgent.SqlServer") 
| extend targetMachineName = tolower(tostring(split(id, '/')[8])) // Extract the machine name from the extension's id
| join kind=leftouter (
    resources
    | where type == "microsoft.hybridcompute/machines"
    | project machineId = id, MachineName = name, subscriptionId, LowerMachineName = tolower(name), resourceGroup , MachineStatus= properties.status , MachineProvisioningStatus= properties.provisioningState, MachineErrors = properties.errorDetails //Project relevant machine health information.
) on $left.targetMachineName == $right.LowerMachineName and $left.resourceGroup == $right.resourceGroup and $left.subscriptionId == $right.subscriptionId // Join Based on MachineName in the id and the machine's name, the resource group, and the subscription. This join allows us to present the data of the machine as well as the extension in the final output.
| extend statusExpirationLengthRange = 3d // Change this value to change the acceptable range for the last time an extension should have reported its status.
| extend startDate = startofday(now() - statusExpirationLengthRange), endDate = startofday(now()) // Get the start and end position for the given range.
| extend extractedDateString = extract("timestampUTC : (\\d{4}\\W\\d{2}\\W\\d{2})", 1, tostring(properties.instanceView.status.message)) // Extracting the date string for the LastUploadTimestamp. Is empty if none is found.
| extend extractedDateStringYear = split(extractedDateString, '/')[0], extractedDateStringMonth = split(extractedDateString, '/')[1], extractedDateStringDay = split(extractedDateString, '/')[2] // Identifying each of the parts of the date that was extracted from the message.
| extend extractedDate = todatetime(strcat(extractedDateStringYear,"-",extractedDateStringMonth,"-",extractedDateStringDay,"T00:00:00Z")) // Converting to a datetime object and rewriting string into ISO format because todatetime() does not work using the previous format.
| extend isNotInDateRange = not(extractedDate >= startDate and extractedDate <= endDate) // Created bool which is true if the date we extracted from the message is not within the specified range. This bool will also be true if the date was not found in the message.
| where properties.instanceView.status.message !contains "SQL Server Extension Agent: Healthy" // Begin searching for unhealthy extensions using the following 1. Does extension report being healthy. 2. Is last upload within the given range. 3. Is the upload status in an OK state. 4. Is provisioning state not in a succeeded state.
    or isNotInDateRange
    or properties.instanceView.status.message !contains "uploadStatus : OK"
    or properties.provisioningState != "Succeeded"
    or MachineStatus != "Connected"
| extend FailureReasons = strcat( // Makes a String to list all the reason that this resource got flagged for
        iif(MachineStatus != "Connected",strcat("- Machine's status is ", MachineStatus," -"),"") ,
        iif(MachineErrors != "[]","- Machine reports errors -", ""),
        iif(properties.instanceView.status.message !contains "SQL Server Extension Agent: Healthy","- Extension reported unhealthy -",""), 
        iif(isNotInDateRange,"- Last upload outside acceptable range -",""),
        iif(properties.instanceView.status.message !contains "uploadStatus : OK","- Upload status is not reported OK -",""), 
        iif(properties.provisioningState != "Succeeded",strcat("- Extension provisiong state is ", properties.provisioningState," -"),"") 
    )
| extend RecommendedAction = //Attempt to Identify RootCause based on information gathered, and point customer to what they should investigate first.
    iif(MachineStatus == "Disconnected", "Machine is disconnected. Please reconnect the machine.",
        iif(MachineStatus == "Expired", "Machine cert is expired. Go to the machine on the Azure portal for more information on how to resolve this issue.",
            iif(MachineStatus != "Connected", strcat("Machine status is ", MachineStatus,". Investigate and resolve this issue."),
                iif(MachineProvisioningStatus != "Succeeded", strcat("Machine provisioning status is ", MachineProvisioningStatus, ". Investigate and resolve machine provisioning status"),
                    iff(MachineErrors != "[]", "Machine is reporting errors. Investigate and resolve machine errors",
                        iif(properties.provisioningState != "Succeeded", strcat("Extension provisioning status is ", properties.provisioningState,". Investigate and resolve extension provisioning state."),
                            iff(properties.instanceView.status.message !contains "SQL Server Extension Agent:" and properties.instanceView.status.message contains "SQL Server Extension Agent Deployer", "SQL Server extension employer ran. However, SQL Server extension seems to not be running. Verify that the extension is currently running.",
                                iff(properties.instanceView.status.message !contains "uploadStatus : OK" or isNotInDateRange or properties.instanceView.status.message !contains "SQL Server Extension Agent: Healthy", "Extension reported as unhealthy. View FailureReasons and LastExtensionStatusMessage for more information as to the cause of the failure.",
                                    "Unable to recommend actions. Please view FailureReasons."
                                )
                            )
                        )
                    )
                )
            )
        )
    )
| project ID = id, MachineName, ResourceGroup = resourceGroup, SubscriptionID = subscriptionId, Location = ___location, RecommendedAction, FailureReasons, LicenseType = properties.settings.LicenseType, 
    LastReportedExtensionHealth = iif(properties.instanceView.status.message !contains "SQL Server Extension Agent: Healthy", "Unhealthy", "Healthy"),
    LastExtensionUploadTimestamp = iif(indexof(properties.instanceView.status.message, "timestampUTC : ") > 0,
        substring(properties.instanceView.status.message, indexof(properties.instanceView.status.message, "timestampUTC : ") + 15, 10),
        "no timestamp"),
    LastExtensionUploadStatus = iif(indexof(properties.instanceView.status.message, "uploadStatus : OK") > 0, "OK", "Unhealthy"),
    ExtensionProvisioningState = properties.provisioningState,
    MachineStatus, MachineErrors, MachineProvisioningStatus,MachineId = machineId,
    LastExtensionStatusMessage = properties.instanceView.status.message
"@

# Execute the Azure Resource Graph query
$result = Search-AzGraph -Query $query

# Output the results
$result | Format-Table -Property ExtensionHealth, LastUploadTimestamp, LastUploadStatus, Message

更新されていない拡張機能を特定する

最近の状態の更新なしで拡張機能を識別します。このクエリは、拡張機能ステータスの最終更新日からの日数順にリストアップしたSQL Server の Azure 拡張機能の一覧を返します。値 '-1' は、拡張機能がクラッシュし、拡張機能の状態に呼び出し履歴があることを示します。

// Show the timestamp extracted
// If an extension has crashed (i.e. no heartbeat), fill timestamp with "1900/01/01, 00:00:00.000"
//
resources
| where type =~ 'microsoft.hybridcompute/machines/extensions'
| extend extensionStatus = parse_json(properties).instanceView.status.message
| extend timestampExtracted = extract(@"timestampUTC\s*:\s*(\d{4}/\d{2}/\d{2}, \d{2}:\d{2}:\d{2}\.\d{3})", 1, tostring(extensionStatus))
| extend timestampNullFilled = iff(isnull(timestampExtracted) or timestampExtracted == "", "1900/01/01, 00:00:00.000", timestampExtracted)
| extend timestampKustoFormattedString = strcat(replace(",", "", replace("/", "-", replace("/", "-", timestampNullFilled))), "Z")
| extend agentHeartbeatUtcTimestamp = todatetime(timestampKustoFormattedString)
| extend agentHeartbeatLagInDays = datetime_diff('day', now(), agentHeartbeatUtcTimestamp)
| project id, extensionStatus, agentHeartbeatUtcTimestamp, agentHeartbeatLagInDays
| limit 100
| order by ['agentHeartbeatLagInDays'] asc

このクエリは、拡張機能ステータスの最終更新日からの日数別にグループ化した拡張機能の件数を返します。値 '-1' は、拡張機能がクラッシュし、拡張機能の状態に呼び出し履歴があることを示します。

// Aggregate by timestamp
//
// -1: Crashed extension with no heartbeat, we got a stacktrace instead
//  0: Healthy
// >1: Stale/Offline
//
resources
| where type =~ 'microsoft.hybridcompute/machines/extensions'
| extend extensionStatus = parse_json(properties).instanceView.status.message
| extend timestampExtracted = extract(@"timestampUTC\s*:\s*(\d{4}/\d{2}/\d{2}, \d{2}:\d{2}:\d{2}\.\d{3})", 1, tostring(extensionStatus))
| extend timestampNullFilled = iff(isnull(timestampExtracted) or timestampExtracted == "", "1900/01/01, 00:00:00.000", timestampExtracted)
| extend timestampKustoFormattedString = strcat(replace(",", "", replace("/", "-", replace("/", "-", timestampNullFilled))), "Z")
| extend agentHeartbeatUtcTimestamp = todatetime(timestampKustoFormattedString)
| extend agentHeartbeatLagInDays = iff(agentHeartbeatUtcTimestamp == todatetime("1900/01/01, 00:00:00.000Z"), -1, datetime_diff('day', now(), agentHeartbeatUtcTimestamp))
| summarize numExtensions = count() by agentHeartbeatLagInDays
| order by numExtensions desc

推奨される操作	アクションの詳細
マシン証明書の有効期限が切れています。この問題を解決する方法の詳細については、Azure portal のコンピューターにアクセスしてください。	Azure に対する認証に使用される証明書の有効期限が切れたため、Arc 対応マシンを Arc に再オンボードする必要があります。 Azure portal で Arc マシンの状態が [期限切れ] になっています。ここでドキュメントに従ってエージェントをアンインストールし、ここで再オンボードします。再オンボードする場合は、ポータルで Arc 対応 SQL Server リソースを削除する必要はありません。自動オンボードが有効になっている (既定) 限り、SQL 拡張機能自動的に再インストールされます。
マシンが切断されています。コンピューターを再接続します。	Arc マシンは `state = Disconnected` 状態にあります。この状態には、さまざまな理由が考えられます。 Arc 接続されたマシンエージェントが停止、無効、または常にクラッシュするまたはエージェントと Azure の間の接続がブロックされます。 Arc に接続されたマシンサービス/デーモンの状態を調べて、それらが有効になっており、実行されていることを確認します。接続を確認します。詳細ログを使用してエージェントのトラブルシューティングを行います。
拡張機能が異常として報告された。エラーの原因の詳細については、FailureReasons と LastExtensionStatusMessage を参照してください。最後のアップロードは許容範囲外 (過去 3 日以内) です。	LastExtensionUploadTimestamp 列を確認します。タイムスタンプがない場合、インベントリや使用状況データは Azure に報告されません。 SQL 拡張機能から Azureへの接続のトラブルシューティングを行います。最後のアップロードが (過去 3 日以内に) 許容範囲外であり、 LastExtensionUploadStatus、 ExtensionProvisioningState、 MachineStatus など、それ以外のすべてが問題なく見える場合は、Azure Extension for SQL Server サービス/デーモンが停止される可能性があります。停止した理由を把握し、もう一度起動します。 LastExtensionStatusMessage で、問題に関するその他の手掛かりを確認します。
拡張機能のプロビジョニングの状態は失敗したです。拡張機能のプロビジョニング状態を調査して解決します。	SQL 拡張機能の初回インストールまたは更新に失敗しました。展開ツールと拡張機能のログ確認します。 LastExtensionStatusMessageの値を確認します。
アップロードの状態が報告されない OK	ダッシュボードの LastExtensionMessage 列を確認し、uploadStatus 値と uploadMessage 値を確認します (バージョンに応じて存在する場合)。 uploadStatus 値は通常、HTTP エラーコードです。エラーコードのトラブルシューティングに関するページを確認します。 uploadMessage には、より具体的な情報が含まれている場合があります。 SQL Server 接続の一般的な Azure 拡張機能のトラブルシューティング。
拡張機能のプロビジョニング状態が [更新中] であるまたは拡張機能のプロビジョニング状態が [作成中] であるまたは拡張機能のプロビジョニング状態が失敗または拡張機能のプロビジョニング状態が [削除中] である	特定の拡張機能がこれらの状態のいずれかに 30 分以上留まる場合は、プロビジョニングに問題がある可能性があります。拡張機能をアンインストールし、CLI またはポータルを使用して再インストールします。問題が解決しない場合は、展開者と拡張機能のログ確認。削除に失敗した場合は、エージェントをアンインストールし、必要に応じてポータルで Arc マシンリソースを削除してから、再デプロイしてみてください。ここでドキュメントに従ってエージェントをアンインストールし、ここで再オンボードします。

次の方法で共有