📘 תיעוד 48

ניטור שימוש (OpenTelemetry חיצוני)

סטטוס: אלפא. הסכמה שלהלן מנוהלת בגרסאות (grok_code.schema.version = v1). שינויים שמוסיפים עשויים להתרחש בלי הודעה מוקדמת. שינויי שם או הסרות יעלו את הגרסה ויצוינו ביומן השינויים.

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

#הגדרות קשורות

המתגים האלה בלתי תלויים זה בזה (וגם בזרם ה-OTEL החיצוני של המדריך הזה), חוץ מכך שכיבוי טלמטריה מכבה גם מדדי שימוש ודיווחי קריסה:

ראו גם אימות והגדרות.

#זרם OTEL חיצוני

הזרם החיצוני הוא:

• כבוי כברירת מחדל, ודורש הסכמה כפולה (מתג ראשי וגם בחירה מפורשת של מייצא).
• בלי תוכן כברירת מחדל: בלי הנחיות, בלי פרוזה של העוזר, בלי קוד, בלי נתיבי קבצים (סיומת בלבד), בלי ארגומנטים של כלים, בלי פקודות bash, ושמות MCP/skill/plugin מכווצים לקטגוריות. שערי תוכן אופציונליים מפעילים מחדש חלק מאלה.
• מופרד מבנית מטלמטריה פנימית של SpaceXAI: המייצאים שלו נושאים רק את הכותרות שהגדרתם, לעולם לא אישורי SpaceXAI.
• בלתי תלוי בביטולי שמירת נתונים של SpaceXAI: הוא עובד גם כש-telemetry כבוי וגם לצוותי ZDR (zero-data-retention). ההגדרות האלה חלות על שמירה בצד SpaceXAI. הזרם החיצוני נשלט רק על ידי הגדרות ה-OTEL שלכם.

#ZDR והזרם הזה

/privacy ו-Zero Data Retention לא מכבים את הזרם הזה. ZDR מכבה שמירה בצד SpaceXAI (אנליטיקת מוצר, העלאת עקבות סשן, שיתוף נתוני קוד). הוא לא משתיק את GROK_EXTERNAL_OTEL.

כשהזרם פעיל:

• user.id, session.id ומזהי ארגון/צוות/פריסה תמיד מיוצאים.
• user.email מצורף ללוגים וגם למדדים בכל פעם שלאימות OAuth/gateway יש כתובת לא ריקה. זו זהות, לא שער תוכן, ואי אפשר לנעוץ אותה אלא על ידי כיבוי הזרם.
• טקסט ההנחיה, response של העוזר וגופי כלים מיוצאים רק כשהשערים שלהם פעילים. אנליטיקת מוצר מצד ראשון לעולם לא מקבלת את הגופים האלה.

כדי שמכונות ZDR יישארו שקטות מול האספן, נעצו otel_enabled = false (או אל תפעילו את הזרם). ל-SIEM של מדדים בלבד, נעצו את כל ארבעת מפתחות otel_log_* ל-false.

#התחלה מהירה

export GROK_EXTERNAL_OTEL=1                  # master switch
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf  # or grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.corp.example:4318
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <collector-token>"
grok

GROK_EXTERNAL_OTEL=1 לבדו מפעיל כלום: חייבים גם לבחור לפחות מייצא אחד. ולהפך, משתני OTEL_* לבדם לא מפעילים כלום בלי המתג הראשי.

#משתני סביבה

#שערי צי מומלצים

ברירת המחדל הארגונית היא DETAILS פעיל, CONTENT כבוי: מטא-נתונים (נתיבים, 4 KB של tool_parameters, שמות MCP/skill/plugin מילוליים) בלי גופי תוצאה של Read, bash או MCP. הפעילו CONTENT רק כשהאספן חייב לאחסן את הגופים האלה. CONTENT לא גורר DETAILS: CONTENT בלבד נותן tool_output של 60 KB כש-tool_name / mcp_tool.name עדיין מכווצים ל-mcp_tool.

