Udostępnij za pośrednictwem

Procesory telemetryczne (wersja zapoznawcza) — usługa Azure Monitor Application Insights dla języka Java

  • Artykuł

Uwaga

Funkcja procesorów telemetrycznych jest wyznaczona jako wersja zapoznawcza, ponieważ nie możemy zagwarantować zgodności z poprzednimi wersjami z wersji do wydania ze względu na stan eksperymentalny konwencji semantycznych atrybutów. Jednak funkcja została przetestowana i jest obsługiwana w środowisku produkcyjnym.

Środowisko Java 3.x usługi Application Insights może przetwarzać dane telemetryczne przed wyeksportowanie danych.

Niektóre przypadki użycia:

  • Maskuj poufne dane.
  • Warunkowe dodawanie wymiarów niestandardowych.
  • Zaktualizuj nazwę zakresu, która jest używana do agregowania podobnych danych telemetrycznych w witrynie Azure Portal.
  • Porzucanie określonych atrybutów zakresu w celu kontrolowania kosztów pozyskiwania.
  • Odfiltruj niektóre metryki, aby kontrolować koszty pozyskiwania.

Uwaga

Jeśli chcesz usunąć określone (całe) zakresy w celu kontrolowania kosztów pozyskiwania, zobacz przesłonięcia próbkowania.

Terminologia

Przed zapoznaniem się z procesorami telemetrii należy zrozumieć terminy dotyczące zakresu i dziennika.

Zakres to typ telemetrii, który reprezentuje jedną z:

  • Żądanie przychodzące.
  • Zależność wychodząca (na przykład zdalne wywołanie do innej usługi).
  • Zależność w procesie (na przykład praca wykonywana przez podskładniki usługi).

Dziennik jest typem danych telemetrycznych reprezentujących:

  • dane dziennika przechwycone z dzienników Log4j, Logback i java.util.logging

W przypadku procesorów telemetrycznych te składniki span/log są ważne:

  • Nazwisko
  • Treść
  • Atrybuty

Nazwa zakresu jest podstawowym wyświetlaniem żądań i zależności w witrynie Azure Portal. Atrybuty span reprezentują zarówno właściwości standardowe, jak i niestandardowe danego żądania lub zależności.

Komunikat śledzenia lub treść jest podstawowym wyświetlaniem dzienników w witrynie Azure Portal. Atrybuty dziennika reprezentują zarówno standardowe, jak i niestandardowe właściwości danego dziennika.

Typy procesorów telemetrycznych

Obecnie cztery typy procesorów telemetrii to

  • Procesory atrybutów
  • Procesory obejmujące
  • Procesory dzienników
  • Filtry metryk

Procesor atrybutów może wstawiać, aktualizować, usuwać lub skróty atrybutów elementu telemetrii (span lub log). Może również użyć wyrażenia regularnego, aby wyodrębnić jeden lub więcej nowych atrybutów z istniejącego atrybutu.

Procesor zakresu może zaktualizować nazwę telemetrii żądań i zależności. Może również użyć wyrażenia regularnego, aby wyodrębnić jeden lub więcej nowych atrybutów z nazwy zakresu.

Procesor dzienników może zaktualizować nazwę telemetrii dzienników. Może również użyć wyrażenia regularnego, aby wyodrębnić jeden lub więcej nowych atrybutów z nazwy dziennika.

Filtr metryki może filtrować metryki, aby ułatwić kontrolowanie kosztów pozyskiwania.

Uwaga

Obecnie procesory telemetryczne przetwarzają tylko atrybuty typu ciąg. Nie przetwarzają atrybutów typu Wartość logiczna ani liczba.

Wprowadzenie

Aby rozpocząć, utwórz plik konfiguracji o nazwie applicationinsights.json. Zapisz go w tym samym katalogu co applicationinsights-agent-*.jar. Użyj następującego szablonu.

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

Procesor atrybutów

Procesor atrybutów modyfikuje atrybuty obiektu span lub log. Może obsługiwać możliwość dołączania lub wykluczania lub log.span Wykonuje listę akcji wykonywanych w kolejności określonej przez plik konfiguracji. Procesor obsługuje następujące akcje:

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

insert

Akcja insert wstawia nowy atrybut w elemencie telemetrii, w którym key jeszcze nie istnieje.

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

