refinery
v2.8.4
Untuk daftar rinci permintaan tarik tertaut yang digabungkan di setiap rilis, lihat Changelog.md. Untuk informasi yang lebih mudah dibaca tentang perubahan terbaru, silakan lihat rilis_notes.md.
Refinery adalah proxy pengambilan sampel berbasis ekor dan beroperasi pada tingkat seluruh jejak. Kilang memeriksa seluruh jejak dan secara cerdas menerapkan keputusan pengambilan sampel untuk setiap jejak. Keputusan ini menentukan apakah akan menyimpan atau menjatuhkan data jejak dalam data sampel yang diteruskan ke sarang lebah.
Model pengambilan sampel berbasis ekor memungkinkan Anda untuk memeriksa seluruh jejak pada satu waktu dan membuat keputusan untuk mencicipi berdasarkan isinya. Misalnya, data Anda mungkin memiliki rentang root yang berisi kode status HTTP untuk melayani untuk permintaan, dan rentang lain yang berisi informasi tentang apakah data tersebut dilayani dari cache. Menggunakan kilang, Anda dapat memilih untuk menyimpan hanya jejak yang memiliki kode status 500 dan juga disajikan dari cache.
Dukungan kilang beberapa jenis pengambilan sampel ekor:
http.status_code , Anda dapat memasukkan dalam data sampel Anda:2xx4xx5xxRefinery memungkinkan Anda menggabungkan semua teknik di atas untuk mencapai perilaku pengambilan sampel yang Anda inginkan.
Kilang dirancang untuk duduk di dalam infrastruktur Anda di mana semua jejak dapat mencapainya. Kilang dapat menjalankan mandiri atau digunakan dalam sekelompok dua atau lebih proses kilang yang dapat diakses melalui penyeimbang beban terpisah.
Proses kilang harus dapat berkomunikasi satu sama lain untuk memusatkan jejak pada server tunggal.
Dalam aplikasi Anda (atau sumber acara Honeycomb lainnya), Anda akan mengkonfigurasi API Host untuk menjadi http(s)://load-balancer/ . Segala sesuatu yang lain tetap sama, seperti kunci API, nama dataset, dan sebagainya karena semua yang hidup dengan klien yang berasal.
Setiap instance kilang harus memiliki minimum:
linux/amd64 atau linux/arm64Dalam banyak kasus, kilang hanya membutuhkan satu simpul. Jika mengalami sejumlah besar lalu lintas, Anda mungkin perlu skala ke beberapa node, dan kemungkinan membutuhkan instance Redis kecil untuk menangani penskalaan.
Kami sarankan meningkatkan jumlah RAM dan jumlah core setelah pengaturan awal Anda. RAM dan CPU tambahan dapat digunakan dengan meningkatkan nilai konfigurasi; Secara khusus, CacheCapacity adalah nilai konfigurasi yang penting. Sistem Stress Relief Refinery memberikan indikasi yang baik tentang bagaimana kilang yang sulit bekerja, dan ketika dipanggil, log (sebagai reason ) nama nilai konfigurasi kilang yang harus ditingkatkan untuk mengurangi stres. Gunakan dokumentasi penskalaan dan pemecahan masalah kami untuk mempelajari lebih lanjut.
Refinery tersedia sebagai grafik helm di repositori helm sarang lebah.
Anda dapat menginstal kilang dengan perintah berikut, yang menggunakan file nilai default:
helm repo add honeycomb https://honeycombio.github.io/helm-charts
helm install refinery honeycomb/refineryAtau, berikan file nilai khusus Anda sendiri:
helm install refinery honeycomb/refinery --values /path/to/refinery-values.yaml where /path/to/refinery-values.yaml adalah jalur file.
Saat beroperasi di sebuah cluster, Refinery berharap untuk mengumpulkan semua rentang dalam jejak ke satu contoh sehingga dapat membuat keputusan jejak. Karena setiap rentang tiba secara mandiri, setiap instance kilang harus dapat berkomunikasi dengan semua rekannya untuk mendistribusikan jejak ke instance yang benar.
Komunikasi ini dapat dikelola dengan dua cara: melalui daftar eksplisit rekan-rekan dalam file konfigurasi, atau dengan menggunakan pendaftaran sendiri melalui cache Redis bersama. Instalasi umumnya lebih suka menggunakan Redis. Bahkan dalam instalasi besar, beban pada server Redis cukup ringan, dengan setiap contoh hanya membuat beberapa permintaan per menit. Sebuah instance Redis tunggal dengan CPU fraksional biasanya cukup.
Konfigurasi dikendalikan oleh dua file konfigurasi Refinery, yang umumnya disebut sebagai config.yaml untuk konfigurasi umum dan rules.yaml untuk konfigurasi pengambilan sampel. File -file ini dapat dimuat dari sistem file yang dapat diakses, atau dimuat dengan permintaan GET yang tidak tertekan dari URL.
Pelajari lebih lanjut tentang config.yaml dan semua parameter yang mengontrol operasi kilang dalam dokumentasi konfigurasi kilang kami.
Pelajari lebih lanjut tentang rules.yaml dan konfigurasi sampler dalam dokumentasi metode pengambilan sampel kilang kami.
Itu valid untuk menentukan lebih dari satu sumber konfigurasi. Misalnya, dimungkinkan untuk memiliki file konfigurasi yang umum, ditambah file terpisah yang hanya berisi kunci. Pada baris perintah, tentukan beberapa file dengan mengulangi sakelar baris perintah. Dalam variabel lingkungan, pisahkan beberapa lokasi konfigurasi dengan koma.
Refinery adalah aplikasi baris perintah gaya Linux yang khas, dan mendukung beberapa sakelar baris perintah.
refinery -h akan mencetak daftar bantuan teks yang diperluas semua opsi baris perintah dan variabel lingkungan yang didukung.
Kilang mendukung variabel lingkungan utama berikut; Silakan lihat bantuan baris perintah atau dokumentasi online untuk daftar lengkap. Sakelar baris perintah diutamakan daripada konfigurasi file, dan variabel lingkungan diutamakan lebih dari keduanya.
| Variabel Lingkungan | Bidang konfigurasi |
|---|---|
REFINERY_GRPC_LISTEN_ADDRESS | GRPCListenAddr |
REFINERY_REDIS_HOST | PeerManagement.RedisHost |
REFINERY_REDIS_USERNAME | PeerManagement.RedisUsername |
REFINERY_REDIS_PASSWORD | PeerManagement.RedisPassword |
REFINERY_HONEYCOMB_API_KEY | HoneycombLogger.LoggerAPIKey |
REFINERY_HONEYCOMB_METRICS_API_KEY | LegacyMetrics.APIKey |
REFINERY_HONEYCOMB_API_KEY | LegacyMetrics.APIKey |
REFINERY_QUERY_AUTH_TOKEN | QueryAuthToken |
Catatan: REFINERY_HONEYCOMB_METRICS_API_KEY lebih diutamakan daripada REFINERY_HONEYCOMB_API_KEY untuk konfigurasi LegacyMetrics.APIKey .
Mengirim data ke sarang lebah membutuhkan melampirkan kunci API ke telemetri. Untuk membuat pengelolaan telemetri lebih mudah, kilang mendukung opsi konfigurasi ReceiveKeys dan SendKey , bersama dengan AcceptOnlyListedKeys dan SendKeyMode . Dalam berbagai kombinasi, mereka memiliki banyak kekuatan ekspresif. Silakan lihat dokumentasi konfigurasi untuk detail tentang cara mengatur parameter ini.
Awal yang cepat untuk skenario tertentu ada di bawah ini:
SendKey ke kunci sarang lebah yang validSendKeyMode ke allSendKey ke kunci sarang lebah yang validSendKeyMode ke nonblankReceiveKeys ke daftar pengecualianSendKey ke kunci sarang lebah yang validSendKeyMode ke unlistedSendKey ke kunci sarang lebah yang validSendKeyMode ke missingonlyReceiveKeysAcceptOnlyListedKeys ke trueSendKey ke kunci sarang lebah yang validSendKeyMode ke listedonlyAcceptOnlyListedKeys menjadi falseReceiveKeys ke tombol yang harus digantiSendKey ke kunci sarang lebah yang validSendKeyMode ke listedonly + Catatan + + Saat menggunakan Beelines dengan kunci API klasik untuk mengirim data ke kilang, pastikan bahwa SendKey juga merupakan kunci klasik, bukan kunci lingkungan dan layanan (E&S).
Saat memulai dengan kilang atau saat memperbarui aturan pengambilan sampel, mungkin bermanfaat untuk memverifikasi bahwa aturan tersebut berfungsi seperti yang diharapkan sebelum Anda mulai menjatuhkan lalu lintas. Untuk melakukannya, gunakan mode run kering di kilang.
Aktifkan mode run kering dengan menambahkan DryRun = true di file konfigurasi Anda ( config.yaml ). Kemudian, gunakan pembangun kueri di UI Honeycomb untuk menjalankan kueri untuk memeriksa hasil Anda dan memverifikasi bahwa aturan tersebut berfungsi sebagaimana dimaksud.
Ketika mode dry run diaktifkan, metric trace_send_kept akan bertambah untuk setiap jejak, dan metrik untuk trace_send_dropped akan tetap 0 , mencerminkan bahwa kami mengirim semua jejak ke sarang lebah.
Refinery menggunakan antrian terikat dan buffer sirkular untuk mengelola jejak alokasi, sehingga bahkan di bawah penggunaan memori volume tinggi tidak boleh berkembang secara dramatis. Namun, mengingat bahwa jejak disimpan dalam buffer melingkar, ketika throughput jejak melebihi ukuran buffer, segalanya akan mulai salah. Jika Anda memiliki statistik yang dikonfigurasi, penghitung bernama collect_cache_buffer_overrun akan bertambah setiap kali ini terjadi. Gejala -gejala ini adalah bahwa jejak akan berhenti mengumpulkan bersama, dan sebaliknya rentang yang harus menjadi bagian dari jejak yang sama akan diperlakukan sebagai dua jejak terpisah. Semua jejak akan terus dikirim (dan disampel), tetapi beberapa keputusan pengambilan sampel akan dibuat pada data yang tidak lengkap. Ukuran buffer melingkar adalah opsi konfigurasi bernama CacheCapacity . Untuk memilih nilai yang baik, Anda harus mempertimbangkan throughput jejak (misalnya, jejak / kedua dimulai) dan kalikan dengan durasi maksimum jejak (seperti 3 detik), kemudian kalikan dengan beberapa buffer besar (mungkin 10x) . Perkiraan ini akan memberikan ruang kepala yang bagus.
Menentukan jumlah mesin yang diperlukan dalam cluster bukanlah ilmu yang tepat, dan paling baik dipengaruhi oleh menonton pembukaan buffer. Tetapi untuk heuristik kasar, hitung pada satu mesin menggunakan sekitar 2GB memori untuk menangani 5.000 peristiwa yang masuk dan melacak 500 jejak sub-detik per detik (untuk setiap jejak penuh yang berlangsung kurang dari detik dan ukuran rata-rata 10 rentang per jejak) .
Refinery menawarkan mekanisme yang disebut Stress Relief yang meningkatkan stabilitas di bawah beban berat. Metrik stress_level adalah metrik sintetis pada skala dari 0 hingga 100 yang dibangun dari beberapa metrik kilang yang berkaitan dengan ukuran antrian dan penggunaan memori. Dalam operasi normal, nilainya biasanya harus dalam satu digit. Selama semburan lalu lintas tinggi, tingkat stres mungkin merayap ke atas dan kemudian turun lagi saat volume turun. Saat mendekati 100, semakin besar kemungkinan kilang akan mulai gagal dan mungkin jatuh.
Stress Relief adalah sistem yang dapat memantau metrik stress_level dan melepaskan beban ketika stres menjadi bahaya bagi stabilitas. Setelah ActivationLevel tercapai, mode Stress Relief akan menjadi aktif. Dalam keadaan ini. Kilang akan secara menentukan sampel setiap rentang berdasarkan TraceID tanpa harus menyimpan sisa jejak atau mengevaluasi kondisi aturan. Stress Relief akan tetap aktif sampai stres jatuh di bawah DeactivationLevel yang ditentukan dalam konfigurasi.
Pengaturan pelepasan stres adalah:
Mode - Pengaturan untuk menunjukkan bagaimana Stress Relief digunakan. never menunjukkan bahwa Stress Relief tidak akan diaktifkan. monitor berarti Stress Relief akan diaktifkan ketika ActivationLevel dan menonaktifkan saat dicapai. always berarti bahwa mode Stress Relief akan terus terlibat. Mode always dimaksudkan untuk digunakan dalam situasi darurat.ActivationLevel - Ketika tingkat stres naik di atas ambang batas ini, kilang akan mengaktifkan Stress Relief .DeactivationLevel - Ketika tingkat stres turun di bawah ambang batas ini, kilang akan menonaktifkan Stress Relief .SamplingRate - laju di mana sampel kilang sementara Stress Relief aktif. stress_level saat ini merupakan proxy terbaik untuk beban keseluruhan pada kilang. Bahkan jika Stress Relief tidak aktif, jika stress_level sering di atas 50, itu adalah indikator yang baik bahwa kilang membutuhkan lebih banyak sumber daya - lebih banyak CPU, lebih banyak memori, atau lebih banyak node. Di sisi lain, jika stress_level tidak pernah masuk ke dua digit, kemungkinan kilang yang berlebihan.
Kilang memancarkan sejumlah metrik untuk memberikan beberapa indikasi tentang kesehatan proses. Metrik ini harus dikirim ke sarang lebah, biasanya dengan telemetri terbuka, dan juga dapat terkena prometheus. Yang menarik untuk ditonton adalah:
[incoming|peer]_router_* : Berapa banyak peristiwa (tidak ada info jejak) vs rentang (memiliki info jejak) telah diterima, dan berapa banyak yang dikirim ke rekan?collect_cache_buffer_overrun : Ini harus tetap nol; Nilai positif menunjukkan perlunya menumbuhkan ukuran buffer jejak melingkar kilang (melalui konfigurasi CacheCapacity ).process_uptime_seconds : merekam uptime dari setiap proses; Cari restart yang tidak terduga sebagai kunci menuju kendala memori. Tingkat warn logging default cukup tenang. Level debug memancarkan terlalu banyak data untuk digunakan dalam produksi, tetapi berisi informasi yang sangat baik di lingkungan pra-produksi, termasuk informasi pengambilan keputusan. info ada di suatu tempat. Mengatur level logging ke debug selama konfigurasi awal akan membantu memahami apa yang berhasil dan apa yang tidak, tetapi ketika volume lalu lintas meningkat, itu harus diatur untuk warn atau bahkan error . Log dapat dikirim ke stdout atau ke honeycomb.
Kilang memvalidasi konfigurasinya pada startup atau ketika konfigurasi dimuat ulang, dan memancarkan diagnostik untuk masalah apa pun. Pada startup, itu akan menolak untuk memulai; Pada Reload, itu tidak akan mengubah konfigurasi yang ada.
Periksa konfigurasi yang dimuat dengan menggunakan salah satu titik akhir /query dari baris perintah pada server yang dapat mengakses host kilang.
Titik akhir /query dilindungi dan dapat diaktifkan dengan menentukan QueryAuthToken dalam file konfigurasi atau menentukan REFINERY_QUERY_AUTH_TOKEN di lingkungan. Semua permintaan ke titik akhir /query apa pun harus menyertakan header X-Honeycomb-Refinery-Query diatur ke nilai token yang ditentukan.
Untuk konfigurasi berbasis file (satu-satunya jenis yang saat ini didukung), nilai hash identik dengan nilai yang dihasilkan oleh perintah md5sum untuk file konfigurasi yang diberikan.
Untuk semua perintah ini:
$REFINERY_HOST harus menjadi URL kilang Anda.$FORMAT bisa menjadi salah satu dari yaml , toml , atau json .$DATASET adalah nama dataset yang ingin Anda periksa.Untuk mengambil seluruh konfigurasi aturan:
curl --include --get $REFINERY_HOST/query/allrules/$FORMAT --header "x-honeycomb-refinery-query: my-local-token"
Untuk mengambil rangkaian aturan yang digunakan kilang untuk dataset yang ditentukan, yang akan dikembalikan sebagai peta jenis sampler ke set aturannya:
curl --include --get $REFINERY_HOST/query/rules/$FORMAT/$DATASET --header "x-honeycomb-refinery-query: my-local-token"
Untuk mengambil informasi tentang konfigurasi yang saat ini digunakan, termasuk cap waktu ketika konfigurasi terakhir dimuat:
curl --include --get $REFINERY_HOST/query/configmetadata --header "x-honeycomb-refinery-query: my-local-token"
Kilang dapat mengirim telemetri yang mencakup informasi yang dapat membantu men -debug keputusan pengambilan sampel yang dibuat. Untuk mengaktifkan, di file konfigurasi, atur AddRuleReasonToTrace ke true . Ini akan menyebabkan jejak yang dikirim ke Honeycomb untuk memasukkan meta.refinery.reason , yang akan berisi teks yang menunjukkan aturan mana yang dievaluasi yang menyebabkan jejak dimasukkan.
Refinery belum buffer jejak atau keputusan pengambilan sampel ke disk. Ketika Anda memulai kembali proses semua jejak dalam penerbangan akan disiram (dikirim ke hulu ke sarang lebah), tetapi Anda akan kehilangan catatan keputusan jejak masa lalu. Ketika dimulai kembali, itu akan dimulai dengan batu tulis yang bersih.
Dalam setiap direktori, antarmuka ekspor ketergantungan ada dalam file dengan nama yang sama dengan direktori dan kemudian (sebagian besar) masing -masing file lain adalah implementasi alternatif dari antarmuka tersebut. Misalnya, di logger , /logger/logger.go berisi definisi antarmuka dan logger/honeycomb.go berisi implementasi antarmuka logger yang akan mengirim log ke honeycomb.
main.go mengatur aplikasi dan membuat pilihan tentang versi implementasi ketergantungan mana yang akan digunakan (misalnya Logger mana, sampler mana, dll.) Memulai semuanya dan kemudian meluncurkan App .
app/app.go adalah titik kontrol utama. Ketika fungsi Start berakhir, program dimatikan. Ini meluncurkan dua Router yang mendengarkan acara yang masuk.
route/route.go mendengarkan jaringan untuk lalu lintas yang masuk. Ada dua router yang berjalan dan mereka menangani berbagai jenis lalu lintas yang masuk: acara yang berasal dari dunia luar (router incoming ) dan acara yang berasal dari anggota lain dari cluster kilang (lalu lintas peer ). Setelah mendapatkan acara, ia memutuskan ke mana harus pergi selanjutnya: apakah ini meminta acara (atau kumpulan acara), dan jika demikian, apakah ia memiliki ID jejak? Segala sesuatu yang bukan suatu peristiwa atau peristiwa yang tidak memiliki ID jejak segera diserahkan ke transmission untuk diteruskan ke sarang lebah. Jika itu adalah acara dengan ID jejak, router mengekstrak ID jejak dan kemudian menggunakan sharder untuk memutuskan anggota klaster kilang mana yang harus menangani jejak ini. Jika itu rekan, acara akan diteruskan ke rekan itu. Jika kami, acara tersebut akan diubah menjadi representasi internal dan diserahkan kepada collector untuk menggabungkan rentang menjadi jejak.
collect/collect.go Kolektor bertanggung jawab untuk menggabungkan rentang bersama menjadi jejak dan memutuskan kapan mengirimnya ke sarang lebah atau jika mereka harus dijatuhkan. Pertama kali ID jejak terlihat, kolektor memulai timer. Jika rentang root, yang merupakan rentang dengan ID jejak dan tidak ada ID induk, tiba sebelum timer kedaluwarsa, maka jejak dianggap lengkap. Jejak dikirim dan timer dibatalkan. Jika timer kedaluwarsa sebelum rentang root tiba, jejak akan dikirim apakah itu lengkap atau tidak. Tepat sebelum dikirim, kolektor meminta sampler untuk laju sampel dan apakah untuk menjaga jejak atau tidak. Kolektor mematuhi keputusan pengambilan sampel ini dan mencatatnya (catatan diterapkan pada setiap rentang yang mungkin masuk sebagai bagian dari jejak setelah keputusan dibuat). Setelah membuat keputusan pengambilan sampel, jika jejak harus disimpan, ia diteruskan ke transmission untuk pengiriman yang sebenarnya.
transmit/transmit.go adalah pembungkus di sekitar interaksi HTTP dengan API sarang lebah. Ini menangani acara batching bersama -sama dan mengirimkannya ke hulu.
logger dan metrics adalah untuk mengelola log dan metrik yang dihasilkan kilang itu sendiri.
sampler berisi algoritma untuk menghitung laju sampel berdasarkan jejak yang disediakan.
sharder menentukan peer mana yang dalam konfigurasi kilang yang dikelompokkan seharusnya menangani jejak individu.
types berisi beberapa definisi jenis yang digunakan untuk menyerahkan data di antara paket.
