Share via

Telemetriprocessorer (förhandsversion) – Azure Monitor Application Insights för Java

  • Artikel

Kommentar

Funktionen telemetriprocessorer är avsedd som förhandsversion eftersom vi inte kan garantera bakåtkompatibilitet från lansering till lansering på grund av det experimentella tillståndet för attributsemantiska konventioner. Funktionen har dock testats och stöds i produktion.

Application Insights Java 3.x kan bearbeta telemetridata innan data exporteras.

Vissa användningsfall:

  • Maskera känsliga data.
  • Lägg till anpassade dimensioner villkorligt.
  • Uppdatera span-namnet, som används för att aggregera liknande telemetri i Azure-portalen.
  • Ta bort specifika span-attribut för att kontrollera inmatningskostnader.
  • Filtrera bort vissa mått för att kontrollera inmatningskostnader.

Kommentar

Om du vill ta bort specifika (hela) intervall för att kontrollera inmatningskostnaden kan du läsa om samplings åsidosättningar.

Terminologi

Innan du lär dig mer om telemetriprocessorer bör du förstå termerna span och log.

Ett spann är en typ av telemetri som representerar något av:

  • En inkommande begäran.
  • Ett utgående beroende (till exempel ett fjärranrop till en annan tjänst).
  • Ett pågående beroende (till exempel arbete som utförs av underkomponenter i tjänsten).

En logg är en typ av telemetri som representerar:

  • loggdata som samlats in från Log4j, Logback och java.util.logging

För telemetriprocessorer är dessa span-/loggkomponenter viktiga:

  • Name
  • Brödtext
  • Attribut

Spannamnet är den primära visningen för begäranden och beroenden i Azure-portalen. Span-attribut representerar både standard- och anpassade egenskaper för en viss begäran eller ett visst beroende.

Spårningsmeddelandet eller brödtexten är den primära visningen för loggar i Azure-portalen. Loggattribut representerar både standard- och anpassade egenskaper för en viss logg.

Typer av telemetriprocessorer

För närvarande är de fyra typerna av telemetriprocessorer

  • Attributprocessorer
  • Spänn över processorer
  • Loggprocessorer
  • Måttfilter

En attributprocessor kan infoga, uppdatera, ta bort eller hash-attribut för ett telemetriobjekt (span eller log). Den kan också använda ett reguljärt uttryck för att extrahera ett eller flera nya attribut från ett befintligt attribut.

En span-processor kan uppdatera telemetrinamnet för begäranden och beroenden. Det kan också använda ett reguljärt uttryck för att extrahera ett eller flera nya attribut från span-namnet.

En loggprocessor kan uppdatera telemetrinamnet för loggar. Det kan också använda ett reguljärt uttryck för att extrahera ett eller flera nya attribut från loggnamnet.

Ett måttfilter kan filtrera bort mått för att styra inmatningskostnaden.

Kommentar

För närvarande bearbetar telemetriprocessorer endast attribut av typen sträng. De bearbetar inte attribut av typen Booleskt värde eller tal.

Komma igång

Börja med att skapa en konfigurationsfil med namnet applicationinsights.json. Spara den i samma katalog som applicationinsights-agent-*.jar. Använd följande mall.

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

Attributprocessor

Attributprocessorn ändrar attribut för en span eller en log. Det kan stödja möjligheten att inkludera eller exkludera span eller log. Den tar en lista över åtgärder som utförs i den ordning som konfigurationsfilen anger. Processorn stöder följande åtgärder:

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

insert

Åtgärden insert infogar ett nytt attribut i telemetriobjektet där det key inte redan finns.

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

Åtgärden insert kräver följande inställningar:

  • key
  • Antingen value eller fromAttribute
  • action: insert

update

Åtgärden update uppdaterar ett attribut i telemetriobjektet där det key redan finns.

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

Åtgärden update kräver följande inställningar:

  • key
  • Antingen value eller fromAttribute
  • action: update

delete

Åtgärden delete tar bort ett attribut från ett telemetriobjekt.

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

Åtgärden delete kräver följande inställningar:

  • key
  • action: delete

hash

Åtgärden hash hashar (SHA1) ett befintligt attributvärde.

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

Åtgärden hash kräver följande inställningar:

  • key
  • action: hash

extract

Kommentar

Funktionen extract är endast tillgänglig i version 3.0.2 och senare.

Åtgärden extract extraherar värden med hjälp av en regel för reguljära uttryck från indatanyckeln till målnycklar som regeln anger. Om det redan finns en målnyckel åsidosätter åtgärden extract målnyckeln. Den här åtgärden fungerar som inställningen för spännviddsprocessorntoAttributes , där det befintliga attributet är källan.

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