Akcja insert wymaga następujących ustawień:

  • key
  • value lub fromAttribute.
  • action: insert

update

Akcja update aktualizuje atrybut w elemencie telemetrii, w którym key już istnieje.

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

Akcja update wymaga następujących ustawień:

  • key
  • value lub fromAttribute.
  • action: update

delete

Akcja delete usuwa atrybut z elementu telemetrii.

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

Akcja delete wymaga następujących ustawień:

  • key
  • action: delete

hash

Skróty hash akcji (SHA1) istniejącą wartość atrybutu.

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

Akcja hash wymaga następujących ustawień:

  • key
  • action: hash

extract

Uwaga

Ta extract funkcja jest dostępna tylko w wersji 3.0.2 lub nowszej.

Akcja extract wyodrębnia wartości przy użyciu reguły wyrażenia regularnego z klucza wejściowego do kluczy docelowych określonych przez regułę. Jeśli klucz docelowy już istnieje, extract akcja zastępuje klucz docelowy. Ta akcja działa jak ustawienie procesora toAttributes span, gdzie istniejący atrybut jest źródłem.

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

Akcja extract wymaga następujących ustawień:

  • key
  • pattern
  • action: extract

mask

Uwaga

Ta mask funkcja jest dostępna tylko w wersji 3.2.5 lub nowszej.

Akcja mask maskuje wartości atrybutów przy użyciu reguły wyrażenia regularnego określonego w i replacepattern .

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

Akcja mask wymaga następujących ustawień:

  • key
  • pattern
  • replace
  • action: mask

pattern może zawierać nazwaną grupę umieszczoną między ?< i >:. Przykład: (?<userGroupName>[a-zA-Z.:\/]+)\d+? Grupa to (?<userGroupName>[a-zA-Z.:\/]+) i userGroupName jest nazwą grupy. pattern może następnie zawierać tę samą grupę o nazwie między ${ i } po której następuje maska. Przykład, w którym maska to **: ${userGroupName}**.

Zobacz Przykłady procesora telemetrii, aby zapoznać się z przykładami maskowania.

Uwzględnij kryteria i wyklucz kryteria

Procesory atrybutów obsługują opcjonalne include i exclude kryteria. Procesor atrybutów jest stosowany tylko do danych telemetrycznych, które spełniają kryteria include (jeśli są dostępne) i nie są zgodne z jej exclude kryteriami (jeśli są dostępne).

Aby skonfigurować tę opcję, w obszarze include lub exclude (lub obu), określ co najmniej jeden matchType i spanNames lub .attributes Konfiguracja include lub exclude zezwala na więcej niż jeden określony warunek. Wszystkie określone warunki muszą mieć wartość true, aby spowodować dopasowanie.

  • Wymagane pola:

    • matchType określa sposób interpretowania elementów w spanNames tablicach i attributes tablicach. Możliwe wartości to regexp i strict. Dopasowania wyrażeń regularnych są wykonywane względem całej wartości atrybutu, więc jeśli chcesz dopasować wartość zawierającą abc ją w dowolnym miejscu, musisz użyć polecenia .*abc.*.

  • Pola opcjonalne:

    • spanNames musi odpowiadać co najmniej jednemu z elementów.
    • attributes określa listę atrybutów, które mają być zgodne. Wszystkie te atrybuty muszą być dokładnie zgodne, aby spowodować dopasowanie.

Uwaga

Jeśli określono obie include wartości i exclude , include właściwości są sprawdzane przed sprawdzeniem exclude właściwości.

Uwaga

include Jeśli konfiguracja lub exclude nie została spanNames określona, kryteria dopasowania są stosowane zarówno w systemach , jak spans i logs.

Przykładowe zastosowanie

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

Aby uzyskać więcej informacji, zobacz Przykłady procesora telemetrii.

Procesor rozpiętości

Procesor span modyfikuje nazwę zakresu lub atrybuty zakresu na podstawie nazwy zakresu. Może obsługiwać możliwość dołączania lub wykluczania zakresów.

Nazwij zakres

Sekcja name wymaga fromAttributes ustawienia. Wartości z tych atrybutów służą do tworzenia nowej nazwy, łączonej w kolejności określonej przez konfigurację. Procesor zmienia nazwę zakresu tylko wtedy, gdy wszystkie te atrybuty znajdują się na rozpiętości.