[telemetry]
otel_log_user_prompts = false
otel_log_assistant_responses = false   # unset would follow prompts; pin off
otel_log_tool_details = true           # metadata for SIEM join
otel_log_tool_content = false          # bodies; independent of details

OTEL_RESOURCE_ATTRIBUTES מתעלמים ממנו בכוונה: המשאב נבנה מקבוצת מאפיינים קבועה ומבוקרת.

הערת מעבר: גרסאות ישנות יותר יכלו לשתף את OTEL_EXPORTER_OTLP_* עם צינור האנליטיקה של המוצר עצמו. ההתנהגות הזו הוצאה משימוש: כש-GROK_EXTERNAL_OTEL מוגדר, אנליטיקת המוצר מתעלמת מהמשתנים האלה, וה-CLI מסרב להפעיל את הזרם החיצוני בכל הגדרה שבה אנליטיקת המוצר כבר צרכה אותם. האספן שלכם מקבל רק את הזרם החיצוני שאליו הסכמתם.

#קובץ הגדרות

ברירות מחדל של הארגון נמצאות תחת טבלת [telemetry] הקיימת ב-config.toml (משתני סביבה גוברים). המפתחות הם עמיתים עם קידומת otel_ של שאר הגדרות [telemetry]:

[telemetry]
otel_enabled = true
otel_metrics_exporter = "otlp"
otel_logs_exporter = "otlp"
otel_endpoint = "https://collector.corp.example:4318"
otel_protocol = "http/protobuf"  # or "grpc"
# Optional PEM *paths* for private-CA trust and mTLS (never PEM contents):
otel_certificate = "/etc/ssl/corp-ca.pem"
otel_client_certificate = "/etc/ssl/client.crt"
otel_client_key = "/etc/ssl/client.key"
otel_log_user_prompts = false   # admins can pin these via requirements
otel_log_assistant_responses = false
otel_log_tool_details = false   # code default; SIEM fleets usually true , see Recommended fleet gates
otel_log_tool_content = false

מפתחות ההגדרה הם otel_* תחת [telemetry]. משתני הסביבה שומרים על שמות OTEL הסטנדרטיים (GROK_EXTERNAL_OTEL, OTEL_*) לצורך תאימות למערכת האקולוגית, כך ששתי השכבות משתמשות במרחבי שמות שונים בכוונה. מפתח ההגדרה otel_protocol ממופה ל-OTEL_EXPORTER_OTLP_PROTOCOL. משתני סביבה גוברים על נתיבים בקובץ ההגדרות עבור CA וזהות לקוח.

אין בכוונה מפתח headers: ספקו אימות אספן דרך OTEL_EXPORTER_OTLP_HEADERS כדי שאסימונים לעולם לא יישמרו על הדיסק. מפתחות הגדרה של אישור ומפתח הם נתיבים בלבד: לעולם אל תטמיעו חומר מפתח פרטי ב-TOML.

כל מפתח [telemetry] otel_* שנוכח ב-requirements.toml חתום הוא נעיצה (סביבה לא יכולה לדרוס אותו). managed_config.toml אינו נעילה: הסביבה עדיין גוברת שם. נעיצת otel_endpoint מסירה משתני סביבה של נקודת קצה גנרית ולפי אות של המפתח וגם אחים לא רשומים בקובצי משתמש או מנוהלים, חוץ מנקודות קצה שגם מפרטים. נעיצת אישור או מפתח לקוח מסירה גם נקודות קצה של המפתח ואחים לא רשומים בקובץ. נעיצת CA (otel_certificate) לא מסירה נקודות קצה. אם requirements מפרט אחד מבין otel_log_user_prompts / otel_log_tool_details / otel_log_assistant_responses / otel_log_tool_content ומשמיט אח, השער שהושמט ברירת המחדל שלו כבוי (אל תסמכו על נפילה מהנחיות לתשובות מעבר לגבול הזה).

הזרם החיצוני מייצא לוגים ומדדים בלבד (אין מייצא עקבות שפונה ללקוח).

הפעלת צי היא requirements.toml חתום אחד (יעד, מייצאים ושערי תוכן יחד). user.email אינו מפתח נעיצה: הוא עוקב אחרי זהות OAuth/gateway. כותרות נשארות בסביבת התהליך מהמפעיל אחרי ההסרה, לעולם לא ב-TOML הזה.

