Mengapa dokumentasi SRE penting? Bagian 3

Selamat malam semuanya! Kami sedang terburu-buru untuk berbagi berita bahwa pada bulan Februari kami meluncurkan aliran baru pada kursus Devops - Praktik dan Alat , yang berarti bahwa inilah saatnya untuk menyelesaikan apa yang kami mulai dan menerbitkan bagian ketiga dari artikel: “Mengapa Dokumentasi SRE Penting” . Ayo pergi!

Dokumen untuk mengelola perintah SRE

Tim SRE membutuhkan dokumentasi yang andal dan terjangkau untuk bekerja secara efisien.

Situs tim

Catatan: Alih-alih situs, Anda dapat menggunakan ruang atau bagian terpisah di Confluence / Wiki.

Situs tim ini penting karena menyediakan koordinasi informasi dan dokumentasi yang terkait dengan tim SRE dan proyek-proyeknya. Misalnya, di Google, banyak tim SRE menggunakan g3doc (platform dokumentasi Google internal tempat dok tinggal di kode sumber dengan kode terkait), dan beberapa tim menggunakan g3doc dan Situs Google: dalam kasus ini, halaman g3doc terkait erat dengan kode / detail implementasi.

Piagam tim



Tim SRE harus mendukung piagam yang diterbitkan yang menguraikan motivasi kerja dan mendokumentasikan keterlibatan yang berkelanjutan. Piagam ini diperlukan untuk menetapkan identitas, tujuan utama, dan nilai tim di seluruh perusahaan.

Piagam ini biasanya memiliki unsur-unsur berikut:

• Deskripsi tingkat tinggi dari area tanggung jawab tim. Termasuk jenis layanan yang didukung oleh tim (dan bagaimana), sistem terkait, contoh.
• Deskripsi singkat tentang beberapa layanan paling penting yang didukung oleh tim. Bagian ini juga menyoroti teknologi utama dan tantangan dalam menggunakannya, manfaat melibatkan SRE, dan tanggung jawab mereka.
• Prinsip dan nilai-nilai utama tim.
• Tautan ke situs web tim dan dokumentasi.

Ini juga mengasumsikan kehadiran pernyataan visi (konsep visi untuk masa depan - deskripsi inspirasional dari tujuan jangka panjang tim) dan peta jalan untuk beberapa kuartal.

Dokumentasi untuk mengintegrasikan SRE baru

Berinvestasi dalam alat dan bahan pelatihan untuk karyawan baru memiliki efek positif pada kecepatan integrasi karyawan ke dalam proses kerja. Adalah bermanfaat bagi tim SRE untuk melatih pendatang baru dengan semua keterampilan kerja shift yang diperlukan sesegera mungkin. Kisah Zoe dengan jelas menunjukkan bagaimana kurangnya pelatihan penuh waktu untuk karyawan baru menjadikan insiden kecil sebagai kerusakan serius.

Banyak tim SRE mempersiapkan karyawan baru untuk shift menggunakan daftar periksa. Daftar periksa shift biasanya mencakup area tingkat tinggi (dibagi menjadi sub-bagian) yang harus dipahami anggota tim. Contoh area tersebut adalah konsep produksi, front-end dan back-end, otomatisasi dan instrumentasi, pemantauan dan penebangan. Juga, instruksi untuk persiapan shift dan tugas yang dilakukan selama shift dapat dimasukkan dalam daftar periksa.

Untuk mempersiapkan anggota baru tim SRE, mereka juga menggunakan latihan bermain peran (mereka disebut Wheel of Misfortune - Roda Kegagalan di Google). Latihan ini adalah skenario kegagalan dengan serangkaian data dan sinyal spesifik yang mungkin diperlukan SRE untuk menyelesaikan masalah selama shift. Anggota tim bergiliran memainkan peran seorang insinyur yang bertugas mengasah penguasaan mereka dalam pemulihan bencana dan kemampuan untuk melakukan debug sistem. Wheel of Misfortune memeriksa untuk melihat apakah setiap anggota tim tahu di mana menemukan dokumentasi untuk memperbaiki masalah, dan bagaimana menangani kegagalan.

Manajemen penyimpanan

Semua informasi dari tim SRE dapat tersebar di beberapa situs, repositori lokal dan folder Google Drive, yang sangat mempersulit pencarian situs yang tepat. Seperti yang terjadi dalam contoh yang dijelaskan sebelumnya, alat operasional kritis dan instruksi untuk penggunaannya tidak tersedia untuk Zoe (SRE bertugas), karena mereka disembunyikan di direktori pribadi dari pimpinan teknisnya, dan ketidakmampuan untuk menemukannya secara signifikan meningkatkan durasi kegagalan layanan. Untuk menghilangkan masalah seperti itu, Anda perlu menyusun semua informasi dan memastikan bahwa anggota tim tahu di mana menemukan dan menyimpannya, dan bagaimana cara memeliharanya. Struktur yang dikembangkan dengan baik akan membantu tim menemukan informasi lebih cepat. Anggota tim baru akan lebih cepat untuk tetap up to date, sementara insinyur yang bertugas akan menyelesaikan masalah lebih cepat.

