使用特权终结点 (PEP) 发送 Azure Stack Hub 诊断日志Send Azure Stack Hub diagnostic logs by using the privileged endpoint (PEP)

若要在集成系统上运行 Get-AzureStackLog,需有权访问特权终结点 (PEP)。To run Get-AzureStackLog on an integrated system, you need to have access to the privileged endpoint (PEP). 下面是一个可运行的示例脚本,它使用 PEP 收集日志。Here's an example script you can run using the PEP to collect logs. 若要取消正在运行的日志收集以启动新的日志收集,请在启动新的日志收集前等待 5 分钟,然后输入 Remove-PSSession -Session $sessionIf you are canceling a running log collection to start a new one, please wait 5 minutes Before starting new log collection and enter Remove-PSSession -Session $session.

$ipAddress = "<IP ADDRESS OF THE PEP VM>" # You can also use the machine name instead of IP here.

$password = ConvertTo-SecureString "<CLOUD ADMIN PASSWORD>" -AsPlainText -Force
$cred = New-Object -TypeName System.Management.Automation.PSCredential ("<DOMAIN NAME>\CloudAdmin", $password)

$shareCred = Get-Credential

$session = New-PSSession -ComputerName $ipAddress -ConfigurationName PrivilegedEndpoint -Credential $cred

$fromDate = (Get-Date).AddHours(-8)
$toDate = (Get-Date).AddHours(-2) # Provide the time that includes the period for your issue

Invoke-Command -Session $session { Get-AzureStackLog -OutputSharePath "<EXTERNAL SHARE ADDRESS>" -OutputShareCredential $using:shareCred -FilterByRole Storage -FromDate $using:fromDate -ToDate $using:toDate}

if ($session) {
    Remove-PSSession -Session $session
}