#דיכוי בעלייה (למה שום דבר לא מגיע בשניות הראשונות)

מכיוון ש-xAI יכולה לכבות בכפייה את הזרם הזה בכל הצי, ה-CLI מחזיק את הפליטה סגורה בעלייה עד שהוא יודע אם המתג הזה מוגדר: הוא מושך את מדיניות הצי מ-/v1/settings ורק אז מתחיל לייצא. בהתקנה תקינה זה הרבה פחות משנייה ולא מורגש.

ההמתנה חסומה, כך שפריסה שלא יכולה להגיע ל-xAI עדיין מייצאת:

• אם שום מדיניות צי לא יכולה לחול בכלל, [features] remote_fetch = false, או ש-[endpoints] cli_chat_proxy_base_url מצביע למקום שאינו xAI, הזרם מתחיל מיד, לפי ההגדרה המקומית שלכם.
• אם משיכת המדיניות נכשלת או אף פעם לא מסתיימת (מארח מאחורי חומת אש, מחשב לא מקוון), הפליטה מתחילה בכל מקרה אחרי שהניסיון מוצה, ובכל המקרים לא מאוחר מ-30 שניות אחרי העלייה.

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

אם האספן לא מקבל כלום בכלל, בדקו את לוג הדיבוג (grok --debug) לשורות external otel:: הן מתעדות אם הזרם פתר את ההגדרה שלו, ואם הוא מייצא או מדוכא.

#מאפייני משאב

מאפייני זהות (user.id, ו-organization.id / team.id / deployment.id כשידועים) מצורפים לכל נקודת נתוני מדד ולכל אירוע אחרי שהאימות מסתיים. user.email מצורף ללוגים וגם למדדים בכל פעם שהסשן מחובר עם OAuth או חשבון gateway שיש לו כתובת לא ריקה: זו זהות, לא שער תוכן, והיא אף פעם לא נלקחת מ-git, ממפתח API או ממפתח פריסה. prompt.id (UUID לכל הנחיה) מופיע באירועים בלבד, לעולם לא במדדים. grok_code.release_line חוזר על נקודות נתוני מדד כי הרבה קצוות מדדים משמיטים מאפייני משאב.

#מדדים (היקף מד ai.xai.grok_code)

startup.total מודד מתחילת התהליך עד סשן שמיש, נרשם פעם אחת לכל תהליך. outcome = timeout או error אומר שהעלייה הסתיימה בלי סשן כזה. startup.interactive רושם מתחילת התהליך עד הפריים הראשון שלולאת החיים אישרה שנכתב, פעם אחת לכל תהליך. phase_duration מפרק את ניסיון החיבור לפי שלב (config_load, managed_policy, bootstrap, model_catalog, worker_spawn, leader_connect, acp_initialize, eager_auth). סננו לפי outcome שלו (ok | timeout | cancelled | error) כדי שדגימות קטועות לא יטו אחוזוני ok. השלבים המאוחרים app_init ו-session_create מופיעים בציר הזמן של הלוג ובמחרוזות הסיכום, לא במדד הזה. stuck_in בפסק זמן מציין את השלב שלא הסתיים. זה לעתים קרובות לא השלב שלקח הכי הרבה זמן, כי שלב שרץ בלי השהיה מסתיים לפני שפסק הזמן נרשם. הודעת השגיאה ש-Grok מדפיס מציינת את השלב הארוך ביותר במקום, כך שהשניים יכולים לציין שלבים שונים לאותו פסק זמן. השתמשו ב-phase_duration כדי להשוות ביניהם. auth_mode הוא personal, team, deployment או unknown: עלות העלייה שונה לפי סוג, אז פצלו לפיו לפני השוואה.

