Apply 6 suggestion(s) to 1 file(s)

Co-authored-by: Russell Dickenson <rdickenson@gitlab.com>

doc/user/project/import/index.md

@@ -456,3 +456,55 @@ If an imported repository does not contain all branches of the source repository
 The error occurs if you attempt to import a `tar.gz` file download of a repository's source code.
 Imports require a [GitLab export](../settings/import_export.md#export-a-project-and-its-data) file, not just a repository download file.
+
+### Diagnosing prolonged or failed imports
+
+If you're experiencing prolonged delays or failures with file-based imports, especially those using S3, the following may help identify the root cause of the problem:
+
+- [Check import steps](#check-import-status)
+- [Review logs](#review-logs)
+- [Identify common issues](#identify-common-issues)
+
+#### Check import status
+
+Check the import status:
+
+1. Use the GitLab API to check the [import status](../../../api/project_import_export.md#import-status) of the affected project.
+1. Review the response for any error messages or status information, especially the `status` and `import_error` values.
+1. Make note of the `correlation_id` in the response, as it's crucial for further troubleshooting.
+
+#### Review logs
+
+Search logs for relevant information:
+
+For self-managed instances:
+
+1. Check the [Sidekiq logs](../../../administration/logs/index.md#sidekiqlog) and [`exceptions_json` logs](../../../administration/logs/index.md#exceptions_jsonlog).
+1. Search for entries related to `RepositoryImportWorker` and the correlation ID from [Check import status](#check-import-status).
+1. Look for fields such as `job_status`, `interrupted_count`, and `exception`.
+
+For GitLab.com (GitLab team members only):
+
+1. Use [Kibana](https://log.gprd.gitlab.net/) to search the Sidekiq logs with queries like:
+
+   Target: `pubsub-sidekiq-inf-gprd*`
+
+   ```plaintext
+   json.class: "RepositoryImportWorker" AND json.correlation_id.keyword: "<CORRELATION_ID>"
+   ```
+   
+   or
+
+   ```plaintext
+   json.class: "RepositoryImportWorker" AND json.meta.project: "<project.full_path>"
+   ```
+
+1. Look for the same fields as mentioned for self-managed instances.
+
+#### Identify common issues
+
+Check the information gathered in [Review logs](#review-logs) against the following common issues:
+
+- **Interrupted jobs**: If you see a high `interrupted_count` or `job_status` indicating failure, the import job may have been interrupted multiple times and placed in a dead queue.
+- **S3 connectivity**: For imports using S3, check for any S3-related error messages in the logs.
+- **Large repository**: If the repository is very large, the import might time out. Consider using [Direct transfer](../../group/import/index.md) in this case.