示例Examples

  • 收集所有角色的所有日志:Collect all logs for all roles:

    Get-AzureStackLog -OutputSharePath "<path>" -OutputShareCredential $cred
    
  • 从 VirtualMachines 和 BareMetal 角色收集日志:Collect logs from VirtualMachines and BareMetal roles:

    Get-AzureStackLog -OutputSharePath "<path>" -OutputShareCredential $cred -FilterByRole VirtualMachines,BareMetal
    
  • 从 VirtualMachines 和 BareMetal 角色收集日志,通过日期筛选功能筛选出过去 8 小时的日志文件:Collect logs from VirtualMachines and BareMetal roles, with date filtering for log files for the past 8 hours:

    Get-AzureStackLog -OutputSharePath "<path>" -OutputShareCredential $cred -FilterByRole VirtualMachines,BareMetal -FromDate (Get-Date).AddHours(-8)
    
  • 从 VirtualMachines 和 BareMetal 角色收集日志,通过日期筛选功能筛选出 8 小时前到 2 小时前这个时间段的日志文件:Collect logs from VirtualMachines and BareMetal roles, with date filtering for log files for the time period between 8 hours ago and 2 hours ago:

    Get-AzureStackLog -OutputSharePath "<path>" -OutputShareCredential $cred -FilterByRole VirtualMachines,BareMetal -FromDate (Get-Date).AddHours(-8) -ToDate (Get-Date).AddHours(-2)
    
  • 在 Azure Stack 上,从运行了自行管理的 Kubernetes 群集(AKS 引擎)的租户部署中收集日志。Collect logs from tenant deployments running self-managed Kubernetes clusters (AKS engine) on Azure Stack. Kubernetes 日志应采用符合条件的格式存储在租户存储帐户中:使用该格式时应能够对日志应用“收集时间范围”。Kubernetes logs should be stored in a tenant storage account in a format that will enable the collection time range to be applied to them as well.

    Get-AzureStackLog -OutputPath <Path> -InputSasUri "<Blob Service Sas URI>" -FromDate "<Beginning of the time range>" -ToDate "<End of the time range>"
    

    例如:For example:

    Get-AzureStackLog -OutputPath C:\KubernetesLogs -InputSasUri "https://<storageAccountName>.blob.core.chinacloudapi.cn/<ContainerName><SAS token>" -FromDate (Get-Date).AddHours(-8) -ToDate (Get-Date).AddHours(-2) 
    
  • 收集 value-add RPs 的日志。Collect logs for the value-add RPs. 常规语法为:The general syntax is:

    Get-AzureStackLogs -FilterByResourceProvider <<value-add RP name>>
    

    收集 IoT 中心的日志:To collect logs for IoT Hub:

    Get-AzureStackLogs -FilterByResourceProvider IotHub
    

    收集事件中心的日志:To collect logs for Event Hubs:

    Get-AzureStackLogs -FilterByResourceProvider eventhub
    

    收集 Azure Stack Edge 的日志:To collect logs for Azure Stack Edge:

    Get-AzureStackLogs -FilterByResourceProvide databoxedge
    
  • 收集日志并将其存储在指定的 Azure 存储 blob 容器中。Collect logs and store them in the specified Azure Storage blob container. 此操作的常规语法如下所示:The general syntax for this operation is as follows:

    Get-AzureStackLog -OutputSasUri "<Blob service SAS Uri>"
    

    例如:For example:

    Get-AzureStackLog -OutputSasUri "https://<storageAccountName>.blob.core.chinacloudapi.cn/<ContainerName><SAS token>"
    

    备注

    此过程用于上传日志。This procedure is useful for uploading logs. 即使没有可以访问的 SMB 共享,或者无法访问 Internet,也可在 Azure Stack Hub 上创建一个 Blob 存储帐户来传输日志,然后使用客户端检索这些日志。Even if you don't have an SMB share accessible or internet access, you can create a blob storage account on your Azure Stack Hub to transfer the logs, and then use your client to retrieve those logs.

    若要为存储帐户生成 SAS 令牌,需要以下权限:To generate the SAS token for the storage account, the following permissions are required:

    • 对 Blob 存储服务的访问权限。Access to the Blob Storage service.
    • 对容器资源类型的访问权限。Access to the container resource type.

    若要生成要用于 -OutputSasUri 参数的 SAS URI 值,请执行以下步骤:To generate a SAS Uri value to be used for the -OutputSasUri parameter, follow these steps:

    1. 按照本文中的步骤创建存储帐户。Create a storage account, following the steps in this article.
    2. 打开 Azure 存储资源管理器的实例。Open an instance of the Azure Storage Explorer.
    3. 连接到在步骤 1 中创建的存储帐户。Connect to the storage account created in step 1.
    4. 存储服务中导航到 Blob 容器Navigate to Blob Containers in Storage Services.
    5. 选择“新建容器”****。Select Create a new container.
    6. 右键单击新容器,然后单击“获取共享访问签名”。****Right-click the new container, then click Get Shared Access Signature.
    7. 根据需求,选择有效的开始时间结束时间Select a valid Start Time and End Time, depending on your requirements.
    8. 根据所需的权限,选择“读取”****、“写入”**** 和“列表”****。For the required permissions, select Read, Write, and List.
    9. 选择“创建” ****。Select Create.
    10. 你将获得共享访问签名。You'll get a Shared Access Signature. 复制 URL 部分,并将其提供给 -OutputSasUri 参数。Copy the URL portion and provide it to the -OutputSasUri parameter.

