Beispiele für Telemetrieprozessoren: Azure Monitor Application Insights für Java

Artikel
10/15/2024

Dieser Artikel enthält Beispiele für Telemetrieprozessoren in Application Insights für Java, einschließlich Beispielen für ein- und ausschließende Konfigurationen. Sie finden auch Beispiele für attribute-Prozessoren und span-Prozessoren.

Beispiele für das Ein- und Ausschließen von span-Elementen

In diesem Abschnitt erfahren Sie, wie Sie span-Elemente einschließen und ausschließen. Sie erfahren auch, wie Sie mehrere span-Elemente ausschließen und eine selektive Verarbeitung anwenden.

Einschließen von span-Elementen

Dieser Abschnitt zeigt, wie Sie span-Elemente für einen attribute-Prozessor einschließen. Der Prozessor verarbeitet keine span-Elemente, die nicht mit den Eigenschaften übereinstimmen.

Um eine Übereinstimmung zu erzielen, muss der Name des span-Elements spanA oder spanB entsprechen.

Die folgenden span-Elemente stimmen mit den include-Eigenschaften überein, und die Prozessoraktionen werden angewendet:

Span1 Name: „spanA“-Attribute: {env: dev, test_request: 123, credit_card: 1234}
Span2 Name: „spanB'“-Attribute: {env: dev, test_request: false}
Span3 Name: „spanA“-Attribute: {env: 1, test_request: dev, credit_card: 1234}

Dieses span-Element stimmt nicht mit den include-Eigenschaften überein, und die Prozessoraktionen werden nicht angewendet:

Span4 Name: „spanC“-Attribute: {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Ausschließen von span-Elementen

Dieser Abschnitt veranschaulicht, wie Sie span-Elemente für einen attribute-Prozessor ausschließen. Dieser Prozessor verarbeitet keine span-Elemente, die mit den Eigenschaften übereinstimmen.

Um eine Übereinstimmung zu erzielen, muss der Name des span-Elements spanA oder spanB entsprechen.

Die folgenden span-Elemente stimmen mit den exclude-Eigenschaften überein, und die Prozessoraktionen werden nicht angewendet:

Span1 Name: „spanA“-Attribute: {env: dev, test_request: 123, credit_card: 1234}
Span2 Name: „spanB'“-Attribute: {env: dev, test_request: false}
Span3 Name: „spanA“-Attribute: {env: 1, test_request: dev, credit_card: 1234}

Dieses span-Element stimmt nicht mit den exclude-Eigenschaften überein, und die Prozessoraktionen werden angewendet:

Span4 Name: „spanC“-Attribute: {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Ausschließen von span-Elementen anhand mehrerer Kriterien

Dieser Abschnitt veranschaulicht, wie Sie span-Elemente für einen attribute-Prozessor ausschließen. Dieser Prozessor verarbeitet keine span-Elemente, die mit den Eigenschaften übereinstimmen.

Um eine Übereinstimmung zu erzielen, müssen die folgenden Bedingungen erfüllt sein:

Im span-Element muss ein Attribut vorhanden sein (z. B. env mit dem Wert dev).
Das span-Element muss über ein Attribut mit dem Schlüssel test_request verfügen.

Die folgenden span-Elemente stimmen mit den exclude-Eigenschaften überein, und die Prozessoraktionen werden nicht angewendet.

Span1 Name: „spanB“-Attribute: {env: dev, test_request: 123, credit_card: 1234}
Span2 Name: „spanA“-Attribute: {env: dev, test_request: false}

Das folgende span-Element stimmt nicht mit den exclude-Eigenschaften überein, und die Prozessoraktionen werden angewendet:

Span3 Name: „spanB“-Attribute: {env: 1, test_request: dev, credit_card: 1234}
Span4 Name: „spanC“-Attribute: {env: dev, dev_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ],
          "attributes": [
            {
              "key": "env",
              "value": "dev"
            },
            {
              "key": "test_request"
            }
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Selektive Verarbeitung

Dieser Abschnitt zeigt, wie Sie die Gruppe von span-Eigenschaften angeben, die festlegen, auf welche span-Elemente dieser Prozessor angewendet werden soll. Die include-Eigenschaften geben an, welche span-Elemente verarbeitet werden sollen. Die exclude-Eigenschaften filtern span-Elemente heraus, die nicht verarbeitet werden sollen.

In der folgenden Konfiguration stimmen diese span-Elemente mit den Eigenschaften überein, und die Prozessoraktionen werden angewendet:

Span1 Name: „spanB“-Attribute: {env: production, test_request: 123, credit_card: 1234, redact_trace: "false"}
Span2 Name: „spanA“-Attribute: {env: staging, test_request: false, redact_trace: true}

Diese span-Elemente stimmen nicht mit den include-Eigenschaften überein, und die Prozessoraktionen werden nicht angewendet:

Span3 Name: „spanB“-Attribute: {env: production, test_request: true, credit_card: 1234, redact_trace: false}
Span4 Name: „spanC“-Attribute: {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "exclude": {
          "matchType": "strict",
          "attributes": [
            {
              "key": "redact_trace",
              "value": "false"
            }
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          },
          {
            "key": "duplicate_key",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Beispiele für attribute-Prozessoren

Einfügen

Das folgende Beispiel fügt das neue Attribut {"attribute1": "attributeValue1"} in span-Elemente und Protokolle ein, in denen der Schlüssel attribute1 nicht vorhanden ist.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "attribute1",
            "value": "attributeValue1",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

Einfügen von einem anderen Schlüssel

Das folgende Beispiel verwendet den Wert aus dem Attribut anotherkey, um das neue Attribut {"newKey": "<value from attribute anotherkey>"} in span-Elemente und Protokolle einzufügen, in denen der Schlüssel newKey nicht vorhanden ist. Wenn das Attribut anotherkey nicht vorhanden ist, wird kein neues Attribut in die span-Elemente eingefügt.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "newKey",
            "fromAttribute": "anotherKey",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

Aktualisieren

Das folgende Beispiel aktualisiert das Attribut zu {"db.secret": "redacted"}. Das Attribut boo wird unter Verwendung des Werts aus dem Attribut foo aktualisiert. Span-Elemente, die das Attribut boo nicht enthalten, werden nicht geändert.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "db.secret",
            "value": "redacted",
            "action": "update"
          },
          {
            "key": "boo",
            "fromAttribute": "foo",
            "action": "update" 
          }
        ]
      }
    ]
  }
}

