appinsights-instrumentation

Überblick über die appinsights-instrumentation-Skill

Die appinsights-instrumentation-Skill hilft einem Agenten dabei, Azure Application Insights-Telemetrie in eine Web-App einzubauen – mit deutlich weniger Rätselraten als bei einem generischen Observability-Prompt. Ihre eigentliche Aufgabe ist nicht einfach nur „Logs einschalten“, sondern den passenden Instrumentierungsweg für Sprache und Hosting-Modell der App zu wählen, die App Insights-Ressource zu erstellen oder anzubinden und sicherzustellen, dass die App die erforderliche APPLICATIONINSIGHTS_CONNECTION_STRING erhält.

Für wen diese Skill am besten geeignet ist

Diese Skill passt besonders gut, wenn Sie eine Web-App in Azure betreiben und praktische Unterstützung bei der Instrumentierung für Observability möchten, insbesondere für:

• ASP.NET Core-Apps, die in Azure gehostet werden
• Node.js-Apps, die in Azure gehostet werden
• Teams, die Azure App Service nutzen
• Repositories, die bereits IaC wie Bicep verwenden und Telemetrie sauber ergänzen möchten

Sie ist auch dann nützlich, wenn der Agent das Repository prüfen, Framework-Details ableiten und entweder Auto-Instrumentierung oder Code-Änderungen empfehlen soll.

Was Nutzer zuerst wirklich wissen wollen

Bevor sie appinsights-instrumentation installieren, wollen die meisten Nutzer Antworten auf diese Fragen:

• Funktioniert das mit meinem App-Stack?
• Kann ich Code-Änderungen vermeiden?
• Welche Dateien müssen bearbeitet werden?
• Wie erstelle oder finde ich den App Insights-Connection-String?
• Sollte ich Infrastructure-as-Code aktualisieren oder Einstellungen manuell patchen?

Genau diese Hürden bei der Einführung adressiert die Skill besser als eine allgemeine Anweisung wie „Observability hinzufügen“.

Wichtigster Unterschied: Auto- vs. manuelle Instrumentierung

Der größte Mehrwert der appinsights-instrumentation skill besteht darin, dass sie nicht alle Apps gleich behandelt. Sie bevorzugt ausdrücklich Auto-Instrumentierung für unterstützte Azure App Service-Szenarien und fällt nur bei Bedarf auf manuelle Code-Änderungen zurück.

Das ist wichtig, weil viele Nutzer Telemetrie lieber aktivieren möchten, ohne den Anwendungscode anzufassen – sofern Azure App Service das unterstützt.

Vom Repository sichtbar unterstützte Wege

Aus den Hinweisen im Repository ergeben sich in der Praxis diese Wege:

• Azure App Service Auto-Instrumentierung für unterstützte ASP.NET Core- und Node.js-Apps
• manuelle ASP.NET Core-Instrumentierung mit Azure.Monitor.OpenTelemetry.AspNetCore
• manuelle Node.js-Instrumentierung mit @azure/monitor-opentelemetry
• Hinweise für Python in references/PYTHON.md, auch wenn der einleitende Voraussetzungen-Text enger gefasst ist

Die wichtigste Einschränkung, die Sie vorab kennen sollten

Die Skill ist Azure-spezifisch und hosting-bewusst. Wenn Ihre App nicht in Azure läuft oder Sie ausschließlich vendor-neutrale OpenTelemetry-Architekturberatung suchen, kann sich appinsights-instrumentation for Observability zu eng anfühlen. Ihren größten Nutzen entfaltet sie, wenn der Agent Ihre App und Ihr Deployment-Modell prüfen und dann Azure Monitor-/App Insights-Konventionen korrekt anwenden kann.

So verwenden Sie die appinsights-instrumentation-Skill

Installationskontext und wo diese Skill liegt

