📘 תיעוד 65

מדדי שרת המפתחות

עודכן לאחרונה: 3 ביוני 2026

שרת המפתחות gokeyless חושף נקודת קצה של מדדי Prometheus שאפשר להשתמש בה כדי לעקוב אחרי ביצועי חתימה, שיעורי שגיאה, תקינות חיבורים ותפוגת אישורים. אפשר גם לאסוף את נקודת הקצה הזו באמצעות מקלט Prometheus של OpenTelemetry Collector, וכך להפוך את המדדים לזמינים לכל backend תואם OpenTelemetry.

#נקודת קצה של המדדים

כברירת מחדל, המדדים מוגשים בכתובת:

http://<host>:2406/metrics

אפשר להגדיר את הפורט באמצעות המפתח metrics_port בקובץ התצורה, הדגל --metrics-port, או משתנה הסביבה KEYLESS_METRICS_PORT.

נקודת הקצה מגישה רק את /metrics. אין נקודות קצה נוספות של HTTP כמו /health או /debug.

#דליים של היסטוגרמה

כל מדדי ההיסטוגרמה חולקים את אותה תצורת דליים: 15 דליים מעריכיים שמתחילים ב-100 מיקרו-שניות, מוכפלים בכל צעד עד כ-1.64 שניות, ועוד דלי +Inf אחרון.

הערה

בשימוש במודול אבטחת חומרה (HSM) עם מאגר סשנים של PKCS#11, פסק הזמן להמתנה למאגר קבוע בקוד על 10 שניות. לכן אירוע של מיצוי המאגר תמיד יופיע בדלי +Inf. עליות בתצפיות +Inf בפעולות חתימה עם error="cryptography error" הן אינדיקציה ישירה לרוויה של מאגר הסשנים של PKCS#11.

#מדריך המדדים

#keyless_requests

סוג: Counter
תוויות: opcode

סופר כל בקשה נכנסת שהתקבלה על חיבור שכבר הוקם, בלי קשר לתוצאה. עולה באחד לכל בקשה לפני שמתחיל עיבוד כלשהו.

תווית opcode משתמשת בשם הקבוע המלא מפרוטוקול gokeyless.

#פעולות RSA

#פעולות ECDSA

#חתימה אחרת

#פעולות איטום ותשתית

#keyless_request_exec_duration_per_opcode

סוג: Histogram
תוויות: type, error

מודד את הזמן לביצוע פעולה אחת, מהרגע שבו העיבוד מתחיל ועד שנוצרת תשובה. בפעולות שמגובות ב-HSM של PKCS#11, הזמן כולל את כל ההמתנה לסשן מהמאגר וגם את זמן הפעולה הקריפטוגרפית ב-HSM.

המדד הזה לא כולל זמן שבו בקשה ממתינה לחריץ בסמפור החיבור. זמן זה נלכד ב-keyless_request_total_duration_per_opcode.

#תווית type

ערכי opcode מקובצים לקטגוריות גסות יותר עבור תווית זו:

הערה

OpPing מקובץ ל-other יחד עם OpSeal ו-OpUnseal. אי אפשר להפריד במדד הזה את חביון הלוך-חזור של Ping מחביון פעולות seal ו-unseal.

#תווית error

בבקשות שהצליחו הערך הוא no error. כל שאר הערכים מציינים פעולה שנכשלה.

#keyless_request_total_duration_per_opcode

סוג: Histogram
תוויות: type, error (אותם ערכים כמו ב-keyless_request_exec_duration_per_opcode)

מודד את הזמן הכולל למילוי בקשה, מרגע שחבילת הבקשה נקראת מהקו ועד שבתים של התשובה נכתבים בחזרה ללקוח.

total_duration = exec_duration + response_write_time

