PR-URL: https://github.com/hasura/graphql-engine-mono/pull/10615 GitOrigin-RevId: 8a45c92bec8444d5ec0aed125f4aa96d9c684728 |
||
---|---|---|
.. | ||
cabal.project.dev | ||
ci-haddock.project | ||
ci-haddock.project.freeze | ||
ci-haddock.project.local | ||
ci.project | ||
ci.project.freeze | ||
ci.project.local | ||
dev-sh-optimized.project | ||
dev-sh-optimized.project.freeze | ||
dev-sh-optimized.project.local | ||
dev-sh-prof-heap-infomap.project | ||
dev-sh-prof-heap-infomap.project.freeze | ||
dev-sh-prof-heap-infomap.project.local | ||
dev-sh-prof-ticky.project | ||
dev-sh-prof-ticky.project.freeze | ||
dev-sh-prof-ticky.project.local | ||
dev-sh-prof-time.project | ||
dev-sh-prof-time.project.freeze | ||
dev-sh-prof-time.project.local | ||
dev-sh.project | ||
dev-sh.project.freeze | ||
dev-sh.project.local | ||
dev.project | ||
README.md |
At the top level we have a cabal.project
file that defines project
configuration settings that stay the same, regardless of whether we're doing
local development, building on CI, etc.
Additionally in this directory we have various cabal.project.local
files that
add or override settings depending on context:
ci-*.project.local
- these are used when building in CI (see.buildkite/
)dev-sh.project.local
- this is used to configure the environment we expect inscripts/dev.sh
, and is where we put good local development defaultsdev-sh-optimized.project.local
- above, but building with optimizations, suitable for prod-like performance testingdev-sh-prof-*.project.local
- Various profiling modes (see below)
Because we can only gives us --project-file
to select configuration, we need
each of these local overrides to have a symlink back to the top-level
cabal.project
. So e.g. if you wanted to build with CI settings locally you
would do:
$ cabal build --project-file=cabal/ci.project exe:graphql-engine
Likewise for the freeze file symlinks.
In cabal-install 3.8 we can have import
s, which we also use.
Here's a helper for making new configurations:
function hasura_new_sub_config () {
cd "$(git rev-parse --show-toplevel)/cabal"
ln -s ../cabal.project.freeze "$1.project.freeze"
ln -s ../cabal.project "$1.project"
touch "$1.project.local"
echo "continue editing: $1.project.local"
cd - &>/dev/null
}
Profiling modes
See the graphql-engine --prof-*
flags in dev.sh
for the happy path to use these modes.
+RTS -hi
(info map) Heap Profiles
Every distinct constructure allocation site is instrumented with source code information
See: dev-sh-prof-heap-infomap.project.local
- Try it when: you want to go deeper debugging high resident memory during development
- Benefits: doesn't inhibit optimizations, very granular
- Downsides: must recompile, binary sizes can get large, sometimes source info is confusing
ghc-debug
A set of client and server libraries for snapshotting and arbitrarily analyzing the Haskell heap
- Try it when: you need to answer any sort of complex question about what's in memory; e.g. why is something retained? do we have many identical strings and memory?
- Benefits: extremely powerful, can run on production without restart
- Downsides: analysis passes can take time to write and debug, analyzing large heaps requires care
“Ticky ticky” profiling
Generates a report for all allocations even those that are very short-lived; quasi- time profiling
See: dev-sh-prof-ticky.project.local
- Try it when: debugging a regression and bytes allocated, comparing two different versions of code
- Benefits: see and compare allocations directly, doesn't inhibit optimizations
- Downsides: STG can take time to decipher, the program gets very slow, not suitable for production
-fprof-late
time profiling
NOT YET IMPLEMENTED
Time profiling that instruments code after all significant optimizations have been performed, so it doesn't distort the profile (on 9.4+ only, but plug-in available)
See: dev-sh-prof-time.project.local
- Try it when: you want to try to make some code faster, or understand where the time is being spent in the system
- Benefits: get call stacks, granular view of execution time
- Downsides: requires recompilation, STG can be confusing, not suitable for production