Löschen

Das folgende Beispiel zeigt, wie ein Attribut mit dem Schlüssel credit_card gelöscht wird.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Hash

Das folgende Beispiel zeigt, wie vorhandene Attributwerte mit einem Hash versehen werden.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "user.email",
            "action": "hash"
          }
        ]
      }
    ]
  }
}

Extract

Das folgende Beispiel zeigt, wie ein regulärer Ausdruck (RegEx) verwendet wird, um neue Attribute basierend auf dem Wert eines anderen Attributs erstellen. Für url.path = /path?queryParam1=value1,queryParam2=value2 werden beispielsweise die folgenden Attribute eingefügt:

httpProtocol: http
httpDomain: example.com
httpPath: path
httpQueryParams: queryParam1=value1,queryParam2=value2
url.path: keine Änderung

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<httpProtocol>.*):\\/\\/(?<httpDomain>.*)\\/(?<httpPath>.*)(\\?|\\&)(?<httpQueryParams>.*)",
            "action": "extract"
          }
        ]
      }
    ]
  }
}

Maske

Angenommen url.path = https://example.com/user/12345622 wird mit einer der folgenden Konfigurationen auf url.path = https://example.com/user/**** aktualisiert.

Erstes Konfigurationsbeispiel:

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "user\\/\\d+",
            "replace": "user\\/****",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

Zweites Konfigurationsbeispiel mit dem Namen der Gruppe regulärer Ausdrücke:

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<userGroupName>[a-zA-Z.:\/]+)\d+",
            "replace": "${userGroupName}**",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

Beispiele für Attribute, die nicht auf Strings basieren

Ab 3.4.19 GA unterstützen die Telemetrie-Prozessoren Attribute, die nicht als Zeichenkette geschrieben sind: boolean, double, long, boolean-array, double-array, long-array und string-array.

Wenn attributes.type nicht in der JSON-Datei bereitgestellt wird, wird standardmäßig string verwendet.

Das folgende Beispiel fügt das neue Attribut {"newAttributeKeyStrict": "newAttributeValueStrict"} in span-Elemente und Protokolle ein, deren Attribute mit den folgenden Beispielen übereinstimmen: {"longAttributeKey": 1234}{"booleanAttributeKey": true}{"doubleArrayAttributeKey": [1.0, 2.0, 3.0, 4.0]}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            {
              "key": "longAttributeKey",
              "value": 1234,
              "type": "long"
            },
            {
              "key": "booleanAttributeKey",
              "value": true,
              "type": "boolean"
            },
            {
              "key": "doubleArrayAttributeKey",
              "value": [1.0, 2.0, 3.0, 4.0],
              "type": "double-array"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyStrict",
            "value": "newAttributeValueStrict",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyStrict"
      }
    ]
  }
}

