gradle/actions
1
0
Fork 0
mirror of https://github.com/gradle/actions synced 2024-11-27 11:52:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Improve documentation for debug logging

Browse source
This commit is contained in:
Daz DeBoer 2024-02-11 18:18:43 -07:00 committed by GitHub
parent 4b284311c3
commit 09bd32c78f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 26 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

51
setup-gradle/README.md
View file

@ -193,30 +193,6 @@ Specifically:
Using either of these mechanisms may interfere with the caching provided by this action. If you choose to use a different mechanism to save and restore the Gradle User Home, you should disable the caching provided by this action, as described above.
### GitHub Action Debug support
To debug a failed job, GitHub provides a [debug mode](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging).
If this debug mode is active, this action adds `--info` and `--stacktrace` by writing these [Gradle properties](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties) into the `${GRADLE_USER_HOME}/gradle.properties` file at the top.
To opt-out of this behaviour you can override these properties manually and put them into your `gradle.properties` file:
```properties
# default lifecycle
org.gradle.logging.level=lifecycle
org.gradle.logging.stacktrace=internal
```
### Cache debugging and analysis
A report of all cache entries restored and saved is printed to the Job Summary when saving the cache entries.
This report can provide valuable insight into how much cache space is being used.
It is possible to enable additional debug logging for cache operations. You do via the `GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED` environment variable:
```yaml
env:
GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED: true
```
Note that when the workflow is run in debug mode (above), cache debugging is automatically enabled.
## How Gradle User Home caching works
### Properties of the GitHub Actions cache
@ -338,7 +314,6 @@ Note there are some cases where writing cache entries is typically unhelpful (th
- For `pull_request` triggered runs, the cache scope is limited to the merge ref (`refs/pull/.../merge`) and can only be restored by re-runs of the same pull request.
- For `merge_group` triggered runs, the cache scope is limited to a temporary branch with a special prefix created to validate pull request changes, and won't be available on subsequent Merge Queue executions.
### Exclude content from Gradle User Home cache
As well as any wrapper distributions, the action will attempt to save and restore the `caches` and `notifications` directories from Gradle User Home.
@ -376,6 +351,32 @@ Gradle Home cache cleanup is considered experimental and is disabled by default.
```yaml
gradle-home-cache-cleanup: true
```
## Debugging and Troubleshooting
In order to debug a failed job, it can be useful to run with [debug logging enabled](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging).
You can enable debug logging either by adding an `ACTIONS_STEP_DEBUG` variable to your repository configuration, or by re-running a Job and checking the "Enable debug logging" box.
### Increased logging from Gradle builds
When debug logging is enabled, this action will cause all builds to run with the `--info` and `--stacktrace` options.
This is done by inserting the relevant [Gradle properties](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties)
at the top of the `${GRADLE_USER_HOME}/gradle.properties` file.
If the additional Gradle logging produced is problematic, you may opt-out of this behaviour by setting these properties manually in your project `gradle.properties` file:
```properties
# default lifecycle
org.gradle.logging.level=lifecycle
org.gradle.logging.stacktrace=internal
```
### Cache debugging and analysis
A report of all cache entries restored and saved is printed to the Job Summary when saving the cache entries.
This report can provide valuable insight into how much cache space is being used.
When debug logging is enabled, more detailed logging of cache operations is included in the GitHub actions log.
This includes a breakdown of the contents of the Gradle User Home directory, which may assist in cache optimization.
## Build reporting