Mengapa dokumentasi SRE penting? Bagian 2

Selamat malam semuanya!

Jadi tidak ada yang tersisa (yaitu, satu hari) sebelum dimulainya aliran kursus DevOps Praktik dan Alat , yang berarti kita perlu memiliki waktu untuk menyelesaikan sisa artikel "Mengapa Dokumentasi SRE Penting" selama waktu ini.

Kami melanjutkan.

Dokumen untuk Layanan Baru Onboarding

SRE melakukan PRR (tinjauan kesiapan produksi) untuk memverifikasi bahwa layanan memenuhi standar kesiapan operasional, dan untuk memastikan bahwa pemilik layanan memahami cara menggunakan pengetahuan SRE untuk mengelola sistem besar.

Layanan harus melalui tes ini sebelum diluncurkan ke produksi. (Sebelum diluncurkan, ini tidak didukung oleh SRE, tetapi oleh tim pengembangan itu sendiri.) Tujuan PRR pada tahap ini adalah untuk memastikan bahwa layanan akan memenuhi standar minimum keandalan pada saat peluncuran.



PRR berikutnya terjadi sebelum transfer layanan SRE, yaitu, banyak waktu dapat berlalu setelah peluncuran. Dan ketika tim SRE memutuskan untuk mengambil layanan baru, analisis menyeluruh tentang kondisi produksi dan praktik layanan yang digunakan dilakukan. Tujuannya adalah untuk menyederhanakan proses transfer layanan dalam hal keandalan dan stabilitas operasional, serta membantu SRE menghadapinya dengan lebih baik.

Dengan melakukan PRR sebelum menyerahkan layanan, SRE dapat mengajukan lebih banyak pertanyaan dan menetapkan standar yang lebih tinggi untuk keandalan dan kemudahan penggunaan daripada saat melakukan PRR sebelum diluncurkan. PRR sebelum peluncuran bisa "ringan" agar tidak memperlambat tim pengembangan.

Dalam kisah Zoe, tim tidak memiliki proses standar atau daftar periksa PRR, yang berarti mereka bisa melewatkan masalah yang sangat penting ketika mentransfer layanan. Dengan demikian, ada risiko tabrakan dengan sejumlah besar masalah yang dapat dengan mudah diantisipasi dan diselesaikan sebelum mengambil tanggung jawab untuk mengelola layanan.

Transfer PRR / layanan memerlukan pembuatan template PRR dan dokumentasi proses (proses dokumen) yang menjelaskan bagaimana tim SRE akan bekerja dengan layanan baru dan menggunakan template PRR. Pola yang digunakan dalam proses transfer bisa lebih komprehensif daripada yang digunakan saat startup.

Templat PRR mencakup beberapa bidang dan diperlukan untuk memeriksa jawaban atas pertanyaan kritis. Tabel 1 menunjukkan beberapa area dan masalah terkait yang dicakup template.

Area	Pertanyaan
Arsitektur dan Ketergantungan	Apa jalur permintaan dari klien ke frontend lalu backend? Apakah ada berbagai jenis permintaan dengan persyaratan latensi yang berbeda?
Perencanaan kapasitas	Apa harapan untuk volume lalu lintas dan tingkat pertumbuhan selama dan setelah peluncuran? Apakah Anda memiliki daya komputasi yang diperlukan untuk mendukung lalu lintas ini?
Jenis kegagalan	Apakah ada satu titik kegagalan dalam arsitektur Anda? Bagaimana Anda menghilangkan tidak tersedianya ketergantungan?
Proses dan Otomasi	Apakah ada proses manual yang diperlukan untuk mendukung layanan ini?
Ketergantungan eksternal	Apa data, kode, layanan, atau peristiwa pihak ketiga yang bergantung pada layanan dan peluncuran? Apakah ada mitra Anda yang bergantung pada layanan? Jika demikian, apakah mereka perlu diberitahu tentang peluncuran?

Tabel 1. Contoh area template PRR

Dokumentasi proses juga harus menunjukkan dokumen yang harus diminta oleh SRE dari tim pengembangan produk sebagai prasyarat untuk transfer. Misalnya, mereka dapat meminta tim pengembangan untuk membuat buku pedoman untuk masalah umum.

