הטמעה של Error Reporting באפליקציות Ruby

ספריית Error Reporting ל-Ruby מאפשרת לשלוח אירועי שגיאה ישירות מאפליקציות Ruby אל Error Reporting, כדי שתוכלו לאבחן ולעקוב אחרי קריסות בזמן ריצה. הטמעה של הספרייה באפליקציה מאפשרת לכם לדווח על אירועי שגיאה מותאמים אישית ולתעד שגיאות גם כשמאגרי היומנים משתמשים במפתחות הצפנה בניהול הלקוח (CMEK).

באפליקציות שפועלות בשירותים משולבים Google Cloud – כולל פונקציות של Cloud Run,‏ App Engine,‏ Compute Engine ו-Google Kubernetes Engine – אפשר גם להסיק באופן אוטומטי אירועי שגיאה מ-Cloud Logging בלי ספריית Error Reporting ל-Ruby. כדי ש-Error Reporting יסיק אירועי שגיאה מיומנים, הרשומות ביומן צריכות לעמוד בדרישות הפורמט של השגיאות ולהישמר בקטגוריית יומנים שלא מוצפנת באמצעות CMEK, שנמצאת בבעלות של פרויקט המקור או של פרויקט היעד שאליו היומנים נותבו.

לפני שמתחילים

נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Error Reporting API , if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Error Reporting API , if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. מתקינים Ruby 2.2+ או גרסה חדשה יותר.

התקנת ספריית הלקוח

ספריית Error Reporting ל-Ruby מאפשרת לכם לעקוב אחרי אירועי שגיאה שדווחו על ידי אפליקציות Ruby שפועלות כמעט בכל מקום, ולצפות בהם.

1. מוסיפים את ה-Gem‏ google-cloud-error_reporting לקובץ Gemfile:

   gem "google-cloud-error_reporting"

2. משתמשים ב-Bundler כדי להתקין את ה-gem:

   bundle install

הפעלת הספרייה

אם אתם משתמשים ב-Ruby on Rails, ‏ Bundler טוען את הספרייה באופן אוטומטי לאפליקציה כשמפעילים אותה.

אפליקציות אחרות שמבוססות על Rack יכולות להשתמש ב-Rack Middleware שמסופק על ידי הספרייה:

require "google/cloud/error_reporting"

use Google::Cloud::ErrorReporting::Middleware

מידע נוסף על התקנה זמין במאמרי העזרה בנושא ספריית Error Reporting ל-Ruby. אפשר גם לדווח על בעיות באמצעות הכלי למעקב אחרי בעיות.

הגדרת ספריית הלקוח

אפשר להתאים אישית את ההתנהגות של ספריית Error Reporting ל-Ruby. רשימת אפשרויות ההגדרה האפשריות מופיעה במאמר בנושא הגדרת הספרייה.

הפעלת אפליקציות ב Google Cloud

כדי ליצור קבוצות שגיאות באמצעות projects.events.report, לחשבון השירות שלכם נדרש התפקיד Error Reporting Writer (roles/errorreporting.writer).

חלק משירותי Google Cloud Google Cloud מעניקים באופן אוטומטי את התפקיד Error Reporting Writer ‏ (roles/errorreporting.writer) לחשבון השירות המתאים. עם זאת, בשביל שחלק מהשירותים יפעלו, צריך להעניק את התפקיד הזה לחשבון השירות המתאים.

פונקציות Cloud Run ו-Cloud Run

לחשבון השירות שמוגדר כברירת מחדל ב-Cloud Run יש את ההרשאות של התפקיד Error Reporting Writer ‏ (roles/errorreporting.writer).

אפשר להשתמש בספריית Error Reporting ל-Ruby בלי לספק באופן מפורש פרטי כניסה.

‫Cloud Run מוגדר לשימוש ב-Error Reporting באופן אוטומטי. חריגים של JavaScript שלא טופלו יופיעו ביומן ויתבצע עיבוד שלהם על ידי דיווח על שגיאות, בלי שתצטרכו להשתמש בספריית דיווח על שגיאות עבור Ruby.

