Span-Anreicherung

Informationen zur Span-Anreicherung

Bieten Sie Benutzern die Möglichkeit, Spans mit benutzerdefinierten Attributen anzureichern oder Daten aus vorhandenen Attributen zu ändern, zu kombinieren oder zu entfernen.
Anreicherungsvorgänge werden über Span-Regeln definiert, die eine oder mehrere Aktionen enthalten, die in einer bestimmten Reihenfolge auf einen bestimmten Zeitraum angewendet werden sollen.
Es gibt zwei Arten von Span-Regeln: "Benutzerdefiniert" und "Von Oracle bereitgestellt".
Span-Anreicherung wird auf APM-Domainebene konfiguriert.

Beispiele für Span-Anreicherung:

Entfernung von personenbezogenen Daten (PII) aus Spans.
Kombinieren Sie Daten aus mehreren Attributen in einem einzelnen Attribut.
Extrahieren Sie Daten aus einem Attribut. Beispiel: Ein Teilpfad aus einer längeren URL.
Wenden Sie mathematische Funktionen auf Daten an. Beispiel: Konvertieren Sie eine Einheit von Sekunden in Millisekunden.
Ordnen Sie einem neuen Wert einen Attributwert zu. Beispiel: Ordnen Sie den Wert "1" der Farbe "blau", dem Wert "2" der Farbe "rot" zu.
Numerische Werte in Buckets aufteilen Beispiel: Ein Temperaturwertbereich, der in "kalte", "warme" und "heiße" Buckets zugeordnet ist.

Themen:

Span-Anreicherung - Verwendung

Span-Anreicherung wird über Span-Regeln konfiguriert, die auf einem Span arbeiten und zum Ändern der Span-Attribute verwendet werden. Die Toolbox "Span-Regeln" enthält eine Vielzahl von Aktionen, die als Teil einer Regel ausgeführt werden können.

Span-Regeln werden in Gruppen verwaltet. Eine Gruppe ist eine Sammlung von Regeln, die in einer bestimmten Reihenfolge angewendet werden. Jede Regel kann eine oder mehrere Aktionen auf einen Span anwenden, und die Ausgabe jeder Regel kann als Eingabe für Nachfassregeln verwendet werden. Regelgruppen erfordern einen Span-Filter, mit dem die Bereiche ausgewählt werden, auf denen die Regeln angewendet werden sollen.

Es können mehrere Gruppen definiert werden. Dies ist nützlich, wenn Sie verschiedene Regeltypen für verschiedene Spans-Typen verwalten müssen, da logische Entitys mit Funktionen erstellt werden, die für einen bestimmten Zweck entwickelt wurden. Dadurch wird die Gesamtkomplexität Ihres Regelsets reduziert.

Wenn für mehrere Gruppen Span-Filter eingerichtet sind, die demselben Span entsprechen, wenden alle ihre Regeln auf diesen Span an. Die Reihenfolge, in der dies durchgeführt wird, wird durch die alphabetische Reihenfolge der Gruppennamen bestimmt. Beachten Sie dies, wenn Sie Ihre Gruppen benennen oder umbenennen. Oracle empfiehlt, den Namen eine Nummer voranzustellen, damit die Gruppennamen nicht alphabetisch sortiert werden. Beispiel: "1. Standortdaten entfernen", "2. Längeneinheiten konvertieren".

Beachten Sie, dass wenn mehrere Gruppen auf demselben Span arbeiten, bedeutet dies, dass jede Gruppe mit einer Version des Span arbeitet, die möglicherweise von einer vorherigen Gruppe in der Kette geändert wurde. Dies kann nützlich sein, da Sie Regeln in Folgegruppen schreiben können, die auf Änderungen basieren, die von vorherigen Gruppen erstellt wurden. Andererseits kann es auch dazu führen, dass Nachfassregeln nicht erfolgreich verlaufen, wenn ein Attribut, auf das eine Regel basiert, von einer vorherigen Gruppe entfernt oder geändert wird.

Hinweis