Selain itu, organisasi SRE perlu membuat dokumen peninjauan yang menjelaskan secara singkat kepada tim pengembangan tentang peran dan bidang tanggung jawab SRE. Ini diperlukan untuk membentuk harapan yang realistis. Dokumen pertama harus menjelaskan apa itu SRE, mencakup semua topik yang dibahas pada bagian sebelumnya dan awal artikel ini, termasuk fungsi utama, siklus hidup layanan, dukungan / tanggung jawab pemeliharaan. Tujuan utama dari dokumen ini adalah untuk memastikan bahwa pengembang tidak mengacaukan SRE dengan tim OPS dan tidak menganggap tanggapan pager sebagai satu-satunya tugas SRE. Seperti yang ditunjukkan dalam cerita yang dijelaskan sebelumnya, jika pada saat transfer layanan pengembang tidak sepenuhnya memahami apa yang SRE lakukan, maka ini akan menyebabkan masalah komunikasi dan kesalahpahaman.

Selain itu, perlu untuk membuat dokumen model keterlibatan untuk mengklarifikasi harapan dan menjelaskan proses interaksi antara tim SRE dan tim pengembangan produk selama dan setelah transfer layanan. Topik yang dibahas dalam dokumentasi dapat mencakup yang berikut:

• Kriteria transfer layanan dan proses PRR.
• Proses membahas laporan tujuan tingkat layanan (secara singkat SLO) dan perhitungan kesalahan.
• Kriteria peluncuran baru dan mulai kebijakan pembekuan (jika mungkin).
• Konten dan frekuensi laporan status layanan dari tim SRE.
• Persyaratan Staf SRE.
• Proses perencanaan peta jalan fungsionalitas baru dan prioritas fungsional yang meningkatkan keandalan (diperlukan oleh SRE) di atas fungsionalitas produk baru.

Dokumentasi Operasi Layanan

Untuk mendukung layanan, tim SRE terutama mengandalkan dokumentasi operasional utama: deskripsi umum (wawancara) dari layanan, buku pedoman dan prosedur, post-mortem, arahan dan SLA. (Catatan: bagian ini ada di bab "Do Docs Better" dalam Mencari SRE.)

Wawancara Layanan

Gambaran umum layanan sangat penting untuk memahami SRE jenis layanan apa yang mereka dukung. SRE perlu mengetahui arsitektur sistem, komponen dan dependensinya, kontak layanan dan pemiliknya. Deskripsi umum dari layanan ini adalah hasil kerja bersama dari tim pengembangan dan tim SRE, dibuat untuk memandu dan memprioritaskan tugas-tugas SRE dan mengidentifikasi area untuk studi lebih lanjut. Wawancara semacam itu biasanya diperoleh sebagai hasil PRR dan harus diperbarui ketika layanan berubah (misalnya, jika muncul ketergantungan baru).

Wawancara sederhana memberikan SRE informasi yang cukup untuk mengeksplorasi layanan lebih lanjut. Wawancara lengkap memberikan deskripsi menyeluruh tentang layanan dan bagaimana interaksi dengan dunia di sekitarnya, serta tautan ke dasbor, metrik, semua informasi yang SRE butuhkan untuk menyelesaikan masalah yang tidak terduga.

Playbook

Kadang-kadang juga disebut runbook, itu adalah dokumen mendasar yang memungkinkan para insinyur untuk menanggapi pemberitahuan sistem pemantauan layanan selama shift. Misalnya, jika tim Zoe memiliki buku pedoman yang menjelaskan arti dari peringatan "Ayub Ragnarok mundur" dan apa yang perlu dilakukan dalam situasi di mana ia diterima, insiden itu akan diselesaikan dalam hitungan menit. Playbook mengurangi waktu pemulihan insiden dan menyediakan tautan yang bermanfaat ke konsol dan prosedur.

Playbook berisi instruksi untuk memeriksa, menghilangkan, dan meningkatkan notifikasi yang dihasilkan dari proses pemantauan jaringan. Nama pemberitahuan di buku pedoman biasanya bertepatan dengan apa yang dihasilkan sistem. Mereka berisi perintah dan langkah-langkah yang perlu diuji keakuratannya. Mereka perlu diperbarui secara teratur ketika metode baru untuk memecahkan masalah ditemukan, serta ketika jenis kegagalan baru diidentifikasi dan ketergantungan ditambahkan.

Playbook tidak dibuat khusus untuk notifikasi. Mereka juga dapat memuat prosedur produksi untuk merilis rilis, pemantauan, dan pemecahan masalah. Contoh lain dari prosedur produksi termasuk menghidupkan / mematikan layanan, pemeliharaan layanan, dan kecelakaan / eskalasi.

Post mortem

SRE bekerja dengan sistem berskala besar, kompleks, terdistribusi, dan juga meningkatkan layanan dengan bantuan fungsi baru dan penambahan sistem baru. Oleh karena itu, mengingat skala dan kecepatan perubahan, insiden dan gangguan tidak bisa dihindari. Post-mortem adalah alat SRE penting, memformalkan proses belajar dari kesalahan kita. Dalam kisah hipotesis Zoe, tim tidak memiliki prosedur post-mortem formal, jadi tidak ada proses formal untuk mencatat kesimpulan insiden yang akan mencegah terulangnya kejadian tersebut. Jadi tim ditakdirkan untuk mengulangi kesalahan yang sama berulang kali.