Ustawienie separator jest opcjonalne. To ustawienie jest ciągiem i można użyć wartości podzielonych.

Uwaga

Jeśli zmiana nazwy zależy od procesora atrybutów w celu zmodyfikowania atrybutów, upewnij się, że procesor span jest określony po procesor atrybutów w specyfikacji potoku.

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

Wyodrębnianie atrybutów z nazwy zakresu

Sekcja toAttributes zawiera listę wyrażeń regularnych odpowiadających nazwie zakresu. Wyodrębnia atrybuty na podstawie podwyrażeń.

Ustawienie rules jest wymagane. To ustawienie wyświetla listę reguł używanych do wyodrębniania wartości atrybutów z nazwy zakresu.

Wyodrębnione nazwy atrybutów zastępują wartości w nazwie zakresu. Każda reguła na liście jest ciągiem wzorca wyrażenia regularnego (regex).

Oto jak wyodrębnione nazwy atrybutów zastępują wartości:

  1. Nazwa zakresu jest sprawdzana względem wyrażenia regularnego.
  2. Wszystkie nazwane podwyrażenia wyrażenia regularnego są wyodrębniane jako atrybuty, jeśli wyrażenie regularne jest zgodne.
  3. Wyodrębnione atrybuty są dodawane do zakresu.
  4. Każda nazwa podexpressionu staje się nazwą atrybutu.
  5. Podexpressiona dopasowana część staje się wartością atrybutu.
  6. Nazwa wyodrębnionego atrybutu zastępuje dopasowaną część w nazwie zakresu. Jeśli atrybuty już istnieją w zakresie, są one zastępowane.

Ten proces jest powtarzany dla wszystkich reguł w podanej kolejności. Każda kolejna reguła działa na nazwie zakresu, która jest wynikiem poprzedniej reguły.

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

Typowe atrybuty zakresu

W tej sekcji wymieniono niektóre typowe atrybuty zakresu, których mogą używać procesory telemetryczne.

Zakresy HTTP

Atrybut Type Opis
http.request.method(używane do )http.method string Metoda żądania HTTP.
url.full (zakres klienta) lub url.path (zakres serwera) (używany do http.url) string Pełny adres URL żądania HTTP w formularzu scheme://host[:port]/path?query[#fragment]. Fragment zazwyczaj nie jest przesyłany za pośrednictwem protokołu HTTP. Ale jeśli fragment jest znany, powinien zostać uwzględniony.
http.response.status_code(używane do )http.status_code Liczba Kod stanu odpowiedzi HTTP.
network.protocol.version(używane do )http.flavor string Typ protokołu HTTP.
user_agent.original(używane do )http.user_agent string Wartość nagłówka HTTP User-Agent wysłanego przez klienta.

Łączność z bazą danych Java obejmuje zakresy

W poniższej tabeli opisano atrybuty, których można używać w zakresie łączności bazy danych Java (JDBC):

Atrybut Type opis
db.system string Identyfikator używanego produktu systemu zarządzania bazami danych (DBMS). Zobacz Semantyczne konwencje dotyczące operacji bazy danych.
db.connection_string string Parametry połączenia używane do nawiązywania połączenia z bazą danych. Zalecamy usunięcie osadzonych poświadczeń.
db.user string Nazwa użytkownika na potrzeby uzyskiwania dostępu do bazy danych.
db.name string Ciąg używany do raportowania nazwy bazy danych, do którego uzyskuje się dostęp. W przypadku poleceń, które przełączają bazę danych, ten ciąg powinien być ustawiony na docelową bazę danych, nawet jeśli polecenie zakończy się niepowodzeniem.
db.statement string Instrukcja bazy danych, która jest uruchamiana.

Uwzględnij kryteria i wyklucz kryteria

Procesory span obsługują opcjonalne include i exclude kryteria. Procesor zakresu jest stosowany tylko do danych telemetrycznych, które spełniają kryteria include (jeśli są dostępne) i nie są zgodne z jej exclude kryteriami (jeśli są dostępne).

