הפעלת רישום ביומן עבור 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 שאין להם ערך רב. מכיוון שכל יעד ליומן בפרויקט מעריך את כל רשומות היומן, יכול להיות שתצטרכו לעדכן כמה יעדים ליומן.

    כדי להחריג רשומות ביומן של 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. בתפריט שדרוג, עוברים מכלי הצפייה ביומנים (גרסה קודמת) אל 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 להעברה הזו.