Autoinstrumentation für Azure Kubernetes Service (Vorschau)

Dieser Leitfaden führt durch die Aktivierung von Azure Monitor Application Insights für Azure Kubernetes Service (AKS)-Workloads, ohne Quellcode zu ändern.

Wir behandeln die Installation der Azure CLI-Erweiterung für die Aks-Vorschau, das Registrieren des AzureMonitorAppMonitoringPreview-Featurekennzeichens, das Vorbereiten eines Clusters, das Onboarding von Bereitstellungen und den Neustart von Bereitstellungen. Diese Schritte führen dazu, dass die automatische Instrumentierung die OpenTelemetry-Distribution für Azure Monitor in Anwendungspods einfügt, um Telemetriedaten zu generieren. Weitere Informationen zu Autoinstrumentation und seinen Vorteilen finden Sie unter Was ist die automatische Instrumentierung für Azure Monitor Application Insights?.

Voraussetzungen

• Ein AKS-Cluster , der eine Kubernetes-Bereitstellung mit Java oder Node.js in der öffentlichen Azure-Cloud ausführt
• Eine arbeitsbereichbasierte Application Insights-Ressource.
• Azure CLI 2.60.0 oder höher. Weitere Informationen finden Sie unter Installieren der Azure CLI, Welche Version der Azure CLI ist installiert?, und wie sie die Azure CLI aktualisieren.

Installieren der Azure CLI-Erweiterung „aks-preview“

Installieren Sie die aks-preview Erweiterung:

az extension add --name aks-preview

Aktualisieren Sie auf die neueste Version der Erweiterung:

az extension update --name aks-preview

Stellen Sie sicher, dass die installierte Azure CLI-Version die Anforderung im Abschnitt "Voraussetzungen" erfüllt:

az version

Wenn die Version die Anforderung nicht erfüllt, führen Sie die oben genannten Schritte aus, um Azure CLI zu installieren und zu aktualisieren.

Registriere die AzureMonitorAppMonitoringPreview-Feature-Flag

# Log into Azure CLI
az login

# Register the feature flag for Azure Monitor App Monitoring in preview
az feature register --namespace "Microsoft.ContainerService" --name "AzureMonitorAppMonitoringPreview"

# List the registration state of the Azure Monitor App Monitoring Preview feature
# It could take hours for the registration state to change from Registering to Registered
az feature list -o table --query "[?contains(name, 'Microsoft.ContainerService/AzureMonitorAppMonitoringPreview')].{Name:name,State:properties.state}"

# Once the feature shows as Registered in the prior step, re-register the Microsoft.ContainerService provider to apply the new feature settings
az provider register --namespace "Microsoft.ContainerService"

# Check the registration state of the Microsoft.ContainerService provider
az provider show --namespace "Microsoft.ContainerService" --query "registrationState"

Vorbereiten eines Clusters

Führen Sie zum Vorbereiten eines Clusters den folgenden Azure CLI-Befehl aus.

az aks update --resource-group={resource_group} --name={cluster_name} --enable-azure-monitor-app-monitoring 

Onboarden von Bereitstellungen

Bereitstellungen können auf zwei Arten integriert werden: pro Namespace oder pro Bereitstellung. Verwenden Sie die namespaceweite Methode, um alle Bereitstellungen in einem Namespace zu integrieren. Verwenden Sie für ein selektives oder variabel konfiguriertes Integrieren über mehrere Bereitstellungen hinweg den Ansatz pro Bereitstellung.

Namespace-weite Integration

Um alle Bereitstellungen in einem Namespace einzubinden, erstellen Sie in jedem Namespace eine einzelne benutzerdefinierte Instrumentationsressource mit dem Namen . Aktualisieren Sie applicationInsightsConnectionString , um die Verbindungszeichenfolge Ihrer Application Insights-Ressource zu erhalten.

apiVersion: monitor.azure.com/v1
kind: Instrumentation
metadata:
  name: default
  namespace: mynamespace1