参数注意事项Parameter considerations

  • 参数 OutputSharePathOutputShareCredential 用于将日志存储在用户指定的位置。The parameters OutputSharePath and OutputShareCredential are used to store logs in a user specified location.

  • 可以使用 FromDateToDate 参数来收集特定时间段的日志。The FromDate and ToDate parameters can be used to collect logs for a particular time period. 如果未指定这些参数,则默认收集过去四小时的日志。If these parameters aren't specified, logs are collected for the past four hours by default.

  • 使用 FilterByNode 参数按计算机名筛选日志。Use the FilterByNode parameter to filter logs by computer name. 例如:For example:

    Get-AzureStackLog -OutputSharePath "<path>" -OutputShareCredential $cred -FilterByNode azs-xrp01
    
  • 使用 FilterByLogType 参数按类型筛选日志。Use the FilterByLogType parameter to filter logs by type. 可以选择按文件、共享或 WindowsEvent 进行筛选。You can choose to filter by File, Share, or WindowsEvent. 例如:For example:

    Get-AzureStackLog -OutputSharePath "<path>" -OutputShareCredential $cred -FilterByLogType File
    
  • 可以使用 TimeOutInMinutes 参数设置日志收集的超时。You can use the TimeOutInMinutes parameter to set the timeout for log collection. 它默认设置为 150(2.5 小时)。It's set to 150 (2.5 hours) by default.

  • 转储文件日志收集默认情况下处于禁用状态。Dump file log collection is disabled by default. 若要启用它,请使用 IncludeDumpFile 开关参数。To enable it, use the IncludeDumpFile switch parameter.

  • 目前,可以使用 FilterByRole 参数按以下角色筛选日志收集:Currently, you can use the FilterByRole parameter to filter log collection by the following roles:

    ACSACS CACA HRPHRP OboServiceOboService VirtualMachinesVirtualMachines
    ACSBlobACSBlob CacheServiceCacheService IBCIBC OEMOEM WASWAS
    ACSDownloadServiceACSDownloadService 计算Compute InfraServiceControllerInfraServiceController OnboardRPOnboardRP WASPUBLICWASPUBLIC
    ACSFabricACSFabric CPICPI KeyVaultAdminResourceProviderKeyVaultAdminResourceProvider PXEPXE
    ACSFrontEndACSFrontEnd CRPCRP KeyVaultControlPlaneKeyVaultControlPlane QueryServiceCoordinatorQueryServiceCoordinator
    ACSMetricsACSMetrics DeploymentMachineDeploymentMachine KeyVaultDataPlaneKeyVaultDataPlane QueryServiceWorkerQueryServiceWorker
    ACSMigrationServiceACSMigrationService DiskRPDiskRP KeyVaultInternalControlPlaneKeyVaultInternalControlPlane SeedRingSeedRing
    ACSMonitoringServiceACSMonitoringService Domain KeyVaultInternalDataPlaneKeyVaultInternalDataPlane SeedRingServicesSeedRingServices
    ACSSettingsServiceACSSettingsService ECEECE KeyVaultNamingServiceKeyVaultNamingService SLBSLB
    ACSTableMasterACSTableMaster EventAdminRPEventAdminRP MDMMDM SQLSQL
    ACSTableServerACSTableServer EventRPEventRP MetricsAdminRPMetricsAdminRP SRPSRP
    ACSWacACSWac ExternalDNSExternalDNS MetricsRPMetricsRP 存储Storage
    ADFSADFS FabricRingFabricRing MetricsServerMetricsServer StorageControllerStorageController
    ApplicationControllerApplicationController FabricRingServicesFabricRingServices MetricsStoreServiceMetricsStoreService URPURP
    ASAppGatewayASAppGateway FirstTierAggregationServiceFirstTierAggregationService MonAdminRPMonAdminRP SupportBridgeControllerSupportBridgeController
    AzureBridgeAzureBridge FRPFRP MonRPMonRP SupportRingSupportRing
    AzureMonitorAzureMonitor 网关Gateway NCNC SupportRingServicesSupportRingServices
    BareMetalBareMetal HealthMonitoringHealthMonitoring NonPrivilegedAppGatewayNonPrivilegedAppGateway SupportBridgeRPSupportBridgeRP
    BRPBRP HintingServiceV2HintingServiceV2 NRPNRP UsageBridgeUsageBridge

