Bagikan melalui

Prosesor telemetri (pratinjau) - Azure Monitor Application Insights for Java

  • Artikel

Catatan

Fitur prosesor telemetri ditetapkan sebagai pratinjau karena kami tidak dapat menjamin kompatibilitas mundur dari rilis ke rilis akibat status eksperimental dari konvensi semantik atribut. Namun, fitur ini telah diuji dan didukung dalam produksi.

Application Insights Java 3.x dapat memproses data telemetri sebelum data diekspor.

Beberapa kasus penggunaan:

  • Melakukan masking data sensitif.
  • Secara kondisional menambahkan dimensi kustom.
  • Memperbarui nama rentang, yang digunakan untuk menggabungkan telemetri serupa di portal Microsoft Azure.
  • Jatuhkan atribut rentang tertentu untuk mengontrol biaya penyerapan.
  • Filter beberapa metrik untuk mengontrol biaya penyerapan.

Catatan

Jika Anda ingin menghilangkan rentang spesifik (semua) untuk mengontrol biaya penyerapan, lihat pengambilalihan pengambilan sampel.

Terminologi

Sebelum Anda mempelajari tentang prosesor telemetri, Anda harus memahami istilah rentang dan log.

Rentang adalah jenis telemetri yang mewakili salah satu dari:

  • Permintaan masuk.
  • Dependensi keluar (misalnya, panggilan jarak jauh ke layanan lain).
  • Dependensi dalam proses (misalnya, pekerjaan yang sedang dilakukan oleh sub-komponen layanan).

Log adalah tipe telemetri yang mewakili:

  • data log yang diambil dari Log4j, Logback, dan java.util.logging

Untuk prosesor telemetri, komponen rentang/log berikut ini penting:

  • Nama
  • Isi
  • Atribut

Nama rentang adalah tampilan utama untuk permintaan dan dependensi di portal Microsoft Azure. Atribut span mewakili properti standar dan kustom dari permintaan atau dependensi tertentu.

Pesan atau isi jejak adalah tampilan utama untuk log di portal Microsoft Azure. Atribut log mewakili properti standar dan kustom dari log tertentu.

Tipe prosesor telemetri

Saat ini, empat jenis prosesor telemetri adalah

  • Prosesor atribut
  • Prosesor rentang
  • Prosesor log
  • Filter metrik

Prosesor atribut dapat menyisipkan, memperbarui, menghapus, atau memberikan hash pada atribut item telemetri (span atau log). Atribut juga dapat menggunakan ekspresi reguler untuk mengekstrak satu atau beberapa atribut baru dari atribut yang ada.

Prosesor rentang dapat memperbarui nama telemetri permintaan dan dependensi. Prosesor rentang juga dapat menggunakan ekspresi reguler untuk mengekstrak satu atau beberapa atribut baru dari nama rentang.

Prosesor log dapat memperbarui nama telemetri log. Prosesor log juga dapat menggunakan ekspresi reguler untuk mengekstrak satu atau beberapa atribut baru dari nama log.

Filter metrik dapat memfilter metrik untuk membantu mengontrol biaya penyerapan.

Catatan

Saat ini, prosesor telemetri hanya memproses atribut string tipe. Prosesor-prosesor tersebut tidak memproses atribut tipe Boolean atau angka.

Memulai

Untuk memulai, buat file konfigurasi bernama applicationinsights.json. Simpan di direktori yang sama dengan applicationinsights-agent-*.jar. Gunakan templat berikut ini.

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

Prosesor atribut

Prosesor atribut memodifikasi atribut sebuah span atau sebuah log. Prosesor ini dapat mendukung kemampuan untuk memasukkan atau mengecualikan span atau log. Dibutuhkan daftar tindakan yang dilakukan dalam urutan yang ditentukan file konfigurasi. Prosesor mendukung tindakan berikut ini:

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

insert

Tindakan insert menyisipkan atribut baru dalam item telemetri tempat key belum ada.

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

Tindakan insert memerlukan pengaturan berikut:

  • key
  • Baik value atau fromAttribute
  • action: insert