Åtgärden extract kräver följande inställningar:

  • key
  • pattern
  • action: extract

mask

Kommentar

Funktionen mask är endast tillgänglig i version 3.2.5 och senare.

Åtgärden mask maskerar attributvärden med hjälp av en regel för reguljära uttryck som anges i pattern och replace.

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

Åtgärden mask kräver följande inställningar:

  • key
  • pattern
  • replace
  • action: mask

pattern kan innehålla en namngiven grupp placerad mellan ?< och >:. Exempel: (?<userGroupName>[a-zA-Z.:\/]+)\d+? Gruppen är (?<userGroupName>[a-zA-Z.:\/]+) och userGroupName är namnet på gruppen. pattern kan sedan innehålla samma namngivna grupp placerad mellan ${ och } följt av masken. Exempel där masken är **: ${userGroupName}**.

Se Exempel på telemetriprocessor för maskeringsexempel.

Inkludera kriterier och exkludera kriterier

Attributprocessorer stöder valfritt include och exclude villkor. En attributprocessor tillämpas endast på telemetri som matchar dess include kriterier (om den är tillgänglig) och inte matchar dess exclude kriterier (om den är tillgänglig).

Om du vill konfigurera det här alternativet under include eller exclude (eller båda) anger du minst en matchType och antingen spanNames eller attributes. Konfigurationen include eller exclude tillåter mer än ett angivet villkor. Alla angivna villkor måste utvärderas till true för att resultera i en matchning.

  • Obligatoriska fält:

    • matchType styr hur objekt i spanNames matriser och attributes matriser tolkas. Möjliga värden är regexp och strict. Reguljära uttrycksmatchningar utförs mot hela attributvärdet, så om du vill matcha ett värde som innehåller abc var som helst i det måste du använda .*abc.*.

  • Valfria fält:

    • spanNames måste matcha minst ett av objekten.
    • attributes anger listan över attribut som ska matchas. Alla dessa attribut måste matcha exakt för att resultera i en matchning.

Kommentar

Om både include och exclude anges include kontrolleras egenskaperna innan exclude egenskaperna kontrolleras.

Kommentar

Om konfigurationen include eller inte har spanNames angetts tillämpas matchningsvillkoren på både spans och logsexclude .

Exempelanvändning

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

Mer information finns i Exempel på telemetriprocessor.

Spänn över processor

Span-processorn ändrar antingen spannamnet eller attributen för ett spann baserat på spannets namn. Det kan stödja möjligheten att inkludera eller exkludera intervall.

Namnge ett intervall

Avsnittet name kräver inställningen fromAttributes . Värdena från dessa attribut används för att skapa ett nytt namn, sammanfogat i den ordning som konfigurationen anger. Processorn ändrar endast spannamnet om alla dessa attribut finns i intervallet.

Inställningen separator är valfri. Den här inställningen är en sträng och du kan använda delade värden.

Kommentar

Om namnbytet förlitar sig på attributprocessorn för att ändra attribut kontrollerar du att span-processorn har angetts efter attributprocessorn i pipelinespecifikationen.

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

Extrahera attribut från spannsnamnet

I toAttributes avsnittet visas de reguljära uttryck som ska matcha span-namnet mot. Den extraherar attribut baserat på underuttryck.

Inställningen rules krävs. Den här inställningen visar de regler som används för att extrahera attributvärden från span-namnet.

Extraherade attributnamn ersätter värdena i span-namnet. Varje regel i listan är en mönstersträng för reguljära uttryck (regex).

Så här ersätter extraherade attributnamn värden:

  1. Spannamnet kontrolleras mot regexen.
  2. Alla namngivna underuttryck av regex extraheras som attribut om regex matchar.
  3. De extraherade attributen läggs till i intervallet.
  4. Varje underuttrycksnamn blir ett attributnamn.
  5. Den underuttrycksmatchade delen blir attributvärdet.
  6. Det extraherade attributnamnet ersätter den matchade delen i spannamnet. Om attributen redan finns i intervallet skrivs de över.

Den här processen upprepas för alla regler i den ordning de anges. Varje efterföljande regel fungerar på span-namnet som är utdata från den tidigare regeln.

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

Vanliga span-attribut

I det här avsnittet visas några vanliga span-attribut som telemetriprocessorer kan använda.

HTTP-intervall