有关诊断日志的其他注意事项Additional considerations on diagnostic logs

  • 此命令需要一些时间来运行,具体取决于日志收集的角色。The command takes some time to run based on which role(s) the logs are collecting. 影响因素还包括指定用于日志收集的时限,以及 Azure Stack Hub 环境中的节点数。Contributing factors also include the time duration specified for log collection, and the numbers of nodes in the Azure Stack Hub environment.

  • 当日志收集运行时,请查看在 OutputSharePath 参数(在命令中指定)中创建的新文件夹。As log collection runs, check the new folder created in the OutputSharePath parameter specified in the command.

  • 每个角色的日志位于单个 zip 文件中。Each role has its logs inside individual zip files. 根据所收集日志的大小,一个角色的日志可能会拆分成多个 zip 文件。Depending on the size of the collected logs, a role may have its logs split into multiple zip files. 对于此类角色,如果需要将所有日志文件解压缩到单个文件夹中,请使用可以批量解压缩的工具。For such a role, if you want to have all the log files unzipped into a single folder, use a tool that can unzip in bulk. 选择角色的所有压缩文件,然后选择“解压缩到此处”。****Select all the zipped files for the role and select extract here. 该角色的所有日志文件会解压缩到单个合并的文件夹中。All the log files for that role will be unzipped into a single merged folder.

  • 在压缩的日志文件所在的文件夹中,还会创建名为 Get-AzureStackLog_Output.log 的文件。A file called Get-AzureStackLog_Output.log is also created in the folder that contains the zipped log files. 此文件是一个命令输出日志,可以用来排查日志收集过程中的问题。This file is a log of the command output, which can be used for troubleshooting problems during log collection. 有时,日志文件包含 PS>TerminatingError 条目,除非运行日志收集后缺少预期的日志文件,否则可以放心忽略这些条目。Sometimes the log file includes PS>TerminatingError entries which can be safely ignored, unless expected log files are missing after log collection runs.

  • 调查某个特定的故障时,可能需要多个组件中的日志。To investigate a specific failure, logs may be needed from more than one component.

    • 所有基础结构 VM 的系统和事件日志收集在 VirtualMachines 角色中。System and event logs for all infrastructure VMs are collected in the VirtualMachines role.
    • 所有主机的系统和事件日志收集在 BareMetal 角色中。System and event logs for all hosts are collected in the BareMetal role.
    • 故障转移群集和 Hyper-V 事件日志收集在“存储”**** 角色中。Failover cluster and Hyper-V event logs are collected in the Storage role.
    • ACS 日志收集在“存储”角色**** 和 ACS 角色中。ACS logs are collected in the Storage and ACS roles.

备注

会对收集的日志强制实施大小和保留时间限制,因为必须确保对存储空间进行有效的利用,以免该空间充斥着日志。Size and age limits are enforced on the logs collected as it's essential to ensure efficient utilization of your storage space and to avoid getting flooded with logs. 但是,在诊断问题时,有时可能需要某些日志,但这些日志因为这些限制而不再存在了。However, when diagnosing a problem, you sometimes need logs that don't exist anymore because of these limits. 因此,强烈建议每隔 8 到 12 小时就将日志卸载到外部存储空间(Azure 中的存储帐户、其他本地存储设备,等等)并在该处保留 1 - 3 月,具体取决于你的要求。Thus, it's highly recommended that you offload your logs to an external storage space (a storage account in Azure, an additional on premises storage device, etc.) every 8 to 12 hours and keep them there for 1 - 3 months, depending on your requirements. 还应确保该存储位置已加密。You should also ensure this storage location is encrypted.

Invoke-AzureStackOnDemandLogInvoke-AzureStackOnDemandLog

可以使用 Invoke-AzureStackOnDemandLog cmdlet 为某些角色生成按需日志(请参阅本部分末尾的列表)。You can use the Invoke-AzureStackOnDemandLog cmdlet to generate on-demand logs for certain roles (see the list at the end of this section). 默认情况下,执行 Get-AzureStackLog cmdlet 时收到的日志捆绑包中不存在此 cmdlet 生成的日志。The logs generated by this cmdlet aren't present by default in the log bundle you receive when you execute the Get-AzureStackLog cmdlet. 此外,建议你仅在 Azure 支持团队请求时才收集这些日志。Also, it's recommended that you collect these logs only when requested by the Azure support team.

目前,可以使用 -FilterByRole 参数按以下角色筛选日志收集:Currently, you can use the -FilterByRole parameter to filter log collection by the following roles:

  • OEMOEM
  • NCNC
  • SLBSLB
  • 网关Gateway