Berikut adalah beberapa panduan tentang cara membuat dan mengelola repositori dokumentasi:

• Identifikasi pemangku kepentingan utama dan lakukan wawancara singkat untuk mengidentifikasi semua kebutuhan.
• Temukan sebanyak mungkin dokumentasi dan analisis kesenjangan dalam konten.
• Basis struktur situs Anda untuk membuat dokumentasi baru di tempat yang tepat.
• Pindahkan dokumentasi yang ada ke lokasi baru.
• Arsipkan dan robek dokumentasi lama.
• Lakukan pemeriksaan rutin untuk memastikan kualitas / konsistensi dokumentasi yang didukung.
• Pastikan bahwa permintaan pencarian standar mengembalikan dokumen yang diperlukan di bagian paling atas dari daftar hasil pencarian.
• Gunakan sinyal, seperti Google Analytics, untuk mengukur praktik standar.

Catatan tentang dukungan repositori: penting untuk secara teratur memeriksa dan memperbarui dokumentasi. Nama pemilik dan tanggal pemeriksaan terakhir harus terlihat - informasi ini membantu memverifikasi keakuratan dokumen yang dipilih. Zoe dalam sejarah hanya dapat menemukan dokumentasi usang dari alat kritis, sehingga kehilangan kemampuan untuk dengan cepat menyelesaikan masalah. Dokumentasi yang tidak dapat diandalkan dan usang membuat SRE kurang efisien, yang berdampak negatif terhadap keandalan layanan yang dikelola.

Ketersediaan Repositori

Tim SRE harus memastikan bahwa dokumentasi tetap tersedia bahkan jika repositori standar macet dan tidak tersedia. Setiap Google SRE memiliki salinan dokumentasi kritisnya. Salinan ini tersedia pada perangkat penyimpanan kompak terenkripsi atau media fisik yang dapat dilepas namun aman serupa yang dimiliki oleh setiap SRE.

Dokumentasi untuk menonaktifkan layanan

Ketika siklus hidup suatu layanan berakhir, SRE akan menonaktifkannya dengan cara yang dapat diprediksi. Bagian ini memberikan rekomendasi untuk dokumentasi tentang mengeluarkan layanan dari layanan.

Penting untuk memberi tahu pengguna sebelum penghentian layanan dan untuk menyediakan jadwal dan langkah-langkah. Iklan Anda harus menjelaskan kapan pendaftaran pengguna baru berakhir, bagaimana bug yang ada dan terdeteksi di masa depan akan diproses, dan kapan layanan akhirnya akan berhenti bekerja. Identifikasi dengan jelas semua tanggal penting dan proses mengurangi dukungan untuk SRE, kirim pengumuman sementara ketika Anda maju.

Distribusi email sederhana tidak cukup - Anda perlu memperbarui halaman utama dokumentasi, buku pedoman, dan codelab. Juga, jika mungkin, komentari file header. Jelaskan rincian pengumuman dalam dokumen (selain surat) yang dapat dirujuk pengguna. Surat itu harus sesingkat mungkin, tetapi pada saat yang sama informatif, mencerminkan semua poin utama. Jelaskan rincian tambahan: motivasi bisnis untuk mematikan layanan, alat apa yang dapat digunakan pengguna untuk bermigrasi ke layanan lain, dukungan apa yang tersedia selama migrasi. Layak juga membuat halaman FAQ, mengisinya dari waktu ke waktu dengan informasi baru tentang pertanyaan yang diajukan oleh pengguna.

Peran editor dokumentasi teknis

Editor teknis (atau penulis teknis) menyediakan layanan yang membuat SRE lebih efisien dan produktif. Rentang tugas tidak terbatas pada penulisan dokumen terpisah sesuai dengan persyaratan yang ditentukan oleh tim SRE.

Berikut adalah beberapa rekomendasi praktis untuk editor teknis tentang bekerja dengan tim SRE.