Attribut Typ Beskrivning
http.request.method (brukade vara http.method) sträng HTTP-begärandemetod.
url.full (klientintervall) eller url.path (serverintervall) (brukade vara http.url) sträng Fullständig URL för HTTP-begäran i formuläret scheme://host[:port]/path?query[#fragment]. Fragmentet överförs vanligtvis inte via HTTP. Men om fragmentet är känt bör det inkluderas.
http.response.status_code (brukade vara http.status_code) Nummer Statuskod för HTTP-svar.
network.protocol.version (brukade vara http.flavor) sträng Typ av HTTP-protokoll.
user_agent.original (brukade vara http.user_agent) sträng Värdet för HTTP User-Agent-huvudet som skickas av klienten.

Java Database Anslut ivity spänner över

I följande tabell beskrivs attribut som du kan använda i JDBC(Java Database Anslut ivity):

Attribut Typ Description
db.system sträng Identifierare för den databashanteringssystemprodukt (DBMS) som används. Se Semantiska konventioner för databasåtgärder.
db.connection_string sträng Anslut ionssträng som används för att ansluta till databasen. Vi rekommenderar att du tar bort inbäddade autentiseringsuppgifter.
db.user sträng Användarnamn för åtkomst till databasen.
db.name sträng Sträng som används för att rapportera namnet på databasen som används. För kommandon som växlar databasen bör den här strängen anges till måldatabasen, även om kommandot misslyckas.
db.statement sträng Databasuttryck som körs.

Inkludera kriterier och exkludera kriterier

Span-processorer stöder valfritt include och exclude kriterier. En span-processor tillämpas endast på telemetri som matchar dess include kriterier (om den är tillgänglig) och inte matchar dess exclude kriterier (om den är tillgänglig).

Om du vill konfigurera det här alternativet, under include eller (eller båda), anger du minst en matchType och antingen spanNames eller sträcker sig över attributesexclude . Konfigurationen include eller exclude tillåter mer än ett angivet villkor. Alla angivna villkor måste utvärderas till true för att resultera i en matchning.

  • Obligatoriska fält:

    • matchType styr hur objekt i spanNames matriser och attributes matriser tolkas. Möjliga värden är regexp och strict. Reguljära uttrycksmatchningar utförs mot hela attributvärdet, så om du vill matcha ett värde som innehåller abc var som helst i det måste du använda .*abc.*.

  • Valfria fält:

    • spanNames måste matcha minst ett av objekten.
    • attributes anger listan över attribut som ska matchas. Alla dessa attribut måste matcha exakt för att resultera i en matchning.

Kommentar

Om både include och exclude anges include kontrolleras egenskaperna innan exclude egenskaperna kontrolleras.

Exempelanvändning

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

Mer information finns i Exempel på telemetriprocessor.

Loggprocessor

Kommentar

Loggprocessorer är tillgängliga från version 3.1.1.

Loggprocessorn ändrar antingen loggmeddelandetexten eller attributen för en logg baserat på loggmeddelandetexten. Det kan ge stöd för möjligheten att inkludera eller exkludera loggar.

Uppdatera loggmeddelandetexten

Avsnittet body kräver inställningen fromAttributes . Värdena från dessa attribut används för att skapa en ny brödtext, sammanfogad i den ordning som konfigurationen anger. Processorn ändrar endast loggtexten om alla dessa attribut finns i loggen.

Inställningen separator är valfri. Den här inställningen är en sträng. Du kan ange det för att dela upp värden.

Kommentar

Om namnbytet förlitar sig på attributprocessorn för att ändra attribut kontrollerar du att loggprocessorn har angetts efter attributprocessorn i pipelinespecifikationen.

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

Extrahera attribut från loggmeddelandetexten

Avsnittet toAttributes visar de reguljära uttryck som matchar loggmeddelandetexten. Den extraherar attribut baserat på underuttryck.

Inställningen rules krävs. Den här inställningen visar de regler som används för att extrahera attributvärden från brödtexten.

Extraherade attributnamn ersätter värdena i loggmeddelandetexten. Varje regel i listan är en mönstersträng för reguljära uttryck (regex).

Så här ersätter extraherade attributnamn värden:

  1. Loggmeddelandetexten kontrolleras mot regex.
  2. Alla namngivna underuttryck av regex extraheras som attribut om regex matchar.
  3. De extraherade attributen läggs till i loggen.
  4. Varje underuttrycksnamn blir ett attributnamn.
  5. Den underuttrycksmatchade delen blir attributvärdet.
  6. Det extraherade attributnamnet ersätter den matchade delen i loggnamnet. Om attributen redan finns i loggen skrivs de över.

