הפעלת רישום ביומן עבור Storage Transfer Service

בדף הזה מוסבר איך להגדיר את Storage Transfer Service כדי ליצור נתוני יומן שמתעדים פעולות ומצבים. אתם יכולים להציג ולנתח את נתוני היומנים באמצעות Cloud Logging.

השירות Storage Transfer Service יכול ליצור נתוני יומן לכל ההעברות. עם זאת, פעולות של FIND לא מתועדות ביומן בהעברות שמבוססות על סוכנים.

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

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

לפני שמתחילים, צריך לוודא שיש לכם גישה ל-Cloud Logging. מומלץ להשתמש בתפקיד צפייה ביומנים (roles/logging.viewer) בניהול הזהויות והרשאות הגישה (IAM). מידע נוסף על גישה ל-Logging מופיע במאמר בקרת גישה באמצעות IAM.

במסמכים הבאים מוסבר איך לאמת את הגישה הנוכחית ואיך להקצות תפקידי IAM:

פעולות שאפשר לתעד

אפשר לתעד ביומן את הפעולות הבאות:

  • ‫FIND: חיפוש עבודה לביצוע, כמו הצגת רשימת קבצים בספרייה, הצגת רשימת אובייקטים בקטגוריה או הצגת רשימת תיקיות מנוהלות בקטגוריה. לא נתמך בהעברות מבוססות-סוכן.
  • ‫COPY: העתקת קבצים או אובייקטים ליעד (Cloud Storage או מערכת קבצים).
  • ‫DELETE: מחיקת קבצים או אובייקטים במקור או ביעד. בהעברות בין שתי מערכות קבצים, מתועדת גם מחיקת הקבצים מהקטגוריה המתווכת של Cloud Storage.

מצבים שניתן לתעד

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

  • ‫SUCCEEDED: הפעולה בוצעה בהצלחה.
  • ‫FAILED: הפעולה נכשלה.
  • ‫SKIPPED: רלוונטי רק לפעולה COPY, ונתמך רק במשימות העברה שמבוססות על סוכנים. צריך להגדיר באמצעות gcloud או API בארכיטקטורת REST. המשמעות של הסטטוס הזה היא שהמערכת דילגה על ההעתקה. זה קורה כשהקובץ כבר קיים בכיור, ומשימת ההעברה מוגדרת להתעלם מקבצים קיימים.

שיטות מומלצות

הפעלת רישום ביומן של הפעולה FIND או של המצב SUCCEEDED יכולה לגרום לנפח גבוה של נתוני יומן.

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

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

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

  • להגדיר את Cloud Logging כך שימחק נתוני יומנים בנפח גבוה ובעלי ערך נמוך. כדי לעשות את זה, צריך לעדכן את כיורי היומנים בפרויקט כך שלא יכללו נתוני יומנים של Storage Transfer Service שאין בהם צורך. מכיוון שכל ה-sinks ביומן בפרויקט מעריכים את כל הרשומות ביומן, ייתכן שתצטרכו לעדכן כמה sinks ביומן.

    כדי להחריג רשומות ביומן של Storage Transfer Service שמתעדות פעולות שהצליחו, משתמשים במסנן ההחרגה הבא:

    resource.type="storage_transfer_job" AND
    jsonPayload.status.statusCode="OK"
    

    במאמר ניתוב יומנים ליעדים נתמכים מוסבר איך למצוא ולשנות את ה-sink ביומנים.

הפעלת הרישום ביומן

כדי להגדיר את Storage Transfer Service ליצירת נתוני יומן, צריך לציין את הפעולות ואת המצבים שרוצים לתעד ביומן.

‫CLI של gcloud

כשיוצרים משימת העברה באמצעות gcloud transfer jobs create, משתמשים בדגלים הבאים כדי להפעיל את הרישום ביומן:

gcloud transfer jobs create SOURCE DESTINATION \
  --log-actions=copy,delete \
  --log-action-states=succeeded,failed

צריך לציין לפחות ערך אחד לכל דגל. אפשר להוסיף את find ל---log-actions רק להעברות ללא סוכן, ואת skipped ל---log-action-states רק להעברות מבוססות-סוכן. אי אפשר לשלב את שניהם באותו תפקיד.

REST

כדי ליצור הגדרת רישום ביומן, משתמשים ב-transferJobs.create עם LoggingConfig:

{
  "name": "transferJobs/myFirstTransfer",
  "status": "ENABLED",
  "projectId": "test-id-001",
  "loggingConfig": {
    "logActions": ["FIND", "DELETE", "COPY"],
    "logActionStates": ["SUCCEEDED", "FAILED"]
  },
  "transferSpec": {
    "gcsDataSource": {
      "bucketName": "source_bucket"
    },
    "gcsDataSink": {
      "bucketName": "destination_bucket",
      "path": "foo/bar/"
    }
  }
}

בהעברות מבוססות-סוכן, משמיטים את "FIND" מ-logActions. אפשר לכלול את "SKIPPED" ב-logActionStates.

