Freigeben über

Stichprobenüberschreibungen – Azure Monitor Application Insights für Java

  • Artikel

Hinweis

Die Funktion für Stichprobenüberschreibungen ist allgemein verfügbar, beginnend ab Version 3.5.0.

Mithilfe von Stichprobenüberschreibungen können Sie den Standardprozentsatz der Stichprobenentnahme überschreiben. Hier einige Beispiele:

  • Legen Sie den Prozentsatz der Stichprobenentnahme für überflüssige Integritätsprüfungen auf 0 (oder einen kleinen Wert) fest.
  • Legen Sie den Prozentsatz der Stichprobenentnahme für überflüssige Abhängigkeitsaufrufe auf 0 (oder einen kleinen Wert) fest.
  • Legen Sie den Prozentsatz der Stichprobenentnahme für einen wichtigen Anforderungstyp (z. B. /login) auf 100 fest, auch wenn die Standardstichprobenentnahme auf einen niedrigeren Wert festgelegt ist.

Terminologie

Bevor wir uns mit Stichprobenüberschreibungen befassen, sollten wir zunächst die Benennung span erläutern. Ein span ist eine allgemeine Bezeichnung für Folgendes:

  • Eine eingehende Anforderung
  • Eine ausgehende Abhängigkeit (z. B. ein Remoteaufruf eines anderen Diensts)
  • Eine In-Process-Abhängigkeit (z. B. Vorgänge, die von Unterkomponenten des Diensts durchgeführt werden)

Bei Stichprobenüberschreibungen sind die folgenden span-Komponenten wichtig:

  • Attribute

Die span-Attribute stehen sowohl für die standardmäßigen als auch die benutzerdefinierten Eigenschaften einer bestimmten Anforderung oder Abhängigkeit.

Erste Schritte

Zunächst erstellen Sie eine Konfigurationsdatei namens applicationinsights.json. Speichern Sie diese im gleichen Verzeichnis, in dem sich auch applicationinsights-agent-*.jar befindet. Verwenden Sie hierfür die folgende Vorlage.

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10,
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 0
      },
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 100
      }
    ]
  }
}

Funktionsweise

telemetryType (telemetryKind in Application Insights 3.4.0) muss entweder request, dependency, trace (log) oder exception sein.

Wenn ein span-Element gestartet wird, werden der Typ des span-Elements und die im span-Element vorhandenen Attribute verwendet, um zu überprüfen, ob eine der Stichprobenüberschreibungen übereinstimmt.

Übereinstimmungen können entweder strict oder regexp sein. Übereinstimmungen bei regulären Ausdrücken werden für den gesamten Attributwert ausgeführt. Wenn Sie also einen Wert abgleichen möchten, der an einer beliebigen Stelle abc enthält, müssen Sie .*abc.* verwenden. Eine Stichprobenüberschreibung kann mehrere Attributkriterien angeben. In diesem Fall müssen alle übereinstimmen, damit die Stichprobenüberschreibung übereinstimmt.

Wenn eine der Stichprobenüberschreibungen übereinstimmt, wird die Stichprobenentnahme in Prozent verwendet, um zu entscheiden, ob vom span-Element eine Stichprobe entnommen werden soll.

Nur die erste übereinstimmende Stichprobenüberschreibung wird verwendet.

Wenn keine Stichprobenüberschreibungen übereinstimmen:

  • Wenn es sich um den ersten Bereich in der Ablaufverfolgung handelt, wird die Konfiguration der obersten Ebene verwendet.
  • Wenn es sich nicht um den ersten Bereich in der Ablaufverfolgung handelt, wird die übergeordnete Stichprobenentscheidung verwendet.

Für Sampling verfügbare Span-Attribute

OpenTelemetry-Span-Attribute werden automatisch gesammelt und basieren auf den OpenTelemetry-Semantikkonventionen.

Sie können auch programmgesteuert Span-Attribute hinzufügen und zum Sampling verwenden.

Hinweis

Um die genaue Menge der von Application Insights Java für Ihre Anwendung erfassten Attribute zu sehen, legen Sie die Selbstdiagnoseebene auf „Debuggen“ fest, und suchen Sie nach Debugmeldungen, die mit dem Text „exporting span“ beginnen.