Den här processen upprepas för alla regler i den ordning de anges. Varje efterföljande regel fungerar på loggnamnet som är utdata från den tidigare regeln.

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

Inkludera kriterier och exkludera kriterier

Loggprocessorer stöder valfritt include och exclude villkor. En loggprocessor tillämpas endast på telemetri som matchar dess include kriterier (om den är tillgänglig) och inte matchar dess exclude kriterier (om den är tillgänglig).

Om du vill konfigurera det här alternativet under include eller exclude (eller båda) anger du matchType och attributes. Konfigurationen include eller exclude tillåter mer än ett angivet villkor. Alla angivna villkor måste utvärderas till true för att resultera i en matchning.

  • Obligatoriskt fält:
    • matchType styr hur objekt i attributes matriser tolkas. Möjliga värden är regexp och strict. Reguljära uttrycksmatchningar utförs mot hela attributvärdet, så om du vill matcha ett värde som innehåller abc var som helst i det måste du använda .*abc.*.
    • attributes anger listan över attribut som ska matchas. Alla dessa attribut måste matcha exakt för att resultera i en matchning.

Kommentar

Om både include och exclude anges include kontrolleras egenskaperna innan exclude egenskaperna kontrolleras.

Kommentar

Loggprocessorer stöder spanNamesinte .

Exempelanvändning

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

Mer information finns i Exempel på telemetriprocessor.

Måttfilter

Kommentar

Måttfilter är tillgängliga från version 3.1.1.

Måttfilter används för att exkludera vissa mått för att styra inmatningskostnaden.

Måttfilter stöder exclude endast kriterier. Mått som matchar kriterierna exclude exporteras inte.

Om du vill konfigurera det här alternativet under excludeanger du matchType en eller flera metricNames.

  • Obligatoriskt fält:
    • matchType styr hur objekt i metricNames matchas. Möjliga värden är regexp och strict. Reguljära uttrycksmatchningar utförs mot hela attributvärdet, så om du vill matcha ett värde som innehåller abc var som helst i det måste du använda .*abc.*.
    • metricNames måste matcha minst ett av objekten.

Exempelanvändning

Följande exempel visar hur du exkluderar mått med namnen "metricA" och "metricB":

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

I följande exempel visas hur du inaktiverar alla mått, inklusive standardmått för automatisk insamling av prestanda som processor och minne.

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

Standardmått som samlas in av Java-agenten

Måttnamn Måtttyp beskrivning Filtrerbar
Current Thread Count anpassade mått Se ThreadMXBean.getThreadCount(). ja
Loaded Class Count anpassade mått Se ClassLoadingMXBean.getLoadedClassCount(). ja
GC Total Count anpassade mått Summan av antalet för alla GarbageCollectorMXBean-instanser (diff sedan senast rapporterade). Se GarbageCollectorMXBean.getCollectionCount(). ja
GC Total Time anpassade mått Tidsåtgång för alla GarbageCollectorMXBean-instanser (diff sedan senast rapporterade). Se GarbageCollectorMXBean.getCollectionTime(). ja
Heap Memory Used (MB) anpassade mått Se MemoryMXBean.getHeapMemoryUsage().getUsed(). ja
% Of Max Heap Memory Used anpassade mått java.lang:type=Memory/maximum amount of memory in bytes. Se Minnesanvändning ja
\Processor(_Total)\% Processor Time standardmått Skillnad i systemomfattande processorbelastningsräknare (endast användare och system) dividerat med antalet logiska processorer under ett givet tidsintervall nej
\Process(??APP_WIN32_PROC??)\% Processor Time standardmått Se OperatingSystemMXBean.getProcessCpuTime() (diff sedan senast rapporterad, normaliserad efter tid och antal processorer). nej
\Process(??APP_WIN32_PROC??)\Private Bytes standardmått Summan av MemoryMXBean.getHeapMemoryUsage() och MemoryMXBean.getNonHeapMemoryUsage(). nej
\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec standardmått /proc/[pid]/io Summan av byte som lästs och skrivits av processen (diff sedan senast rapporterade). Se proc(5). nej
\Memory\Available Bytes standardmått Se OperatingSystemMXBean.getFreePhysicalMemorySize(). nej

Vanliga frågor och svar

Varför bearbetar inte loggfilerna för loggprocessorn med TelemetryClient.trackTrace()?

TelemetryClient.trackTrace() är en del av Application Insights klassiska SDK-brygga och loggprocessorerna fungerar bara med den nya OpenTelemetry-baserade instrumentationen.