收集按需诊断日志的示例Example of collecting on-demand diagnostic logs

$ipAddress = "<IP ADDRESS OF THE PEP VM>" # You can also use the machine name instead of IP here.

$password = ConvertTo-SecureString "<CLOUD ADMIN PASSWORD>" -AsPlainText -Force
$cred = New-Object -TypeName System.Management.Automation.PSCredential ("<DOMAIN NAME>\CloudAdmin", $password)

$shareCred = Get-Credential

$session = New-PSSession -ComputerName $ipAddress -ConfigurationName PrivilegedEndpoint -Credential $cred

$fromDate = (Get-Date).AddHours(-8)
$toDate = (Get-Date).AddHours(-2) # Provide the time that includes the period for your issue

Invoke-Command -Session $session {
   Invoke-AzureStackOnDemandLog -Generate -FilterByRole "<on-demand role name>" # Provide the supported on-demand role name e.g. OEM, NC, SLB, Gateway
   Get-AzureStackLog -OutputSharePath "<external share address>" -OutputShareCredential $using:shareCred -FilterByRole Storage -FromDate $using:fromDate -ToDate $using:toDate
}

if ($session) {
   Remove-PSSession -Session $session
}

使用 PEP 收集诊断日志的工作原理How diagnostic log collection using the PEP works

可以通过 Azure Stack Hub 诊断工具轻松高效地进行日志收集。Azure Stack Hub diagnostics tools help make log collection easy and efficient. 下图显示了诊断工具的工作原理:The following diagram shows how the diagnostics tools work:

Azure Stack Hub 诊断工具工作流图

跟踪收集器Trace Collector

跟踪收集器默认启用,可以在后台持续运行,以便从 Azure Stack Hub 组件服务收集所有 Windows 事件跟踪 (ETW) 日志。The Trace Collector is enabled by default and runs continuously in the background to collect all Event Tracing for Windows (ETW) logs from Azure Stack Hub component services. ETW 日志存储在一个常用的本地共享中,其时间限制为五天。ETW logs are stored in a common local share with a five-day age limit. 一旦达到此限制,就会在创建新文件时删除最旧的文件。Once this limit is reached, the oldest files are deleted as new ones are created. 每个文件默认允许的最大大小为 200 MB。The default maximum size allowed for each file is 200 MB. 每 2 分钟进行一次大小检查,如果当前文件 >= 200 MB,则会保存该文件并生成新文件。A size check happens every 2 minutes, and if the current file is >= 200 MB, it's saved and a new file generates. 按事件会话生成的文件的总大小也存在 8 GB 的限制。There's also an 8 GB limit on the total file size generated per event session.

Get-AzureStackLogGet-AzureStackLog

可以使用 PowerShell cmdlet Get-AzureStackLog 从 Azure Stack Hub 环境中的所有组件收集日志。The PowerShell cmdlet Get-AzureStackLog can be used to collect logs from all the components in an Azure Stack Hub environment. 此工具将日志以 zip 文件形式保存在用户定义的位置。It saves them in zip files in a user-defined location. 如果 Azure Stack Hub 技术支持团队需要日志来排查问题,他们可能要求你运行 Get-AzureStackLog。If the Azure Stack Hub technical support team needs your logs to help troubleshoot an issue, they may ask you to run Get-AzureStackLog.

注意

这些日志文件可能包含个人身份信息 (PII)。These log files may contain personally identifiable information (PII). 在公开发布任何日志文件之前,请考虑到这一因素。Take this into account before you publicly post any log files.

下面是一些收集的示例日志类型:The following are some example log types that are collected:

  • Azure Stack Hub 部署日志Azure Stack Hub deployment logs
  • Windows 事件日志Windows event logs
  • Panther 日志Panther logs
  • 群集日志Cluster logs
  • 存储诊断日志Storage diagnostic logs
  • ETW 日志ETW logs

这些文件由跟踪收集器收集并保存在共享中。These files are collected and saved in a share by Trace Collector. 然后,可以根据需要使用 Get-AzureStackLog 来收集它们。Get-AzureStackLog can then be used to collect them when necessary.