Dies ist nur wichtig, wenn ein Span mit mehreren Gruppen übereinstimmt.

Wenn Ihre Gruppen eindeutig unzusammenhängende Filter haben, wird eine Spanne immer von einer einzelnen Gruppe geändert, und die obigen Überlegungen sind irrelevant.

Attribute in Span-Ereignissen

Spans können eine Liste von Ereignissen enthalten, die auch als Logmeldungen bezeichnet werden. Diese werden normalerweise verwendet, um Informationen über wichtige Momente während der Ausführung des Spans zu speichern. Beispiel: Wenn ein Span eine Datenbankabfrage beschreibt, können Ereignisse generiert werden, um den Zeitpunkt zu kennzeichnen, zu dem die Verbindung geöffnet war, dann wann die Abfrageanforderung tatsächlich weitergeleitet wurde und wann die Antwort empfangen wurde.

Ein Ereignis wird durch name, timestamp und eine Gruppe von attributes (Schlüssel/Wert-Paare) identifiziert, die weiteren Kontext für die aufgezeichneten Informationen bereitstellen.

Alle unten beschriebenen Span-Regelaktionen, für die ein Attribut als Eingabe oder Ausgabe erforderlich ist, können auch auf die Attribute einzelner Ereignisse angewendet werden. Da die Ereignisattribute von regulären Span-Attributen unabhängig sind, müssen Sie die folgende event reference-Syntax verwenden, um das richtige Ereignisattribut zu identifizieren:

event['NameOfEvent']:'NameOfAttribute'.

Hinweis

Ereignisattribute können nicht als Span-Filter verwendet werden.

Span-Regeln erstellen und verwalten

Je nach Reportinganforderungen können Sie Span-Regeln erstellen und verwalten.

So erstellen Sie Span-Regeln für eine bestimmte APM-Domain:

Gehen Sie zur Seite APM-Domains, und klicken Sie auf die gewünschte APM-Domain.

Die Seite Domaindetails wird angezeigt.
Gehen Sie zu Ressourcen unten links, und klicken Sie auf Span-Anreicherung.

Der Bereich Span-Anreicherung wird angezeigt.
Klicken Sie auf Gruppe erstellen, um eine neue Span-Regelgruppe zu erstellen.
Der Bereich Span-Regelgruppe erstellen wird angezeigt.
- Geben Sie den Namen der neuen Gruppe ein.
- Wählen Sie einen Span-Filter für diese Gruppe aus.
- Geben Sie optional eine Beschreibung für die neue Gruppe an.
- Klicken Sie auf Weiter, um mit dem Bereich Regelaktionen fortzufahren, um der neuen Gruppe je nach Span-Regeltyp Span-Regeln hinzuzufügen: Benutzerdefinierte Span-Regel oder Von Oracle bereitgestellte Span-Regel.
- Geben Sie den Regelnamen ein.
- Wählen Sie optional einen Regelspannenfilter aus, um den Geltungsbereich des Regelvorgangs weiter einzugrenzen.
  
  Hinweis
  
  Span-Filter werden separat erstellt. Weitere Informationen finden Sie unter Span-Filter.