משנים את loggingConfig כך שיכלול את logActions ו-logActionStates הספציפיים שרוצים לתעד ביומן. לדוגמה, כדי לתעד ביומן מתי פעולות ההעתקה והחיפוש נכשלות, צריך לספק את הערך הבא בשדה loggingConfig:

"loggingConfig": {
  "logActions": ["COPY", "FIND"],
  "logActionStates": ["FAILED"]
}

עדכון של הגדרת רישום ביומן

‫CLI של gcloud

כדי לעדכן את הגדרות הרישום ביומן של משימה קיימת, משתמשים בדגלים המתאימים עם הפקודה gcloud transfer jobs update:

gcloud transfer jobs update NAME \
  --log-actions=copy,delete \
  --log-action-states=succeeded,failed

כדי להשבית את הרישום ביומן של המשימה הזו, מציינים את הערך --clear-log-config:

gcloud transfer jobs update NAME --clear-log-config

REST

כדי לעדכן את הגדרות הרישום ביומן של משימת העברה קיימת, משתמשים ב-transferJobs.patch עם LoggingConfig:

{
  "projectId": "test-id-001",
  "transferJob": {
    "loggingConfig": {
      "logActions": ["FIND", "DELETE", "COPY"],
      "logActionStates": ["SUCCEEDED", "FAILED"]
    }
  },
  "updateTransferJobFieldMask": "loggingConfig"
}

השדה updateTransferJobFieldMask מציין את השדה שמתעדכן בבקשה הזו, והוא שדה חובה.

כדי להשבית את הרישום ביומן של המשימה הזו, שולחים loggingConfig עם רשימות ריקות של logActions ו-logActionStates:

{
  "projectId": "test-id-001",
  "transferJob": {
    "loggingConfig": {
      "logActions": [],
      "logActionStates": []
    }
  },
  "updateTransferJobFieldMask": "loggingConfig"
}

צפייה ביומנים

כדי לראות את יומני ההעברות:

מסוף Google Cloud

  1. נכנסים ל Google Cloud תפריט הניווט ובוחרים באפשרות Logging > Logs Explorer:

    כניסה לדף Logs Explorer

  2. בוחרים פרויקט ב- Google Cloud .

  3. כדי לסנן את היומנים כך שיוצגו רק רשומות של Storage Transfer Service, מקלידים storage_transfer_job בשדה השאילתה ולוחצים על Run query.

  4. בחלונית Query results, לוחצים על Edit time כדי לשנות את התקופה שלגביה רוצים לקבל תוצאות.

למידע נוסף על השימוש ב-Logs Explorer, קראו את המאמר שימוש ב-Logs Explorer.

‫CLI של gcloud

כדי לחפש יומנים של Storage Transfer Service באמצעות ה-CLI של gcloud, משתמשים בפקודה gcloud logging read.

מציינים מסנן כדי להגביל את התוצאות ליומנים של Storage Transfer Service.

gcloud logging read "resource.type=storage_transfer_job"

Cloud Logging API

משתמשים ב-method ‏entries.list של Cloud Logging API.

כדי לסנן את התוצאות כך שיכללו רק רשומות שקשורות לשירות Storage Transfer Service, משתמשים בשדה filter. בהמשך מופיע אובייקט בקשה לדוגמה ב-JSON.

{
"resourceNames":
  [
    "projects/my-project-name"
  ],
  "orderBy": "timestamp desc",
  "filter": "resource.type=\"storage_transfer_job\""
}

הפורמט של יומן ההעברות

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

כל השדות הספציפיים ל-Storage Transfer Service נמצאים באובייקט jsonPayload.

FIND פעולות

{
"jsonPayload": {
  "@type": "type.googleapis.com/google.storagetransfer.logging.TransferActivityLog",
  "action": "FIND",
  "completeTime": "2021-12-16T18:58:49.344509695Z",
  "destinationContainer": {
    "gcsBucket": {
      "bucket": "my-bucket-2"
    },
    "type": "GCS"
  },
  "operation": "transferOperations/transferJobs-7876027868280507149--3019866490856027148",
  "sourceContainer": {
    "gcsBucket": {
      "bucket": "my-bucket-1"
    },
    "type": "GCS"
  },
  "status": {
    "statusCode": "OK"
  }
}
}

COPY ו-DELETE פעולות

{
"jsonPayload": {
  "@type": "type.googleapis.com/google.storagetransfer.logging.TransferActivityLog",
  "action": "COPY",
  "completeTime": "2021-12-16T18:59:00.510509049Z",
  "destinationObject": {
    "gcsObject": {
      "bucket": "my-bucket-2",
      "objectKey": "README.md"
    },
    "type": "GCS"
  },
  "operation": "transferOperations/transferJobs-7876027868280507149--3019866490856027148",
  "sourceObject": {
    "gcsObject": {
      "bucket": "my-bucket-1",
      "lastModifiedTime": "2021-12-07T16:41:09.456Z",
      "md5": "WgnCOIdfCXNTUDpQJSKb2w==",
      "objectKey": "README.md"
    },
    "type": "GCS"
  },
  "status": {
    "statusCode": "OK"
  }
}
}
שדה ביומן תיאור
@type הערך הוא תמיד type.googleapis.com/google.storagetransfer.logging.TransferActivityLog.
action