Diese Skill stammt aus github/awesome-copilot unter skills/appinsights-instrumentation. Wenn Ihr Tooling die Installation von Skills unterstützt, nutzen Sie den üblichen Add-Skill-Ablauf für dieses Repository und rufen Sie die Skill dann auf, wenn Sie Azure App Insights einrichten möchten.

Da sich das Repository nicht um eine eigene Custom-CLI für diese Skill dreht, ist die eigentliche Installationsentscheidung weniger eine Frage des Paketmanagements, sondern eher, ob Ihr Workspace Folgendes enthält:

• App-Quellcode
• Hinweise auf Deployment oder Hosting
• IaC-Dateien wie Bicep oder Terraform
• genug Azure-Kontext, um die laufende App zu identifizieren

Geben Sie dem Agenten zuerst den richtigen Kontext

Für eine effektive appinsights-instrumentation usage sollten Sie nicht mit „add App Insights“ starten. Beginnen Sie stattdessen mit dem App-Tupel, auf das die Skill angewiesen ist:

• Sprache
• Framework
• Hosting-Ziel
• Deployment-Stil
• ob Code-Änderungen akzeptabel sind

Eine gute erste Anfrage sieht zum Beispiel so aus:

• „Instrument this ASP.NET Core app running in Azure App Service. Prefer codeless setup if supported. If not, update code and Bicep.”
• “This Node.js app is deployed to Azure App Service from this repo. Find the entry file, add Azure Monitor instrumentation, and show the env var changes needed.”
• “Inspect this repo and tell me whether auto-instrumentation is possible or whether manual App Insights instrumentation is required.”

Die wichtigste Frage, die die Skill beantwortet haben muss

Das Repository ist hier eindeutig: Der Agent sollte immer zuerst klären, wo die Anwendung gehostet wird. Dieser eine Input verändert den Plan stärker als jeder andere. Wenn Sie Hosting-Details weglassen, müssen Sie mit zusätzlichem Rückfragen rechnen.

Hilfreiche Antworten zum Hosting sind zum Beispiel:

• Azure App Service als Code-Deployment
• Azure App Service als Container
• Azure Container Apps
• nur lokale Maschine
• unbekannt, bitte aus Repo und Deployment-Dateien ableiten

Welche Repository-Dateien Sie zuerst lesen sollten

Wenn Sie die Qualität einer appinsights-instrumentation install bewerten oder einen Agenten gezielt steuern möchten, lesen Sie diese Dateien in genau dieser Reihenfolge:

1. SKILL.md
2. references/AUTO.md
3. references/ASPNETCORE.md
4. references/NODEJS.md
5. examples/appinsights.bicep
6. scripts/appinsights.ps1
7. references/PYTHON.md

Warum diese Reihenfolge sinnvoll ist:

• SKILL.md liefert die Routing-Logik
• AUTO.md zeigt, wann keine Code-Änderung nötig ist
• die sprachspezifischen Dateien zeigen die exakten Pakete und Code-Änderungen
• das Bicep-Beispiel macht Infrastrukturänderungen konkret
• das PowerShell-Skript verweist auf Azure CLI-Operationen für Connection Strings und Settings

So entscheiden Sie zwischen Auto- und manueller Instrumentierung

Nutzen Sie dieses Entscheidungsmuster:

• Wenn die App ASP.NET Core oder Node.js auf Azure App Service ist, prüfen Sie zuerst Auto-Instrumentierung.
• Wenn Auto-Instrumentierung nicht unterstützt wird, unerwünscht ist oder für Ihren Deployment-Prozess zu intransparent wirkt, wechseln Sie zu manueller Instrumentierung.
• Wenn Ihr Team Infrastruktur deklarativ verwaltet, aktualisieren Sie IaC und App-Konfiguration bevorzugt gemeinsam, statt einmalige Portal-Änderungen vorzunehmen.

Das ist einer der stärksten Praxisvorteile der appinsights-instrumentation guide: Sie vermeiden unnötigen Aufwand durch überflüssige Code-Änderungen.