Aby skonfigurować tę opcję, w obszarze include lub exclude (lub obu), określ co najmniej jeden matchType i spanNames lub zakres attributes. Konfiguracja include lub exclude zezwala na więcej niż jeden określony warunek. Wszystkie określone warunki muszą mieć wartość true, aby spowodować dopasowanie.

  • Wymagane pola:

    • matchType określa sposób interpretowania elementów w spanNames tablicach i attributes tablicach. Możliwe wartości to regexp i strict. Dopasowania wyrażeń regularnych są wykonywane względem całej wartości atrybutu, więc jeśli chcesz dopasować wartość zawierającą abc ją w dowolnym miejscu, musisz użyć polecenia .*abc.*.

  • Pola opcjonalne:

    • spanNames musi odpowiadać co najmniej jednemu z elementów.
    • attributes określa listę atrybutów, które mają być zgodne. Wszystkie te atrybuty muszą być dokładnie zgodne, aby spowodować dopasowanie.

Uwaga

Jeśli określono obie include wartości i exclude , include właściwości są sprawdzane przed sprawdzeniem exclude właściwości.

Przykładowe zastosowanie

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

Aby uzyskać więcej informacji, zobacz Przykłady procesora telemetrii.

Procesor dzienników

Uwaga

Procesory dzienników są dostępne od wersji 3.1.1.

Procesor dziennika modyfikuje treść komunikatu dziennika lub atrybuty dziennika na podstawie treści komunikatu dziennika. Może obsługiwać możliwość dołączania lub wykluczania dzienników.

Aktualizowanie treści komunikatu dziennika

Sekcja body wymaga fromAttributes ustawienia. Wartości z tych atrybutów służą do tworzenia nowej treści, łączonej w kolejności określonej przez konfigurację. Procesor zmienia treść dziennika tylko wtedy, gdy wszystkie te atrybuty są obecne w dzienniku.

Ustawienie separator jest opcjonalne. To ustawienie jest ciągiem. Można określić ją tak, aby dzieliła wartości.

Uwaga

Jeśli zmiana nazwy zależy od procesora atrybutów w celu zmodyfikowania atrybutów, upewnij się, że procesor dzienników jest określony po procesorze atrybutów w specyfikacji potoku.

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

Wyodrębnianie atrybutów z treści komunikatu dziennika

Sekcja toAttributes zawiera listę wyrażeń regularnych odpowiadających treści komunikatu dziennika. Wyodrębnia atrybuty na podstawie podwyrażeń.

Ustawienie rules jest wymagane. To ustawienie wyświetla listę reguł używanych do wyodrębniania wartości atrybutów z treści.

Wyodrębnione nazwy atrybutów zastępują wartości w treści komunikatu dziennika. Każda reguła na liście jest ciągiem wzorca wyrażenia regularnego (regex).

Oto jak wyodrębnione nazwy atrybutów zastępują wartości:

  1. Treść komunikatu dziennika jest sprawdzana względem wyrażenia regularnego.
  2. Wszystkie nazwane podwyrażenia wyrażenia regularnego są wyodrębniane jako atrybuty, jeśli wyrażenie regularne jest zgodne.
  3. Wyodrębnione atrybuty są dodawane do dziennika.
  4. Każda nazwa podexpressionu staje się nazwą atrybutu.
  5. Podexpressiona dopasowana część staje się wartością atrybutu.
  6. Nazwa wyodrębnionego atrybutu zastępuje dopasowaną część w nazwie dziennika. Jeśli atrybuty już istnieją w dzienniku, zostaną zastąpione.

Ten proces jest powtarzany dla wszystkich reguł w podanej kolejności. Każda kolejna reguła działa na nazwie dziennika, która jest wynikiem poprzedniej reguły.

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

Uwzględnij kryteria i wyklucz kryteria

Procesory dzienników obsługują opcjonalne include i exclude kryteria. Procesor dzienników jest stosowany tylko do danych telemetrycznych, które spełniają kryteria include (jeśli są dostępne) i nie są zgodne z jej exclude kryteriami (jeśli są dostępne).

Aby skonfigurować tę opcję, w obszarze include lub exclude (lub obu), określ wartości matchType i attributes. Konfiguracja include lub exclude zezwala na więcej niż jeden określony warunek. Wszystkie określone warunki muszą mieć wartość true, aby spowodować dopasowanie.

  • Wymagane pole:
    • matchType określa sposób interpretowania elementów w attributes tablicach. Możliwe wartości to regexp i strict. Dopasowania wyrażeń regularnych są wykonywane względem całej wartości atrybutu, więc jeśli chcesz dopasować wartość zawierającą abc ją w dowolnym miejscu, musisz użyć polecenia .*abc.*.
    • attributes określa listę atrybutów, które mają być zgodne. Wszystkie te atrybuty muszą być dokładnie zgodne, aby spowodować dopasowanie.

