ทางเข้าออก

โพรมีธีอุส พุชเกตเวย์

Prometheus Pushgateway มีอยู่เพื่อให้งานชั่วคราวและงานเป็นชุดสามารถเปิดเผยตัววัดของตนให้ Prometheus ได้ เนื่องจากงานประเภทนี้อาจมีอยู่ได้ไม่นานพอที่จะคัดลอก จึงสามารถพุชหน่วยเมตริกไปที่ Pushgateway แทนได้ จากนั้น Pushgateway จะเปิดเผยหน่วยวัดเหล่านี้แก่ Prometheus

ไม่ใช่เป้าหมาย

ประการแรก Pushgateway ไม่สามารถเปลี่ยน Prometheus เป็นระบบตรวจสอบแบบพุชได้ สำหรับคำอธิบายทั่วไปเกี่ยวกับกรณีการใช้งาน Pushgateway โปรดอ่านเมื่อใดจึงควรใช้ Pushgateway

Pushgateway ไม่ใช่ ตัวรวบรวมหรือตัวนับแบบกระจาย อย่างชัดเจน แต่เป็นแคชเมตริก มันไม่มีความหมายเหมือน statsd ตัวชี้วัดที่พุชนั้นเหมือนกับที่คุณนำเสนอสำหรับการคัดลอกในโปรแกรมที่ทำงานอย่างถาวรทุกประการ หากคุณต้องการการนับแบบกระจาย คุณสามารถใช้ statsd จริงร่วมกับผู้ส่งออก Prometheus statsd หรือดูที่ Prom-aggregation-gateway ด้วยประสบการณ์ที่รวบรวมได้มากขึ้น วันหนึ่งโครงการ Prometheus อาจจะสามารถจัดหาโซลูชันแบบเนทิฟได้ โดยแยกจากหรืออาจเป็นส่วนหนึ่งของ Pushgateway ก็ได้

สำหรับตัวชี้วัดระดับเครื่อง ตัวรวบรวมไฟล์ข้อความของผู้ส่งออกโหนดมักจะเหมาะสมกว่า Pushgateway มีไว้สำหรับการวัดระดับการบริการ

Pushgateway ไม่ใช่ ร้านจัดงาน แม้ว่าคุณจะสามารถใช้ Prometheus เป็นแหล่งข้อมูลสำหรับคำอธิบายประกอบ Grafana ได้ แต่การติดตามเหตุการณ์เช่นเหตุการณ์การเปิดตัวจะต้องเกิดขึ้นกับเฟรมเวิร์กการบันทึกเหตุการณ์บางอย่าง

เมื่อไม่นานมานี้ เราตัดสินใจที่จะไม่ใช้ "การหมดเวลา" หรือ TTL สำหรับการวัดแบบพุช เนื่องจากกรณีการใช้งานที่เสนอเกือบทั้งหมดกลายเป็นรูปแบบที่ต่อต้านซึ่งเราไม่สนับสนุนอย่างยิ่ง คุณสามารถติดตามการสนทนาล่าสุดเกี่ยวกับรายชื่ออีเมลของนักพัฒนา Prometheus

เรียกใช้มัน

ดาวน์โหลดไบนารี่รีลีสสำหรับแพลตฟอร์มของคุณจากหน้ารีลีส และแกะ tarball

หากคุณต้องการรวบรวมตัวเองจากแหล่งที่มา คุณต้องมีการตั้งค่า Go ที่ใช้งานได้ จากนั้นใช้ Makefile ที่ให้มา (พิมพ์ make )

สำหรับการตั้งค่าพื้นฐานที่สุด เพียงเริ่มไบนารี่ หากต้องการเปลี่ยนที่อยู่ที่จะฟัง ให้ใช้แฟล็ก --web.listen-address (เช่น "0.0.0.0:9091" หรือ ":9091") ตามค่าเริ่มต้น Pushgateway จะไม่คงอยู่การวัด อย่างไรก็ตาม การตั้งค่าสถานะ --persistence.file ช่วยให้คุณสามารถระบุไฟล์ที่เมตริกที่ถูกพุชยังคงอยู่ (เพื่อให้สามารถรีสตาร์ท Pushgateway ได้)

การใช้นักเทียบท่า

คุณสามารถปรับใช้ Pushgateway ได้โดยใช้อิมเมจ Prom/pushgateway Docker

ตัวอย่างเช่น:

docker pull prom/pushgateway

docker run -d -p 9091:9091 prom/pushgateway

ใช้มัน

กำหนดค่า Pushgateway เป็นเป้าหมายที่จะขูด

ต้องกำหนดค่า Pushgateway เป็นเป้าหมายเพื่อขูดโดย Prometheus โดยใช้วิธีปกติวิธีใดวิธีหนึ่ง อย่างไรก็ตาม คุณควรตั้ง honor_labels: true ในการกำหนดค่า scrape เสมอ (ดูคำอธิบายโดยละเอียดด้านล่าง)

ห้องสมุด

ไลบรารีไคลเอ็นต์ Prometheus ควรมีคุณสมบัติในการส่งตัววัดที่ลงทะเบียนไว้ไปยัง Pushgateway โดยปกติแล้ว ไคลเอนต์ Prometheus จะแสดงตัววัดสำหรับการคัดลอกโดยเซิร์ฟเวอร์ Prometheus แบบพาสซีฟ ไลบรารีไคลเอนต์ที่รองรับการพุชมีฟังก์ชันการพุชซึ่งจำเป็นต้องถูกเรียกโดยโค้ดไคลเอนต์ จากนั้นจะผลักดันตัววัดไปยัง Pushgateway อย่างแข็งขัน โดยใช้ API ที่อธิบายไว้ด้านล่าง