Manueller ASP.NET Core-Workflow

Für ASP.NET Core verweist das Repository auf diese Schritte:

• Paket installieren: dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
• using Azure.Monitor.OpenTelemetry.AspNetCore; hinzufügen
• vor builder.Build() Folgendes ergänzen: builder.Services.AddOpenTelemetry().UseAzureMonitor();

Stellen Sie den App Insights-Connection-String anschließend über die Umgebung bereit und nicht durch beiläufiges Bearbeiten von appsettings. Dieser Hinweis ist wichtig, weil viele Teams Konfiguration versehentlich hart codieren oder lokal ablegen und sie dann im Deployment nicht sauber übernommen wird.

Manueller Node.js-Workflow

Für Node.js ist der praktische Ablauf:

• Paket installieren: npm install @azure/monitor-opentelemetry
• die Entry-Datei finden, meist über das main-Feld in package.json
• die Bibliothek möglichst weit oben einbinden:
  const { useAzureMonitor } = require("@azure/monitor-opentelemetry");
• useAzureMonitor(); aufrufen

Das Timing ist entscheidend: Laden Sie zuerst Umgebungsvariablen, rufen Sie dann useAzureMonitor() auf und laden Sie erst danach den Rest der App. Wenn die App dotenv verwendet, initialisieren Sie dotenv vor dem Azure Monitor-Setup.

Umgang mit App Insights-Ressource und Connection String

Ein häufiger Einführungsblocker ist nicht der Instrumentierungs-Code, sondern die Anbindung der Ressource. Diese Skill hilft auf beiden Ebenen:

• die Application Insights-Ressource erstellen oder referenzieren
• den Connection String abrufen
• APPLICATIONINSIGHTS_CONNECTION_STRING setzen
• diese Einstellung nach Möglichkeit in IaC dauerhaft verankern

Das Repo enthält examples/appinsights.bicep und scripts/appinsights.ps1. Das ist ein starkes Signal dafür, dass die Skill über Quellcode hinaus auf Code- und Infrastruktur-Ebene arbeiten soll, statt nur Source-Dateien zu bearbeiten.

Prompt-Muster, das bessere Ergebnisse liefert

Ein schwacher Prompt:

• „Add observability.”

Ein stärkerer Prompt:

• “Use the appinsights-instrumentation skill on this repo. First detect whether this is ASP.NET Core, Node.js, or Python and how it is hosted. Prefer Azure App Service auto-instrumentation if supported. Otherwise, make the minimum code and IaC changes needed to send telemetry to Azure Application Insights. Show the exact files to edit and explain how to set APPLICATIONINSIGHTS_CONNECTION_STRING.”

Warum das besser ist:

• es erzwingt die Erkennung des Stacks
• es codiert die Präferenz für Auto-Instrumentierung
• es fordert Änderungen auf Dateiebene an
• es enthält die naheliegende, aber oft übersehene Voraussetzung der env var

Was Sie nach der ersten Antwort prüfen sollten

Nachdem der Agent geantwortet hat, prüfen Sie diese Punkte, bevor Sie den Plan übernehmen:

• Hat er die Hosting-Umgebung identifiziert und nicht nur die Sprache?
• Hat er, wo relevant, zuerst Azure App Service Auto-Instrumentierung geprüft?
• Hat er das richtige Paket für die jeweilige Sprache genannt?
• Hat er die Initialisierung früh genug im App-Startup platziert?
• Hat er den Connection String als Umgebungsvariable behandelt?
• Hat er IaC-Änderungen vorgeschlagen, wenn das Repo bereits IaC nutzt?

Wenn diese Punkte fehlen, ist die Ausgabe wahrscheinlich generisch und nicht wirklich durch die Skill geführt.

FAQ zur appinsights-instrumentation-Skill

Ist appinsights-instrumentation besser als ein normaler Prompt?