update

Tindakan update memperbarui atribut dalam item telemetri tempat key sudah ada.

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

Tindakan update memerlukan pengaturan berikut:

  • key
  • Baik value atau fromAttribute
  • action: update

delete

Tindakan delete menghapus atribut dari item telemetri.

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

Tindakan delete memerlukan pengaturan berikut:

  • key
  • action: delete

hash

Tindakan hash memberikan hash (SHA1) pada nilai atribut yang ada.

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

Tindakan hash memerlukan pengaturan berikut:

  • key
  • action: hash

extract

Catatan

Fitur extract ini hanya tersedia di versi 3.0.2 dan yang lebih baru.

Tindakan extract mengekstrak nilai menggunakan aturan ekspresi reguler dari kunci input ke kunci target yang ditentukan oleh aturan. Jika kunci target sudah ada, extract tindakan akan mengambil alih kunci target. Tindakan ini berperilaku seperti pengaturan toAttributes prosesor rentang, saat atribut yang ada adalah sumbernya.

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

Tindakan extract memerlukan pengaturan berikut:

  • key
  • pattern
  • action: extract

mask

Catatan

Fitur mask ini hanya tersedia di versi 3.2.5 dan yang lebih baru.

Tindakan menutupi mask nilai atribut dengan menggunakan aturan ekspresi reguler yang ditentukan dalam pattern dan replace.

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

Tindakan mask memerlukan pengaturan berikut:

  • key
  • pattern
  • replace
  • action: mask

pattern dapat berisi grup bernama yang ditempatkan antara ?< dan >:. Contoh: (?<userGroupName>[a-zA-Z.:\/]+)\d+? Grup adalah (?<userGroupName>[a-zA-Z.:\/]+) dan userGroupName adalah nama grup. pattern kemudian dapat berisi grup bernama yang sama yang ditempatkan di antara ${ dan } diikuti oleh masker. Contoh di mana masker adalah **: ${userGroupName}**.

Lihat Contoh prosesor telemetri untuk contoh masking.

Menyertakan kriteria dan mengecualikan kriteria

Prosesor atribut mendukung kriteria include dan exclude opsional. Prosesor atribut hanya diterapkan ke telemetri yang cocok dengan kriterianya include (jika tersedia) dan tidak cocok dengan kriterianya exclude (jika tersedia).

Untuk mengonfigurasi opsi ini, di bawah include atau exclude (atau keduanya), tentukan setidaknya satu matchType dan pilih spanNames atau attributes. Konfigurasi include atau exclude memungkinkan lebih dari satu kondisi yang ditentukan. Semua kondisi yang ditentukan harus melakan evaluasi true pada hasil dalam sebuah kecocokan.

  • Bidang yang diperlukan:

    • matchType mengontrol bagaimana item dalam spanNames array dan attributes array ditafsirkan. Nilai yang mungkin adalah regexp dan strict. Pencocokan regex dilakukan terhadap seluruh nilai atribut, jadi jika Anda ingin mencocokkan nilai yang berisi abc di mana pun di dalamnya, maka Anda perlu menggunakan .*abc.*.

  • Bidang opsional:

    • spanNames harus cocok dengan setidaknya salah satu item.
    • attributes menentukan daftar atribut yang cocok. Semua atribut ini harus sama persis untuk menghasilkan kecocokan.

Catatan

Jika include dan exclude keduanya ditentukan, properti include diperiksa sebelum properti exclude diperiksa.

Catatan

Jika konfigurasi include atau exclude tidak memiliki spanNames yang ditentukan, maka kriteria pencocokan diterapkan pada kedua spans dan logs.

Penggunaan sampel

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

Untuk informasi selengkapnya, lihat Contoh prosesor telemetri.

Prosesor rentang

Prosesor rentang memodifikasi nama rentang atau atribut rentang berdasarkan nama rentang. Ini dapat mendukung kemampuan untuk memasukkan atau mengecualikan rentang.

Berikan nama pada rentang