บรรทัดคำสั่ง

การใช้โปรโตคอลข้อความ Prometheus การพุชหน่วยวัดเป็นเรื่องง่ายมากจนไม่มี CLI แยกต่างหาก เพียงใช้เครื่องมือ HTTP แบบบรรทัดคำสั่งเช่น curl ภาษาสคริปต์ที่คุณชื่นชอบน่าจะมีความสามารถ HTTP ในตัวที่คุณสามารถใช้ประโยชน์ได้ที่นี่เช่นกัน

โปรดทราบว่าในโปรโตคอลข้อความ แต่ละบรรทัดจะต้องลงท้ายด้วยอักขระป้อนบรรทัด (หรือที่เรียกว่า 'LF' หรือ 'n') การสิ้นสุดบรรทัดด้วยวิธีอื่น เช่น ด้วย 'CR' หรือที่รู้จักในชื่อ 'r', 'CRLF' หรือที่รู้จักในชื่อ 'rn' หรือเพียงแค่สิ้นสุดแพ็กเก็ต จะส่งผลให้เกิดข้อผิดพลาดของโปรโตคอล

ตัววัดที่พุชได้รับการจัดการเป็นกลุ่ม ระบุโดยคีย์การจัดกลุ่มของป้ายกำกับจำนวนเท่าใดก็ได้ โดยคีย์แรกจะต้องเป็นป้ายกำกับ job ตรวจสอบกลุ่มได้ง่ายผ่านทางเว็บอินเตอร์เฟส

สำหรับความหมายของอักขระพิเศษในค่าป้ายกำกับ โปรดดูส่วน URL ด้านล่าง

ตัวอย่าง:

• พุชตัวอย่างเดียวเข้าไปในกลุ่มที่ระบุโดย {job="some_job"} :

    echo "some_metric 3.14" | curl --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job
  

  เนื่องจากไม่ได้ระบุข้อมูลประเภทไว้ some_metric จะเป็นประเภท untyped

• ผลักดันสิ่งที่ซับซ้อนมากขึ้นเข้าไปในกลุ่มที่ระบุโดย {job="some_job",instance="some_instance"} :

    cat <

  โปรดสังเกตวิธีการระบุข้อมูลประเภทและสตริงวิธีใช้ บรรทัดเหล่านั้นเป็นทางเลือก แต่ควรสนับสนุนอย่างยิ่งสำหรับสิ่งที่ซับซ้อนกว่านี้

• ลบตัวชี้วัดทั้งหมดในกลุ่มที่ระบุโดย {job="some_job",instance="some_instance"} :

    curl -X DELETE http://pushgateway.example.org:9091/metrics/job/some_job/instance/some_instance
  

• ลบเมตริกทั้งหมดในกลุ่มที่ระบุโดย {job="some_job"} (โปรดทราบว่าการดำเนินการนี้จะไม่รวมเมตริกในกลุ่ม {job="some_job",instance="some_instance"} จากตัวอย่างก่อนหน้านี้ แม้ว่าเมตริกเหล่านั้นจะมี ป้ายงานเดียวกัน):

    curl -X DELETE http://pushgateway.example.org:9091/metrics/job/some_job
  

• ลบตัวชี้วัดทั้งหมดในทุกกลุ่ม (ต้องเปิดใช้งาน API ผู้ดูแลระบบผ่านแฟล็กบรรทัดคำสั่ง --web.enable-admin-api ):

    curl -X PUT http://pushgateway.example.org:9091/api/v1/admin/wipe
  

เกี่ยวกับป้ายกำกับงานและอินสแตนซ์

เซิร์ฟเวอร์ Prometheus จะแนบป้าย job และป้ายกำกับ instance เข้ากับตัววัดที่คัดลอกมาแต่ละรายการ ค่าของป้าย job มาจากการกำหนดค่าการขูด เมื่อคุณกำหนดค่า Pushgateway เป็นเป้าหมายการคัดลอกสำหรับเซิร์ฟเวอร์ Prometheus ของคุณ คุณอาจเลือกชื่องานเช่น pushgateway ค่าของป้าย instance จะถูกตั้งค่าเป็นโฮสต์และพอร์ตของเป้าหมายที่คัดลอกโดยอัตโนมัติ ดังนั้น ตัววัดทั้งหมดที่คัดลอกมาจาก Pushgateway จะมีโฮสต์และพอร์ตของ Pushgateway เป็นป้ายกำกับ instance และป้ายกำกับ job เช่น pushgateway ข้อขัดแย้งกับป้าย job และ instance ที่คุณอาจแนบไปกับตัววัดที่พุชไปยัง Pushgateway ได้รับการแก้ไขโดยการเปลี่ยนชื่อป้ายกำกับเหล่านั้นเป็น exported_job และ exported_instance

อย่างไรก็ตาม พฤติกรรมนี้มักไม่เป็นที่พึงปรารถนาเมื่อขูด Pushgateway โดยทั่วไป คุณต้องการรักษา job และป้ายกำกับ instance ของตัววัดที่พุชไปยัง Pushgateway นั่นเป็นเหตุผลที่คุณต้องตั้งค่า honor_labels: true ในการกำหนดค่าการขูดสำหรับ Pushgateway ช่วยให้เกิดพฤติกรรมที่ต้องการ ดูเอกสารประกอบสำหรับรายละเอียด

