Samla in Loggar och mått för Apache Spark-program med hjälp av Azure Event Hubs

I den här artikeln beskrivs Azure Event Hubs mål för Fabric Apache Spark Diagnostic Emitter.

Fabric Apache Spark Diagnostic Emitter tillhandahåller en gemensam konfigurationsmodell för Spark-diagnostik mellan mål. I den här artikeln konfigurerar du modellen för att dirigera Apache Spark-loggar, händelseloggar och mått till Azure Event Hubs.

Vägledning för emitterarkitektur och val av destination finns i Översikt över Fabric Apache Spark Diagnostic Emitter.

Samla in loggar och mätdata till Azure Event Hubs

Steg 1: Skapa en Azure Event Hubs-instans

Om du vill samla in diagnostikloggar och mått kan du använda en befintlig Azure Event Hubs instans. Om du inte har någon kan du skapa en händelsehubb.

Steg 2: Skapa ett Fabric Environment-objekt med Apache Spark-konfiguration

Alternativ 1: Konfigurera med Azure Event Hubs anslutningssträng

  1. Skapa ett miljöobjekt i Fabric

  2. Lägg till följande Spark-egenskaper med lämpliga värden i miljöobjektet, eller välj Add from .yml i ribbon för att ladda ner exempelfilen yaml som redan innehåller följande egenskaper.

    spark.synapse.diagnostic.emitters: MyEventHub
spark.synapse.diagnostic.emitter.MyEventHub.type: "AzureEventHub"
spark.synapse.diagnostic.emitter.MyEventHub.categories: "Log,EventLog,Metrics"
spark.synapse.diagnostic.emitter.MyEventHub.secret: <connection-string>
spark.fabric.pools.skipStarterPools: "true" //Add this Spark property when using the default pool.

    Fyll i parametrarna <connection-string> i konfigurationsfilen. Mer information finns i Azure Event Hubs konfigurationer.

Alternativ 2: Konfigurera med Azure Key Vault

Anteckning

Se till att användare som skickar Apache Spark-program beviljas läshemliga behörigheter. Mer information finns i Ge åtkomst till Key Vault-nycklar, certifikat och hemligheter med ett Azure-rollbaserat åtkomstkontrollsystem.

Så här konfigurerar du Azure Key Vault för lagring av arbetsytenyckeln:

  1. Skapa och gå till ditt nyckelvalv i Azure-portalen.

  2. På inställningssidan för nyckelvalvet väljer du Hemligheter och sedan Generera/importera.

  3. Välj följande värden på skärmen Skapa en hemlighet:

    • Namn: Ange ett namn för hemligheten.
    • Värde: Ange <connection-string> för hemligheten.
    • Lämna standardvärdena för de andra alternativen. Välj sedan Skapa.

  4. Skapa ett miljöobjekt i Fabric.

  5. Lägg till följande Spark-egenskaper. Eller välj Lägg till från .yml i menyfliksområdet för att ladda ned yaml-exempelfilen, som innehåller följande Spark-egenskaper.

    spark.synapse.diagnostic.emitters: MyEventHub
spark.synapse.diagnostic.emitter.MyEventHub.type: "AzureEventHub"
spark.synapse.diagnostic.emitter.MyEventHub.categories: "Log,EventLog,Metrics"
spark.synapse.diagnostic.emitter.MyEventHub.secret.keyVault: <AZURE_KEY_VAULT_URI>
spark.synapse.diagnostic.emitter.MyEventHub.secret.keyVault.secretName: <AZURE_KEY_VAULT_SECRET_KEY_NAME>
spark.fabric.pools.skipStarterPools: "true" //Add this Spark property when using the default pool.

    Fyll i följande parametrar i konfigurationsfilen: <AZURE_KEY_VAULT_URI>, <AZURE_KEY_VAULT_SECRET_KEY_NAME>. Mer information om dessa parametrar finns i Azure Event Hubs konfigurationer.

  6. Spara och publicera ändringarna.

Alternativ 3: Konfigurera med autentisering av tjänsteprincipalcertifikat

Använd detta alternativ för att autentisera dig mot Azure Event Hubs med en Microsoft Entra-tjänsteprincip och ett certifikat lagrat i Azure Key Vault. Mer information finns i Skapa ett huvudnamn för tjänsten som innehåller ett certifikat med hjälp av Azure CLI.

Innan du konfigurerar Spark-egenskaperna:

  • Skapa eller importera ett certifikat i Azure Key Vault. Certifikatet måste innehålla en exportbar privat nyckel.
  • Ladda endast ner det offentliga certifikatet i CER- eller PEM-format och ladda upp det till Microsoft Entra-appregistreringen under Certifikat och hemligheterCertifikat.
  • Registrera Azure Key Vault URI och certifikatnamn. Du använder dessa värden i Spark-egenskaperna.
  • Tilldela rollen Azure Event Hubs Data Sender till tjänstehuvudpersonen på målnamnet Event Hubs eller Event Hub-instansen.
  • Tilldela rollen Key Vault Certificate User på Azure Key Vault till den inloggade Fabric-användaren som startar Spark-sessionen.

