Telemetrieprocessors - Preview van Azure Monitor Application Insights voor Java

Application Insights Java 3.x kan telemetriegegevens verwerken voordat de gegevens worden geëxporteerd.

Enkele gebruiksvoorbeelden:

• Gevoelige gegevens maskeren.
• Aangepaste dimensies voorwaardelijk toevoegen.
• Werk de spannaam bij, die wordt gebruikt voor het aggregeren van vergelijkbare telemetrie in Azure Portal.
• Verwijder specifieke span-attributen om de opnamekosten te beperken.
• Filter enkele metrische gegevens om de opnamekosten te beheren.

Terminologie

Voordat u meer te weten komt over telemetrieprocessors, moet u inzicht krijgen in de termenspanne en het logboek.

Een bereik is een type telemetrie dat een van de volgende vertegenwoordigt:

• Een binnenkomende aanvraag.
• Een uitgaande afhankelijkheid (bijvoorbeeld een externe aanroep naar een andere service).
• Een in-process afhankelijkheid (bijvoorbeeld werk dat wordt uitgevoerd door subonderdelen van de service).

Een logboek is een type telemetrie dat het volgende voorstelt:

• logboekgegevens vastgelegd vanuit Log4j, Logback en java.util.logging

Voor telemetrieprocessors zijn deze span-/logboekonderdelen belangrijk:

• Naam
• Hoofdtekst
• Kenmerken

De spannaam is de primaire weergave voor aanvragen en afhankelijkheden in Azure Portal. Spanattributen vertegenwoordigen zowel standaard- als aangepaste eigenschappen van een bepaalde aanvraag of afhankelijkheid.

Het traceringsbericht of de hoofdtekst is de primaire weergave voor logboeken in Azure Portal. Logboekkenmerken vertegenwoordigen zowel standaard- als aangepaste eigenschappen van een bepaald logboek.

Telemetrieprocessortypen

Momenteel zijn de vier typen telemetrieprocessors

• Kenmerkprocessors
• Spanprocessors
• Logboekprocessors
• Metrische filters

Een kenmerkprocessor kan kenmerken van een telemetrie-item (span of log) invoegen, bijwerken, verwijderen of hashen. Het kan ook een reguliere expressie gebruiken om een of meer nieuwe kenmerken uit een bestaand kenmerk te extraheren.

Een spanprocessor kan de telemetrienaam van aanvragen en afhankelijkheden bijwerken. Het kan ook een reguliere expressie gebruiken om een of meer nieuwe kenmerken uit de spannaam te extraheren.

Een logboekprocessor kan de telemetrienaam van logboeken bijwerken. Het kan ook een reguliere expressie gebruiken om een of meer nieuwe kenmerken uit de logboeknaam te extraheren.

Een filter voor metrische gegevens kan metrische gegevens filteren om de opnamekosten te beheren.

Aan de slag

Maak eerst een configuratiebestand met de naam applicationinsights.json. Sla deze op in dezelfde map als applicationinsights-agent-*.jar. Gebruik de volgende sjabloon.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        ...
      },
      {
        "type": "attribute",
        ...
      },
      {
        "type": "span",
        ...
      },
      {
        "type": "log",
        ...
      },
      {
        "type": "metric-filter",
        ...
      }
    ]
  }
}

Kenmerkprocessor

De kenmerkprocessor wijzigt kenmerken van een span of een log. Het kan ondersteuning bieden voor de mogelijkheid om op te nemen of uit te sluiten span of .log Er wordt een lijst uitgevoerd met acties die worden uitgevoerd in de volgorde waarin het configuratiebestand is opgegeven. De processor ondersteunt deze acties:

• insert
• update
• delete
• hash
• extract
• mask

insert

Met insert de actie wordt een nieuw kenmerk ingevoegd in het telemetrie-item waar het key nog niet bestaat.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "value1",
        "action": "insert"
      }
    ]
  }
]

Voor de insert actie zijn de volgende instellingen vereist:

• key
• value of fromAttribute
• action: insert

update

Met de update actie wordt een kenmerk bijgewerkt in telemetrie-item waar het key al bestaat.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "newValue",
        "action": "update"
      }
    ]
  }
]

Voor de update actie zijn de volgende instellingen vereist:

• key
• value of fromAttribute
• action: update

delete

Met de delete actie wordt een kenmerk uit een telemetrie-item verwijderd.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "delete"
      }
    ]
  }
]

Voor de delete actie zijn de volgende instellingen vereist:

• key
• action: delete

hash

De actie hash voert een SHA1-hash uit op een bestaande attribuutwaarde.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "hash"
      }
    ]
  }
]

Voor de hash actie zijn de volgende instellingen vereist:

• key
• action: hash

extract

Met extract de actie worden waarden geëxtraheerd met behulp van een reguliere expressieregel van de invoersleutel naar doelsleutels die door de regel worden opgegeven. Als er al een doelsleutel bestaat, overschrijft de extract actie de doelsleutel. Deze actie gedraagt zich als de instelling voor de spanprocessortoAttributes, waarbij het bestaande kenmerk de bron is.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "pattern": "<regular pattern with named matchers>",
        "action": "extract"
      }
    ]
  }
]

Voor de extract actie zijn de volgende instellingen vereist:

• key
• pattern
• action: extract

mask

De mask actie maskert kenmerkwaarden met behulp van een reguliere expressieregel die is opgegeven in de pattern en replace.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attributeName",
        "pattern": "<regular expression pattern>",
        "replace": "<replacement value>",
        "action": "mask"
      }
    ]
  }
]

Voor de mask actie zijn de volgende instellingen vereist:

• key
• pattern
• replace
• action: mask

pattern kan een benoemde groep bevatten tussen ?< en >:. Voorbeeld: (?<userGroupName>[a-zA-Z.:\/]+)\d+? De groep is (?<userGroupName>[a-zA-Z.:\/]+) en userGroupName is de naam van de groep. pattern kan vervolgens dezelfde benoemde groep bevatten tussen ${ en } gevolgd door het masker. Voorbeeld waarbij het masker ** is: ${userGroupName}**.

Zie voorbeelden van telemetrieprocessor voor maskeringsvoorbeelden.

Criteria opnemen en criteria uitsluiten

Attribuutprocessors ondersteunen optioneel include en exclude criteria. Een kenmerkprocessor wordt alleen toegepast op telemetrie die voldoet aan de include criteria (als deze beschikbaar is) en niet voldoet aan de exclude criteria (als deze beschikbaar is).

Als u deze optie wilt configureren, geeft u onder include of exclude (of beide) ten minste één matchType en een spanNames of attributes. De include of exclude configuratie staat meer dan één opgegeven voorwaarde toe. Alle opgegeven voorwaarden moeten waar zijn om te resulteren in een overeenkomst.

• Vereiste velden:

  • matchType bepaalt hoe items in spanNames matrices en attributes matrices worden geïnterpreteerd. Mogelijke waarden zijn regexp en strict. Reguliere expressieovereenkomsten worden uitgevoerd op basis van de gehele kenmerkwaarde, dus als u een waarde wilt vergelijken die abc ergens in de expressie staat, moet u deze gebruiken .*abc.*.

• Optionele velden:

  • spanNames moet overeenkomen met ten minste één van de items.
  • attributes hiermee geeft u de lijst met kenmerken die overeenkomen. Al deze kenmerken moeten exact overeenkomen om te resulteren in een overeenkomst.

Voorbeeldgebruik

"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"
      }
    ]
  }
]

Zie voorbeelden van telemetrieprocessor voor meer informatie.

Spanprocessor

De spanprocessor wijzigt de spannaam of -kenmerken van een span op basis van de spannaam. Het kan ondersteuning bieden voor de mogelijkheid om spanten op te nemen of uit te sluiten.

Een spannaam opgeven

Voor name de sectie is de fromAttributes instelling vereist. De waarden van deze kenmerken worden gebruikt om een nieuwe naam te maken, samengevoegd in de volgorde waarin de configuratie is opgegeven. De processor wijzigt alleen de spannaam als al deze kenmerken aanwezig zijn op de span.

De separator instelling is optioneel. Deze instelling is een tekenreeks en u kunt gesplitste waarden gebruiken.