Bagian name ini memerlukan pengaturan fromAttributes. Nilai dari atribut ini digunakan untuk membuat nama baru, digabungkan dalam urutan yang ditentukan oleh konfigurasi. Prosesor mengubah nama rentang hanya jika semua atribut ini ada pada rentang.

Pengaturan separator bersifat opsional. Pengaturan ini adalah string, dan Anda dapat menggunakan nilai terpisah.

Catatan

Jika mengganti nama bergantung pada prosesor atribut untuk memodifikasi atribut, pastikan prosesor rentang ditentukan setelah prosesor atribut dalam spesifikasi alur.

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

Mengekstrak atribut dari nama rentang

Bagian toAttributes ini mencantumkan ekspresi reguler agar sesuai dengan nama rentang. Ini mengekstrak atribut berdasarkan subekspresi.

Pengaturan rules diperlukan. Pengaturan ini mencantumkan aturan yang digunakan untuk mengekstrak nilai atribut dari nama rentang.

Nama atribut yang diekstrak menggantikan nilai dalam nama rentang. Setiap aturan dalam daftar adalah string pola ekspresi reguler (regex).

Berikut adalah cara nama atribut yang diekstrak menggantikan nilai:

  1. Nama rentang diperiksa terhadap regex.
  2. Semua subekspresi bernama regex diekstrak sebagai atribut jika regex cocok.
  3. Atribut yang diekstrak ditambahkan ke rentang.
  4. Setiap nama subekspresi menjadi nama atribut.
  5. Bagian subekspresi yang cocok menjadi nilai atribut.
  6. Nama atribut yang diekstrak menggantikan bagian yang cocok dalam nama rentang. Jika atribut sudah ada dalam rentang, atribut tersebut ditimpa.

Proses ini diulangi untuk semua aturan dalam urutan yang ditentukan. Setiap aturan berikutnya bekerja pada nama rentang yang menjadi output dari aturan sebelumnya.

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

Atribut rentang umum

Bagian ini mencantumkan beberapa atribut rentang umum yang dapat digunakan oleh prosesor telemetri.

Rentang HTTP

Atribut Tipe Deskripsi
http.request.method (dulunya http.method) string Metode permintaan HTTP.
url.full (rentang klien) atau url.path (rentang server) (dulunya http.url) string URL permintaan HTTP lengkap dalam formulir scheme://host[:port]/path?query[#fragment]. Fragmen biasanya tidak ditransmisikan melalui HTTP. Tetapi jika diketahui, fragmen itu harus dimasukkan.
http.response.status_code (dulunya http.status_code) number kode status respons HTTP.
network.protocol.version (dulunya http.flavor) string Jenis protokol HTTP.
user_agent.original (dulunya http.user_agent) string Nilai header Agen Pengguna HTTP yang dikirim oleh klien.

Rentang Konektivitas Database Java

Tabel berikut ini menjelaskan atribut yang bisa Anda gunakan dalam rentang Java Database Connectivity (JDBC):

Atribut Tipe Deskripsi
db.system string Pengidentifikasi produk sistem pengelolaan database (DBMS) yang digunakan. Lihat Konvensi Semantik untuk operasi database.
db.connection_string string String koneksi yang digunakan untuk terhubung ke database. Kami menyarankan agar Anda menghapus kredensial yang disematkan.
db.user string Nama pengguna untuk mengakses database.
db.name string String yang digunakan untuk melaporkan nama database yang sedang diakses. Untuk perintah yang mengalihkan database, string ini harus diatur ke database target, meski perintah gagal.
db.statement string Pernyataan database yang sedang dijalankan.

Menyertakan kriteria dan mengecualikan kriteria

Prosesor rentang mendukung kriteria include dan exclude opsional. Prosesor rentang hanya diterapkan ke telemetri yang cocok dengan kriterianya include (jika tersedia) dan tidak cocok dengan kriterianya exclude (jika tersedia).