Important

Certifikathämtning och åtkomst till Event Hubs använder olika identiteter. Den inloggade Fabric-användaren hämtar certifikatet och dess privata nyckel från Azure Key Vault. Tjänstehuvudpersonen använder certifikatet för att autentisera och skicka diagnosdata till Event Hubs. Att endast ge Key Vault-åtkomst till tjänstehuvudpersonen är inte tillräckligt.

Lägg till följande Spark-egenskaper i Fabric-miljön:

spark.synapse.diagnostic.emitters: MyEventHub 
spark.synapse.diagnostic.emitter.MyEventHub.type: "AzureEventHub" 
spark.synapse.diagnostic.emitter.MyEventHub.categories: "DriverLog,ExecutorLog,EventLog,Metrics" 
spark.synapse.diagnostic.emitter.MyEventHub.hostName: "<EVENT_HUB_NAMESPACE>.servicebus.windows.net" 
spark.synapse.diagnostic.emitter.MyEventHub.entityPath: "<EVENT_HUB_NAME>" 
spark.synapse.diagnostic.emitter.MyEventHub.certificate.keyVault.certificateName: "<CERTIFICATE_NAME>" 
spark.synapse.diagnostic.emitter.MyEventHub.certificate.keyVault: "https://<KEY_VAULT_NAME>.vault.azure.net/" 
spark.synapse.diagnostic.emitter.MyEventHub.tenantId: "<SERVICE_PRINCIPAL_TENANT_ID>" 
spark.synapse.diagnostic.emitter.MyEventHub.clientId: "<SERVICE_PRINCIPAL_CLIENT_ID>" 
spark.fabric.pools.skipStarterPools: "true"

För certifikatbaserad autentisering är hostName det fullt kvalificerade domännamnet för Event Hubs-namnrymden, utan prefixet sb:// . entityPath är namnet på den målinstansen Event Hub. Certifikatnamnet måste exakt matcha certifikatnamnet i Azure Key Vault.

Steg 3: Koppla miljöobjektet till anteckningsböcker eller Spark-jobbdefinitioner, eller ange det som standard för arbetsytan

Anteckning

  • Endast arbetsyteadministratörer kan ange en miljö som standard för en arbetsyta.
  • När den har angetts blir den standardmiljö för alla notebook-filer och Spark-jobbdefinitioner på arbetsytan. Mer information finns i Fabric Arbetsyteinställningar.

För att bifoga miljön till anteckningsboks- eller Spark-jobbdefinitioner:

  1. Gå till den specifika notebook- eller Spark-jobbdefinitionen i Fabric.
  2. Välj menyn Miljö på fliken Start och välj miljön med de konfigurerade Spark-egenskaperna för diagnostik.
  3. Konfigurationen tillämpas när du startar en Spark-session.

Så här anger du miljön som standard för arbetsytan:

  1. Gå till arbetsytinställningar i Fabric.
  2. Hitta Spark-inställningar i arbetsyteinställningar (Inställningar för arbetsyteinställning>datateknik/Science>Spark).
  3. Välj fliken Miljö, och välj den miljö där diagnostik-sparklägen är konfigurerade, och välj Spara.

Steg 4. Skicka ett Apache Spark-program och visa loggarna och måtten

Du kan använda Apache Log4j-biblioteket för att skriva anpassade loggar.

Exempel för Scala:

	   %%spark
	   val logger = org.apache.log4j.LogManager.getLogger("com.contoso.LoggerExample")
	   logger.info("info message")
	   logger.warn("warn message")
	   logger.error("error message")
	   //log exception
	   try {
	      1/0
	   } catch {
	      case e:Exception =>logger.warn("Exception", e)
	   }
	   // run job for task level metrics
	   val data = sc.parallelize(Seq(1,2,3,4)).toDF().count()

Exempel för PySpark:

	   %%pyspark
	   logger = sc._jvm.org.apache.log4j.LogManager.getLogger("com.contoso.PythonLoggerExample")
	   logger.info("info message")
	   logger.warn("warn message")
	   logger.error("error message")

Tillgängliga konfigurationer