- Geben Sie optional eine Regelbeschreibung an.
- Wählen Sie einen Span-Regeltyp aus.
  - Wenn Sie Von Oracle bereitgestellte Span-Regel auswählen, wird Ihnen eine Liste mit Regeln zur Auswahl angeboten.
    
    Die Regeln wurden bereits von Oracle erstellt, um die Benutzer zu unterstützen. Die Liste enthält Folgendes:
    Fügt die Client-IP-Adresse zu einem Span hinzu.
    Die Client-IP-Adresse wird einem Span als Attribut mit dem Namen ClientIP hinzugefügt.
    
    EBS-Suite.
    Sie stellt die E-Business Suite-Vorlage bereit.
    
    OpenTelemetry in APM-Benennungskonvertierung.
    Er konvertiert Span-Attributnamen von der Benennungskonvention OpenTelemetry in die APM-Benennungskonvention. Informationen zur Verwendung von OpenTelemetry mit APM finden Sie unter Datenquellen OpenTelemetry konfigurieren.
    Klicken Sie auf eine Regel aus der Liste, um sie der Gruppe hinzuzufügen.
    
    Hinweis
    
    Sie können keine Aktionen konfigurieren, da sie intern von der Regel selbst verwaltet werden. Außerdem können Sie nicht sehen, was die Aktionen für eine von Oracle bereitgestellte Regel sind.
  - Wenn Sie eine benutzerdefinierte Span-Regel erstellen möchten, müssen Sie mindestens eine Aktion definieren. (Eine Regel enthält immer mindestens eine Aktion).
    Bevor Sie eine Aktion auswählen können, müssen Sie ein Aktionsziel und einen Aktionstyp auswählen.
    
    Das Aktionsziel gibt den Teil des Span an, auf dem die Aktion ausgeführt wird. Es sind zwei Ziele verfügbar:
    
    Entity: Richten Sie den gesamten Span als Ziel ein.
    
    Attribut: Richten Sie ein einzelnes Attribut als Ziel ein.
    
    Der Aktionstyp gibt den Typ an. Sie wird hauptsächlich zur logischen Gruppierung von Aktionen verwendet. Beispiel: Zeichenfolge oder numerisch.
    
    Wählen Sie jetzt die entsprechende Aktion in der Dropdown-Liste Verfügbare Aktionen aus.
    Da Aktionen verschiedene Kontexte aufweisen, ändert sich das Fenster entsprechend jeder Aktionsart. Weitere Details zu Aktionen finden Sie unter Mit Aktionen arbeiten.
    Weitere Informationen zu den verfügbaren Aktionen für Aktionsziel und Aktionstyp finden Sie unter Verfügbare Aktionen.
    Verwenden Sie die Schaltfläche Aktion hinzufügen, um der Regel weitere Aktionen hinzuzufügen.
    
    Verwenden Sie das Aktionspunktmenü oben rechts in jeder Aktion, um es in der Regelreihenfolge nach oben oder unten zu verschieben, oder löschen Sie eine Aktion.

Mit Aktionen arbeiten

Bei Aktionen mit dem Ziel Attribut müssen Sie immer den Namen des Attributs angeben, dessen Wert als Eingabe für die Aktion verwendet wird. Das Konfigurationsfenster für jede Aktion bezieht sich auf Input Attribute.

Bei einigen Aktionen müssen Sie auch den Namen eines Attributs angeben, in dem das Ergebnis des Vorgangs gespeichert werden soll. Dies wird als Output Attribute bezeichnet. Wenn das Attribut auf dem Span vorhanden ist, wird jeder Wert, den es zu diesem Zeitpunkt hat, durch das Ergebnis der Aktion überschrieben. Wenn sie noch nicht vorhanden ist, wird sie dem Span mit dem neuen Wert hinzugefügt. Mit diesem Mechanismus können Sie den Wert jedes Attributs auf dem Span (auch das Eingabeattribut) durch das Ergebnis des Vorgangs ersetzen.

Dadurch können Sie die Ergebnisse jeder Aktion einer Folgeaktion (oder sogar einer Regel innerhalb derselben Regelgruppe) zuführen.

Sie können damit auch Werte in temporären Attributen speichern, die von Nachfassregeln oder -aktionen verwendet werden können. Sie müssen sie jedoch nicht als Teil des Endergebnisses beibehalten. Achten Sie darauf, die temporären Attribute als letzten Schritt mit der Aktion Attribut entfernen zu entfernen.

Hinweis

Eine Block-Aktion lehnt den Span ab und Sie können ihn später nicht mehr verwenden, selbst von einer anderen Regelgruppe.

Verfügbare Aktionen