Tim SRE perlu membuat templat post-mortem standar dengan bagian-bagian yang menangkap informasi penting tentang kegagalan. Idealnya, template harus terstruktur sehingga dapat dengan mudah diurai oleh alat analisis data. Ini mengirimkan laporan dinamika crash menggunakan post-mortem sebagai sumber data. Setiap post mortem yang dibuat menggunakan templat ini menjelaskan kegagalan produksi, termasuk informasi berikut (minimum):

• Kronologi peristiwa (garis waktu).
• Deskripsi dampak pada pengguna.
• Penyebab root
• Poin / Pelajaran yang Dipelajari.

Postmortem ditulis oleh anggota tim yang mengalami kegagalan, idealnya bagi mereka yang berpartisipasi dalam penghapusannya dan yang dapat bertanggung jawab atas perbaikan. Post mortem harus ditulis dengan cara yang tidak bersalah. Ini harus berisi informasi yang diperlukan untuk memahami apa yang telah terjadi, serta daftar keputusan yang perlu diambil untuk mengurangi kemungkinan kekambuhan, mengurangi konsekuensi dan / atau menyederhanakan pemulihan.

Arahan

Dalam dokumentasi kebijakan, aturan teknis dan non-teknis spesifik dan arahan produksi ditunjukkan. Aturan teknis dapat berlaku, misalnya, untuk mencatat perubahan dalam produksi, memelihara log, memberi nama layanan internal (menyebutkan aturan yang harus diikuti oleh insinyur saat mengimplementasikan layanan), dan penggunaan serta ketersediaan data identifikasi darurat.

Arahan juga dapat diarahkan ke proses. Aturan eskalasi membantu insinyur mengklasifikasikan kegagalan sebagai darurat dan non-darurat dan memahami tindakan apa yang harus diambil dalam situasi tertentu; arahan harapan shift menggambarkan struktur tim dan bidang tanggung jawab masing-masing anggotanya.

Perjanjian Tingkat Layanan

Perjanjian Tingkat Layanan (Service-Level Agreement, singkatnya - SLA) - perjanjian formal dengan klien tentang pekerjaan yang disediakan dari layanan dan tindakan yang diambil dalam kasus kegagalan untuk memenuhi kewajiban. Tim SRE mendokumentasikan ketersediaan dan latensi layanan, dan memantau kinerja layanan yang terkait dengan SLA.

Dokumentasi dan publikasi SLA, serta analisis menyeluruh tentang pengalaman pengguna dan perbandingannya dengan SLA, memungkinkan tim SRE untuk berinovasi lebih cepat tanpa kehilangan kualitas UX. SRE yang mendukung layanan dengan pemberitahuan SLA yang jelas gagal lebih cepat dan karenanya memperbaikinya lebih cepat. SLA juga mengurangi jumlah gesekan antara tim SRE dan SWE (pengembang perangkat lunak), yang memungkinkan tim untuk mendiskusikan tujuan dan hasil secara objektif, menghindari penilaian subyektif tentang risiko.

Perlu dicatat bahwa keberadaan perjanjian eksternal yang sah secara hukum mungkin tidak berlaku untuk sebagian besar tim SRE. Dalam kasus tersebut, tim SRE dapat membatasi diri mereka sendiri untuk tujuan tingkat layanan (SLO). SLO - Tentukan tingkat layanan yang diinginkan untuk metrik tertentu, misalnya, ketersediaan atau penundaan.

Dokumentasi produk

Tim SRE berusaha untuk menghabiskan 50 persen dari waktu mereka bekerja pada suatu proyek, mengembangkan perangkat lunak untuk mengotomatiskan pekerjaan manual, atau meningkatkan keandalan layanan. Bagian ini menjelaskan dokumen yang terkait dengan produk dan alat yang dikembangkan SRE.

Dokumen-dokumen ini penting karena memungkinkan pengguna untuk memahami apakah produk ini cocok untuk mereka, cara mulai bekerja dengannya, dan bagaimana mendapatkan dukungan. Mereka juga memberikan pengalaman pengguna yang tepat dan membuat adopsi produk lebih mudah.

Produk Tentang Halaman

Halaman deskripsi membantu SRE dan insinyur pengembangan produk memahami apa produk atau alat itu, apa fungsinya, dan bagaimana menggunakannya.

Manual konsep

