Renamed from job traces to job logs in GitLab 12.5.
Job logs are sent by a runner while it's processing a job. You can see logs in job pages, pipelines, email notifications, etc.
In general, there are two states for job logs:
In the following table you can see the phases a log goes through:
|Phase||State||Condition||Data flow||Stored path|
|1: patching||log||When a job is running||Runner => Puma => file storage||
|2: overwriting||log||When a job is finished||Runner => Puma => file storage||
|3: archiving||archived log||After a job is finished||Sidekiq moves log to artifacts folder||
|4: uploading||archived log||After a log is archived||Sidekiq moves archived log to object storage (if configured)||
ROOT_PATH varies per environment. For Omnibus GitLab it
/var/opt/gitlab, and for installations from source
it would be
Changing the job logs local location
To change the location where the job logs will be stored, follow the steps below.
In Omnibus installations:
/etc/gitlab/gitlab.rband add or amend the following line:
gitlab_ci['builds_directory'] = '/mnt/to/gitlab-ci/builds'
Save the file and reconfigure GitLab for the changes to take effect.
In installations from source:
/home/git/gitlab/config/gitlab.ymland add or amend the following lines:
gitlab_ci: # The location where build logs are stored (default: builds/). # Relative paths are relative to Rails.root. builds_path: path/to/builds/
Save the file and restart GitLab for the changes to take effect.
Uploading logs to object storage
See "Phase 4: uploading" in Data flow to learn about the process.
Prevent local disk usage
If you want to avoid any local disk usage for job logs, you can do so using one of the following options:
How to remove job logs
There isn't a way to automatically expire old job logs, but it's safe to remove them if they're taking up too much space. If you remove the logs manually, the job output in the UI will be empty.
For example, to delete all job logs older than 60 days, run the following from a shell in your GitLab instance:
DANGER: Danger: This command will permanently delete the log files and is irreversible.
find /var/opt/gitlab/gitlab-rails/shared/artifacts -name "job.log" -mtime +60 -delete
New incremental logging architecture
- Introduced in GitLab 10.4.
NOTE: Note: This beta feature is off by default. See below for how to enable or disable it.
By combining the process with object storage settings, we can completely bypass the local file storage. This is a useful option if GitLab is installed as cloud-native, for example on Kubernetes.
The data flow is the same as described in the data flow section with one change: the stored path of the first two phases is different. This incremental log architecture stores chunks of logs in Redis and a persistent store (object storage or database) instead of file storage. Redis is used as first-class storage, and it stores up-to 128KB of data. Once the full chunk is sent, it is flushed to a persistent store, either object storage (temporary directory) or database. After a while, the data in Redis and a persistent store will be archived to object storage.
The data are stored in the following Redis namespace:
Here is the detailed data flow:
- The runner picks a job from GitLab
- The runner sends a piece of log to GitLab
- GitLab appends the data to Redis
- Once the data in Redis reach 128KB, the data is flushed to a persistent store (object storage or the database).
- The above steps are repeated until the job is finished.
- Once the job is finished, GitLab schedules a Sidekiq worker to archive the log.
- The Sidekiq worker archives the log to object storage and cleans up the log in Redis and a persistent store (object storage or the database).
Enabling incremental logging
The following commands are to be issued in a Rails console:
# Omnibus GitLab gitlab-rails console # Installation from source cd /home/git/gitlab sudo -u git -H bin/rails console -e production
To check if incremental logging (trace) is enabled:
To enable incremental logging (trace):
NOTE: Note: The transition period will be handled gracefully. Upcoming logs will be generated with the incremental architecture, and on-going logs will stay with the legacy architecture, which means that on-going logs won't be forcibly re-generated with the incremental architecture.
To disable incremental logging (trace):
NOTE: Note: The transition period will be handled gracefully. Upcoming logs will be generated with the legacy architecture, and on-going incremental logs will stay with the incremental architecture, which means that on-going incremental logs won't be forcibly re-generated with the legacy architecture.
In some cases, having data stored on Redis could incur data loss:
Case 1: When all data in Redis are accidentally flushed
- On going incremental logs could be recovered by re-sending logs (this is supported by all versions of GitLab Runner).
- Finished jobs which have not archived incremental logs will lose the last part (~128KB) of log data.
Case 2: When Sidekiq workers fail to archive (e.g., there was a bug that prevents archiving process, Sidekiq inconsistency, etc.)
- Currently all log data in Redis will be deleted after one week. If the Sidekiq workers can't finish by the expiry date, the part of log data will be lost.
Another issue that might arise is that it could consume all memory on the Redis instance. If the number of jobs is 1000, 128MB (128KB * 1000) is consumed.
Also, it could pressure the database replication lag.
INSERTs are generated to
indicate that we have log chunk.
UPDATEs with 128KB of data is issued once we
receive multiple chunks.