Konfiguration beskrivning
spark.synapse.diagnostic.emitters Obligatoriskt. Kommaavgränsade målnamn för diagnostikemittare. Till exempel: MyDest1,MyDest2
spark.synapse.diagnostic.emitter.<destination>.type Obligatoriskt. Inbyggd måltyp. Om du vill aktivera Azure Event Hubs mål ska värdet vara AzureEventHub.
spark.synapse.diagnostic.emitter.<destination>.categories Valfritt. De valda loggkategorierna som är avgränsade med kommatecken. Tillgängliga värden är DriverLog, ExecutorLog, EventLog, Metrics. Om det inte anges är standardvärdet alla kategorier.
spark.synapse.diagnostic.emitter.<destination>.secret Valfritt. Azure Event Hubs anslutningssträng. Krävs om du inte använder certifikatbaserad autentisering och .secret.keyVault inte har angetts. Det här fältet ska matcha mönstret Endpoint=sb://<FQDN>/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<KeyValue>;EntityPath=<PathName>.
spark.synapse.diagnostic.emitter.<destination>.secret.keyVault Krävs om anslutningssträngsautentisering används och .secret inte har angetts. Den Azure Key Vault uri där hemligheten (reťazec pripojenia) lagras.
spark.synapse.diagnostic.emitter.<destination>.secret.keyVault.secretName Krävs om .secret.keyVault anges. Det Azure Key Vault hemliga namnet där hemligheten (reťazec pripojenia) lagras.
spark.synapse.diagnostic.emitter.<destination>.hostName Krävs för certifikatbaserad autentisering. Det fullt kvalificerade domännamnet för Event Hubs-namnrymden, utan prefixet sb:// . Till exempel <namespace>.servicebus.windows.net.
spark.synapse.diagnostic.emitter.<destination>.entityPath Krävs för certifikatbaserad autentisering. Namnet på Event Hubs-instansen som tar emot diagnostikdatan.
spark.synapse.diagnostic.emitter.<destination>.tenantId Krävs om du använder certifikatbaserad autentisering. Det Azure Active Directory klient-ID:t för tjänstens huvudprincip.
spark.synapse.diagnostic.emitter.<destination>.clientId Krävs om du använder certifikatbaserad autentisering. Applikationens (klient) ID för Service Principal.
spark.synapse.diagnostic.emitter.<destination>.certificate.keyVault Krävs för certifikatbaserad autentisering. Azure Key Vault-URL:en som lagrar certifikatet. Den inloggade Fabric-användaren som startar Spark-sessionen måste ha behörighet att hämta certifikatet och dess privata nyckel, såsom rollen Key Vault Certificate User.
spark.synapse.diagnostic.emitter.<destination>.certificate.keyVault.certificateName Krävs för certifikatbaserad autentisering. Namnet på certifikatet som lagras i Azure Key Vault. Certifikatet måste innehålla en tillgänglig privat nyckel, och dess publika certifikat måste vara registrerat i Microsoft Entra-appen.
spark.synapse.diagnostic.emitter.<destination>.filter.eventName.match Valfritt. De kommaavgränsade spark-händelsenamnen, kan du specificera vilka händelser som ska samlas in. Till exempel: SparkListenerApplicationStart,SparkListenerApplicationEnd
spark.synapse.diagnostic.emitter.<destination>.filter.loggerName.match Valfritt. Med de kommaavgränsade Log4j-loggningsnamnen kan du specificera vilka loggar som ska samlas in. Till exempel: org.apache.spark.SparkContext,org.example.Logger
spark.synapse.diagnostic.emitter.<destination>.filter.metricName.match Valfritt. Med kommaavgränsade spark-måttnamnssuffix kan du ange vilka mått som ska samlas in. Till exempel: jvm.heap.used
spark.fabric.pools.skipStarterPools Obligatoriskt. Den här Spark-egenskapen används för att tvinga fram en Spark-session på begäran. Du bör ange värdet till true när du använder standardpoolen för att utlösa biblioteken för att generera loggar och mått.

Anteckning

Den Azure Event Hubs-instansens anslutningssträng ska alltid innehålla EntityPath, som är namnet på Azure Event Hubs-instansen.

Exempel på loggdata

Här är en exempelloggpost i JSON-format:

{
  "timestamp": "2025-02-28T09:13:57.978Z",
  "category": "Log|EventLog|Metrics",
  "fabricLivyId": "<fabric-livy-id>",
  "applicationId": "<application-id>",
  "applicationName": "<application-name>",
  "executorId": "<driver-or-executor-id>",
  "userId": "<the-submitter-user-id>",
  "fabricTenantId": "<my-fabric-tenant-id>",
  "capacityId": "<my-fabric-capacity-id>",
  "artifactType": "SynapseNotebook|SparkJobDefinition",
  "artifactId": "<my-fabric-item-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": "2025-02-28T09:13:57.941Z",
    "message": "ApplicationAttemptId: appattempt_1740734011890_0001_000001",
    "logger_name": "org.apache.spark.deploy.yarn.ApplicationMaster",
    "level": "INFO",
    "thread_name": "main"
    // ...
  }
}

När diagnostiken skickas till Azure Event Hubs kan du använda Event Hub som källa i en Fabric-händelseström för att bearbeta eller dirigera data.

Fabric arbetsytor med hanterat virtuellt nätverk

Skapa en hanterad privat slutpunkt för det tilltänkta Azure Event Hubs. Mer detaljerade instruktioner finns i Skapa och använd hanterade privata slutpunkter i Fabric.

När den hanterade privata slutpunkten har godkänts kan användarna börja skicka loggar och mätvärden till målets Azure Event Hubs.

Nästa steg

  • Last updated on