במסמך הזה מתוארת המבנה של דוגמאות האינסטרומנטציה שזמינות לשפות Go, Java, Node.js ו-Python. בדוגמאות האלה מוסבר איך להטמיע באפליקציה את OpenTelemetry SDK ואת OpenTelemetry Collector.
האינסטרומנטציה בדוגמאות האלה, שכוללת שימוש ב-OpenTelemetry SDK ובכלי לייצוא OTLP של ה-SDK בתוך התהליך, היא ניטרלית לספק. ה-exporter של התהליך שולח טלמטריה אל OpenTelemetry Collector, שמקבל את הנתונים האלה ואז שולח אותם אל פרויקט Google Cloud . המאסף מכיל את הקישור אל Google Cloud. בדוגמאות האלה נעשה שימוש ב Google Cloud כלי ייצוא כדי לשלוח נתוני יומן ומדדים לפרויקט. עם זאת, הם שולחים נתוני מעקב לפרויקט שלכם באמצעות Telemetry API.
אולי יעניינו אותך דוגמאות אחרות שממחישות הגדרות שונות:
במאמר העברה מ-Trace exporter לנקודת הקצה OTLP מוסבר איך להשתמש בשדרוג המידע ממעקבים בתהליך כדי לשלוח נתוני מעקב ישירות ל Google Cloud פרויקט.
מומלץ להשתמש ב-OpenTelemetry Collector כדי לייצא את נתוני הטלמטריה אם הסביבה שלכם תומכת בשימוש ב-Collector. אם אין לכם אפשרות להשתמש במאסף, אתם צריכים להשתמש בכלי ייצוא שפועל בתהליך ושולח נתונים ישירות לפרויקט Google Cloud .
במאמר הצגת קורלציה בין מדדים ועקבות באמצעות נתונים מייצגים מוסבר איך להגדיר אפליקציית Go כדי ליצור נתונים מייצגים. דוגמה היא נקודה על הגרף לדוגמה שמצורפת לנקודה על הגרף של מדד. אפשר להשתמש בנתוני exemplars כדי ליצור קורלציה בין נתוני העקבות לבין נתוני המדדים.
שימוש בסוכן תפעול ובפרוטוקול OpenTelemetry (OTLP) מתאר איך אפשר להגדיר את סוכן התפעול ואת מקלט OTLP כדי לאסוף מדדים ועקבות מאפליקציה.
איך הדוגמאות פועלות
הדוגמאות ל-Go, ל-Java, ל-Node.js ול-Python משתמשות בפרוטוקול OpenTelemetry כדי לאסוף נתוני מעקב ומדדים.
בדוגמאות מוגדרת מסגרת רישום כדי לכתוב יומנים מובנים, ואוסף OpenTelemetry מוגדר לקרוא מזרם stdout של האפליקציה. המלצות לגבי מסגרות זמינות במאמר בחירת גישה להטמעה.
האפליקציות נבנות ונפרסות באמצעות Docker. לא חייבים להשתמש ב-Docker כשמשתמשים ב-OpenTelemetry כדי להוסיף לאפליקציה כלי מעקב.
אפשר להריץ את הדוגמאות ב-Cloud Shell, במשאבים של Google Cloudאו בסביבת פיתוח מקומית.
ירידה לפרטים
בדוגמאות נעשה שימוש ב-OpenTelemetry Collector כ-sidecar כדי לקבל את נתוני הטלמטריה של האפליקציה ולהוסיף להם מידע, ואז לשלוח אותם לפרויקטGoogle Cloud באמצעות Google Cloud exporter. הכלי לייצוא ממיר את נתוני הטלמטריה לפורמט שתואם ל-Cloud Trace API, ל-Cloud Monitoring API או ל-Cloud Logging API. לאחר מכן הם שולחים את הנתונים שעברו טרנספורמציה לפרויקטGoogle Cloud שלכם באמצעות פקודת API.
בדוגמאות אפשר לראות איך:
מגדירים את OpenTelemetry לאיסוף מדדים ומעקבים באמצעות OpenTelemetry Collector.
אם תבדקו את הדוגמאות, תראו שהמורכבות של השלב הזה תלויה בשפה. לדוגמה, בשפת Go, בשלב הזה מוגדרת הפונקציה
mainלקריאה של פונקציה שמגדירה את איסוף המדדים והמעקבים. ב-Go, גם שרת ה-HTTP והלקוח עודכנו.מגדירים מסגרת רישום ביומן כדי לכתוב יומנים מובנים.
מומלץ שהאפליקציות שלכם יכתבו יומנים מובְנים, וכתוצאה מכך מטען הייעודי (payload) של היומן יעוצב כאובייקט JSON. ביומנים האלה, אתם יכולים ליצור שאילתות שמחפשות נתיבי JSON ספציפיים, וגם ליצור אינדקס לשדות ספציפיים במטען הייעודי (payload) של היומן.
בחלק מהשירותים, כמו Google Kubernetes Engine, יש סוכנים מובנים שמגרדים יומנים מובנים ושולחים אותם לפרויקט Google Cloud . בשירותים אחרים, כמו Compute Engine, צריך להתקין סוכן שמגרד ושולח את היומנים. אם אתם רוצים לקבל מידע על סוכני תפעול שאתם מתקינים, תוכלו לעיין במאמר סקירה כללית על Ops Agent.
לא צריך להתקין סוכנים כדי להשתמש בדוגמאות האלה.
מגדירים קובצי Docker. כל הדוגמאות מכילות את קובצי ה-YAML הבאים:
docker-compose.yaml: מגדיר את השירותים לאפליקציה, ל-OpenTelemetry collector ולמחולל עומסים. לדוגמה, השירות של OpenTelemetry Collector,otelcol, מציין תמונה, נפח ומשתני סביבה. נקודת הקצה (endpoint) של OpenTelemetry Collector מוגדרת על ידי משתנה הסביבהOTEL_EXPORTER_OTLP_ENDPOINT, שמוגדר בשירותapp.
otel-collector-config.yaml: הגדרת OpenTelemetry Collector. הקולקטור הזה מציין מקלטים, יצואנים, מעבדים וצינורות.שירות
telemetryמגדיר צינורות להעברת נתוני מעקב, מדדים ויומנים. כל רשומה בצינור הנתונים מציינת מקלט, מעבד ורכיב לייצוא. אותו מקלט,otlp, משמש למדדים ולעקבות.בקטע
exportersמוסבר איך הנתונים שנאספו מיוצאים ל Google Cloud פרויקט. לנתוני יומן ומדדים, נעשה שימוש בייצואנים שלGoogle Cloud . הכלי הזה ממיר את נתוני הטלמטריה לפורמט שתואם ל-API המתאים, ואז שולח את הנתונים שעברו המרה לפרויקטGoogle Cloud באמצעות פקודת API. לעומת זאת, נתוני מעקב נשלחים לפרויקט באמצעות Telemetry API, שתומך ב-OTLP.
docker-compose.creds.yaml: הקובץ הזה יכול לכלול הרכבה שלGoogle Cloud קובץ פרטי כניסה בקונטיינרotelcol. הקובץ הזה נדרש כשמריצים דוגמה במחשב מקומי שבו Application Default Credentials (ADC) זמינים רק כקובץ.
ההרשאות הנדרשות
-
כדי לקבל את ההרשאות שדרושות לאפליקציות לדוגמה כדי לכתוב נתוני יומן, מדדים ומעקב, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:
- Logs Writer (
roles/logging.logWriter) - כתיבת מדדי מעקב (
roles/monitoring.metricWriter) - Cloud Telemetry Traces Writer (
roles/telemetry.tracesWriter)
ההרשאות האלה מספיקות אם מריצים את הדוגמה ב-Cloud Shell, במשאבים או בסביבת פיתוח מקומית. Google Cloud
- Logs Writer (
-
כדי לקבל את ההרשאות שדרושות להצגת נתוני היומן, המדדים והמעקב, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:
- כלי הצפייה ביומנים (
roles/logging.viewer) - צפייה ב-Monitoring (
roles/monitoring.viewer) - משתמש Cloud Trace (
roles/cloudtrace.user)
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.
- כלי הצפייה ביומנים (
ממשקי API נדרשים
מפעילים את ממשקי ה-API של Cloud Logging, Cloud Monitoring, Cloud Trace וטלמטריה:
תפקידים שנדרשים להפעלת ממשקי API
כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים
gcloud services enable logging.googleapis.commonitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com
המאמרים הבאים
מידע נוסף על קולקטורים זמין במאמר בנושא Google-Built OpenTelemetry Collector.
אפשר לעיין בדוגמאות שבהן נעשה שימוש בייצוא מבוסס-איסוף.