• Editor teknis berkolaborasi dengan SRE untuk membuat dokumentasi operasi untuk menjalankan layanan dan dokumentasi produksi untuk produk dan alat SRE.
• Mereka membuat dan memperbarui repositori dokumentasi, struktur dan mengatur ulang mereka sesuai dengan kebutuhan pengguna, dan meningkatkan dokumen individu sebagai bagian dari manajemen repositori keseluruhan.
• Editor membantu mengidentifikasi perbaikan yang diperlukan oleh dokumentasi dan manajemen informasi. Ini termasuk mengevaluasi dokumentasi untuk mengumpulkan persyaratan, memperbaiki dokumen dan situs yang dibuat oleh para insinyur, memberi saran kepada tim tentang aturan untuk membuat, mengatur, mendesain ulang, mencari dan memelihara dokumentasi.
• Editor harus mengevaluasi dan meningkatkan alat dokumentasi untuk memberikan solusi SRE yang lebih baik.

Pola

Editor teknis juga menyediakan templat yang menyederhanakan pembuatan dan penggunaan dokumentasi SRE. Template melakukan hal berikut:

• Sederhanakan pembuatan dokumentasi dengan menyediakan insinyur dengan struktur yang jelas untuk membuat dokumen baru.
• Tambahkan bagian dari semua dokumen yang diperlukan untuk melengkapi dokumentasi.
• Mereka membantu pembaca untuk dengan cepat memahami topik dokumen, jenis informasi dan bagaimana mengaturnya.

Rekayasa Keandalan Situs berisi beberapa contoh templat dokumentasi. Di bagian ini, kami akan memberikan beberapa contoh lagi untuk menunjukkan bagaimana templat menyediakan struktur dan panduan bagi insinyur untuk mengisi konten.

Wawancara Layanan

Ulasan

Apa ini Apa yang dia lakukan Tingkat tinggi menggambarkan fungsionalitas yang diberikan kepada pelanggan (pengguna akhir, komponen, dll.).

Arsitektur

Jelaskan cara kerja arsitektur. Jelaskan pergerakan data antar komponen. Pertimbangkan untuk menambahkan diagram sistem ketergantungan kritis dan aliran kueri dan data.

Klien dan Ketergantungan

Buat daftar semua klien (milik tim lain) yang bergantung padanya dan semua layanan (milik tim lain) yang bergantung padanya. (Ini juga dapat ditunjukkan dalam bentuk diagram sistem.)

Kode dan Konfigurasi

Jelaskan struktur produksi. Di mana itu berjalan? Daftar binari, pekerjaan, pusat data dan pengaturan file konfigurasi, atau tunjukkan di mana mereka semua berada. Juga berikan lokasi kode dan, jika perlu, informasi tentang pembuatan.

Daftar dan jelaskan file konfigurasi, perubahan, dan port yang diperlukan untuk mengoperasikan produk atau layanan ini.

Jelaskan hal berikut: file konfigurasi apa yang telah diubah untuk produk atau layanan ini? Bagaimana pengaturannya?

Prosesnya

Jelaskan berikut ini: Daemon apa dan proses lain yang harus dijalankan agar layanan dapat berfungsi? Skrip kontrol apa yang dibuat untuk mengelola layanan?

Jejak

Buat daftar dan jelaskan file log yang dibuat oleh komponen dan pengamatan apa yang dilakukan. Jelaskan yang berikut ini: Log apa yang dihasilkan oleh komponen ini? Apa yang ada di setiap file? Apa rekomendasi untuk mempelajari file-file ini? Aspek komponen apa yang harus dipantau untuk operasi layanan yang andal?

Dasbor dan Alat

Tempel tautan ke dasbor dan alat terkait.

Kekuasaan

Tunjukkan kekuatan satu instance; Datacenter secara global: nilai QPS, bandwidth dan latensi.

SLA

Berikan target aksesibilitas.

Prosedur Standar

Tambahkan tautan ke prosedur, termasuk pengujian muat, status pembaruan / push / bendera, dan sebagainya. Tambahkan tautan ke dokumentasi lansiran di buku pedoman lansiran.

Referensi

Tambahkan tautan ke dokumentasi desain untuk komponen atau komponen terkait, biasanya ditulis oleh tim pengembangan, serta informasi terkait lainnya.

Playbook

Judul

Dalam namanya, tentukan nama lansiran (misalnya, NormalAlert_AlertVery Sangat Normal).

Ulasan

Jelaskan yang berikut: Apa artinya lansiran ini? Apakah itu datang ke pager atau hanya mengirim surat? Faktor-faktor apa yang memicu peringatan? Bagian mana dari layanan yang terpengaruh? Lansiran apa yang dikaitkan dengannya? Siapa yang perlu diberitahu?

Peringatan Tingkat Bahaya

Membenarkan tingkat bahaya pemberitahuan dan dampak dari bagian yang terpengaruh pada kondisi umum layanan.

Konfirmasi

Berikan instruksi yang jelas untuk memeriksa dan memvalidasi status.