spec:
  settings:
    autoInstrumentationPlatforms: []
  destination: # required
    applicationInsightsConnectionString: "InstrumentationKey=11111111-1111-1111-1111-111111111111;IngestionEndpoint=https://eastus2-3.in.applicationinsights.azure.com/;LiveEndpoint=https://eastus2.livediagnostics.monitor.azure.com/"

Mindestens die folgende Konfiguration ist erforderlich:

• spec.settings.autoInstrumentationPlatforms: Einer oder mehrere Werte, basierend auf den Sprachen, die Ihre Pods verwenden.
• spec.destination.applicationInsightsConnectionString: Die Verbindungszeichenfolge einer Application Insights-Ressource.

Integration pro Bereitstellung

Verwenden Sie das Onboarding pro Bereitstellung, um sicherzustellen, dass Bereitstellungen mit bestimmten Sprachen instrumentiert werden oder um Telemetrie an separate Application Insights-Ressourcen zu leiten.

1. Erstellen Sie eine benutzerdefinierte eindeutige Instrumentationsressource für jedes Szenario. Vermeiden Sie die Verwendung des Namens default, der für das namespaceweite Onboarding verwendet wird.

   Erstellen Sie benutzerdefinierte Ressourcen für die Instrumentation , um Application Insights in den einzelnen Namespaces zu konfigurieren. Aktualisieren Sie applicationInsightsConnectionString , um die Verbindungszeichenfolge Ihrer Application Insights-Ressource zu erhalten.

   Tipp

   Sie können die Verbindungszeichenfolge über die Übersichtsseite Ihrer Application Insights-Ressource abrufen.

   apiVersion: monitor.azure.com/v1
   kind: Instrumentation
   metadata:
     name: cr1
     namespace: mynamespace1
   spec:
     settings:
       autoInstrumentationPlatforms: []
     destination: # required
       applicationInsightsConnectionString: "InstrumentationKey=11111111-1111-1111-1111-111111111111;IngestionEndpoint=https://eastus2-3.in.applicationinsights.azure.com/;LiveEndpoint=https://eastus2.livediagnostics.monitor.azure.com/"
   

   Mindestens die folgende Konfiguration ist erforderlich:

   • spec.destination.applicationInsightsConnectionString: Die Verbindungszeichenfolge einer Application Insights-Ressource.

2. Ordnen Sie jede Bereitstellung der entsprechenden benutzerdefinierten Ressource mithilfe von Anmerkungen zu. Die Anmerkung setzt die sprache außer Kraft, die in der benutzerdefinierten Ressource festgelegt ist.

   Wichtig

   Um zu verhindern, dass sie versehentlich zu den Anmerkungen der Bereitstellung hinzugefügt werden, fügen Sie Anmerkungen auf der spec.template.metadata.annotations-Ebene Ihrer Bereitstellung hinzu.

   Beispiele

   • Java: instrumentation.opentelemetry.io/inject-java: "cr1"
   • Node.js: instrumentation.opentelemetry.io/inject-nodejs: "cr1"

   Die Anmerkungsplatzierung sollte wie folgt aussehen.

   apiVersion: apps/v1
   kind: Deployment
   ...
   spec:
     template:
       metadata:
         annotations:
           instrumentation.opentelemetry.io/inject-nodejs: "cr1"
   

Integration im gemischten Modus

Verwenden Sie den gemischten Modus, wenn die meisten Bereitstellungen eine Standardkonfiguration verwenden und einige Bereitstellungen unterschiedliche Konfigurationen verwenden müssen.

1. Implementieren Sie namespaceweites Onboarding , um die Standardkonfiguration zu definieren.
2. Erstellen Sie Onboardingkonfigurationen pro Bereitstellung , die die Standardkonfiguration für bestimmte Ressourcen außer Kraft setzen.

Bereitstellung neu starten

Führen Sie den folgenden Befehl aus, nachdem alle benutzerdefinierten Ressourcen erstellt wurden und Bereitstellungen optional kommentiert werden.

