Details

    • Type: Sub-task Sub-task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 4.1.0
    • Component/s: None
    • Labels:
      None

      Description

      1. BOOKKEEPER-270.patch
        7 kB
        Flavio Junqueira
      2. BOOKKEEPER-270.patch
        7 kB
        Flavio Junqueira
      3. BOOKKEEPER-270.diff
        9 kB
        Ivan Kelly
      4. BOOKKEEPER-270.diff
        9 kB
        Ivan Kelly

        Activity

        Hide
        Ivan Kelly added a comment -

        This is internal to the bookie implementation. It shouldn't be in the user doc. We can doc in the wiki when we do the stuff for adding/removing disks in 4.2

        Show
        Ivan Kelly added a comment - This is internal to the bookie implementation. It shouldn't be in the user doc. We can doc in the wiki when we do the stuff for adding/removing disks in 4.2
        Hide
        Flavio Junqueira added a comment -

        Isn't the cookie related to management of bookies as well? If so, it should go to the admin guide page, no?

        Show
        Flavio Junqueira added a comment - Isn't the cookie related to management of bookies as well? If so, it should go to the admin guide page, no?
        Hide
        Ivan Kelly added a comment -

        It's an internal mechanism. The administrator should never touch cookies directly. Given that this is the case, if they want to mess with internals they should read the code directly.

        Show
        Ivan Kelly added a comment - It's an internal mechanism. The administrator should never touch cookies directly. Given that this is the case, if they want to mess with internals they should read the code directly.
        Hide
        Flavio Junqueira added a comment -

        Cut at documentation for cookies.

        Show
        Flavio Junqueira added a comment - Cut at documentation for cookies.
        Hide
        Ivan Kelly added a comment -

        I'd prefer not to talk about the cookies or their format, and just simply say that if you change the disk configuration of a bookie, it will not be able to start. Detailing the contents creates overhead for making modifications in the future, and we will certainly be making modifications in this area in 4.2.0.

        Show
        Ivan Kelly added a comment - I'd prefer not to talk about the cookies or their format, and just simply say that if you change the disk configuration of a bookie, it will not be able to start. Detailing the contents creates overhead for making modifications in the future, and we will certainly be making modifications in this area in 4.2.0.
        Hide
        Flavio Junqueira added a comment -

        I understand that it would be best to treat bookies as black boxes. However, I couldn't think of a good way of saying precisely the cases we cover (and I don't claim my description is currently precise enough) without giving some detail about the implementation. I'm fine with hiding internal detail, but I'm not ok with not being precise about the cases we cover. If you can think of a better way, I'll be happy to hear.

        Show
        Flavio Junqueira added a comment - I understand that it would be best to treat bookies as black boxes. However, I couldn't think of a good way of saying precisely the cases we cover (and I don't claim my description is currently precise enough) without giving some detail about the implementation. I'm fine with hiding internal detail, but I'm not ok with not being precise about the cases we cover. If you can think of a better way, I'll be happy to hear.
        Hide
        Sijie Guo added a comment -

        I agreed Flavio that we should let admin guys be aware of why the bookie can't start and how they should do when encountering such cases. I would suggest moving the detail cookie format to bookkeeper internal documents, and add some trouble shooting guideline in administrator guide so admin guys know how to handle when encountering similar cases.

        Besides that, do we have any guidelines that when to run bookie recover tool?

        Show
        Sijie Guo added a comment - I agreed Flavio that we should let admin guys be aware of why the bookie can't start and how they should do when encountering such cases. I would suggest moving the detail cookie format to bookkeeper internal documents, and add some trouble shooting guideline in administrator guide so admin guys know how to handle when encountering similar cases. Besides that, do we have any guidelines that when to run bookie recover tool?
        Hide
        Flavio Junqueira added a comment -

        I agreed Flavio that we should let admin guys be aware of why the bookie can't start and how they should do when encountering such cases. I would suggest moving the detail cookie format to bookkeeper internal documents, and add some trouble shooting guideline in administrator guide so admin guys know how to handle when encountering similar cases.

        There are multiple reasons that could lead to a bookie to not start. Wiping out a directory by either replacing a disk or accidentally deleting it are two reasons. In such cases, I'm not entirely sure of what the troubleshooting procedure is right now. Is it to wipe out the whole bookie state and reconstruct its state from scratch by using the bookie recovery tool? If this is something that we will better handle in 4.2.0, we may want to point out that the current version does not provide a feature that handles nicely such situations and it will come in a future version.

        In any case, it sounds like a good idea to me to have a section in the admin's guide called "Troubleshooting".

        do we have any guidelines that when to run bookie recover tool?

        In the docs folder, we have bookieRecovery.textile. It seems to be missing the case in which we have the target bookie as part of the input.

        Show
        Flavio Junqueira added a comment - I agreed Flavio that we should let admin guys be aware of why the bookie can't start and how they should do when encountering such cases. I would suggest moving the detail cookie format to bookkeeper internal documents, and add some trouble shooting guideline in administrator guide so admin guys know how to handle when encountering similar cases. There are multiple reasons that could lead to a bookie to not start. Wiping out a directory by either replacing a disk or accidentally deleting it are two reasons. In such cases, I'm not entirely sure of what the troubleshooting procedure is right now. Is it to wipe out the whole bookie state and reconstruct its state from scratch by using the bookie recovery tool? If this is something that we will better handle in 4.2.0, we may want to point out that the current version does not provide a feature that handles nicely such situations and it will come in a future version. In any case, it sounds like a good idea to me to have a section in the admin's guide called "Troubleshooting". do we have any guidelines that when to run bookie recover tool? In the docs folder, we have bookieRecovery.textile. It seems to be missing the case in which we have the target bookie as part of the input.
        Hide
        Ivan Kelly added a comment -

        I've taken a run at this to document the failure procedure while keeping the internal implementation details out of view. See the attached patch.

        Show
        Ivan Kelly added a comment - I've taken a run at this to document the failure procedure while keeping the internal implementation details out of view. See the attached patch.
        Hide
        Flavio Junqueira added a comment -

        This is excellent, Ivan. I just have a couple of comments:

        1. My spell checker is complaining about a couple of things, so it would be good to fix those. I can do them upon commit if necessary, but if you end up updating the patch because of the second comment, please check the spelling;
        2. I liked the idea of having a section called troubleshooting and it sounds like this discussion fits perfectly such a section. How do you feel about having such a section and moving this discussion there?
        Show
        Flavio Junqueira added a comment - This is excellent, Ivan. I just have a couple of comments: My spell checker is complaining about a couple of things, so it would be good to fix those. I can do them upon commit if necessary, but if you end up updating the patch because of the second comment, please check the spelling; I liked the idea of having a section called troubleshooting and it sounds like this discussion fits perfectly such a section. How do you feel about having such a section and moving this discussion there?
        Hide
        Ivan Kelly added a comment -

        Spelling fixed.

        Regarding having a troubleshooting section, I think it would be better to wait until we have seen issues in the wild, and add them to the troubleshooting section as needed. I think trying to preemptively add troubleshooting without experience wouldn't be very useful.

        In fact, I think for 4.2.0 we should go through the mailing list and create a FAQ.

        Show
        Ivan Kelly added a comment - Spelling fixed. Regarding having a troubleshooting section, I think it would be better to wait until we have seen issues in the wild, and add them to the troubleshooting section as needed. I think trying to preemptively add troubleshooting without experience wouldn't be very useful. In fact, I think for 4.2.0 we should go through the mailing list and create a FAQ.
        Hide
        Flavio Junqueira added a comment -

        +1, fair enough the point about troubleshooting. There is still a typo in the Bookie Recovery page, not introduced by you. The one committing it, please fix it.

        Show
        Flavio Junqueira added a comment - +1, fair enough the point about troubleshooting. There is still a typo in the Bookie Recovery page, not introduced by you. The one committing it, please fix it.
        Hide
        Flavio Junqueira added a comment -

        Committed revision 1343973, 1343986 (CHANGES.txt missing in the first commit).

        Show
        Flavio Junqueira added a comment - Committed revision 1343973, 1343986 (CHANGES.txt missing in the first commit).
        Hide
        Hudson added a comment -

        Integrated in bookkeeper-trunk #533 (See https://builds.apache.org/job/bookkeeper-trunk/533/)
        BOOKKEEPER-270: Review documentation on bookie cookie (ivank via fpj) (Revision 1343981)

        Result = SUCCESS
        fpj :
        Files :

        • /zookeeper/bookkeeper/trunk/doc/bookieRecovery.textile
        • /zookeeper/bookkeeper/trunk/doc/bookkeeperConfig.textile
        Show
        Hudson added a comment - Integrated in bookkeeper-trunk #533 (See https://builds.apache.org/job/bookkeeper-trunk/533/ ) BOOKKEEPER-270 : Review documentation on bookie cookie (ivank via fpj) (Revision 1343981) Result = SUCCESS fpj : Files : /zookeeper/bookkeeper/trunk/doc/bookieRecovery.textile /zookeeper/bookkeeper/trunk/doc/bookkeeperConfig.textile
        Hide
        Hudson added a comment -

        Integrated in bookkeeper-trunk #534 (See https://builds.apache.org/job/bookkeeper-trunk/534/)
        BOOKKEEPER-270: Review documentation on bookie cookie (ivank via fpj) (Revision 1343986)

        Result = ABORTED
        fpj :
        Files :

        • /zookeeper/bookkeeper/trunk/CHANGES.txt
        Show
        Hudson added a comment - Integrated in bookkeeper-trunk #534 (See https://builds.apache.org/job/bookkeeper-trunk/534/ ) BOOKKEEPER-270 : Review documentation on bookie cookie (ivank via fpj) (Revision 1343986) Result = ABORTED fpj : Files : /zookeeper/bookkeeper/trunk/CHANGES.txt

          People

          • Assignee:
            Ivan Kelly
            Reporter:
            Flavio Junqueira
          • Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development