使用 Azure 存储帐户收集 Apache Spark 应用程序日志和指标（预览版）

项目
11/05/2024

Fabric Apache Spark 诊断发射器扩展是一个库，通过该库，Apache Spark 应用程序能够将日志、事件日志和指标发送到多个目标，包括 Azure Log Analytics、Azure 存储和 Azure 事件中心。

在本教程中，你将了解如何使用 Fabric Apache Spark 诊断发射器扩展将 Apache Spark 应用程序日志、事件日志和指标发送到 Azure 存储帐户。

将日志和指标收集到存储帐户

步骤 1：创建存储帐户

若要收集诊断日志和指标，可以使用现有的 Azure 存储帐户。如果没有帐户，可以创建一个 Azure Blob 存储帐户，或创建一个用于 Azure Data Lake Storage Gen2 的存储帐户。

步骤 2：使用 Apache Spark 配置创建 Fabric 环境项目

选项 1：使用 Azure 存储 URI 和访问密钥进行配置

在 Fabric 中创建 Fabric 环境项目

将以下 Spark 属性及其相应值添加到环境项目，或者选择功能区中的“从 .yml 添加”以下载示例 yaml 文件，该文件已包含以下属性。

spark.synapse.diagnostic.emitters: MyStorageBlob
spark.synapse.diagnostic.emitter.MyStorageBlob.type: "AzureStorage"
spark.synapse.diagnostic.emitter.MyStorageBlob.categories: "DriverLog,ExecutorLog,EventLog,Metrics"
spark.synapse.diagnostic.emitter.MyStorageBlob.uri:  "https://<my-blob-storage>.blob.core.windows.net/<container-name>/<folder-name>"
spark.synapse.diagnostic.emitter.MyDestination1.auth: "AccessKey"
spark.synapse.diagnostic.emitter.MyDestination1.secret: <storage-access-key>
spark.fabric.pools.skipStarterPools: "true" //Add this Spark property when using the default pool.

在配置文件中填写以下参数：<my-blob-storage>、<container-name>、<folder-name>、<storage-access-key>。有关这些参数的更多详细信息，请参阅 Azure 存储配置。

选项 2：配置 Azure 密钥保管库

注意

已知问题：无法使用选项 2 临时启动会话。目前，将机密存储在密钥保管库中会阻止 Spark 会话启动。请优先使用选项 1 中概述的方法对其进行配置。

确保提交 Apache Spark 应用程序的用户被授予读取机密权限。有关详细信息，请参阅使用 Azure 基于角色的访问控制提供对密钥保管库密钥、证书和机密的访问权限。

若要配置 Azure Key Vault 以存储工作区密钥，请执行以下操作：

在 Azure 门户中，创建并转到密钥保管库。
在密钥保管库的设置页面上，选择“机密”，然后选择“生成/导入”。
在“创建机密”屏幕上，选择以下值：
- 名称：输入机密的名称。
- 值：输入机密的 <storage-access-key>。
- 让其他值保留默认设置。然后选择“创建”。
在 Fabric 中创建 Fabric 环境项目。

添加以下 Spark 属性。或者在功能区上选择“从 .yml 添加”，以上传包含以下 Spark 属性的示例 yaml 文件。

spark.synapse.diagnostic.emitters: <MyStorageBlob>
spark.synapse.diagnostic.emitter.MyStorageBlob.type: "AzureStorage"
spark.synapse.diagnostic.emitter.MyStorageBlob.categories: "DriverLog,ExecutorLog,EventLog,Metrics"
spark.synapse.diagnostic.emitter.MyStorageBlob.uri:  "https://<my-blob-storage>.blob.core.windows.net/<container-name>/<folder-name>"
spark.synapse.diagnostic.emitter.MyStorageBlob.auth: "AccessKey"
spark.synapse.diagnostic.emitter.MyStorageBlob.secret.keyVault: <AZURE_KEY_VAULT_NAME>
spark.synapse.diagnostic.emitter.MyStorageBlob.secret.keyVault.secretName: <AZURE_KEY_VAULT_SECRET_KEY_NAME>
spark.fabric.pools.skipStarterPools: "true" //Add this Spark property when using the default pool.

在配置文件中填写以下参数：<my-blob-storage>、<container-name>、<folder-name>、<AZURE_KEY_VAULT_NAME>、<AZURE_KEY_VAULT_SECRET_KEY_NAME>。有关这些参数的更多详细信息，请参阅 Azure 存储配置。

保存并发布更改。

步骤 3：将环境项目附加到笔记本或 Spark 作业定义，或将其设置为工作区默认值

将环境附加到笔记本或 Spark 作业定义：

导航到 Fabric 中的特定笔记本或 Spark 作业定义。
选择“主页”选项卡上的“环境”菜单，然后选择具有已配置诊断 Spark 属性的环境。
启动 Spark 会话时会应用配置。

将环境设置为工作区默认值：