הערה: שירות דיווח השגיאות יוצר באופן אוטומטי אירוע שגיאה כשערך יומן מכיל מעקב מחסנית ורמת החומרה של ערך היומן לא מוגדרת או מוגדרת לערך של ERROR לפחות.

שימוש בממשק ההגדרות של Ruby on Rails

כדי להשתמש בספריית Error Reporting עבור Ruby עם מסגרת Ruby on Rails, צריך לספק את הפרמטרים דרך ממשק ההגדרה של Ruby on Rails:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.google_cloud.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.error_reporting.keyfile    = "/path/to/service-account.json"
end

אפשר גם להגדיר הגדרות משותפות לכל אבני ה-gem של Stackdriver באמצעות הפקודה הבאה:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Shared parameters
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
end

Error Reporting מופעל כברירת מחדל כש-Rails פועל במצב ייצור. כדי להפעיל את דיווח השגיאות במצב פיתוח, מוסיפים את הקוד הבא:

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_error_reporting = true
end

שימוש בממשק ההגדרות של המכשיר

כדי להשתמש בספריית Error Reporting עבור Ruby באפליקציות אחרות שמבוססות על Rack, צריך לספק את הפרמטרים דרך ממשק ההגדרות:

require "google/cloud/error_reporting"

Google::Cloud.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.error_reporting.keyfile    = "/path/to/service-account.json"
end

אפשר גם להגדיר הגדרה משותפת לכל אבני החן של Google Cloud Observability באמצעות הפקודה הבאה:

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

סביבה גמישה ב-App Engine

ב-App Engine, לחשבון השירות שמוגדר כברירת מחדל מוענק באופן אוטומטי התפקיד 'כתיבה ביומן' (roles/errorreporting.writer).

אפשר להשתמש בספריית Error Reporting ל-Ruby בלי לספק באופן מפורש פרטי כניסה.

התכונה 'דיווח על שגיאות' מופעלת באופן אוטומטי באפליקציות של סביבה גמישה ב-App Engine. לא נדרשת הגדרה נוספת.

הערה: רשומות ביומן השגיאות שנכתבות אל stderr מעובדות באופן אוטומטי על ידי Error Reporting, בלי שצריך להשתמש בספריית Error Reporting ל-Ruby באופן ישיר.

Google Kubernetes Engine

כדי להשתמש ב-Error Reporting עם Google Kubernetes Engine, צריך לבצע את הפעולות הבאות:

1. מוודאים שלחשבון השירות שבו ישתמש הקונטיינר הוקצה התפקיד 'כתיבה ב-Error Reporting' (roles/errorreporting.writer).

   אפשר להשתמש בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine או בחשבון שירות מותאם אישית.

   מידע על הקצאת תפקידים מופיע במאמר ניהול הגישה לפרויקטים, לתיקיות ולארגונים.

2. יוצרים את האשכול ומעניקים לו את היקף הגישה של cloud-platform.

   לדוגמה, בפקודת היצירה הבאה מצוינים היקף הגישה cloud-platform וחשבון שירות:

   gcloud container clusters create CLUSTER_NAME --service-account  SERVICE_ACCT_NAME --scopes=cloud-platform
   

הערה: אחרי שיוצרים אשכול, אי אפשר לשנות את חשבון השירות שלו.

Compute Engine

כדי להשתמש ב-Error Reporting עם מכונות וירטואליות (VM) של Compute Engine:

1. מוודאים שלחשבון השירות שבו המכונה הווירטואלית תשתמש הוקצה התפקיד 'כותב דוחות' (roles/errorreporting.writer).

   אפשר להשתמש בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine או בחשבון שירות מותאם אישית.

   מידע על הקצאת תפקידים מופיע במאמר ניהול הגישה לפרויקטים, לתיקיות ולארגונים.

2. נכנסים לדף VM instances במסוף Google Cloud :

   כניסה לדף VM instances

   אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים את התוצאה שבה כותרת המשנה היא Compute Engine.

3. בוחרים את המכונה הווירטואלית שרוצים להקצות לה את cloud-platform היקף הגישה.

4. לוחצים על עצירה ואז על עריכה.