Uwaga

Jeśli określono obie include wartości i exclude , include właściwości są sprawdzane przed sprawdzeniem exclude właściwości.

Uwaga

Procesory dzienników nie obsługują spanNamespolecenia .

Przykładowe zastosowanie

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

Aby uzyskać więcej informacji, zobacz Przykłady procesora telemetrii.

Filtr metryk

Uwaga

Filtry metryk są dostępne od wersji 3.1.1.

Filtry metryk służą do wykluczania niektórych metryk w celu kontrolowania kosztów pozyskiwania.

Filtry metryk obsługują tylko kryteria obsługi exclude . Metryki spełniające kryteria exclude nie są eksportowane.

Aby skonfigurować tę opcję, w obszarze excludeokreśl matchType co najmniej jeden metricNameselement .

  • Wymagane pole:
    • matchType określa sposób dopasowywania elementów metricNames . Możliwe wartości to regexp i strict. Dopasowania wyrażeń regularnych są wykonywane względem całej wartości atrybutu, więc jeśli chcesz dopasować wartość zawierającą abc ją w dowolnym miejscu, musisz użyć polecenia .*abc.*.
    • metricNames musi odpowiadać co najmniej jednemu z elementów.

Przykładowe zastosowanie

W poniższym przykładzie pokazano, jak wykluczyć metryki o nazwach "metricA" i "metricB":

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

W poniższym przykładzie pokazano, jak wyłączyć wszystkie metryki, w tym domyślne metryki wydajności, takie jak procesor i pamięć.

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

Domyślne metryki przechwycone przez agenta Java

Nazwa metryki Typ metryki opis Filtrowanie
Current Thread Count metryki niestandardowe Zobacz ThreadMXBean.getThreadCount(). tak
Loaded Class Count metryki niestandardowe Zobacz ClassLoadingMXBean.getLoadedClassCount(). tak
GC Total Count metryki niestandardowe Suma liczby wszystkich wystąpień GarbageCollectorMXBean (różnice od ostatniego zgłoszenia). Zobacz GarbageCollectorMXBean.getCollectionCount(). tak
GC Total Time metryki niestandardowe Suma czasu dla wszystkich wystąpień GarbageCollectorMXBean (różnice od ostatniego zgłoszenia). Zobacz GarbageCollectorMXBean.getCollectionTime(). tak
Heap Memory Used (MB) metryki niestandardowe Zobacz MemoryMXBean.getHeapMemoryUsage().getUsed(). tak
% Of Max Heap Memory Used metryki niestandardowe java.lang:type=Memory / maksymalna ilość pamięci w bajtach. Zobacz PamięćUsage tak
\Processor(_Total)\% Processor Time domyślne metryki Różnica w licznikach znaczników obciążenia procesora CPU (tylko użytkownik i system) podzielonych przez liczbę procesorów logicznych w danym interwale czasu nie
\Process(??APP_WIN32_PROC??)\% Processor Time domyślne metryki Zobacz OperatingSystemMXBean.getProcessCpuTime() (różnice od czasu ostatniego zgłoszenia, znormalizowane według czasu i liczby procesorów CPU). nie
\Process(??APP_WIN32_PROC??)\Private Bytes domyślne metryki Suma pamięciMXBean.getHeapMemoryUsage() i MemoryMXBean.getNonHeapMemoryUsage(). nie
\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec domyślne metryki /proc/[pid]/io Suma bajtów odczytanych i zapisanych przez proces (różnice od ostatniego zgłoszenia). Zobacz proc(5). nie
\Memory\Available Bytes domyślne metryki Zobacz OperatingSystemMXBean.getFreePhysicalMemorySize(). nie

Często zadawane pytania

Dlaczego procesor dziennika nie przetwarza plików dziennika przy użyciu elementu TelemetryClient.trackTrace()?

TelemetryClient.trackTrace() jest częścią klasycznego mostka zestawu SDK usługi Application Insights, a procesory dzienników współpracują tylko z nową instrumentacją opartą na protokole OpenTelemetry.