Hinweis

Nur Attribute, die zu Beginn des span-Attributs festgelegt wurden, stehen für die Stichprobenentnahme zur Verfügung. Daher können Attribute wie http.response.status_code oder Anforderungsdauer, die später erfasst werden, durch die OpenTelemetry Java-Erweiterung gefiltert werden. Hier ist eine Beispielerweiterung, die Spans basierend auf der Anforderungsdauer filtert.

Hinweis

Die Attribute, die mit einem Telemetrieprozessor hinzugefügt wurden, sind für das Sampling nicht verfügbar.

Anwendungsfälle

Unterdrücken der Erfassung von Telemetriedaten für Integritätsprüfungen

Mit diesem Beispiel wird die Erfassung von Telemetriedaten für alle Anforderungen an /health-checks unterdrückt.

Zudem wird damit auch die Erfassung von allen nachgelagerten span-Elementen (Abhängigkeiten) unterdrückt, die normalerweise unter /health-checks erfasst werden.

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/health-check",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

Unterdrücken der Erfassung von Telemetriedaten für einen störende Abhängigkeitsaufruf

Mit diesem Beispiel wird die Erfassung von Telemetriedaten für alle GET my-noisy-key-redis-Aufrufe unterdrückt.

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "db.system",
            "value": "redis",
            "matchType": "strict"
          },
          {
            "key": "db.statement",
            "value": "GET my-noisy-key",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

100%-iges Erfassen von Telemetriedaten für einen wichtigen Anforderungstyp

Mit diesem Beispiel werden für /login Telemetriedaten zu 100 % erfasst.

Da nachgelagerte Bereiche (Abhängigkeiten) die Sampling-Entscheidung des übergeordneten Bereichs respektieren (sofern keine Sampling-Übersteuerung für diesen nachgelagerten Bereich vorliegt), werden sie auch für alle „/login“-Anfragen gesammelt.

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10
  },
  "sampling": {
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/login",
            "matchType": "strict"
          }
        ],
        "percentage": 100
      }
    ]
  }
}

Bereitstellen von Span-Attributen zum Unterdrücken von SQL-Abhängigkeitsaufrufen

In diesem Beispiel wird die Erfahrung der Suche nach verfügbaren Attributen zum Unterdrücken lauter SQL-Aufrufe erläutert. Die folgende Abfrage zeigt die verschiedenen SQL-Aufrufe und die Anzahl der zugeordneten Datensätze in den letzten 30 Tagen:

dependencies
| where timestamp > ago(30d)
| where name == 'SQL: DB Query'
| summarize count() by name, operation_Name, data
| sort by count_ desc

SQL: DB Query    POST /Order             DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    36712549    
SQL: DB Query    POST /Receipt           DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    2220248    
SQL: DB Query    POST /CheckOutForm      DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    554074    
SQL: DB Query    GET /ClientInfo         DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    37064

Aus den obigen Ergebnissen geht hervor, dass alle Vorgänge den gleichen Wert im Feld data aufweisen: DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;. Diese Datensätze sind aufgrund ihrer Gemeinsamkeit ein guter Kandidat für eine Stichprobenüberschreibung.

Durch Festlegen der Selbstdiagnose auf Debuggen werden die folgenden Protokolleinträge in der Ausgabe sichtbar:

2023-10-26 15:48:25.407-04:00 DEBUG c.m.a.a.i.exporter.AgentSpanExporter - exporting span: SpanData{spanContext=ImmutableSpanContext...

Der interessante Bereich dieser Protokolle ist der Abschnitt „Attribute”:

{
  "attributes": {
    "data": {
      "thread.name": "DefaultDatabaseBroadcastTransport: MessageReader thread",
      "thread.id": 96,
      "db.connection_string": "apache:",
      "db.statement": "DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;",
      "db.system": "other_sql",
      "applicationinsights.internal.item_count": 1
    }
  }
}

Mit dieser Ausgabe können Sie eine Stichprobenüberschreibung wie die unten aufgeführt konfigurieren, die unsere lauten SQL-Aufrufe filtert:

{
  "connectionString": "...",
  "preview": {
    "sampling": {
      "overrides": [
        {
          "telemetryType": "dependency",
          "attributes": [
            {
              "key": "db.statement",
              "value": "DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;",
              "matchType": "strict"
            }
          ],
          "percentage": 0
        }
      ]
    }
  }
}

Nachdem die Änderungen angewendet wurden, können wir mit der folgenden Abfrage ermitteln, wie lange diese Abhängigkeiten zuletzt in Application Insights erfasst wurden:

dependencies
| where timestamp > ago(30d)
| where data contains 'DECLARE @MyVar'
| summarize max(timestamp) by data
| sort by max_timestamp desc

DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    11/13/2023 8:52:41 PM

Unterdrücken des Sammelns von Telemetriedaten für das Protokoll

Mit SL4J können Sie Protokollattribute hinzufügen:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;

public class MdcClass {

  private static final Logger logger = LoggerFactory.getLogger(MdcClass.class);

  void method {
	
    MDC.put("key", "value");
    try {
       logger.info(...); // Application log to remove
    finally {
       MDC.remove("key"); // In a finally block in case an exception happens with logger.info
    }
	
  }
  
}

Anschließend können Sie das Protokoll mit dem hinzugefügten Attribut entfernen:

{
  "sampling": {
    "overrides": [
      {
        "telemetryType": "trace",
        "percentage": 0,
        "attributes": [
          {
            "key": "key",
            "value": "value",
            "matchType": "strict"
          }
        ]
      }
    ]
  }
}

Unterdrücken des Sammelns von Telemetrie für eine Java-Methode

Wir werden ein Span-Attribut zu einer Java-Methode hinzufügen und dieses Span-Attribut mit Samplingüberschreibung entfernen.

Fügen wir zunächst die opentelemetry-instrumentation-annotations-Abhängigkeit hinzu:

    <dependency>
      <groupId>io.opentelemetry.instrumentation</groupId>
      <artifactId>opentelemetry-instrumentation-annotations</artifactId>
    </dependency>

Wir können nun die WithSpan-Anmerkung zu einer Java-Methode hinzufügen, die SQL-Anforderungen ausführt:

package org.springframework.samples.petclinic.vet;

@Controller
class VetController {

	private final VetRepository vetRepository;

	public VetController(VetRepository vetRepository) {
		this.vetRepository = vetRepository;
	}

	@GetMapping("/vets.html")
	public String showVetList(@RequestParam(defaultValue = "1") int page, Model model) {
		Vets vets = new Vets();
		Page<Vet> paginated = findPaginated(page);
		vets.getVetList().addAll(paginated.toList());
		return addPaginationModel(page, paginated, model);
	}

	@WithSpan
	private Page<Vet> findPaginated(int page) {
		int pageSize = 5;
		Pageable pageable = PageRequest.of(page - 1, pageSize);
		return vetRepository.findAll(pageable);  // Execution of SQL requests
	}

Mit der folgenden Samplingüberschreibungskonfiguration können Sie das von der WithSpan-Anmerkung hinzugefügte Span-Attribut entfernen:

  "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "code.function",
            "value": "findPaginated",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }

Der Attributwert ist der Name der Java-Methode.

Diese Konfiguration entfernt alle Telemetriedaten, die aus der findPaginated-Methode erstellt wurden. SQL-Abhängigkeiten werden für die SQL-Ausführungen, die aus der findPaginated-Methode stammen, nicht erstellt.

Die folgende Konfiguration entfernt alle Telemetriedaten, die aus Methoden der VetController-Klasse mit der WithSpan-Anmerkung ausgegeben werden:

 "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "code.namespace",
            "value": "org.springframework.samples.petclinic.vet.VetController",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }

Problembehandlung

Wenn Sie regexp verwenden und die Stichprobenüberschreibung nicht funktioniert, versuchen Sie es mit dem regulären Ausdruck .*. Wenn die Stichprobenentnahme jetzt funktioniert, bedeutet dies, dass ein Problem mit dem ersten regulären Ausdruck vorliegt. Lesen Sie diese Dokumentation zu regulären Ausdrücken.

Wenn es mit .* nicht funktioniert, haben Sie möglicherweise ein Syntaxproblem in Ihrem application-insights.json file. Sehen Sie sich die Application Insights-Protokolle an, und überprüfen Sie, ob Warnmeldungen angezeigt werden.