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

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

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

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

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

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

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

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

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

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

מצבים שאפשר לרשום ביומן

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

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

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

הפעלת הרישום ביומן לפעולה FIND או למצב SUCCEEDED עלולה לגרום לנפח גדול של נתוני יומן, וזה עשוי להשפיע על העלויות של Cloud Logging.

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

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

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

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

    כדי להחריג רשומות ביומן של 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,find \
  --log-action-states=succeeded,failed,skipped

צריך לציין לפחות ערך אחד לכל דגל.

REST

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

{
  "name":"transferJobs/myFirstTransfer",
  "status": "ENABLED",
  "projectId": "test-id-001",
  "loggingConfig": {
     "logActions": ["FIND", "DELETE", "COPY"],
     "logActionStates": ["SUCCEEDED", "FAILED", "SKIPPED"], #SKIPPED is only supported for agent-based transfers
  },
  "transferSpec": {
      "awsS3DataSource": {
          "bucketName": "AWS_SOURCE_NAME",
          "awsAccessKey": {
              "accessKeyId": "AWS_ACCESS_KEY_ID",
              "secretAccessKey": "AWS_SECRET_ACCESS_KEY"
          }
      },
      "gcsDataSink": {
           "bucketName": "destination_bucket",
           "path": "foo/bar/"
      },
   }
}

משנים את 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,find \
  --log-action-states=succeeded,failed,skipped

כדי להשבית את הרישום ביומן עבור המשימה הזו, מציינים --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", "SKIPPED"], #SKIPPED is only supported for agent-based transfers
    },
  },
  "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. בתפריט שדרוג, עוברים מLegacy Logs Viewer אל Logs Explorer.

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

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

מידע נוסף על השימוש ב-Logs Explorer זמין במאמר שימוש ב-Logs Explorer.

‫CLI של gcloud

כדי להשתמש ב-CLI של gcloud כדי לחפש יומנים של Storage Transfer Service, משתמשים בפקודה 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.

כל השדות הספציפיים ל-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, בהתאם ליעד. כל האפשרויות כוללות כמה שדות משנה שמציינים את השם, המיקום, פרטי התאריך/השעה והגיבוב של האובייקט או הקובץ.
  • ‫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.
    • ‫azureBlob: קובץ ב-Azure Blob Storage.
    • ‫gcsObject: אובייקט ב-Cloud Storage.
    • ‫gcsManagedFolder: תיקייה מנוהלת ב-Cloud Storage.
    • ‫httpFile: קובץ שצוין על ידי רשימת כתובות URL.
    • ‫posixFile: קובץ במערכת קבצים של POSIX.
  • ‫type הוא אחד מהערכים הבאים: AWS_S3, ‏AZURE_BLOB, ‏GCS, ‏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 להעברה הזו.