מתאר את הפעולה של המשימה הספציפית הזו. אחת מהאפשרויות הבאות:

  • ‫FIND: חיפוש עבודה לביצוע, כמו הצגת רשימת קבצים בספרייה או הצגת רשימת אובייקטים בקטגוריה. לא מדווח בהעברות מבוססות-סוכן.
  • ‫COPY: העתקת קבצים או אובייקטים ליעד (Cloud Storage או מערכת קבצים).
  • ‫DELETE: מחיקת קבצים או אובייקטים בקטגוריית המקור, היעד או הביניים.
findAction

מציין אם הנושא של פעולת החיפוש היה אובייקט או תיקייה מנוהלת.

completeTime חותמת הזמן שבה הפעולה הושלמה, בפורמט תואם לתקן ISO 8601.
destinationContainer

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

מאגר היעד של ההעברה הזו. מכיל שני שדות משנה:

  • ‫gcsBucket.bucket: השם של קטגוריית היעד ב-Cloud Storage.
  • ‫type: תמיד GCS.
destinationObject

מוצג רק בפעולות COPY ו-DELETE.

מידע על האובייקט ביעד. מכיל שני שדות משנה:

  • אחד מהערכים gcsObject,‏ gcsManagedFolder או posixFile, בהתאם ליעד. כל האפשרויות מכילות כמה שדות משנה שמציינים את השם, המיקום, פרטי התאריך/השעה וה-hash של האובייקט או הקובץ.
  • ‫type הוא GCS או POSIX_FS.

לדוגמה:

"destinationObject": {
  "type": "POSIX_FS",
  "posixFile": {
    "crc32c": "0",
    "path": "/tmp/data/filename.txt",
    "lastModifiedTime": "2022-09-22T04:33:45Z"
  }
}
operation השם המלא של transferOperations.
sourceContainer

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

מאגר המקור של ההעברה הזו. מכיל שני שדות משנה:

  • רשומה שמציינת את מיקום המקור. השדה נקרא בהתאם לסוג המקור. אלה השדות האפשריים:
    • ‫awsS3Bucket.bucket: השם של קטגוריית AWS S3.
    • ‫azureBlobContainer: מכיל את שדות המשנה account ו-container, שיחד מגדירים את ה-URI של Microsoft Azure Blob Storage.
    • ‫gcsBucket.bucket: השם של הקטגוריה ב-Cloud Storage.
    • ‫httpManifest.url: כתובת ה-URL של רשימת כתובות URL שמציינת קבצים שזמינים לכולם להורדה משרת HTTP(S).
  • ‫type הוא אחד מהערכים הבאים: AWS_S3, ‏AZURE_BLOB, ‏GCS או HTTP.

לדוגמה:

"sourceContainer": {
  "gcsBucket": {
    "bucket": "my-bucket-1"
  },
  "type": "GCS"
}
sourceObject

מוצג רק בפעולות COPY ו-DELETE.

מידע על אובייקט המקור. מכיל שני שדות משנה:

  • רשומה ספציפית למארח של אובייקט המקור. השדה נקרא בהתאם לסוג המקור, והוא מכיל שדות משנה למטא-נתונים. אלה השדות האפשריים:
    • ‫awsS3Object: אובייקט AWS S3.
    • ‫awsS3CompatibleObject: אובייקט באחסון תואם-S3.
    • ‫azureBlob: קובץ ב-Azure Blob Storage.
    • ‫gcsObject: אובייקט ב-Cloud Storage.
    • ‫gcsManagedFolder: תיקייה מנוהלת ב-Cloud Storage.
    • ‫hdfsFile: קובץ ב-HDFS.
    • ‫httpFile: קובץ שצוין על ידי רשימת כתובות URL.
    • ‫posixFile: קובץ במערכת קבצים של POSIX.
  • ‫type הוא אחד מהערכים הבאים: AWS_S3,‏ AWS_S3_COMPATIBLE,‏ AZURE_BLOB,‏ GCS,‏ HDFS,‏ HTTP או POSIX_FS.

לדוגמה:

"sourceObject": {
  "gcsObject": {
    "bucket": "my-bucket-1",
    "lastModifiedTime": "2021-12-07T16:41:09.456Z",
    "md5": "WgnCOIdfCXNTUDpQJSKb2w==",
    "objectKey": "README.md"
  },
  "type": "GCS"
}
status

סטטוס הפעולה. אם הערך של status.statusCode הוא OK, הפעולה הצליחה. אחרת, הפעולה נכשלה. השדות status.errorType ו-status.errorMessage מאוכלסים רק אם הסטטוס הוא לא OK.

בנוסף, השדה resource ברמה העליונה מכיל את השדות הבאים.

"resource": {
  "labels": {
    "job_id": "transferJobs/7876027868280507149",
    "project_id": "my-project-id"
  },
  "type": "storage_transfer_job"
}
שדה ביומן תיאור
resource.labels.job_id שם המשימה ב-Storage Transfer Service שאליה שייך היומן הזה.
resource.labels.project_id מזהה הפרויקט ב- Google Cloud של ההעברה הזו.