สิ่งนี้ทำให้เรามีกรณีที่ตัววัดที่พุชไปที่ Pushgateway ไม่มีป้ายกำกับ instance กรณีนี้พบได้บ่อยเนื่องจากตัววัดที่พุชมักจะอยู่ในระดับบริการ ดังนั้นจึงไม่เกี่ยวข้องกับอินสแตนซ์ใดโดยเฉพาะ แม้จะมี honor_labels: true เซิร์ฟเวอร์ Prometheus จะแนบป้ายกำกับ instance หากไม่มีการตั้งค่าป้ายกำกับ instance ตั้งแต่แรก ดังนั้น หากตัววัดถูกพุชไปที่ Pushgateway โดยไม่มีป้ายกำกับอินสแตนซ์ (และไม่มีป้ายกำกับอินสแตนซ์ในคีย์การจัดกลุ่ม โปรดดูด้านล่าง) Pushgateway จะส่งออกเมตริกนั้นด้วยป้ายกำกับอินสแตนซ์ว่าง ( {instance=""} ) ซึ่งเทียบเท่ากัน ไม่มีป้ายกำกับ instance เลย แต่ทำให้เซิร์ฟเวอร์ไม่สามารถแนบป้ายกำกับได้

เกี่ยวกับความไม่สอดคล้องกันของเมตริก

Pushgateway เปิดเผยตัววัดที่พุชทั้งหมดพร้อมกับตัววัดของตัวเองผ่านทางตำแหน่ง /metrics เดียวกัน (ดูรายละเอียดในหัวข้อเกี่ยวกับเมตริกที่เปิดเผย) ดังนั้น เมตริกทั้งหมดจะต้องสอดคล้องกัน: เมตริกที่มีชื่อเดียวกันจะต้องมีประเภทเดียวกัน แม้ว่าจะถูกพุชไปยังกลุ่มที่แตกต่างกัน และจะต้องไม่มีการซ้ำกัน กล่าวคือ เมตริกที่มีชื่อเดียวกันและคู่ป้ายกำกับเดียวกันทุกประการ การพุชที่อาจนำไปสู่ความไม่สอดคล้องกันจะถูกปฏิเสธด้วยรหัสสถานะ 400

แม้ว่าสตริงความช่วยเหลือที่ไม่สอดคล้องกันจะได้รับการยอมรับก็ตาม Pushgateway จะเลือกสตริงความช่วยเหลือที่ชนะและบันทึกเกี่ยวกับมันในระดับข้อมูล

หมายเหตุแบบดั้งเดิม: สตริงวิธีใช้ของการวัด push_time_seconds ของ Pushgateway มีการเปลี่ยนแปลงในเวอร์ชัน 0.10.0 ด้วยการใช้ไฟล์คงอยู่ ตัววัดที่พุชไปยัง Pushgateway เวอร์ชันก่อนหน้าสามารถทำให้เป็น Pushgateway เวอร์ชัน 0.10.0 หรือใหม่กว่าได้ ในกรณีนี้ ข้อความบันทึกที่กล่าวถึงข้างต้นจะปรากฏขึ้น เมื่อแต่ละกลุ่มที่พุชก่อนหน้านี้ถูกลบหรือได้รับการพุชใหม่ ข้อความบันทึกจะหายไป

การตรวจสอบความสอดคล้องที่ดำเนินการระหว่างการพุชจะเหมือนกับการตรวจสอบที่เกิดขึ้นในระหว่างการขูด ในกรณีการใช้งานทั่วไป การขูดจะเกิดขึ้นบ่อยกว่าการพุช ดังนั้นต้นทุนประสิทธิภาพของการตรวจสอบเวลาแบบพุชจึงไม่เกี่ยวข้อง อย่างไรก็ตาม หากมีการรวมตัววัดจำนวนมากบน Pushgateway เข้ากับการพุชบ่อยครั้ง ระยะเวลาการพุชอาจนานจนเกินไป ในกรณีนี้ คุณอาจลองใช้แฟล็กบรรทัดคำสั่ง --push.disable-consistency-check ซึ่งช่วยประหยัดค่าใช้จ่ายในการตรวจสอบความสอดคล้องระหว่างการพุช แต่ช่วยให้พุชหน่วยวัดที่ไม่สอดคล้องกันได้ การตรวจสอบจะยังคงเกิดขึ้นในระหว่างการขูด ดังนั้นการคัดลอกทั้งหมดจะล้มเหลวตราบใดที่มีการจัดเก็บตัววัดที่ไม่สอดคล้องกันบน Pushgateway การตั้งค่าสถานะทำให้คุณมีความเสี่ยงที่จะปิดการใช้งาน Pushgateway โดยการกดที่ไม่สอดคล้องกันเพียงครั้งเดียว

เกี่ยวกับการประทับเวลา

หากคุณพุชหน่วยเมตริก ณ เวลา t 1 คุณอาจถูกล่อลวงให้เชื่อว่า Prometheus จะขูดหน่วยเมตริกเหล่านั้นด้วยการประทับเวลาเดียวกันนั้น t 1 สิ่งที่ Prometheus แนบไว้เป็นการประทับเวลาคือเวลาที่ขูด Pushgateway แทน ทำไมเป็นเช่นนั้น?

ในมุมมองโลกของ Prometheus คุณสามารถคัดลอกหน่วยวัดได้ตลอดเวลา โดยทั่วไปแล้ว เมตริกที่ไม่สามารถคัดลอกได้นั้นได้ยุติลงแล้ว Prometheus ค่อนข้างมีความทนทาน แต่หากไม่สามารถรับตัวอย่างใดๆ สำหรับหน่วยวัดได้ภายใน 5 นาที ก็จะทำงานเหมือนกับว่าไม่มีหน่วยวัดนั้นอีกต่อไป การป้องกันนั่นเป็นเหตุผลหนึ่งที่ต้องใช้ Pushgateway Pushgateway จะทำให้หน่วยวัดของงานชั่วคราวของคุณสามารถคัดลอกได้ตลอดเวลา การแนบเวลาของการพุชเป็นการประทับเวลาอาจเอาชนะจุดประสงค์นั้นได้ เนื่องจาก 5 นาทีหลังจากการพุชครั้งล่าสุด หน่วยวัดของคุณจะดูเก่าสำหรับ Prometheus ราวกับว่าไม่สามารถขูดได้เลยอีกต่อไป (โพรมีธีอุสรู้การประทับเวลาเพียงครั้งเดียวต่อตัวอย่าง ไม่มีวิธีใดที่จะแยกแยะ 'เวลาในการผลัก' และ 'เวลาในการขูด' ได้)