Untuk mengonfigurasi opsi ini di include atau exclude (atau keduanya), tentukan setidaknya satu matchType dan pilih spanNames atau attributes span. Konfigurasi include atau exclude memungkinkan lebih dari satu kondisi yang ditentukan. Semua kondisi yang ditentukan harus melakan evaluasi true pada hasil dalam sebuah kecocokan.

  • Bidang yang diperlukan:

    • matchType mengontrol bagaimana item dalam spanNames array dan attributes array ditafsirkan. Nilai yang mungkin adalah regexp dan strict. Pencocokan regex dilakukan terhadap seluruh nilai atribut, jadi jika Anda ingin mencocokkan nilai yang berisi abc di mana pun di dalamnya, maka Anda perlu menggunakan .*abc.*.

  • Bidang opsional:

    • spanNames harus cocok dengan setidaknya salah satu item.
    • attributes menentukan daftar atribut yang cocok. Semua atribut ini harus sama persis untuk menghasilkan kecocokan.

Catatan

Jika include dan exclude keduanya ditentukan, properti include diperiksa sebelum properti exclude diperiksa.

Penggunaan sampel

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

Untuk informasi selengkapnya, lihat Contoh prosesor telemetri.

Prosesor log

Catatan

Prosesor log tersedia mulai dari versi 3.1.1.

Prosesor log memodifikasi isi pesan log atau atribut log berdasarkan isi pesan log. Ini dapat mendukung kemampuan untuk memasukkan atau mengecualikan log.

Perbarui isi pesan Log

Bagian body ini memerlukan pengaturan fromAttributes. Nilai dari atribut ini digunakan untuk membuat isi baru, digabungkan dalam urutan konfigurasi yang ditentukan. Prosesor mengubah isi log hanya jika semua atribut ini ada di log.

Pengaturan separator bersifat opsional. Pengaturan ini adalah string. Anda dapat menentukannya untuk membagi nilai.

Catatan

Jika mengganti nama bergantung pada prosesor atribut untuk memodifikasi atribut, pastikan prosesor log ditentukan setelah prosesor atribut dalam spesifikasi alur.

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

Mengekstrak atribut dari isi pesan log

Bagian toAttributes ini mencantumkan ekspresi reguler agar sesuai dengan isi pesan log. Ini mengekstrak atribut berdasarkan subekspresi.

Pengaturan rules diperlukan. Pengaturan ini mencantumkan aturan yang digunakan untuk mengekstrak nilai atribut dari isi.

Nama atribut yang diekstrak menggantikan nilai dalam isi pesan log. Setiap aturan dalam daftar adalah string pola ekspresi reguler (regex).

Berikut adalah cara nama atribut yang diekstrak menggantikan nilai:

  1. Isi pesan log diperiksa terhadap regex.
  2. Semua subekspresi bernama regex diekstrak sebagai atribut jika regex cocok.
  3. Atribut yang diekstrak ditambahkan ke log.
  4. Setiap nama subekspresi menjadi nama atribut.
  5. Bagian subekspresi yang cocok menjadi nilai atribut.
  6. Nama atribut yang diekstrak menggantikan bagian yang cocok dalam nama log. Jika atribut sudah ada di log, atribut akan ditimpa.

Proses ini diulangi untuk semua aturan dalam urutan yang ditentukan. Setiap aturan berikutnya bekerja pada nama log yang menjadi output dari aturan sebelumnya.

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

Menyertakan kriteria dan mengecualikan kriteria

Prosesor log mendukung kriteria include dan exclude opsional. Prosesor log hanya diterapkan ke telemetri yang cocok dengan kriterianya include (jika tersedia) dan tidak cocok dengan kriterianya exclude (jika tersedia).

Untuk mengonfigurasi opsi ini, di bawah include atau exclude (atau keduanya), tentukan matchType dan attributes. Konfigurasi include atau exclude memungkinkan lebih dari satu kondisi yang ditentukan. Semua kondisi yang ditentukan harus melakan evaluasi true pada hasil dalam sebuah kecocokan.

  • Bidang yang diperlukan:
    • matchType mengontrol bagaimana item dalam array attributes ditafsirkan. Nilai yang mungkin adalah regexp dan strict. Pencocokan regex dilakukan terhadap seluruh nilai atribut, jadi jika Anda ingin mencocokkan nilai yang berisi abc di mana pun di dalamnya, maka Anda perlu menggunakan .*abc.*.
    • attributes menentukan daftar atribut yang cocok. Semua atribut ini harus sama persis untuk menghasilkan kecocokan.