5. בקטע Identity and API access בוחרים חשבון שירות עם התפקיד Error Reporting Writer (roles/errorreporting.writer).

6. בקטע Access scopes, בוחרים באפשרות Allow full access to all Cloud APIs ושומרים את השינויים.

7. לוחצים על התחלה/המשך.

דוגמה

דיווח על שגיאות במסגרות מבוססות-Rack

ספריית Error Reporting ל-Ruby מאפשרת לשלב בקלות את Error Reporting במסגרות אינטרנט פופולריות של Ruby שמבוססות על Rack, כמו Ruby on Rails ו-Sinatra. כשהספרייה מופעלת, היא מדווחת באופן אוטומטי על חריגים שנתפסו ממערך Rack של האפליקציה.

דיווח על שגיאות באופן ידני

אפשר לדווח על שגיאה באופן ידני על ידי הפעלת השיטה report, כמו בדוגמה הבאה:

require "google/cloud/error_reporting"

begin
  raise "Something went wrong"
rescue StandardError => e
  Google::Cloud::ErrorReporting.report e
end

הרצת אפליקציות בסביבת פיתוח מקומית

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

כדי להשתמש בדוגמאות של Ruby שבדף הזה בסביבת פיתוח מקומית, מתקינים ומפעילים את ה-CLI של gcloud, ואז מגדירים את Application Default Credentials באמצעות פרטי הכניסה של המשתמש.

1. התקינו את ה-CLI של Google Cloud.

2. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

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

   gcloud auth application-default login

   אם אתם משתמשים ב-Cloud Shell, אין צורך לבצע את הפעולה הזו.

   הערה: אם ב-CLI של gcloud מופיעה אזהרה שלחשבון אין את ההרשאה serviceusage.services.use, יכול להיות שחלק מהפקודות וחלק מספריות הלקוח ב-CLI של gcloud לא יפעלו. תוכלו לבקש מאדמין להקצות לכם את תפקיד ה-IAM של צרכן השימוש בשירות (roles/serviceusage.serviceUsageConsumer)‏, ולאחר מכן להריץ את הפקודה הבאה:

   gcloud auth application-default set-quota-project PROJECT_ID

   אם מוחזרת שגיאת אימות ואתם משתמשים בספק זהויות חיצוני (IdP), ודאו ש נכנסתם ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

מפתחות API נתמכים גם על ידי projects.events.report method. אם אתם רוצים להשתמש במפתחות API לצורך אימות, לא צריך להגדיר קובץ מקומי של Application Default Credentials. מידע נוסף זמין במאמר בנושא יצירת מפתח API במסמכי האימות של Google Cloud .

שימוש בממשק ההגדרות של Ruby on Rails

כדי להשתמש בספריית Error Reporting עבור Ruby עם מסגרת Ruby on Rails, צריך לספק את הפרמטרים דרך ממשק ההגדרה של Ruby on Rails:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.google_cloud.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.error_reporting.keyfile    = "/path/to/service-account.json"
end

אפשר גם להגדיר הגדרות משותפות לכל אבני ה-gem של Stackdriver באמצעות הפקודה הבאה:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Shared parameters
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
end

Error Reporting מופעל כברירת מחדל כש-Rails פועל במצב ייצור. כדי להפעיל את דיווח השגיאות במצב פיתוח, מוסיפים את הקוד הבא:

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_error_reporting = true
end

שימוש בממשק ההגדרות של המכשיר

כדי להשתמש בספריית Error Reporting עבור Ruby באפליקציות אחרות שמבוססות על Rack, צריך לספק את הפרמטרים דרך ממשק ההגדרות:

require "google/cloud/error_reporting"

Google::Cloud.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.error_reporting.keyfile    = "/path/to/service-account.json"
end

אפשר גם להגדיר הגדרה משותפת לכל אבני החן של Google Cloud Observability באמצעות הפקודה הבאה:

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

הצגת קבוצות של שגיאות

נכנסים לדף Error Reporting במסוף Google Cloud :

עבור אל Error Reporting

אפשר גם להשתמש בסרגל החיפוש כדי למצוא את הדף הזה.

מידע נוסף זמין במאמר בנושא הצגה וסינון של קבוצות שגיאות.