이러한 역할은 에이전트가 사용하는 서비스 계정에 부여될 수 있으며, 또는 이러한 역할을 가진 사용자는 에이전트 설치 시 기본 사용자 인증 정보를 사용할 수 있습니다.
각 에이전트에서 소스 파일 시스템의 모든 경로를 읽을 수 있는지 확인합니다.
객체에는 버킷의 보존 정책이 적용되며, 이를 삭제하거나 덮어쓰거나 보관처리할 수 없습니다.
PERMISSION_FAILURE
버킷에는 보관 정책이 적용되고 객체가 이미 버킷에 있습니다. Storage Transfer Service에서 버킷의 기존 객체를 덮어쓸 수 없습니다. 이 오류는 파일이 소스에서 파일이 변경되거나 Storage Transfer Service가 네트워크 조건으로 인해 업로드를 두 번 시도하고 첫 번째 업로드가 성공한 경우에 표시될 수 있습니다.
Cloud Storage 버킷의 데이터가 예상과 일치하는지 확인합니다. 작업을 다시 실행하고 오류가 없는지 확인하여 소스 파일의 크기 및 수정 시간(mtime)이 Cloud Storage 객체와 일치하는지 확인할 수 있습니다.
서비스에 충분한 권한이 없음
SERVICE_PERMISSION_FAILURE
Storage Transfer Service에 작업을 수행할 수 있는 충분한 권한이 없습니다.
sudo docker pull gcr.io/cloud-ingest/tsop-agent를 실행하여 최신 Docker 이미지를 가져옵니다.
Docker run 명령어를 실행하여 모든 에이전트 컨테이너를 시작합니다.
문제가 지속되면 지원팀에 문의하세요.
해시 불일치로 인해 실패함
HASH_MISMATCH_FAILURE
Storage Transfer Service에서 이 파일을 업로드하려고 할 때마다 업로드된 바이트가 손상됩니다. 이로 인해 온프레미스 파일의 해시가 결과 Cloud Storage 객체의 해시와 일치하지 않습니다.
이 오류는 여러 잠재적 문제로 인해 발생할 수 있습니다. 대량 전송에서 해시 불일치 오류가 1% 미만인 경우 실패한 파일을 다시 시도하세요. 해시 불일치 오류가 많은 경우(1% 이상) 에이전트 머신에서 잠재 메모리, CPU 또는 기타 하드웨어 오류를 조사하는 것이 좋습니다.
지원되지 않는 파일 모드로 인해 실패함
UNSUPPORTED_FILE_MODE
Storage Transfer Service에서 기기, 소켓, 명명된 파이프 또는 일반적이지 않은 파일과 같이 지원되지 않는 모드가 포함된 파일이 발생했습니다.
소스 디렉터리에서 이러한 특수 파일 형식을 삭제합니다.
파일 시스템의 오류로 인해 실패함
FILESYSTEM_ERROR
에이전트에 읽기, 탐색, 통계 등 파일 시스템 작업 수행 시 파일 시스템 오류 또는 운영체제 오류가 발생했습니다.
실패 설명을 참조하여 어떤 파일 시스템 작업이 실패했는지 확인합니다. 파일 시스템이 온프렘 에이전트가 액세스할 수 있으며 기본 파일 작업에 응답하는지 확인합니다.
알 수 없는 오류로 인해 실패함
UNKNOWN_FAILURE
예기치 않은 오류가 발생했습니다.
실패 설명을 읽습니다. 실패 설명에 문제 해결에 필요한 정보가 부족하면 지원팀에 문의하세요.
사양이 잘못되어 실패했습니다.
INVALID_SPEC
에이전트가 손상된 내부 사양을 받았습니다.
에이전트 호스트에서 데이터 손상이 있는지 확인하고 찾을 수 없는 경우 지원팀에 문의하세요.
비어 있거나 잘못된 매니페스트 파일로 인해 실패함
CONFORMANCE_FAILURE
잘못된 형식 또는 CSV 항목으로 인해 에이전트에서 유효한 CSV 바이트를 읽거나 가져올 수 없습니다.
매니페스트 항목이 유효한 파일 경로인지 확인합니다. 실패 설명에 문제 해결에 필요한 정보가 부족하면 지원팀에 문의하세요.
권한 거부됨 오류로 인해 멀티파트 업로드 대신 재개 가능한 업로드로 돌아감
PERMISSION_FAILURE
이 전송에는 멀티파트 업로드가 사용 설정되었지만 버킷에 올바른 권한이 설정되지 않았습니다.
에이전트 로그에는 에이전트 프로세스와 관련된 정보가 포함되어 에이전트 연결 문제를 해결할 수 있습니다. 에이전트가 Google Cloud Console에 연결되어 있는 것으로 표시되고 전송 실패가 발생하면 오류 보기에서 전송 오류 샘플을 확인하세요. 전송 중에 고려되는 모든 Storage Transfer Service 파일의 레코드가 포함된 로그를 보려면 전송 로그 보기를 참조하세요.
기본적으로 에이전트 로그는 /tmp에 저장됩니다. --log-dir=logs-directory명령줄 옵션을 사용하여 위치를 변경할 수 있습니다.
로그의 이름은 다음과 같습니다.
agent.hostname.username.log.log-level.timestamp
각 항목의 의미는 다음과 같습니다.
hostname - 에이전트가 실행 중인 호스트 이름입니다.
username - 에이전트를 실행하는 사용자 이름입니다.
log-level은 다음 중 하나입니다.
INFO - 정보 제공 메시지
ERROR - 전송 중에 오류가 발생했지만 전송 작업이 계속 실행되는 것을 막지는 않습니다.
FATAL - 전송 작업을 계속 진행할 수 없는 오류가 발생했습니다.
timestamp - YYYYMMDD-hhmmss.thread-id 형식의 타임스탬프
로그 디렉터리에는 각 우선순위 수준의 최신 로그에 대한 심볼릭 링크가 포함되어 있습니다.
agent.ERROR
agent.FATAL
agent.INFO
느린 전송 속도
데이터를 전송하는 데 시간이 오래 걸리는 경우 다음을 확인하세요.
파일 시스템의 읽기 처리량은 원하는 업로드 속도의 약 1.5배여야 합니다. FIO를 사용하여 파일 시스템의 읽기 처리량을 테스트할 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2024-12-21(UTC)"],[],[],null,["# Troubleshoot file system transfers\n\nThis document describes how to troubleshoot and resolve transfer and agent\nissues, and where to find agent logs to help you troubleshoot issues.\n\nErrors\n------\n\nThe following table describes transfer error messages, and how to resolve\nthem:\n\nViewing agent logs\n------------------\n\nAgent logs contain information relevant to agent processes, and can help you\ntroubleshoot agent connection problems. If your agents are listed as connected\nin Google Cloud console and you are experiencing transfer failures, see\n[Viewing errors](/storage-transfer/docs/managing-on-prem-jobs#view-errors) to view a sample of transfer\nerrors. To view logs that contain a record of every file Storage Transfer Service\nconsidered during a transfer, see\n[Viewing transfer logs](/storage-transfer/docs/managing-on-prem-jobs#viewing-logs).\n\nBy default, agent logs are stored in `/tmp`. You can change the location with\nthe `--log-dir=`\u003cvar translate=\"no\"\u003elogs-directory\u003c/var\u003e\n[command-line option](/storage-transfer/docs/on-prem-agent-command-options).\n\nThe logs are named:\n\n`agent.`\u003cvar translate=\"no\"\u003ehostname\u003c/var\u003e`.`\u003cvar translate=\"no\"\u003eusername\u003c/var\u003e`.log.`\u003cvar translate=\"no\"\u003elog-level\u003c/var\u003e`.`\u003cvar translate=\"no\"\u003etimestamp\u003c/var\u003e\n\nWhere:\n\n- \u003cvar translate=\"no\"\u003ehostname\u003c/var\u003e - hostname the agent is running on.\n- \u003cvar translate=\"no\"\u003eusername\u003c/var\u003e - username running the agent.\n- \u003cvar translate=\"no\"\u003elog-level\u003c/var\u003e is one of:\n - **`INFO`** - informational messages\n - **`ERROR`** - errors encountered during transfer, but that don't prevent the transfer job from continuing.\n - **`FATAL`** - errors encountered that prevent the transfer job from continuing.\n- \u003cvar translate=\"no\"\u003etimestamp\u003c/var\u003e - timestamp in `YYYYMMDD-hhmmss.thread-id` format.\n\nThe logs directory contains symlinks to the most recent logs for each of the\npriority levels:\n\n- `agent.ERROR`\n- `agent.FATAL`\n- `agent.INFO`\n\nSlow transfer speed\n-------------------\n\nIf your data is taking a long time to transfer, check the following:\n\n1. The read throughput of your file system should be approximately 1.5\n times your desired upload speed. You can use [FIO](https://fio.readthedocs.io/en/latest/fio_doc.html)\n to test the read throughput of your file system.\n\n \u003cbr /\u003e\n\n Install fio: \n\n sudo apt install -y fio\n \n Create a new directory `fiotest`: \n\n TEST_DIR=/mnt/mnt_dir/fiotest\n sudo mkdir -p $TEST_DIR\n \n Test read throughput: \n\n sudo fio --directory=$TEST_DIR --direct=1\n --rw=randread --randrepeat=0 --ioengine=libaio --bs=1M --iodepth=8\n --time_based=1 --runtime=180 --name=read_test --size=1G\n \n \u003cbr /\u003e\n\n After you run the commands above, Fio generates a report. The line labeled\n \"bw\" represents the total aggregate bandwidth of all threads, and it can be\n used as a proxy for read throughput.\n2. Use [iPerf3](https://iperf.fr/iperf-download.php) to check your\n available internet bandwidth to Storage Transfer Service.\n\n3. Make sure each of your transfer agents have at least 4 vCPU and 8GB of RAM.\n\nIf you've checked the conditions above and are still experiencing long transfer\ntimes, you can add additional agents to increase the number of concurrent\nconnections to your data's file system.\n\nFor more information on how to maximize the performance of your transfer agents,\nsee [Agent best practices](/storage-transfer/docs/on-prem-agent-best-practices).\n\nTroubleshooting agent errors\n----------------------------\n\nThe following sections describe how to troubleshoot and resolve transfer\nagent errors:\n\n### Agents are not connected\n\nIf transfer agents are not displayed as connected within Google Cloud console:\n\n1. Verify that agents can connect to Cloud Storage APIs:\n\n 1. Run the following command from the same machine as the transfer agent to\n test the agent's connection to Cloud Storage APIs:\n\n `gcloud storage cp test.txt gs://`\u003cvar translate=\"no\"\u003emy-bucket\u003c/var\u003e\n\n Replace:\n\n \u003cvar translate=\"no\"\u003emy-bucket\u003c/var\u003e with the name of your Cloud Storage\n bucket.\n2. If your project uses VPC Service Controls,\n [view the agent logs](#agent-logs) for errors. If\n VPC Service Controls is misconfigured, the `INFO` agent logs will contain\n the following error:\n\n `Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: `\u003cvar translate=\"no\"\u003eid\u003c/var\u003e\n\n In this output:\n - \u003cvar translate=\"no\"\u003eid\u003c/var\u003e is the [VPC Service Controls error's unique id](/vpc-service-controls/docs/troubleshooting#using_the_errors_unique_id)\n\n### Agents are connected but jobs fail\n\nIf agents are displayed as connected but transfer jobs fail, check the\n[error details of the failed jobs](/storage-transfer/docs/managing-on-prem-jobs#view-errors).\n\n### Proxy rejects IP addresses\n\nIf you run behind a proxy like [Squid](https://www.squid-cache.org/)\nand you use an allowlist, you may see requests being denied because of\nIP addresses being used instead of hostnames.\n\nTo resolve this issue, use the\n[docker run command to run the agents](/storage-transfer/docs/managing-on-prem-agents#docker-run)\nand add the following flag: \n\n --transfer-service-endpoint=storagetransfer.googleapis.com:443\n\nIf you use an alternative endpoint to reach `googleapis.com` (e.g. for\nPrivate Service Connect), replace `googleapis.com` with the\nalternative endpoint.\n\n### Agent is unable to connect to an HTTPS endpoint using a self-signed certificate\n\nIf your agent is unable to connect to an HTTPS endpoint using a self-signed\ncertificate, use an extra `-v` option to mount your custom certificate\nbundle into the container's default location (`/etc/ssl/certs`).\n\nTo do this, modify the\n[`docker run` command](/storage-transfer/docs/managing-on-prem-agents#docker-run)\nby adding the following flag: \n\n -v \u003cvar translate=\"no\"\u003ePATH_TO_LOCAL_CERT\u003c/var\u003e:/etc/ssl/certs/ca-certificates.crt\n\nReplace:\n\n- \u003cvar translate=\"no\"\u003ePATH_TO_LOCAL_CERT\u003c/var\u003e with the path to your custom certificate file."]]