Aktionsziel	Vorgangstyp	Verfügbare Aktionen
Entität	Passthrough Aktionen, die steuern, ob der gesamte Span durchlaufen oder blockiert wird. Gesperrte Spans werden von der Verarbeitungspipeline abgelehnt. Abgelehnte Spans werden nicht mehr von APM verarbeitet wird an keiner Stelle gespeichert und können später in anderen APM-Tools oder Dashboards nicht mehr angezeigt werden.	Blockieren: Blockiert diesen Span ohne Bedingungen. Alle Nachfassaktionen und -regeln werden nicht auf sie angewendet, und der Span ist nicht mehr in APM-OCI-Tools und -Produkten verfügbar. Beispiel: Beispiele (akzeptiert) erstrecken sich basierend auf einem Beispielprozentsatz. Beispiel: Ein Beispielprozentsatz von 25% nimmt (zufällig) 25% aller Spans an und blockiert den Rest. Hier blockierte Spans werden genauso behandelt wie Spans, die von der Blockieren-Aktion blockiert wurden.
Attribut	Zeichenfolge Aktionen, die verschiedene Vorgänge für den Wert des Attributs zulassen, das eine Zeichenfolge ist. Beispiel: Wenn Sie die Groß-/Kleinschreibung ändern, einen Wert ersetzen oder einen Teil der Zeichenfolge extrahieren.	Anhängen: Hängt mit einer optionalen Trennzeichenfolge eine statische Zeichenfolge an den Wert eines Attributs an. Verketten: Verkettet zwei Attributwerte. Es kann eine optionale Trennzeichenzeichenfolge angegeben werden, mit der die Werte verknüpft werden. Das Ergebnis wird als neues Attribut zurückgegeben. Extrahieren: Extrahiert einen Teil des Attributwertes basierend auf einem regulären Ausdruck. Das Ergebnis wird als neues Attribut zurückgegeben. Der reguläre Ausdruck muss einen Erfassungsgruppenoperator enthalten, der den Teil der zu erfassenden Zeichenfolge identifiziert. Wenn der reguläre Ausdruck nicht übereinstimmt oder keine Capture-Gruppe vorhanden ist, erzeugt die Aktion keine Ausgabe. Sie können optional einen Fallback-Wert angeben, der als Ausgabe der Aktion verwendet wird, falls der Extrakt selbst kein Ergebnis erzeugt hat. Kleinschreibung: Konvertiert den Wert eines Attributs in Kleinbuchstaben. Suchen und ersetzen: Ersetzt einen oder mehrere Teile eines Attributwertes mit einem regulären Ausdruck. Die geänderte Zeichenfolge wird als neues Attribut zurückgegeben. Der reguläre Ausdruck kann eine Capture-Gruppe enthalten. Ohne eine Capture-Gruppe wird der vollständige Inhalt der Übereinstimmungen des Ausdrucks ersetzt. Wenn eine Capture-Gruppe vorhanden ist, wird nur der von der Gruppe erfasste Inhalt ersetzt. Das optionale Übereinstimmungsereignis kann verwendet werden, wenn nur ein bestimmtes Vorkommen einer Übereinstimmung ersetzt werden muss. Wenn diese Option nicht aktiviert oder auf 0 gesetzt ist, werden alle übereinstimmenden Vorkommen ersetzt. Dies ist das Standardverhalten. Trimieren: Es werden alle vor- und nachgestellten Leerzeichen aus dem Wert eines Attributs entfernt. Großbuchstaben: Konvertiert den Wert eines Attributs in Großbuchstaben.
Attribut	Numerisch Aktionen, die verschiedene mathematische Vorgänge für die Attributwerte zulassen (sofern es sich um Zahlen handelt). Numerische Aktionen unterstützen sowohl tatsächliche Zahlen als auch Zahlen, die als Zeichenfolgen im Attributwert dargestellt werden. Die beiden folgenden Aktionen sind äquivalent: "Betrag" : 2,5 "Betrag" : "2.5" Numerische Aktionen können als Eingabe entweder eine Zeichenfolge verwenden, die den Namen eines Attributs darstellt, dessen Wert im Vorgang verwendet werden soll, oder eine Zahl, die direkt in der Berechnung verwendet wird. Bei allen numerischen Aktionen können Sie Rundungen auf den Ausgabewert anwenden. Folgende Rundungen sind möglich: Runden: Rundet die Zahl auf die nächste Ganzzahl auf oder ab. Boden: Rundet die Zahl auf die nächste ganze Zahl ab. Kreis: Rundet die Zahl auf die nächste ganze Zahl auf. Keine Rundung: Standardoption.	Abwesenheit: Gibt den absoluten Wert des Eingabewerts zurück. Hinzufügen: Summiert zwei Werte. Bucketize: Ordnet einen numerischen Attributwert in Bucket-Namen zu. Wenn der Attributwert in den Bereich eines Buckets fällt, wird der Bucket-Name zurückgegeben. Wenn kein Bucket übereinstimmt, wird ein Fallback-Wert zurückgegeben. Dividieren: Dividiert den ersten durch den zweiten Wert. Wenn der zweite Wert 0 ist, ist das Ergebnis 0. Maximum: Gibt den Höchstwert der beiden Werte zurück. Minimum: Gibt den Mindestwert der beiden Werte zurück. Mehrfach: Multipliziert die beiden Werte. Negate: Negiert (wechselt das Zeichen) des Wertes. Subtrahieren: Subtrahiert das zweite Attribut vom ersten Attribut.
Attribut	Allgemein Generische Aktionen stellen Vorgänge auf Attributebene bereit, wie das Entfernen eines Attributs aus dem Span.	Attributwert zuordnen: Nimmt den Wert eines Attributs und ordnet ihn einem neuen Wert zu. Attribut entfernen: Entfernt das Attribut aus dem Span. Wenn das Attribut eine Ereignisnamenreferenz (`event['EventName']`) ist, wird das gesamte Span-Ereignis entfernt. Attribut umbenennen: Benennt das Attribut um. Attribut festlegen: Legt ein Attribut auf einen statischen Wert fest. Wenn das Attribut nicht vorhanden ist, wird es hinzugefügt. Andernfalls wird ihm der neue Wert zugewiesen und der vorhandene Wert überschrieben.