Panduan konsep atau glosarium mendefinisikan semua konsep unik untuk produk. Definisi konsep memungkinkan menjaga konsistensi dalam dokumentasi dan elemen antarmuka pengguna, API, dan CLI (antarmuka baris perintah).

Panduan Memulai

Tujuan dari panduan memulai ini adalah untuk secepatnya memperbarui para insinyur dengan penundaan minimal. Ini berguna untuk pengguna baru yang ingin mencoba produk.

Codelab

Insinyur dapat menggunakan tutorial ini, menggabungkan penjelasan teoretis, contoh kode dan latihan, untuk segera mengenal produk. Codelabs juga menyediakan skrip terperinci yang mengarahkan insinyur langkah demi langkah melalui serangkaian tugas. Tutorial ini biasanya lebih panjang dari panduan memulai. Mereka dapat mencakup lebih dari satu produk atau alat jika terkait dengan sesuatu.

Panduan praktis

Panduan semacam itu diperlukan untuk pengguna yang ingin menyelesaikan masalah tertentu. Panduan ini biasanya panduan langkah demi langkah yang harus Anda ikuti.
Faq

Pada halaman FAQ, pengguna dapat memperoleh jawaban atas pertanyaan-pertanyaan paling populer, mencari tahu tentang kesulitan dan batasan yang dapat ditemui, menemukan tautan ke dokumen dan halaman lain untuk informasi lebih rinci.

Dukungan

Di halaman dukungan, para insinyur dapat mempelajari cara memecahkan masalah yang mereka hadapi. Anda juga dapat menemukan rencana eskalasi, informasi pemecahan masalah, tautan grup, dasbor, dan SLO, serta informasi pergeseran.

Deskripsi API

Panduan ini menjelaskan fungsi, kelas, dan metode, biasanya dengan teks yang disertakan. Dokumentasi semacam itu paling sering dibuat berdasarkan komentar dalam kode dan kadang-kadang ditulis oleh penulis teknis.

Panduan Pengembang

Dari panduan ini, pengembang dapat mempelajari cara memprogram dengan API produk. Panduan semacam itu biasanya diperlukan jika SRE membuat produk yang menyediakan API untuk pengembang, yang memungkinkan Anda membuat alat campuran yang saling memohon API untuk melakukan tugas yang lebih kompleks.

Dokumen untuk melaporkan status layanan

Bagian ini menjelaskan dokumen yang dibuat oleh tim SRE untuk menjelaskan status layanan yang didukung.

Ulasan Layanan Triwulanan

Informasi tentang status layanan disajikan dalam dua format: laporan triwulanan yang disetujui oleh pemimpin SRE, yang didistribusikan ke seluruh organisasi SRE, dan presentasi untuk memimpin dalam pengembangan produk dan tim.

Para pemimpin SRE tertarik pada laporan triwulanan, karena mereka memberikan informasi tentang hal-hal berikut:

• Masalah dukungan (shift, tiket, post-mortem). Pemimpin SRE tahu bahwa jika masalah dukungan mulai mengambil lebih dari 50 persen sumber daya tim SRE, penting untuk merespons dan mengubah prioritas. Tujuannya adalah untuk mengidentifikasi masalah yang sudah ada di tahap awal.
• Eksekusi SLA. Para pemimpin SRE ingin tahu apakah semuanya baik-baik saja dengan SLA, apakah ada komponen tidak sehat dalam ekosistem yang menimbulkan ancaman.
• Risiko Para pemimpin SLA ingin tahu tentang risiko yang diketahui oleh SRE yang dapat mengganggu tujuan produk dan bisnis.

Laporan triwulanan memberi tim SRE peluang untuk:

• Tekankan manfaat SRE untuk tim pengembangan produk, dan juga hasil kerja tim SRE.
• Meminta prioritas untuk menyelesaikan masalah yang mengganggu perintah SRE (resiliensi).
• Minta umpan balik tentang prioritas tim SRE.
• Tekankan kontribusi tim yang lebih luas.

Tinjauan Teknik yang Berhasil

Tinjauan ini membantu untuk mengadopsi teknik-teknik yang berhasil dan mencapai kondisi stabil di mana operasi memerlukan waktu minimum. Untuk menyiapkan laporan semacam itu, tim SRE menyediakan piagam situs dan tim, menggeser rincian status, proyek vs. interupsi, perencanaan kapasitas, dll.

Tinjauan praktik yang berhasil membantu tim SRE membandingkan dirinya dengan organisasi SRE lainnya dan meningkatkan kinerja di bidang-bidang utama: status shift, proyek vs gangguan, SLO dan perencanaan kapasitas.

Akhir dari bagian kedua.

Baca bagian selanjutnya.

Kami menunggu pertanyaan dan komentar Anda seperti biasa.