שתי חותמות הזמן נלכדות אחרי שסמפור החיבור כבר מוחזק, ולכן זמן ההמתנה בתור של הסמפור לא נכלל באף אחת משתי ההיסטוגרמות. בעומס רגיל, המשך הכולל ומשך הביצוע שווים בקירוב. פער גדל ביניהם מעיד על כתיבה איטית בחזרה ללקוח, למשל לחץ נגדי ברשת בין שרת המפתחות לקצה של Cloudflare.

#keyless_key_load_duration

סוג: Histogram
תוויות: אין

מודד את הזמן שלוקח ל-keystore לאתר ולהחזיר את המפתח הפרטי לכל בקשה, לפי SKI, SNI וכתובת IP של השרת.

• במאגרי מפתחות שמגובים בקבצים, זהו חיפוש במפה, ובדרך כלל הוא קצר ממילישנייה.
• במאגרי מפתחות של PKCS#11 או HSM, זה עשוי לכלול הלוך-חזור ברשת אל ה-HSM אם הפניות למפתחות אינן שמורות במטמון בזיכרון.

המדד נרשם לכל פעולות החתימה והפענוח: OpRSADecrypt, כל OpRSASign*, כל OpRSAPSSSign*, כל OpECDSASign* ו-OpEd25519Sign.

הוא לא נרשם עבור OpPing, OpSeal, OpUnseal, OpRPC או OpCustom, שאינם דורשים חיפוש מפתח פרטי.

#keyless_failed_connection

סוג: Counter
תוויות: אין

סופר כשלי תעבורה ברמת החיבור. המדד הזה משקף בעיות בשכבת הרשת או TLS. הוא לא סופר שגיאות חתימה או כשלי חיפוש מפתח, שמדווחים בתווית error של היסטוגרמות המשך.

#certificate_expiration_timestamp_seconds

סוג: Gauge
תוויות: source, serial_no, cn, hostnames, ca, server, client

מדווח את זמן התפוגה (NotAfter) של כל אישור ששרת המפתחות טען, כחותמת זמן Unix. נפלטת סדרת זמן אחת לכל אישור.

המדד מתעדכן:

• בהפעלה, עבור אישור האימות של השרת (auth_cert) ועבור אישור ה-CA של Cloudflare (cloudflare_ca_cert).
• בכל חיבור TLS נכנס שהצליח, עבור אישורי העמית שהציג הלקוח המתחבר.

הערה

server_utilization הוא מדד GaugeVec רשום ששרת המפתחות אף פעם לא כותב אליו. מכיוון שאף ערכי תוויות לא נקבעים, הוא לא פולט שום סדרת זמן בפלט של /metrics. אל תשתמשו בו.

#שאילתות PromQL לדוגמה

#תפוקת חתימה לפי סוג מפתח

sum by (opcode) (rate(keyless_requests[1m]))

#שיעור שגיאות לפי סוג שגיאה

sum by (error) (
  rate(keyless_request_exec_duration_per_opcode_count{error!="no error"}[5m])
)

#חביון חתימה באחוזון 99 עבור RSA

histogram_quantile(
  0.99,
  rate(keyless_request_exec_duration_per_opcode_bucket{type="rsa"}[5m])
)

ערך שמתקרב ל-10 שניות מציין מיצוי של מאגר הסשנים של PKCS#11. ראו Scaling and benchmarking ואת תיעוד ה-HSM להנחיה על הגדלת גודל מאגר הסשנים.

#חביון טעינת מפתח באחוזון 99

histogram_quantile(0.99, rate(keyless_key_load_duration_bucket[5m]))

עלייה כאן בלי עלייה מקבילה במשך הביצוע מרמזת שחיפוש ה-keystore עצמו איטי: ייתכן שזו בעיית קלט/פלט של דיסק או עיכוב במניית אובייקטים של PKCS#11.

#שיעור כשלי חיבור

rate(keyless_failed_connection_total[5m])

שיעור מתמשך שאינו אפס מציין בעיות רשת או TLS בין רשת Cloudflare לשרת המפתחות.

#התראה על תפוגת אישור בתוך 30 יום

(certificate_expiration_timestamp_seconds - time()) / 86400 < 30