In der Regel ja, wenn Ihr Ziel die Einrichtung von Azure App Insights in einem echten Repository ist. Ein generischer Prompt vergisst oft die hosting-abhängige Entscheidung, die Auto-Instrumentierungsoption oder den exakten Workflow rund um den Connection String. Die appinsights-instrumentation skill ist besser, wenn Sie weniger Azure-spezifische Lücken in der Antwort möchten.

Ist diese Skill anfängerfreundlich?

Eingeschränkt. Sie ist praxisnah, setzt aber voraus, dass Sie grundlegende Fragen zum Deployment beantworten können oder dem Agenten erlauben, das Repository zu prüfen. Einsteiger können sie trotzdem gut nutzen, wenn sie Folgendes angeben:

• App-Sprache/Framework
• Azure-Hosting-Typ
• ob App Service verwendet wird
• ob Infrastruktur als Code verwaltet wird

Ohne diese Angaben braucht die Skill erst Rückfragen, bevor sie einen verlässlichen Plan liefern kann.

Funktioniert sie nur für Azure App Service?

Nein, aber bei Azure App Service zeigt sich ihre wertvollste Entscheidungslogik, weil dort Auto-Instrumentierung verfügbar sein kann. Außerhalb dieses Pfads hilft die Skill weiterhin bei manueller Instrumentierung, Ressourcenerstellung und der Konfiguration des Connection Strings.

Unterstützt sie Python?

Das Repo enthält references/PYTHON.md, also gibt es Hinweise für Python. Der einleitende Voraussetzungen-Text auf oberster Ebene legt den Schwerpunkt jedoch auf ASP.NET Core und Node.js. Betrachten Sie Python deshalb als nützlichen Referenzpfad, prüfen Sie die Eignung aber immer gegen Ihr tatsächliches Hosting-Modell, bevor Sie es als Hauptszenario ansetzen.

Wann sollte ich appinsights-instrumentation nicht verwenden?

Lassen Sie appinsights-instrumentation aus, wenn:

• Ihre App nicht in Azure gehostet wird und Sie cloud-agnostische Observability-Hinweise suchen
• Sie tiefgehendes Custom-Tracing-Design statt einer initialen App Insights-Aktivierung benötigen
• Sie bereits ausgereifte OpenTelemetry-Instrumentierung haben und nur kleine Anpassungen brauchen
• Ihre Aufgabe vor allem Dashboarding, Alerting oder KQL betrifft, nicht Instrumentierung

Erstellt die Skill Azure-Ressourcen für mich?

Sie kann die Einrichtung der Ressource anleiten und verweist auf Infrastrukturbeispiele wie examples/appinsights.bicep, aber ob Ressourcen tatsächlich erstellt werden, hängt von den Berechtigungen Ihres Agenten und Ihrem Workflow ab. In der Praxis eignet sie sich am besten dafür, die exakten IaC- oder CLI-Schritte zu erzeugen, die Ihre Umgebung zulässt.

So verbessern Sie die appinsights-instrumentation-Skill

Geben Sie der Skill ein vollständiges Deployment-Bild

Der schnellste Weg, die appinsights-instrumentation usage zu verbessern, ist ein vollständiges Bild des Deployments direkt zu Beginn:

• Quellsprache und Framework
• Azure-Hosting-Service
• Deployment-Methode
• vorhandene Infra-as-Code-Dateien
• ob Portal-Änderungen erlaubt sind

So reduzieren Sie den häufigsten Fehlmodus der Skill: einen technisch korrekten Weg zu wählen, der aber nicht zu Ihrem Betriebsmodell passt.

Lassen Sie zuerst entscheiden, dann erst bearbeiten

Ein hochwertiger Workflow sieht so aus:

1. Bitten Sie den Agenten, App und Hosting zu klassifizieren.
2. Fragen Sie, ob Auto-Instrumentierung unterstützt wird.
3. Erst danach verlangen Sie Dateiänderungen oder IaC-Patches.

