diff options
Diffstat (limited to 'doc/ci/services/index.md')
| -rw-r--r-- | doc/ci/services/index.md | 42 |
1 files changed, 41 insertions, 1 deletions
diff --git a/doc/ci/services/index.md b/doc/ci/services/index.md index 0f82f2301c7..830b9406c6e 100644 --- a/doc/ci/services/index.md +++ b/doc/ci/services/index.md @@ -37,7 +37,7 @@ the CI container itself. ## How services are linked to the job To better understand how container linking works, read -[Linking containers together](https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/). +[Linking containers together](https://docs.docker.com/network/links/). If you add `mysql` as service to your application, the image is used to create a container that's linked to the job container. @@ -392,6 +392,46 @@ time. 1. Check the exit status of build script. 1. Remove the build container and all created service containers. +## Capturing service container logs + +Logs generated by applications running in service containers can be captured for subsequent examination and debugging. +You might want to look at service container's logs when the service container has started successfully, but is not +behaving es expected, leading to job failures. The logs can indicate missing or incorrect configuration of the service +within the container. + +`CI_DEBUG_SERVICES` should only by enabled when service containers are being actively debugged as there are both storage +and performance consequences to capturing service container logs. + +To enable service logging, add the `CI_DEBUG_SERVICES` variable to the project's +`.gitlab-ci.yml` file: + +```yaml +variables: + CI_DEBUG_SERVICES: "true" +``` + +Accepted values are: + +- Enabled: `TRUE`, `true`, `True` +- Disabled: `FALSE`, `false`, `False` + +Any other values will result in an error message and effectively disable the feature. + +When enabled, logs for _all_ service containers will be captured and streamed into the jobs trace log concurrently with +other logs. Logs from each container will be prefixed with the container's aliases, and displayed in a different color. + +NOTE: +You may want to adjust the logging level in the service container for which you want to capture logs since the default +logging level may not provide sufficient details to diagnose job failures. + +WARNING: +Enabling `CI_DEBUG_SERVICES` _may_ result in masked variables being revealed. When `CI_DEBUG_SERVICES` is enabled, +service container logs and the CI job's logs are streamed to the job's trace log _concurrently_, which makes it possible +for a service container log to be inserted _inside_ a job's masked log. This would thwart the variable masking mechanism +and result in the masked variable being revealed. + +See [Mask a CI/CD Variable](../variables/index.md#mask-a-cicd-variable) + ## Debug a job locally The following commands are run without root privileges. You should be |