เนื่องจากไม่มีกรณีการใช้งานใดๆ ที่ควรแนบการประทับเวลาอื่น และผู้ใช้จำนวนมากพยายามทำเช่นนั้นอย่างไม่ถูกต้อง (แม้ว่าไลบรารีไคลเอ็นต์จะไม่รองรับสิ่งนี้ก็ตาม) Pushgateway จะปฏิเสธการพุชที่มีการประทับเวลา

หากคุณคิดว่าคุณจำเป็นต้องพุชการประทับเวลา โปรดดูเมื่อต้องใช้ Pushgateway

เพื่อให้ง่ายต่อการแจ้งเตือนเกี่ยวกับผู้ส่งที่ล้มเหลวหรือที่ไม่ได้ทำงานเมื่อเร็ว ๆ นี้ Pushgateway จะเพิ่มตัวชี้วัด push_time_seconds และ push_failure_time_seconds พร้อมด้วยการประทับเวลา Unix ของ POST / PUT ที่สำเร็จและล้มเหลวครั้งล่าสุดในแต่ละกลุ่ม การดำเนินการนี้จะแทนที่เมตริกที่พุชด้วยชื่อนั้น ค่าศูนย์สำหรับเมตริกใดๆ หมายความว่ากลุ่มไม่เคยเห็น POST / PUT ที่สำเร็จหรือล้มเหลว

เอพีไอ

การพุชทั้งหมดทำได้ผ่าน HTTP อินเทอร์เฟซนั้นเหมือนกับ REST อย่างคลุมเครือ

URL