导航到 Fabric 中的“工作区设置”。
在“工作区设置”中找到“Spark 设置”（“工作区设置”->“数据工程/科学”->“Spark 设置”）。
选择“环境”选项卡，选择已配置诊断 spark 属性的环境，然后单击“保存”。

注意

只有工作区管理员可以管理工作区配置。此处所做的更改将应用到附加到工作区设置的所有笔记本和 Spark 作业定义。有关详细信息，请参阅 Fabric 工作区设置。

步骤 4：查看 Azure 存储帐户中的日志文件

将作业提交到配置的 Spark 会话后，可以查看目标存储帐户中的日志和指标文件。日志根据 <workspaceId>.<fabricLivyId> 所标识的不同应用程序存储在相应的路径中。所有日志文件都采用 JSON 行格式（也称为换行符分隔的 JSON 或 ndjson），便于数据处理。

“可用配置”

配置	说明
`spark.synapse.diagnostic.emitters`	必需。诊断发射器以逗号分隔的目标名称。例如： `MyDest1,MyDest2`
`spark.synapse.diagnostic.emitter.<destination>.type`	必需。内置目标类型。若要启用 Azure 存储目标，此字段中需要包含 `AzureStorage`。
`spark.synapse.diagnostic.emitter.<destination>.categories`	可选。以逗号分隔的选定日志类别。可用的值包括 `DriverLog`、`ExecutorLog`、`EventLog`、`Metrics`。如果未设置，则默认值为“所有”类别。
`spark.synapse.diagnostic.emitter.<destination>.auth`	必需。 `AccessKey` 表示使用存储帐户访问密钥授权。 `SAS` 表示共享访问签名授权。
`spark.synapse.diagnostic.emitter.<destination>.uri`	必需。目标 Blob 容器文件夹 URI。应匹配模式 `https://<my-blob-storage>.blob.core.windows.net/<container-name>/<folder-name>`。
`spark.synapse.diagnostic.emitter.<destination>.secret`	可选。机密（AccessKey 或 SAS）内容。
`spark.synapse.diagnostic.emitter.<destination>.secret.keyVault`	如果未指定 `.secret`，则为必需项。存储机密（AccessKey 或 SAS）的 Azure Key Vault 名称。
`spark.synapse.diagnostic.emitter.<destination>.secret.keyVault.secretName`	如果指定了 `.secret.keyVault`，则该参数是必需的。存储机密（AccessKey 或 SAS）的 Azure Key Vault 机密名称。
`spark.synapse.diagnostic.emitter.<destination>.filter.eventName.match`	可选。以逗号分隔的 Spark 事件名称，你可指定要收集的事件。例如： `SparkListenerApplicationStart,SparkListenerApplicationEnd`
`spark.synapse.diagnostic.emitter.<destination>.filter.loggerName.match`	可选。以逗号分隔的 Log4j 记录器名称，你可指定要收集的日志。例如： `org.apache.spark.SparkContext,org.example.Logger`
`spark.synapse.diagnostic.emitter.<destination>.filter.metricName.match`	可选。以逗号分隔的 Spark 指标名称后缀，你可指定要收集的指标。例如：`jvm.heap.used`
`spark.fabric.pools.skipStarterPools`	必需。此 Spark 属性用于强制按需 Spark 会话。使用默认池时，应将值设置为 `True`，以触发库来发出日志和指标。

日志数据示例

下面是 JSON 格式的示例日志记录：

{
  "timestamp": "2024-09-06T03:09:37.235Z",
  "category": "Log|EventLog|Metrics",
  "fabricLivyId": "<fabric-livy-id>",
  "applicationId": "<application-id>",
  "applicationName": "<application-name>",
  "executorId": "<driver-or-executor-id>",
  "fabricTenantId": "<my-fabric-tenant-id>",
  "capacityId": "<my-fabric-capacity-id>",
  "artifactType": "SynapseNotebook|SparkJobDefinition",
  "artifactId": "<my-fabric-artifact-id>",
  "fabricWorkspaceId": "<my-fabric-workspace-id>",
  "fabricEnvId": "<my-fabric-environment-id>",
  "executorMin": "<executor-min>",
  "executorMax": "<executor-max>",
  "isHighConcurrencyEnabled": "true|false",
  "properties": {
    // The message properties of logs, events and metrics.
    "timestamp": "2024-09-06T03:09:37.235Z",
    "message": "Initialized BlockManager: BlockManagerId(1, vm-04b22223, 34319, None)",
    "logger_name": "org.apache.spark.storage.BlockManager",
    "level": "INFO",
    "thread_name": "dispatcher-Executor"
    //...
  }
}

具有托管虚拟网络的 Fabric 工作区

为目标 Azure Blob 存储创建托管专用终结点。有关详细说明，请参阅在 Microsoft Fabric 中创建和使用托管专用终结点 - Microsoft Fabric。

一旦托管专用终结点获得批准，用户就可以开始向目标 Azure Blob 存储发出日志和指标。

通过