Catatan

Jika include dan exclude keduanya ditentukan, properti include diperiksa sebelum properti exclude diperiksa.

Catatan

Prosesor log tidak mendukung spanNames.

Penggunaan sampel

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

Untuk informasi selengkapnya, lihat Contoh prosesor telemetri.

Filter metrik

Catatan

Filter metrik tersedia mulai dari versi 3.1.1.

Filter metrik digunakan untuk mengecualikan beberapa metrik untuk membantu mengontrol biaya penyerapan.

Filter metrik hanya mendukung kriteria exclude. Metrik yang cocok dengan kriterianya exclude tidak diekspor.

Untuk mengonfigurasi opsi ini, di bawah exclude, tentukan matchType satu atau beberapa metricNames.

  • Bidang yang diperlukan:
    • matchType mengontrol bagaimana item di metricNames dicocokkan. Nilai yang mungkin adalah regexp dan strict. Pencocokan regex dilakukan terhadap seluruh nilai atribut, jadi jika Anda ingin mencocokkan nilai yang berisi abc di mana pun di dalamnya, maka Anda perlu menggunakan .*abc.*.
    • metricNames harus cocok dengan setidaknya salah satu item.

Penggunaan sampel

Sampel berikut menunjukkan cara mengecualikan metrik dengan nama "metricA" dan "metricB":

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

Sampel berikut menunjukkan cara menonaktifkan semua metrik termasuk metrik performa otomatis default seperti cpu dan memori.

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

Metrik default yang diambil oleh agen Java

Nama metrik Jenis metrik Deskripsi Dapat difilter
Current Thread Count metrik khusus Lihat ThreadMXBean.getThreadCount(). yes
Loaded Class Count metrik khusus Lihat ClassLoadingMXBean.getLoadedClassCount(). yes
GC Total Count metrik khusus Jumlah jumlah di semua instans GarbageCollectorMXBean (berbeda sejak terakhir dilaporkan). Lihat GarbageCollectorMXBean.getCollectionCount(). yes
GC Total Time metrik khusus Jumlah waktu di semua instans GarbageCollectorMXBean (berbeda sejak terakhir dilaporkan). Lihat GarbageCollectorMXBean.getCollectionTime(). yes
Heap Memory Used (MB) metrik khusus Lihat MemoryMXBean.getHeapMemoryUsage().getUsed(). yes
% Of Max Heap Memory Used metrik khusus java.lang:type=Memory/jumlah maksimum memori dalam byte. Lihat MemoryUsage yes
\Processor(_Total)\% Processor Time Metrik default Perbedaan penghitung centang beban CPU lebar sistem (Hanya Pengguna dan Sistem) yang dibagi dengan jumlah prosesor logis dalam interval waktu tertentu no
\Process(??APP_WIN32_PROC??)\% Processor Time Metrik default Lihat OperatingSystemMXBean.getProcessCpuTime() (diff sejak terakhir dilaporkan, dinormalisasi berdasarkan waktu dan jumlah CPU). no
\Process(??APP_WIN32_PROC??)\Private Bytes Metrik default Jumlah MemoryMXBean.getHeapMemoryUsage() dan MemoryMXBean.getNonHeapMemoryUsage(). no
\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec Metrik default /proc/[pid]/io Jumlah byte yang dibaca dan ditulis oleh proses (diff sejak terakhir dilaporkan). Lihat proc(5). no
\Memory\Available Bytes Metrik default Lihat OperatingSystemMXBean.getFreePhysicalMemorySize(). no

Tanya jawab umum

Mengapa prosesor log tidak memproses file log menggunakan TelemetryClient.trackTrace()?

TelemetryClient.trackTrace() adalah bagian dari jembatan Application Insights Classic SDK, dan prosesor log hanya berfungsi dengan instrumentasi berbasis OpenTelemetry baru.