พอร์ตเริ่มต้นที่ Pushgateway กำลังฟังอยู่คือ 9091 เส้นทางมีลักษณะดังนี้

 /metrics/job/{//}

ถูกใช้เป็นค่าของป้าย job ตามด้วยคู่ป้ายกำกับอื่นๆ จำนวนเท่าใดก็ได้ (ซึ่งอาจมีหรือไม่มีป้ายกำกับ instance ก็ได้) ชุดป้ายกำกับที่กำหนดโดยเส้นทาง URL จะถูกใช้เป็นคีย์การจัดกลุ่ม ป้ายกำกับใดๆ ที่ตั้งค่าไว้แล้วในเนื้อความของคำขอ (เช่น ป้ายกำกับปกติ เช่น name{job="foo"} 42 ) จะถูกเขียนทับเพื่อให้ตรงกับป้ายกำกับที่กำหนดโดยเส้นทาง URL!

หาก job หรือชื่อป้ายกำกับใดๆ ต่อท้ายด้วย @base64 ชื่องานหรือค่าป้ายกำกับต่อไปนี้จะถูกตีความว่าเป็นสตริงที่เข้ารหัส base64 ตาม RFC 4648 โดยใช้ URL และตัวอักษรที่ปลอดภัยของชื่อไฟล์ (การเติมเป็นทางเลือก แต่ต้องใช้ = เดียวในการเข้ารหัสค่าเลเบลว่าง) นี่เป็นวิธีเดียวที่จะจัดการกับกรณีต่อไปนี้:

• ชื่องานหรือค่าป้ายกำกับที่มี / เนื่องจากธรรมดา (หรือแม้แต่เข้ารหัส URI) / จะถูกตีความว่าเป็นตัวแยกเส้นทาง
• ค่าป้ายกำกับว่างเปล่า เนื่องจากผลลัพธ์ // หรือต่อท้าย / จะหายไปเมื่อเส้นทางถูกทำให้สะอาดด้วยโค้ดเราเตอร์ HTTP โปรดทราบว่าชื่อ job ที่ว่างเปล่าไม่ถูกต้อง ค่าป้ายกำกับที่ว่างเปล่านั้นถูกต้องแต่ไม่ค่อยมีประโยชน์ หากต้องการเข้ารหัสด้วย base64 คุณต้องใช้อักขระ = padding อย่างน้อยหนึ่งตัวเพื่อหลีกเลี่ยงการ // หรือส่วนท้าย /

สำหรับอักขระพิเศษอื่นๆ การเข้ารหัสองค์ประกอบ URI ตามปกติก็ใช้งานได้เช่นกัน แต่ base64 อาจสะดวกกว่า

ตามหลักการแล้ว ไลบรารีไคลเอ็นต์จะดูแลส่วนต่อท้ายและการเข้ารหัส

ตัวอย่าง:

• หากต้องการใช้คีย์การจัดกลุ่ม job="directory_cleaner",path="/var/tmp" พาธต่อไปนี้จะ ไม่ ทำงาน:

   /metrics/job/directory_cleaner/path//var/tmp
  

  ให้ใช้การเข้ารหัส URL ที่ปลอดภัยแบบ base64 สำหรับค่าป้ายกำกับและทำเครื่องหมายโดยต่อท้ายชื่อป้ายกำกับด้วย @base64 :

   /metrics/job/directory_cleaner/path@base64/L3Zhci90bXA
  

  หากคุณไม่ได้ใช้ไลบรารีไคลเอ็นต์ที่จัดการการเข้ารหัสสำหรับคุณ คุณสามารถใช้เครื่องมือการเข้ารหัสได้ ตัวอย่างเช่น มีเครื่องมือบรรทัดคำสั่ง base64url (แพ็คเกจ Debian basez ) ซึ่งคุณสามารถรวมกับ curl เพื่อพุชจากบรรทัดคำสั่งด้วยวิธีต่อไปนี้:

   echo 'some_metric{foo="bar"} 3.14' | curl --data-binary @- http://pushgateway.example.org:9091/metrics/job/directory_cleaner/path@base64/$(echo -n '/var/tmp' | base64url)
  

• หากต้องการใช้คีย์การจัดกลุ่มที่มีค่าป้ายกำกับว่าง เช่น job="example",first_label="",second_label="foobar" เส้นทางต่อไปนี้จะ ไม่ ทำงาน:

   /metrics/job/example/first_label//second_label/foobar
  

  ให้ใช้เส้นทางต่อไปนี้รวมถึงอักขระ = padding แทน:

   /metrics/job/example/first_label@base64/=/second_label/foobar
  

• คีย์การจัดกลุ่ม job="titan",name="Προμηθεύς" สามารถแสดงแบบ "ดั้งเดิม" ด้วยการเข้ารหัส URI:

   /metrics/job/titan/name/%CE%A0%CF%81%CE%BF%CE%BC%CE%B7%CE%B8%CE%B5%CF%8D%CF%82
  

  หรือคุณสามารถใช้การเข้ารหัส base64 ที่กะทัดรัดยิ่งขึ้น:

   /metrics/job/titan/name@base64/zqDPgc6_zrzOt864zrXPjc-C
  

รองรับ UTF-8 สำหรับชื่อเมตริกและป้ายกำกับ

รูปแบบการแสดงออกของ Prometheus เวอร์ชันใหม่กว่า (ข้อความและ protobuf) รองรับชุดอักขระ UTF-8 แบบเต็มในชื่อหน่วยเมตริกและป้ายกำกับ Pushgateway ยอมรับเฉพาะอักขระพิเศษในชื่อหากตั้งค่าสถานะบรรทัดคำสั่ง --push.enable-utf8-names หากต้องการอนุญาตให้ใช้อักขระพิเศษในชื่อป้ายกำกับที่เป็นส่วนหนึ่งของเส้นทาง URL แฟล็กยังเปิดใช้งานกลไกการเข้ารหัสเฉพาะอีกด้วย ซึ่งคล้ายกับการเข้ารหัส base64 สำหรับ ค่า ป้ายกำกับที่อธิบายไว้ข้างต้น แต่ทำงานแตกต่างกันในรายละเอียดด้วยเหตุผลทางเทคนิคและในอดีต โดยปกติแล้วไลบรารีไคลเอ็นต์ควรดูแลการเข้ารหัส มันทำงานดังนี้:

• ชื่อป้ายกำกับที่มีอักขระที่เข้ารหัสเริ่มต้นด้วย U__
• อักขระที่ไม่เป็นมาตรฐานทั้งหมด (เช่น อักขระอื่นที่ไม่ใช่ตัวอักษร ตัวเลข และขีดล่าง) จะถูกเข้ารหัสเป็นขีดล่างล้อมรอบค่า Unicode เช่น _1F60A_
• ขีดล่างที่มีอยู่แล้วทั้งหมดจะถูกเข้ารหัสเป็นขีดล่างคู่: __
• หากชื่อป้ายกำกับขึ้นต้นด้วย U__ แล้ว อักขระเหล่านี้จะต้องได้รับการเข้ารหัสด้วย ซึ่งจะส่งผลให้เป็น U___55_____ (นั่นคือ U__ + _55_ (สำหรับ U ) + __ + __ )
• ชื่อป้ายกำกับที่ขึ้นต้นด้วย U__ ในรูปแบบที่เข้ารหัส แต่มีลำดับที่ไม่ถูกต้อง (เช่น U__in_xxx_valid ) จะไม่มีการเปลี่ยนแปลง

ตัวอย่างเช่น ป้ายกำกับ "foo.bar"="baz" จะถูกเข้ารหัสดังนี้:

 /metrics/job/example/U__foo_2e_bar/baz

การเข้ารหัสนี้เข้ากันได้กับการเข้ารหัส base64 สำหรับค่าป้ายกำกับ:

 /metrics/job/example/U__foo_2e_bar@base64/YmF6

โปรดทราบว่าวิธีนี้มีกรณี Edge ที่ไม่น่าเป็นไปได้ซึ่งไม่ได้รับการจัดการอย่างถูกต้อง: ผู้ผลักดันที่ไม่ทราบถึงกลไกการเข้ารหัสอาจใช้ชื่อป้ายกำกับที่เป็นเวอร์ชันเข้ารหัสที่ถูกต้องของชื่อป้ายกำกับอื่น เช่น หากผู้ผลักดันตั้งใจที่จะใช้ชื่อป้ายกำกับ U__foo_2e_bar แต่ไม่เข้ารหัสเป็น U___55_____foo__2e__bar Pushgateway จะถอดรหัส U__foo_2e_bar เป็น foo.bar นี่คือสาเหตุหลักว่าทำไมจึงเลือกใช้การถอดรหัสผ่านแฟล็ก --push.enable-utf8-names

วิธี PUT

PUT ใช้เพื่อพุชกลุ่มของเมตริก เมตริกทั้งหมดที่มีคีย์การจัดกลุ่มที่ระบุใน URL จะถูกแทนที่ด้วยเมตริกที่พุชด้วย PUT

เนื้อความของคำขอมีตัววัดที่จะพุชเป็นบัฟเฟอร์โปรโตคอลไบนารีแบบคั่นหรือในรูปแบบข้อความธรรมดาธรรมดา (ทั้งในเวอร์ชัน 0.0.4 โปรดดูข้อกำหนดรูปแบบการแสดงข้อมูล) การเลือกปฏิบัติระหว่างตัวแปรทั้งสองทำได้ผ่านส่วนหัว Content-Type (ใช้ค่า application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited สำหรับบัฟเฟอร์โปรโตคอล มิฉะนั้น ระบบจะพยายามใช้รูปแบบข้อความเป็นแบบสำรอง)

รหัสตอบกลับเมื่อสำเร็จคือ 200, 202 หรือ 400 การตอบสนอง 200 หมายถึงการพุชที่ประสบความสำเร็จ ไม่ว่าจะแทนที่กลุ่มเมตริกที่มีอยู่หรือสร้างกลุ่มใหม่ การตอบสนอง 400 อาจเกิดขึ้นได้หากคำขอมีรูปแบบไม่ถูกต้อง หรือหากตัววัดที่พุชไม่สอดคล้องกับตัววัดที่พุชไปยังกลุ่มอื่น หรือขัดแย้งกับตัววัดของ Pushgateway เอง คำอธิบายจะถูกส่งกลับในเนื้อความของการตอบกลับและบันทึกไว้ในระดับข้อผิดพลาด 202 สามารถเกิดขึ้นได้ก็ต่อเมื่อมีการตั้งค่าสถานะ --push.disable-consistency-check ในกรณีนี้ เมทริกที่พุชจะอยู่ในคิวเท่านั้นและไม่ได้ตรวจสอบความสอดคล้องกัน ความไม่สอดคล้องกันจะนำไปสู่การขูดที่ล้มเหลวตามที่อธิบายไว้ข้างต้น

ในบางกรณีที่เกิดขึ้นไม่บ่อยนัก อาจเป็นไปได้ที่ Pushgateway จบลงด้วยชุดเมตริกที่ไม่สอดคล้องกันที่ถูกพุชไปแล้ว ในกรณีนั้น การพุชใหม่จะถูกปฏิเสธเช่นกันว่าไม่สอดคล้องกัน แม้ว่าผู้ร้ายจะเป็นหน่วยเมตริกที่ถูกพุชก่อนหน้านี้ก็ตาม ลบตัวชี้วัดที่ไม่เหมาะสมเพื่อออกจากสถานการณ์นั้น

หากใช้รูปแบบ protobuf อย่าส่งข้อความโปรโต MetricFamily ที่ซ้ำกัน (เช่น มากกว่าหนึ่งข้อความที่มีชื่อเดียวกัน) ในการกดเพียงครั้งเดียว เนื่องจากข้อความเหล่านี้จะเขียนทับซึ่งกันและกัน

โปรดทราบว่า Pushgateway ไม่ได้ให้การรับประกันที่ชัดเจนใดๆ ว่าเมตริกที่พุชจะยังคงอยู่ในดิสก์ (เซิร์ฟเวอร์ล่มอาจทำให้ข้อมูลสูญหาย หรือมีการกำหนดค่า Pushgateway ไม่ให้คงอยู่ในดิสก์เลย)

คำขอ PUT ที่มีเนื้อหาว่างจะลบเมตริกทั้งหมดที่มีคีย์การจัดกลุ่มที่ระบุอย่างมีประสิทธิภาพ อย่างไรก็ตาม ตรงกันข้ามกับคำขอ DELETE ที่อธิบายไว้ด้านล่าง คำขอจะอัปเดตเมตริก push_time_seconds

วิธี POST

POST ทำงานเหมือนกับวิธี PUT ทุกประการ แต่จะแทนที่เฉพาะหน่วยเมตริกที่มีชื่อเดียวกันกับหน่วยเมตริกที่เพิ่งพุชใหม่เท่านั้น (ในจำนวนที่มีคีย์การจัดกลุ่มเดียวกัน)

คำขอ POST ที่มีเนื้อหาว่างเปล่าเพียงอัปเดตตัววัด push_time_seconds แต่ไม่ได้เปลี่ยนแปลงตัววัดใด ๆ ที่พุชก่อนหน้านี้

วิธี DELETE

DELETE ใช้เพื่อลบเมตริกออกจาก Pushgateway คำขอจะต้องไม่มีเนื้อหาใดๆ เมตริกทั้งหมดที่มีคีย์การจัดกลุ่มที่ระบุใน URL จะถูกลบออก

รหัสตอบกลับเมื่อสำเร็จจะเป็น 202 เสมอ คำขอลบจะอยู่ในคิวในขณะนั้นเท่านั้น ไม่มีการรับประกันว่าคำขอจะถูกดำเนินการจริงหรือผลลัพธ์จะส่งไปยังเลเยอร์การคงอยู่ (เช่น ในกรณีที่เซิร์ฟเวอร์ขัดข้อง) อย่างไรก็ตาม รับประกันลำดับคำขอ PUT / POST และ DELETE เช่น หากคุณส่งคำขอ DELETE สำเร็จแล้วส่ง PUT รับประกันว่า DELETE จะได้รับการประมวลผลก่อน (และในทางกลับกัน)

การลบคีย์การจัดกลุ่มโดยไม่มีเมตริกเป็นการดำเนินการที่ไม่จำเป็นและจะไม่ส่งผลให้เกิดข้อผิดพลาด

ขอการบีบอัด

เนื้อความของคำขอ POST หรือ PUT อาจมีการบีบอัดแบบ gzip หรือ snappy เพิ่มส่วนหัว Content-Encoding: gzip หรือ Content-Encoding: snappy เพื่อดำเนินการดังกล่าว

ตัวอย่าง:

 echo " some_metric 3.14 " | gzip | curl -H ' Content-Encoding: gzip ' --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job
echo " some_metric 3.14 " | snzip | curl -H ' Content-Encoding: snappy ' --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job

API ผู้ดูแลระบบ

Admin API ให้สิทธิ์ผู้ดูแลระบบในการเข้าถึง Pushgateway และต้องเปิดใช้งานอย่างชัดเจนโดยการตั้งค่าสถานะ --web.enable-admin-api

URL

พอร์ตเริ่มต้นที่ Pushgateway กำลังฟังคือ 9091 เส้นทางมีลักษณะดังนี้:

 /api//admin/

• ปลายทางที่มีอยู่:

HTTP_METHOD	API_VERSION	ตัวจัดการ	คำอธิบาย
ใส่	เวอร์ชัน 1	เช็ด	ลบเมตริกทั้งหมดออกจาก Pushgateway อย่างปลอดภัย

• ตัวอย่างเช่น การล้างข้อมูลเมตริกทั้งหมดจาก Pushgateway:

    curl -X PUT http://pushgateway.example.org:9091/api/v1/admin/wipe
  

สอบถาม API

API การสืบค้นช่วยให้สามารถเข้าถึงตัววัดที่พุชและข้อมูลบิลด์และรันไทม์ได้

URL

 /api//

• ปลายทางที่มีอยู่:

HTTP_METHOD	API_VERSION	ตัวจัดการ	คำอธิบาย
รับ	เวอร์ชัน 1	สถานะ	ส่งคืนข้อมูลบิวด์ แฟล็กบรรทัดคำสั่ง และเวลาเริ่มต้นในรูปแบบ JSON
รับ	เวอร์ชัน 1	เมตริก	ส่งคืนกลุ่มเมตริกที่พุชในรูปแบบ JSON

• ตัวอย่างเช่น :

    curl -X GET http://pushgateway.example.org:9091/api/v1/status | jq
    
    {
      "status": "success",
      "data": {
        "build_information": {
          "branch": "master",
          "buildDate": "20200310-20:14:39",
          "buildUser": "[email protected]",
          "goVersion": "go1.13.6",
          "revision": "eba0ec4100873d23666bcf4b8b1d44617d6430c4",
          "version": "1.1.0"
        },
        "flags": {
          "log.format": "logfmt",
          "log.level": "info",
          "persistence.file": "",
          "persistence.interval": "5m0s",
          "push.disable-consistency-check": "false",
          "web.enable-admin-api": "false",
          "web.enable-lifecycle": "false",
          "web.external-url": "",
          "web.listen-address": ":9091",
          "web.route-prefix": "",
          "web.telemetry-path": "/metrics"
        },
        "start_time": "2020-03-11T01:44:49.9189758+05:30"
      }
    }
    
    curl -X GET http://pushgateway.example.org:9091/api/v1/metrics | jq
    
    {
      "status": "success",
      "data": [
        {
          "labels": {
            "job": "batch"
          },
          "last_push_successful": true,
          "my_job_duration_seconds": {
            "time_stamp": "2020-03-11T02:02:27.716605811+05:30",
            "type": "GAUGE",
            "help": "Duration of my batch job in seconds",
            "metrics": [
              {
                "labels": {
                  "instance": "",
                  "job": "batch"
                },
                "value": "0.2721322309989773"
              }
            ]
          },
          "push_failure_time_seconds": {
            "time_stamp": "2020-03-11T02:02:27.716605811+05:30",
            "type": "GAUGE",
            "help": "Last Unix time when changing this group in the Pushgateway failed.",
            "metrics": [
              {
                "labels": {
                  "instance": "",
                  "job": "batch"
                },
                "value": "0"
              }
            ]
          },
          "push_time_seconds": {
            "time_stamp": "2020-03-11T02:02:27.716605811+05:30",
            "type": "GAUGE",
            "help": "Last Unix time when changing this group in the Pushgateway succeeded.",
            "metrics": [
              {
                "labels": {
                  "instance": "",
                  "job": "batch"
                },
                "value": "1.5838723477166057e+09"
              }
            ]
          }
        }
      ]
    }
  

API การจัดการ

Pushgateway มอบชุด API การจัดการเพื่อทำให้ระบบอัตโนมัติและการผสานรวมง่ายขึ้น

• ปลายทางที่มีอยู่:

HTTP_METHOD	เส้นทาง	คำอธิบาย
รับ	/-/สุขภาพดี	ส่งคืน 200 ทุกครั้งที่ Pushgateway มีสุขภาพดี
รับ	/-/พร้อม	ส่งกลับ 200 เมื่อใดก็ตามที่ Pushgateway พร้อมให้บริการการจราจร

• ตำแหน่งข้อมูลต่อไปนี้ถูกปิดใช้งานโดยค่าเริ่มต้น และสามารถเปิดใช้งานได้ผ่านทางแฟล็ก --web.enable-lifecycle

HTTP_METHOD	เส้นทาง	คำอธิบาย
ใส่	/-/ล้มเลิก	ทริกเกอร์การปิดระบบ Pushgateway อย่างสง่างาม

อีกทางหนึ่ง สามารถทริกเกอร์การปิดระบบอย่างค่อยเป็นค่อยไปได้โดยการส่ง SIGTERM ไปยังกระบวนการ Pushgateway

เมตริกที่เปิดเผย

Pushgateway เปิดเผยตัววัดต่อไปนี้ผ่านทาง --web.telemetry-path ที่กำหนดค่าไว้ (ค่าเริ่มต้น: /metrics ):

• ตัวชี้วัดที่ถูกผลักดัน
• สำหรับแต่ละกลุ่มที่พุช จะมีเมตริก push_time_seconds และ push_failure_time_seconds ตามที่อธิบายไว้ข้างต้น
• ตัววัดปกติที่จัดทำโดยไลบรารีไคลเอ็นต์ Prometheus Go ได้แก่:
  • process_...
  • go_...
  • promhttp_metric_handler_requests_...
• ตัวชี้วัดจำนวนหนึ่งเฉพาะสำหรับ Pushgateway ตามที่บันทึกไว้ในตัวอย่างการขูดด้านล่าง

 # HELP pushgateway_build_info A metric with a constant '1' value labeled by version, revision, branch, and goversion from which pushgateway was built.
# TYPE pushgateway_build_info gauge
pushgateway_build_info{branch="master",goversion="go1.10.2",revision="8f88ccb0343fc3382f6b93a9d258797dcb15f770",version="0.5.2"} 1
# HELP pushgateway_http_push_duration_seconds HTTP request duration for pushes to the Pushgateway.
# TYPE pushgateway_http_push_duration_seconds summary
pushgateway_http_push_duration_seconds{method="post",quantile="0.1"} 0.000116755
pushgateway_http_push_duration_seconds{method="post",quantile="0.5"} 0.000192608
pushgateway_http_push_duration_seconds{method="post",quantile="0.9"} 0.000327593
pushgateway_http_push_duration_seconds_sum{method="post"} 0.001622878
pushgateway_http_push_duration_seconds_count{method="post"} 8
# HELP pushgateway_http_push_size_bytes HTTP request size for pushes to the Pushgateway.
# TYPE pushgateway_http_push_size_bytes summary
pushgateway_http_push_size_bytes{method="post",quantile="0.1"} 166
pushgateway_http_push_size_bytes{method="post",quantile="0.5"} 182
pushgateway_http_push_size_bytes{method="post",quantile="0.9"} 196
pushgateway_http_push_size_bytes_sum{method="post"} 1450
pushgateway_http_push_size_bytes_count{method="post"} 8
# HELP pushgateway_http_requests_total Total HTTP requests processed by the Pushgateway, excluding scrapes.
# TYPE pushgateway_http_requests_total counter
pushgateway_http_requests_total{code="200",handler="static",method="get"} 5
pushgateway_http_requests_total{code="200",handler="status",method="get"} 8
pushgateway_http_requests_total{code="202",handler="delete",method="delete"} 1
pushgateway_http_requests_total{code="202",handler="push",method="post"} 6
pushgateway_http_requests_total{code="400",handler="push",method="post"} 2

แจ้งเตือนเมื่อพุชล้มเหลว

โดยทั่วไปแล้ว เป็นความคิดที่ดีที่จะแจ้งเตือนเมื่อ push_time_seconds ช้ากว่าที่คาดไว้มาก วิธีนี้จะตรวจจับทั้งการผลักที่ล้มเหลวและผู้ผลักที่ล้มลงโดยสิ้นเชิง

หากต้องการตรวจจับการพุชที่ล้มเหลวเร็วขึ้น ให้แจ้งเตือนเมื่อ push_failure_time_seconds > push_time_seconds

การพุชอาจล้มเหลวได้เนื่องจากมีรูปแบบไม่ถูกต้อง ในกรณีนี้ พวกเขาจะไม่เข้าถึงกลุ่มเมตริกใดๆ เลย ดังนั้นจะไม่ตั้งค่าเมตริก push_failure_time_seconds ใดๆ การพุชเหล่านั้นยังคงนับเป็น pushgateway_http_requests_total{code="400",handler="push"} คุณสามารถแจ้งเตือน rate ของตัวชี้วัดนี้ได้ แต่คุณต้องตรวจสอบบันทึกเพื่อระบุผู้กระทำผิด

TLS และการรับรองความถูกต้องขั้นพื้นฐาน

Pushgateway รองรับ TLS และการตรวจสอบสิทธิ์ขั้นพื้นฐาน ซึ่งช่วยให้สามารถควบคุมจุดสิ้นสุด HTTP ต่างๆ ได้ดียิ่งขึ้น

หากต้องการใช้ TLS และ/หรือการตรวจสอบสิทธิ์ขั้นพื้นฐาน คุณต้องส่งไฟล์การกำหนดค่าโดยใช้พารามิเตอร์ --web.config.file รูปแบบของไฟล์อธิบายไว้ในที่เก็บเครื่องมือผู้ส่งออก

โปรดทราบว่าการตั้งค่า TLS และการตรวจสอบสิทธิ์ขั้นพื้นฐานส่งผลต่อตำแหน่งข้อมูล HTTP ทั้งหมด: /metrics for scraping, API เพื่อพุชตัววัดผ่าน /metrics/..., API ผู้ดูแลระบบผ่าน /api/... และ UI ของเว็บ

การพัฒนา

ไบนารีปกติฝังไฟล์เว็บไว้ในไดเร็กทอรี resources เพื่อวัตถุประสงค์ในการพัฒนา จะสะดวกมากที่จะให้ไบนารี่ที่กำลังรันอยู่ใช้ไฟล์เหล่านั้นโดยตรง (เพื่อให้คุณเห็นผลกระทบของการเปลี่ยนแปลงได้ทันที) หากต้องการสลับไปใช้โดยตรง ให้เพิ่ม -tags dev ในรายการ flags ใน .promu.yml จากนั้น make build เปลี่ยนกลับเป็นโหมด "ปกติ" โดยคืนค่าการเปลี่ยนแปลงเป็น .promu.yml แล้วพิมพ์ make assets

มีส่วนร่วม

แนวทางสไตล์ที่เกี่ยวข้องคือความคิดเห็นเกี่ยวกับการตรวจสอบโค้ด Go และส่วน การจัดรูปแบบและสไตล์ ของ Go ของ Peter Bourgon: แนวทางปฏิบัติที่ดีที่สุดสำหรับสภาพแวดล้อมการผลิต