kubectl rollout restart deployment <deployment-name> -n mynamespace1

Dieser Befehl bewirkt, dass die automatische Instrumentierung wirksam wird und Application Insights aktiviert wird. Sie können überprüfen, ob Application Insights aktiviert ist, indem Sie Datenverkehr generieren und zu Ihrer Ressource navigieren. Ihre App wird als Cloudrolle in Application Insights-Erfahrungen dargestellt. Sie können alle Application Insights-Erfahrungen außer Livemetriken und Application Insights Code Analysis-Features verwenden. Erfahren Sie mehr über die verfügbaren Application Insights-Erfahrungen hier.

Autoinstrumentierung für AKS entfernen

Stellen Sie sicher, dass keine instrumentierten Bereitstellungen vorhanden sind. Um die Instrumentierung einer Bereitstellung aufzuheben, entfernen Sie die zugehörige benutzerdefinierte Instrumentierungsressource und führen Sie kubectl rollout restart auf der Bereitstellung aus. Führen Sie als Nächstes den folgenden Befehl aus.

az aks update --resource-group={resource_group} --name={cluster_name} --disable-azure-monitor-app-monitoring 

Anmerkungen

Deaktivieren der automatischen Instrumentierung

Mit den folgenden Anmerkungen wird die automatische Instrumentierung für die angegebene Sprache deaktiviert.

• Java: instrumentation.opentelemetry.io/inject-java

• Node.js: instrumentation.opentelemetry.io/inject-nodejs

  instrumentation.opentelemetry.io/inject-java: "false"
  

So aktivieren Sie die automatische Instrumentierung nach dem Deaktivieren wieder.

instrumentation.opentelemetry.io/inject-java: "true"

Die Anmerkungsplatzierung sollte wie folgt aussehen.

apiVersion: apps/v1
kind: Deployment
...
spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-java: "false"

Aktivieren von Protokollen in Application Insights

Sie können sich für das Sammeln von Protokollen in Application Insights als Ergänzung oder Ersatz für Container Insights-Protokolle entscheiden.

Durch das Aktivieren von Protokollen in Application Insights werden korrelierte Protokolle bereitgestellt, sodass Benutzer verteilte Ablaufverfolgungen problemlos zusammen mit ihren verwandten Protokollen anzeigen können. Darüber hinaus schreiben einige Microservices keine Protokolle in die Konsole, sodass Container Insights sie nicht sammeln kann und nur die Application Insights-Instrumentierung diese Protokolle erfasst.

Umgekehrt ist Application Insights möglicherweise nicht in der Lage, alle Microservices zu instrumentieren. Beispiel: Solche, die NGINX oder nicht unterstützte Sprachen verwenden. Benutzende verlassen sich bei solchen Microservices möglicherweise lieber nur auf Container Insights-Protokolle.

Sie können auch beide Quellen für Protokolle aktivieren, wenn Sie über mehrere Observability-Teams wie Infrastrukturingenieure mit Container Insights und Entwicklern mit Application Insights verfügen.

Überprüfen Sie die Konsolenprotokollierungskonfigurationen im Code Ihrer Anwendung, um zu bestimmen, ob Sie Application Insights-Protokolle, Container-Insights-Protokolle oder beides aktivieren möchten. Wenn Sie Container Insights-Protokolle deaktivieren, lesen Sie die Informationen zu Container Insights-Einstellungen.

Verwenden Sie die folgende Anmerkung, um Protokolle in Application Insights zu aktivieren.

• monitor.azure.com/enable-application-logs

monitor.azure.com/enable-application-logs: "true"

Vorbereiten eines Clusters während der Erstellung eines AKS-Clusters

AKS-Cluster können während der Clustererstellung für dieses Feature vorbereitet werden. Führen Sie den folgenden Azure CLI-Befehl aus, wenn Sie es vorziehen, den Cluster während der Erstellung vorab festzulegen. Die Anwendungsüberwachung ist nicht aktiviert, nur, weil Ihr Cluster vorbereitet ist. Sie müssen eine Anwendung bereitstellen und die Anwendung in dieses Feature integrieren.