Beispiele für die Aktionskonfiguration

Dieser Abschnitt enthält Beispiele für die Konfigurationsschritte, die für einige einzelne Aktionen erforderlich sind.

Bucketize-Beispiel:
Bei dieser Aktion wird ein Mini-Editor verwendet, um eine Reihe von Buckets und deren Schwellenwerte einzurichten. Mit dem Steuerelement auf der rechten Seite können Sie Buckets erstellen, aktualisieren und entfernen.

Buckets werden automatisch nach ihren Schwellenwerten sortiert. Ein Fallback-Wert wird verwendet, wenn ein Wert für den letzten Bucket zu groß ist. Die folgende Abbildung zeigt ein Beispiel mit fünf Buckets und einem Fallback-Wert:
Kartenbeispiel:
Diese Aktion verwendet einen Mini-Editor, um die Zuordnung von Eingabe-/Ausgabewertpaaren einzurichten. Beide Werte können Zahlen oder Zeichenfolgen sein. Verwenden Sie das Steuerelement auf der rechten Seite, um eine Zuordnung zu erstellen, zu aktualisieren und/oder zu entfernen.
Über die Schaltfläche Exportieren können Sie alle Zuordnungen in eine Datei (im CSV-Format) auf Ihren Computer herunterladen.
Mit der Schaltfläche Importieren können Sie die Zuordnungen aus einer CSV-Datei auf Ihrem Computer auffüllen. Dies ist besonders nützlich, wenn Sie eine große Anzahl von Zuordnungen haben.

Span-Anreicherungsregeln - Validierung

Span-Anreicherungskonfigurationen können komplex zu schreiben sein, und es kann manchmal schwierig sein, vorher zu wissen, ob eine Regel oder Regelgruppe wie erwartet funktioniert. Um dies zu unterstützen, bietet der Konfigurationseditor für Span-Anreicherung eine Option zum Testen einer Regel oder Regelgruppe in einem Beispiel-Span vor dem Speichern.

