From 17d35b367d8b3fce5bb2b529fae8aab924143d36 Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Thu, 24 Sep 2020 14:39:41 +0800 Subject: [PATCH] doc/dev/crimson: add instructions on how to build crimson and add a link to Scylla's document on debugging with GDB Signed-off-by: Kefu Chai --- doc/dev/crimson.rst | 65 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 54 insertions(+), 11 deletions(-) diff --git a/doc/dev/crimson.rst b/doc/dev/crimson.rst index 77e55ef97b102..15bbb05ecf33c 100644 --- a/doc/dev/crimson.rst +++ b/doc/dev/crimson.rst @@ -8,12 +8,43 @@ the art technologies like DPDK and SPDK, for better performance. And it will keep the support of HDDs and low-end SSDs via BlueStore. Crismon will try to be backward compatible with classic OSD. +.. highlight:: console + +Building Crimson +================ + +Crismon is not enabled by default. To enable it:: + + $ mkdir build && cd build + $ cmake -DWITH_SEASTAR=ON .. + +Please note, `ASan`_ is enabled by default if crimson is built from a source +cloned using git. + +Also, Seastar uses its own lockless allocator which does not play well with +the alien threads. So, to use alienstore / bluestore backend, you might want to +pass ``-DSeastar_CXX_FLAGS=-DSEASTAR_DEFAULT_ALLOCATOR`` to ``cmake`` when +configuring this project to use the libc allocator, like:: + + $ cmake -DWITH_SEASTAR=ON -DSeastar_CXX_FLAGS=-DSEASTAR_DEFAULT_ALLOCATOR .. + +.. _ASan: https://github.com/google/sanitizers/wiki/AddressSanitizer Running Crimson =============== As you might expect, crimson is not featurewise on par with its predecessor yet. +object store backend +-------------------- + +At the moment ``crimson-osd`` offers two object store backends: + +- CyanStore: CyanStore is modeled after memstore in classic OSD. +- AlienStore: AlienStore is short for Alienized BlueStore. + +Seastore is still under active development. + daemonize --------- @@ -34,8 +65,6 @@ to do the trick. .. _fork(): http://pubs.opengroup.org/onlinepubs/9699919799/functions/fork.html -.. highlight:: console - logging ------- @@ -83,7 +112,20 @@ using ``vstart.sh``, ``--osd-args`` pass extra command line options to crimson-osd or ceph-osd. It's quite - useful for passing Seastar options to crimson-osd. + useful for passing Seastar options to crimson-osd. For instance, you could + use ``--osd-args "--memory 2G"`` to set the memory to use. Please refer + the output of:: + + crimson-osd --help-seastar + + for more Seastar specific command line options. + +``--memstore`` + use the CyanStore as the object store backend. + +``--bluestore`` + use the AlienStore as the object store backend. This is the default setting, + if not specified otherwise. So, a typical command to start a single-crimson-node cluster is:: @@ -93,8 +135,6 @@ So, a typical command to start a single-crimson-node cluster is:: --osd-args "--memory 4G" Where we assign 4 GiB memory, a single thread running on core-0 to crimson-osd. -Please refer ``crimson-osd --help-seastar`` for more Seastar specific command -line options. You could stop the vstart cluster using:: @@ -142,11 +182,17 @@ corresponding test results are highlighted. Debugging Crimson ================= +Debugging with GDB +------------------ + +The `tips`_ for debugging Scylla also apply to Crimson. -debugging in your workspace ---------------------------- +.. _tips: https://github.com/scylladb/scylla/blob/master/docs/debugging.md#tips-and-tricks -When a seastar application crashes, it leaves us a serial of addresses, like:: +Human-readable backtraces with addr2line +---------------------------------------- + +When a seastar application crashes, it leaves us with a serial of addresses, like:: Segmentation fault. Backtrace: @@ -206,9 +252,6 @@ the input, so you can also paste the log messages like:: 2020-07-22T11:37:04.501 INFO:teuthology.orchestra.run.smithi061.stderr: 0x0000000000e3e985 2020-07-22T11:37:04.501 INFO:teuthology.orchestra.run.smithi061.stderr: /lib64/libpthread.so.0+0x0000000000012dbf -debugging crashes of teuthology based tests -------------------------------------------- - Unlike classic OSD, crimson does not print a human-readable backtrace when it handles fatal signals like `SIGSEGV` or `SIGABRT`. And it is more complicated when it comes to a stripped binary. So before planting a signal handler for -- 2.39.5