az aks create --resource-group={resource_group} --name={cluster_name} --enable-azure-monitor-app-monitoring --generate-ssh-keys

Problembehandlung

Fehlende Telemetrie

Mit den folgenden Schritten können Sie Probleme beheben, wenn keine Daten in Ihrer arbeitsbereichsbasierten Ressource "Application Insights" angezeigt werden.

1. Vergewissern Sie sich, dass der Pod ausgeführt wird.

2. Überprüfen Sie, ob die Bereitstellung instrumentiert ist.

   Überprüfen Sie die Anmerkung monitor.azure.com/instrumentation auf der Bereitstellung selbst und dem neuesten Replikatsatz, der dazu gehört.

   Die Anmerkung sollte mit dem richtigen JSON-Code im folgenden Muster vorhanden sein: {"crName": "crName1","crResourceVersion": "20177993","platforms":["Java"]}

   Wenn die Anmerkung nicht vorhanden ist, ist die Bereitstellung nicht instrumentiert und die folgenden Schritte müssen ausgeführt werden.

   1. Bereiten Sie den Cluster vor. Weitere Informationen finden Sie unter Vorbereiten des Clusters.
   2. Vergewissern Sie sich, dass sich die benutzerdefinierte Ressource für die Instrumentierung im richtigen Namespace (gleicher Namespace wie die Bereitstellung) befindet.
   3. Vergewissern Sie sich, dass die benutzerdefinierte Ressource "Instrumentation " die richtige Verbindungszeichenfolge und -Instrumentierungsplattform enthält.
   4. Starten Sie die Bereitstellung neu. Weitere Informationen finden Sie unter Neustartbereitstellung.

   Wenn die Anmerkung vorhanden ist, wird die Bereitstellung instrumentiert, und Sie können mit dem nächsten Schritt fortfahren.

3. Suchen Sie nach Netzwerkfehlern im SDK-Protokoll, das sich im Protokollvolume des Pods befindet. /var/log/applicationinsights

   Die folgenden Fehler deuten beispielsweise auf ein Verbindungsproblem hin.

   • Ingestion endpoint could not be reached.
   • Error: getaddrinfo ENOTFOUND eastus2-3.in.applicationinsights.azure.com
   • getaddrinfo ENOTFOUND eastus2-3.in.applicationinsights.azure.com

   Wenn dieser Fehlertyp vorhanden ist, melden Sie sich beim Container an, und testen Sie die Verbindung mit dem Endpunkt.

   kubectl exec -ti customer-java-1-1234567890-abcde -- /bin/bash

   Wenn keine Verbindung hergestellt werden kann, beheben Sie das Problem mit der Netzwerkkonnektivität, z. B. einer Firewall oder einer Namensauflösung.

Testen der Konnektivität zwischen Ihrem Anwendungshost und dem Erfassungsdienst

Application Insights SDKs und -Agents senden Telemetriedaten, die als REST-Aufrufe unserer Erfassungsendpunkte erfasst werden sollen. Sie können die Konnektivität Ihres Webservers oder Anwendungshostcomputers mit den Endpunkten des Erfassungsdiensts testen, indem Sie unformatierte REST-Clients über PowerShell- oder cURL-Befehle verwenden. Weitere Informationen finden Sie unter Problembehandlung bei fehlender Anwendungstelemetrie in Azure Monitor Application Insights.

Nächste Schritte

• Informationen zum Überprüfen häufig gestellter Fragen (FAQ) finden Sie unter "Autoinstrumentation for Azure Kubernetes Service FAQ".
• Informieren Sie sich ausführlicher über Azure Monitor und Application Insights.
• Informieren Sie sich über die Möglichkeiten der Anwendungsübersicht für Ihr Unternehmen.