So verwenden Sie die Testoption:

Wählen Sie eine Gruppe aus, und klicken Sie auf Bearbeiten, um den Bereich Span-Regelgruppe bearbeiten zu öffnen. Eine andere Möglichkeit besteht darin, eine neue Gruppe zu erstellen. Der Bereich Bearbeiten wird angezeigt.
Klicken Sie auf den Schritt "Regelaktionen konfigurieren".
Klicken Sie auf Testen, um die gesamte Regelgruppe zu testen. Alternativ können Sie eine einzelne Regel testen, indem Sie die Regel auswählen und auf Regel testen klicken.
Hinweis

Die Testregel ist nicht verfügbar, wenn die Regelgruppe nur eine Regel enthält.
Der Bereich Span-Regelgruppe testen wird angezeigt.
Die zu testenden Regeln werden mit einem Kontrollkästchen neben ihnen angezeigt. Sie können diese nach Bedarf umschalten.
Geben Sie einen Beispielbereich in das Textfeld Span-Beispiel ein.
Klicken Sie auf Span testen, um einen Test der ausgewählten Regeln für den angegebenen Span auszuführen.

Abbildung 9-1 Validierung der Span-Anreicherungsregel

Der Testlauf gibt an, ob der Span mit den konfigurierten Span-Filtern übereinstimmt oder nicht.

Wenn die Filter übereinstimmen, werden die Regeln auf den Span angewendet, und die resultierenden Unterschiede (sofern vorhanden) werden in der folgenden Tabelle angezeigt. Alle Attribute, die als Ergebnis der Regel hinzugefügt wurden, werden grün hervorgehoben. Entfernte Attribute werden rot hervorgehoben. Geänderte Attribute werden gelb hervorgehoben.

Trace-Explorer: Um genaue Beispiele für Spans aus Ihrem Traffic abzurufen, klicken Sie oben rechts auf Trace-Explorer, um den Trace-Explorer zu öffnen und die tatsächlich verarbeiteten Spans anzuzeigen. Sie können einen Span auswählen, das Kontextmenü auf der rechten Seite (die drei vertikalen Punkte) öffnen und auf Root-Span-Daten kopieren klicken.

Ein Popup mit dem Inhalt des Spans wird angezeigt. Sie können die Span-Daten kopieren und beim Testen verwenden.

Eine andere Möglichkeit besteht darin, eigene Spans einzufügen oder manuell einzugeben, sofern sie dem vom Trace Explorer gemeldeten Span-Format entsprechen.

Aliasnamen für Span-Eigenschaft

Hinweis

Wenige der tatsächlichen Span-Eigenschaften werden durch einen anderen Namen referenziert, wenn sie in den Features Span-Anreicherung oder Span-Filter verwendet werden. Abgesehen vom visuellen Unterschied hat dies keine Auswirkungen darauf, wie Sie Ihre Regeln und Filter einrichten. Beispiel: Sie sollten den Alias immer verwenden, wenn Sie auf die angegebene Eigenschaft verweisen.

Folgende Eigenschaften haben derzeit einen Alias:

Span-Eigenschaft	Span-Anreicherungsalias	Anmerkungen
`td-micros`	`SpanDuration`	`td-micros` ist in Mikrosekunden, während `SpanDuration` in Millisekunden angegeben ist. Die Zeiteinheitenumrechnung wird automatisch von Span-Anreicherung und Span-Filtern angewendet.
`name`	`OperationName`	Der Name des Spans stellt den ausgeführten Vorgang dar
`ts-micros`	`StartTime`	`ts-micros` ist in Mikrosekunden, während `StartTime` in Millisekunden angegeben ist. Die Zeiteinheitenumrechnung wird automatisch von Span-Anreicherung und Span-Filtern angewendet.
`id`	`SpanId`
`parent-id`	`ParentId`
`trace-id`	`TraceId`

Oracle Cloud Infrastructure-Dokumentation

Span-Anreicherung