Das verbessert die Ausgabe, weil der zentrale Verzweigungspunkt in der Skill architektonisch ist und nicht nur syntaktisch.

Weisen Sie den Agenten ausdrücklich auf die richtigen Dateien hin

Wenn das Repo groß ist, sagen Sie dem Agenten explizit, wo er schauen soll:

• Program.cs für ASP.NET Core
• package.json und die Entry-Datei für Node.js
• Bicep- oder Terraform-Dateien für die Infra-Konfiguration
• Deployment-Manifeste oder Workflows, aus denen das Hosting hervorgeht

So vermeiden Sie oberflächliche Änderungen in der falschen Startup-Datei oder das Übersehen der richtigen IaC-Stelle für die env var.

Fordern Sie Datei-Diffs statt allgemeiner Hinweise an

Für bessere Ergebnisse mit der appinsights-instrumentation guide sollten Sie konkret anfordern:

• exakte Dateien, die geändert werden müssen
• exakte Paket-Installationsbefehle
• exakte Platzierung der Startup-Initialisierung
• exakten Einfügepunkt für die Umgebungsvariable
• exakte IaC-Ergänzungen für die App Insights-Ressource und die App-Settings

Damit wird aus einer beratenden Beschreibung ein umsetzbarer Implementierungsplan.

Häufige Fehlerbilder, auf die Sie achten sollten

Die wahrscheinlichsten Qualitätsprobleme sind:

• der Hosting-Check wird übersprungen
• die Auto-Instrumentierungsoption fehlt
• Telemetrie wird zu spät im App-Startup initialisiert
• der Connection String wird an der falschen Stelle gesetzt
• Code wird aktualisiert, aber die Deployment-Konfiguration vergessen
• lokale App-Settings werden als Quelle der Wahrheit behandelt, obwohl die App in Azure läuft

Genau an diesen Stellen bringt eine zweite Prüfung den größten Mehrwert.

Mit einem stärkeren Follow-up-Prompt bessere Ergebnisse erzielen

Wenn die erste Antwort zu generisch ist, verwenden Sie einen Korrektur-Prompt wie:

• “Re-run appinsights-instrumentation with hosting-aware decisions. Confirm whether this Azure App Service app qualifies for auto-instrumentation before proposing code changes.”
• “Revise this plan to include the exact file edits, package command, and IaC changes for APPLICATIONINSIGHTS_CONNECTION_STRING.”
• “Compare manual instrumentation vs auto-instrumentation for this repo and recommend one based on the deployment files present.”

Validieren Sie Observability, nicht nur die Kompilierung

Ein gutes Ergebnis liegt nicht nur dann vor, wenn die App baut. Bitten Sie den Agenten festzulegen, wie sich bestätigen lässt, dass Telemetrie tatsächlich fließt:

• woher der Connection String bezogen wird
• welcher Deployment-Schritt die Einstellung anwendet
• welche Request- oder Startup-Aktivität Telemetrie erzeugen sollte
• welches Azure-seitige Signal Sie nach dem Deployment erwarten sollten

So wird appinsights-instrumentation for Observability auch in Produktion nützlicher, wo stille Fehlkonfigurationen häufig sind.

Der beste Weg, appinsights-instrumentation in der Praxis zu erweitern

Wenn Sie aus dieser Skill langfristig mehr Nutzen ziehen möchten, erweitern Sie Ihr eigenes Prompting-Muster darum:

• immer Hosting-Details angeben
• immer einen Vergleich Auto vs. manuell anfordern
• immer Infrastruktur- und Code-Änderungen gemeinsam anfordern
• immer eine Checkliste zur Verifikation nach dem Deployment verlangen

Dieses Muster passt eng zur Struktur des Repositories und liefert deutlich bessere Ergebnisse als eine Ein-Zeilen-Anfrage.