turn.ttft הוא הזמן מתחילת התור עד הטוקן הראשון של כל ערוץ (חשיבה, טקסט או קריאת כלי) ו-turn.ttfm הזמן מתחילת התור עד הודעת הטקסט הראשונה של העוזר (חשיבה וקריאות כלים לא נכללות), דגימה אחת לכל תור על אותו שעון, כך ש-ttft לעולם לא עולה על ttfm. תור שלא ייצר פלט מודל לא רושם ttft. תור של חשיבה בלבד או כלי בלבד רושם ttft אבל לא ttfm.

אין מדד cost.usage: חברו את grok_code.token.usage עם מחירון משלכם. lines_of_code.count ו-active_time.total מתוכננים לשלב מאוחר יותר.

ערכי tool_name: שמות כלים מובנים עוברים מילולית. כלי MCP מכווצים ל-mcp_tool וכלים אחרים שאינם מובנים ל-custom_tool, אלא אם OTEL_LOG_TOOL_DETAILS=1.

#אירועים (רשומות לוג OTLP)

כל אירוע נושא את event.sequence, session.id, turn_number (בתוך התור), prompt.id, ועוד את מאפייני הזהות. מקרא שערים: details = דורש OTEL_LOG_TOOL_DETAILS, prompts = דורש OTEL_LOG_USER_PROMPTS, responses = דורש OTEL_LOG_ASSISTANT_RESPONSES (כשלא מוגדר, עוקב אחרי שער ה-prompts), content = דורש OTEL_LOG_TOOL_CONTENT (בלתי תלוי ב-details; ברירת המחדל כבויה); כל השאר תמיד מיוצא כל עוד הזרם פעיל.

#מודל פרטיות

שלושה מנגנונים עצמאיים של fail-closed שומרים על פורמט התעבורה:

1. סכמה עם טיפוסים: מפתחות המאפיינים הם enum סגור; אי אפשר לצרף דבר שמחוץ לו.
2. השחרה בזמן הפליטה: כל מחרוזת עוברת ניקוי של צורת סוד וניקוי של ספריית הבית, עם קיצור (512→128 תווים לכל מחרוזת ארגומנט של כלי מקוננת, 4 KB לתצוגה מקדימה של DETAILS tool_parameters / CONTENT error_message, 60 KB עבור prompt / response / tool_input / tool_output / full_command).
3. מאמתים בזמן הייצוא: כל רשומה שנושאת מפתח שאינו בסכמה, מפתח של שער סגור, או צורת סוד שלא נוקתה נזרקת לפני היציאה מהתהליך; ייצואי מדדים עם מפתחות מאפיינים מחוץ לסכמה נזרקים במלואם.

לעולם לא מיוצאים: טקסט חשיבה/היסק, גופי בקשות API גולמיים, api_key.id, טביעות אצבע של המכונה, דרגת מנוי. טקסט הפרומפט, response של העוזר, נתיבי קבצים, תצוגות מקדימות של ארגומנטי כלים, וגופי CONTENT (tool_input, tool_output, full_command, error_message) מיוצאים רק כשהשער שלהם פתוח; אנליטיקת מוצר מצד ראשון לעולם לא מקבלת את הגופים האלה. user.email מיוצא בכל פעם שלאימות OAuth/gateway יש כתובת (זה לא שער תוכן).

#דוגמה להגדרת אספן

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:

exporters:
  prometheus:
    endpoint: 0.0.0.0:9464

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: []   # point at your log backend (loki, elasticsearch, …)

שאילתות לדוגמה (PromQL, עם מייצא Prometheus שלמעלה):

# Tokens by model and type across the org, 1h rate
sum by (model, type) (rate(grok_code_token_usage_total[1h]))

# Sessions per team per day
sum by (team_id) (increase(grok_code_session_count_total[1d]))

# Tool-permission denial ratio
sum(rate(grok_code_tool_decision_total{decision="deny"}[1h]))
  / sum(rate(grok_code_tool_decision_total[1h]))

#ניפוי באגים

הגדירו OTEL_LOGS_EXPORTER=console / OTEL_METRICS_EXPORTER=console כדי להדפיס רשומות מושחרות אל stderr (מושתק בנקודות הכניסה agent/headless כדי לשמור על לוגים שנלכדו נקיים). שגיאות ייצוא לעולם לא מופיעות ב-TUI; בדקו את לוג הדיבוג.