"processors": [
  {
    "type": "span",
    "name": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
] 

Kenmerken extraheren uit de spannaam

De toAttributes sectie bevat de reguliere expressies die overeenkomen met de naam van het bereik. Het extraheert kenmerken op basis van subexpressies.

De rules instelling is vereist. Deze instelling bevat de regels die worden gebruikt om kenmerkwaarden uit de spannaam te extraheren.

Uitgepakte kenmerknamen vervangen de waarden in de spannaam. Elke regel in de lijst is een reguliere expressiepatroontekenreeks (regex).

Hier ziet u hoe geëxtraheerde kenmerknamen waarden vervangen:

1. De spannaam wordt gecontroleerd aan de hand van de regex.
2. Alle benoemde subexpressies van de regex worden geëxtraheerd als kenmerken als de regex overeenkomt.
3. De geëxtraheerde kenmerken worden toegevoegd aan het bereik.
4. Elke subexpressienaam wordt een kenmerknaam.
5. Het overeenkomende gedeelte van de subexpressie wordt de kenmerkwaarde.
6. De geëxtraheerde kenmerknaam vervangt het overeenkomende gedeelte in de spannaam. Als de kenmerken al in de periode bestaan, worden ze overschreven.

Dit proces wordt herhaald voor alle regels in de volgorde waarin ze zijn opgegeven. Elke volgende regel werkt op de spannaam die de uitvoer van de vorige regel is.

"processors": [
  {
    "type": "span",
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Algemene span-attributen

In deze sectie vindt u enkele algemene spankenmerken die telemetrieprocessors kunnen gebruiken.

HTTP-spans

Connectiviteit van Java Database omvat

In de volgende tabel worden attributen beschreven die u kunt gebruiken in JDBC-spans (Java Database Connectivity).

Criteria opnemen en criteria uitsluiten

Spanprocessors ondersteunen optioneel include en exclude criteria. Een spanprocessor wordt alleen toegepast op telemetrie die voldoet aan de include criteria (als deze beschikbaar is) en niet voldoet aan de exclude criteria (als deze beschikbaar is).

Om deze optie te configureren, geeft u onder include of exclude (of beide) ten minste één matchType op en specificeer spanNames of span attributes. De include of exclude configuratie staat meer dan één opgegeven voorwaarde toe. Alle opgegeven voorwaarden moeten waar zijn om te resulteren in een overeenkomst.

• Vereiste velden:

  • matchType bepaalt hoe items in spanNames matrices en attributes matrices worden geïnterpreteerd. Mogelijke waarden zijn regexp en strict. Reguliere expressieovereenkomsten worden uitgevoerd op basis van de gehele kenmerkwaarde, dus als u een waarde wilt vergelijken die abc ergens in de expressie staat, moet u deze gebruiken .*abc.*.

• Optionele velden:

  • spanNames moet overeenkomen met ten minste één van de items.
  • attributes hiermee geeft u de lijst met kenmerken die overeenkomen. Al deze kenmerken moeten exact overeenkomen om te resulteren in een overeenkomst.

Voorbeeldgebruik

"processors": [
  {
    "type": "span",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "attributeValue1"
        }
      ]
    },
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Zie voorbeelden van telemetrieprocessor voor meer informatie.

Logboekprocessor

De logboekprocessor wijzigt de hoofdtekst van het logboekbericht of de kenmerken van een logboek op basis van de hoofdtekst van het logboekbericht. Het kan ondersteuning bieden voor de mogelijkheid om logboeken op te nemen of uit te sluiten.

Hoofdtekst van logboekbericht bijwerken

Voor body de sectie is de fromAttributes instelling vereist. De waarden van deze kenmerken worden gebruikt om een nieuwe hoofdtekst te maken, samengevoegd in de volgorde waarin de configuratie is opgegeven. De processor wijzigt alleen de hoofdtekst van het logboek als al deze kenmerken aanwezig zijn in het logboek.

De separator instelling is optioneel. Deze instelling is een tekenreeks. U kunt deze opgeven om waarden te splitsen.

"processors": [
  {
    "type": "log",
    "body": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
] 

Kenmerken extraheren uit de hoofdtekst van het logboekbericht

De toAttributes sectie bevat de reguliere expressies die overeenkomen met de hoofdtekst van het logboekbericht. Het extraheert kenmerken op basis van subexpressies.

De rules instelling is vereist. Deze instelling bevat de regels die worden gebruikt om kenmerkwaarden uit de hoofdtekst te extraheren.

Uitgepakte kenmerknamen vervangen de waarden in de hoofdtekst van het logboekbericht. Elke regel in de lijst is een reguliere expressiepatroontekenreeks (regex).

Hier ziet u hoe geëxtraheerde kenmerknamen waarden vervangen:

1. De hoofdtekst van het logboekbericht wordt gecontroleerd aan de hand van de regex.
2. Alle benoemde subexpressies van de regex worden geëxtraheerd als kenmerken als de regex overeenkomt.
3. De geëxtraheerde kenmerken worden toegevoegd aan het logboek.
4. Elke subexpressienaam wordt een kenmerknaam.
5. Het overeenkomende gedeelte van de subexpressie wordt de kenmerkwaarde.
6. De geëxtraheerde kenmerknaam vervangt het overeenkomende gedeelte in de logboeknaam. Als de kenmerken al aanwezig zijn in het logboek, worden ze overschreven.

Dit proces wordt herhaald voor alle regels in de volgorde waarin ze zijn opgegeven. Elke volgende regel werkt op de lognaam die de uitvoer is van de vorige regel.

"processors": [
  {
    "type": "log",
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Criteria opnemen en criteria uitsluiten

Logboekprocessors ondersteunen optioneel include en exclude criteria. Een logboekprocessor wordt alleen toegepast op telemetrie die voldoet aan de include criteria (als deze beschikbaar is) en niet voldoet aan de exclude criteria (als deze beschikbaar is).

Als u deze optie wilt configureren, specificeert u onder include of exclude (of beide) de matchType en attributes. De include of exclude configuratie staat meer dan één opgegeven voorwaarde toe. Alle opgegeven voorwaarden moeten waar zijn om te resulteren in een overeenkomst.

• Verplicht veld:
  • matchType bepaalt hoe items in attributes matrices worden geïnterpreteerd. Mogelijke waarden zijn regexp en strict. Reguliere expressieovereenkomsten worden uitgevoerd op basis van de gehele kenmerkwaarde, dus als u een waarde wilt vergelijken die abc ergens in de expressie staat, moet u deze gebruiken .*abc.*.
  • attributes hiermee geeft u de lijst met kenmerken die overeenkomen. Al deze kenmerken moeten exact overeenkomen om te resulteren in een overeenkomst.

Voorbeeldgebruik

"processors": [
  {
    "type": "log",
    "include": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "value1"
        }
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute2",
          "value": "value2"
        }
      ]
    },
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Zie voorbeelden van telemetrieprocessor voor meer informatie.

Filter voor metrische gegevens

Metrische filters worden gebruikt om bepaalde metrische gegevens uit te sluiten om de kosten van gegevensinvoer te helpen beheersen.

Metrische filters ondersteunen alleen exclude criteria. Metrische gegevens die voldoen aan de exclude criteria worden niet geëxporteerd.

Als u deze optie wilt configureren, specificeert u onder exclude een matchType of meer metricNames.

• Verplicht veld:
  • matchType bepaalt hoe items in metricNames worden gematcht. Mogelijke waarden zijn regexp en strict. Reguliere expressieovereenkomsten worden uitgevoerd op basis van de gehele kenmerkwaarde, dus als u een waarde wilt vergelijken die abc ergens in de expressie staat, moet u deze gebruiken .*abc.*.
  • metricNames moet overeenkomen met ten minste één van de items.

Voorbeeldgebruik

In het volgende voorbeeld ziet u hoe u metrische gegevens kunt uitsluiten met de namen 'metricA' en 'metricB':

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "strict",
      "metricNames": [
        "metricA",
        "metricB"
      ]
    }
  }
]

In het volgende voorbeeld ziet u hoe u alle metrische gegevens uitschakelt, inclusief de standaard metrische gegevens voor automatisch opgehaalde prestaties, zoals cpu en geheugen.

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "regexp",
      "metricNames": [
        ".*"
      ]
    }
  }
]

Standaard metrische gegevens die zijn vastgelegd door Java-agent

Volgende stappen

• Zie Veelgestelde vragen over telemetrieprocessors voor meer informatie over veelgestelde vragen