Außerdem unterstützen Attribute, die nicht auf Strings basieren, regexp.

Das folgende Beispiel fügt das neue Attribut {"newAttributeKeyRegexp": "newAttributeValueRegexp"} in span-Elemente und Protokolle ein, in denen das Attribut longRegexpAttributeKey dem Wert von 400 bis 499 entspricht.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "regexp",
          "attributes": [
            {
              "key": "longRegexpAttributeKey",
              "value": "4[0-9][0-9]",
              "type": "long"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyRegexp",
            "value": "newAttributeValueRegexp",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyRegexp"
      }
    ]
  }
}

Beispiele für span-Prozessoren

Name einer Span

Das folgende Beispiel gibt die Werte der Attribute db.svc, operation und id an. Es formt einen neuen Namen für das span-Element, indem diese Elemente in der angegebenen Reihenfolge und durch den Wert :: getrennt verwendet werden.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "fromAttributes": [
            "db.svc",
            "operation",
            "id"
          ],
          "separator": "::"
        }
      }
    ]
  }
}

Extrahieren von Attributen aus dem Namen eines span-Elements

Angenommen, der Eingabename des span-Elements lautet /api/v1/document/12345678/update. Das folgende Beispiel führt zum Ausgabenamen /api/v1/document/{documentId}/update des span-Elements. Dem span-Element wird das neue Attribut documentId=12345678 hinzugefügt.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "toAttributes": {
            "rules": [
              "^/api/v1/document/(?<documentId>.*)/update$"
            ]
          }
        }
      }
    ]
  }
}

Extrahieren von Attributen aus dem Namen eines span-Elements mithilfe von „include“ und „exclude“

Das folgende Beispiel zeigt, wie der Name eines span-Elements zu {operation_website} geändert wird. Ein Attribut mit dem Schlüssel operation_website und dem Attribut {oldSpanName} wird hinzugefügt, wenn das span-Element die folgenden Eigenschaften aufweist:

Der Name des span-Elements enthält an einer beliebigen Stelle in der Zeichenfolge das Zeichen /.
Der Name des span-Elements lautet nicht donot/change.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "include": {
          "matchType": "regexp",
          "spanNames": [
            "^(.*?)/(.*?)$"
          ]
        },
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "donot/change"
          ]
        },
        "name": {
          "toAttributes": {
            "rules": [
              "(?<operation_website>.*?)$"
            ]
          }
        }
      }
    ]
  }
}

Beispiele für Protokollprozessoren

Extrahieren von Attributen aus dem Nachrichtentext von Protokollen

Angenommen, der eingegebene Protokollnachrichtentext lautet Starting PetClinicApplication on WorkLaptop with PID 27984 (C:\randompath\target\classes started by userx in C:\randompath). Mit folgendem Beispiel wird der Nachrichtentext Starting PetClinicApplication on WorkLaptop with PID {PIDVALUE} (C:\randompath\target\classes started by userx in C:\randompath) ausgegeben. Dem Protokoll wird das neue Attribut PIDVALUE=27984 hinzugefügt.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "^Starting PetClinicApplication on WorkLaptop with PID (?<PIDVALUE>\\d+) .*"
            ]
          }
        }
      }
    ]
  }
}

Maskieren vertraulicher Daten in Protokollmeldungen

Im folgenden Beispiel wird gezeigt, wie vertrauliche Daten in einem Protokollnachrichtentext mithilfe eines Protokollprozessors und eines Attributprozessors maskiert werden. Angenommen, der eingegebene Protokollnachrichtentext lautet User account with userId 123456xx failed to login. Der log-Prozessor ändert den ausgegebenen Nachrichtentext in User account with userId {redactedUserId} failed to login, und der attribute-Prozessor löscht das neue redactedUserId-Attribut, das im vorherigen Schritt hinzugefügt wurde.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "userId (?<redactedUserId>[0-9a-zA-Z]+)"
            ]
          }
        }
      },
      {
        "type": "attribute",
        "actions": [
          {
            "key": "redactedUserId",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Häufig gestellte Fragen

Warum verarbeitet der Protokollprozessor Protokolle nicht mithilfe von „TelemetryClient.trackTrace()“?

„TelemetryClient.trackTrace()“ ist Teil der klassischen SDK-Brücke von Application Insights, und die Protokollprozessoren funktionieren nur mit der neuen OpenTelemetry-basierten Instrumentierung.

Freigeben über