Pemecahan masalah

Buat daftar dan jelaskan metode debugging dan sumber informasi terkait. Jangan lupa tentang tautan ke dasbor yang sesuai. Aktifkan peringatan. Jelaskan yang berikut ini: Apa yang akan muncul di log ketika suatu peringatan dipicu? Penangan debugging apa yang ada di sana? Apakah ada skrip dan perintah yang berguna? Output apa yang mereka hasilkan? Apakah ada tugas tambahan yang perlu diselesaikan setelah penghapusan tanda?

Solusi

Jelaskan dan daftarkan semua solusi yang mungkin untuk masalah yang menyebabkan lansiran. Jelaskan hal berikut: Bagaimana cara saya memperbaiki masalah dan menyelesaikan peringatan? Perintah apa yang harus dijalankan untuk reboot? Siapa yang harus diberitahu jika peringatan dipicu karena tindakan pengguna? Siapa yang memiliki pengalaman men-debug masalah yang sama?

Eskalasi

Buat daftar dan jelaskan jalur eskalasi. Tunjukkan orang atau tim untuk diberi tahu dan kapan melakukannya. Jika eskalasi tidak perlu - tulis tentang itu.

Tautan Terkait

Berikan tautan ke peringatan terkait, prosedur, dan tinjau dokumentasi.
Laporan Layanan Triwulan
Pendahuluan
Jelaskan layanan yang menjadi tanggung jawab tim.

Perencanaan Kapasitas

Termasuk:

• Permintaan aktual untuk layanan, mulai dari 6-8 kuartal terakhir, dinyatakan dalam metrik yang paling relevan untuk layanan (misalnya, QPS atau DAU).
• Prakiraan untuk 8 kuartal berikutnya.
• Rencana kapasitas yang memenuhi permintaan yang diproyeksikan pada tingkat redundansi yang disyaratkan - tentukan risiko defisit dan / atau perencanaan kapasitas.

Kami juga menyarankan menambahkan prakiraan untuk 2-4 kuartal terakhir sehingga pembaca dapat mengevaluasi stabilitas dan keakuratan prakiraan tersebut.

Implementasi / Ketersediaan SLA

Semua layanan yang didukung oleh SRE harus memiliki SLA tertulis, yang mengevaluasi kinerja setiap kuartal.

Bagian SLA harus berisi parameter komponen utama layanan untuk mengukur kelayakan triwulanan kondisi SLA, serta tautan ke tim SLA tertulis.

Insiden Bersamaan (Opsional)

Sebutkan 3-5 insiden atau kegagalan besar per kuartal.

Prestasi (Opsional)

Daftar pencapaian utama untuk kuartal ini.

Perubahan SLA (Diinginkan)

Perubahan terbaru untuk SLA.

Detail Layanan (Diinginkan)

Bagian ini dapat mencakup pertumbuhan, statistik keterlambatan, dll.

Informasi Tim (Opsional)

Dapat mencakup informasi tentang komposisi tim, status, proyek, statistik shift.

Sumber Data (Diperlukan)

Jelaskan sumber yang digunakan untuk mendapatkan nilai aksesibilitas, metode perhitungan, berikan tautan ke dasbor yang sesuai.

Piagam Tim

Siapa kita

Dalam satu kalimat (~ 1 baris) menggambarkan lingkungan teknologi, pelanggan dan proposal tim, serta tingkat keterlibatan SRE dan keahlian khusus.

Layanan yang didukung

Untuk lebih memperjelas ruang lingkup pekerjaan, jelaskan layanan (atau kelompok mereka) yang didukung oleh tim.

Bagaimana Kami Menghabiskan Waktu

Pelingkupan membantu dalam menciptakan peta jalan dan mencapai dan mendukung tujuan jangka panjang.

Nilai Tim

Jelaskan dengan jelas nilai-nilainya. Ini memengaruhi cara anggota tim berinteraksi satu sama lain, dan bagaimana tim Anda dipahami oleh orang lain.

Kesimpulan

Terlepas dari apakah Anda seorang SRE, atau manajer SRE, atau editor teknis, Anda sekarang memahami pentingnya dokumentasi dalam kehidupan tim SRE yang efektif. Dokumentasi yang baik memungkinkan tim SRE untuk tumbuh dan mematuhi metodologi yang jelas untuk mengelola layanan baru dan yang sudah ada.

Jadi, kami menerbitkan bagian akhir dari artikel ini, bagian pertama dan kedua dapat dibaca dengan mengklik hyperlink, dan Anda bisa mendapatkan informasi yang lebih berguna dalam pelajaran terbuka kami, yang akan diadakan pada 19 Februari. Kami menunggu semuanya!