Derby
  1. Derby
  2. DERBY-6359

Document rolling derby.log file feature

    Details

      Description

      The rolling derby.log file feature needs to be documented. This will be used to provide the information necessary to do so.

      1. DERBY-6359-2.zip
        22 kB
        Kim Haase
      2. DERBY-6359-2.diff
        20 kB
        Kim Haase
      3. DERBY-6359.zip
        22 kB
        Kim Haase
      4. DERBY-6359.stat
        0.3 kB
        Kim Haase
      5. DERBY-6359.diff
        20 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Brett Bergquist added a comment -

          I will add the information needed to document the feature.

          Show
          Brett Bergquist added a comment - I will add the information needed to document the feature.
          Hide
          Brett Bergquist added a comment -

          Here is what I have for the documentation Kim.

          The rolling file implementation can either write to a specified file, or it can write to a rotating set of files.

          For a rotating set of files, as each file reaches a given size limit, it is closed, rotated out, and a new file opened. Successively older files are named by adding "0", "1", "2", etc into the base filename.

          The rolling file implementation is specified by adding:

          derby.stream.error.style=rollingFile

          in the "derby.properties" file. This property overrides:

          derby.stream.error.file
          derby.stream.error.method
          derby.stream.error.field

          With no other options specified, the rolling file implementation will create up to 10 rolling files "derby-0.log, derby-1.log, … derby-9.log" with each file having a limit of 1024000 bytes.

          The rolling file implementation can be configured with the following optional properties:

          derby.stream.error.rollingFile.limit=<bytes>

          which specifies the number of bytes to limit each rolling file to before rolling to the next file. The default value is "1024000"

          derby.stream.error.rollingFile.count=<file count>

          which specifies the number of rolling files to permit before deleting the oldest file when rolling to the next file. The default value is "10"

          derby.stream.error.rollingFile.pattern=<pattern>

          A pattern consists of a string that includes the following special components that will be replaced at runtime. The default value is "%d/derby-%g.log"
          • "/" the local pathname separator
          • "%t" the system temporary directory
          • "%h" the value of the "user.home" system property
          • "%d" the value of the "derby.system.home" system property
          • "%g" the generation number to distinguish rotated logs
          • "%u" a unique number to resolve conflicts
          • "%%" translates to a single percent sign "%"

          If no "%g" field has been specified and the file count is greater than one, then the generation number will be added to the end of the generated filename, after a dot.
          Thus for example a pattern of "%t/java%g.log" with a count of 2 would typically cause log files to be written on Solaris to /var/tmp/java0.log and /var/tmp/java1.log whereas on Windows 95 they would be typically written to C:\TEMP\java0.log and C:\TEMP\java1.log
          Generation numbers follow the sequence 0, 1, 2, etc.

          Normally the "%u" unique field is set to 0. However, if the FileHandler tries to open the filename and finds the file is currently in use by another process it will increment the unique number field and try again. This will be repeated until FileHandler finds a file name that is not currently in use. If there is a conflict and no "%u" field has been specified, it will be added at the end of the filename after a dot. (This will be after any automatically added generation number.)
          Thus if three processes were all trying to log to fred%u.%g.txt then they might end up using fred0.0.txt, fred1.0.txt, fred2.0.txt as the first file in their rotating sequences.

          Note that the use of unique ids to avoid conflicts is only guaranteed to work reliably when using a local disk file system.

          The property "derby.infolog.append" is also supported. When set to

          derby.infolog.append=true

          an existing log file, if any, will be appended to. When set to

          derby.infolog.append=false

          the existing log files, if any, will be rolled and a new log file will be created.

          Show
          Brett Bergquist added a comment - Here is what I have for the documentation Kim. The rolling file implementation can either write to a specified file, or it can write to a rotating set of files. For a rotating set of files, as each file reaches a given size limit, it is closed, rotated out, and a new file opened. Successively older files are named by adding "0", "1", "2", etc into the base filename. The rolling file implementation is specified by adding: derby.stream.error.style=rollingFile in the "derby.properties" file. This property overrides: derby.stream.error.file derby.stream.error.method derby.stream.error.field With no other options specified, the rolling file implementation will create up to 10 rolling files "derby-0.log, derby-1.log, … derby-9.log" with each file having a limit of 1024000 bytes. The rolling file implementation can be configured with the following optional properties: derby.stream.error.rollingFile.limit=<bytes> which specifies the number of bytes to limit each rolling file to before rolling to the next file. The default value is "1024000" derby.stream.error.rollingFile.count=<file count> which specifies the number of rolling files to permit before deleting the oldest file when rolling to the next file. The default value is "10" derby.stream.error.rollingFile.pattern=<pattern> A pattern consists of a string that includes the following special components that will be replaced at runtime. The default value is "%d/derby-%g.log" • "/" the local pathname separator • "%t" the system temporary directory • "%h" the value of the "user.home" system property • "%d" the value of the "derby.system.home" system property • "%g" the generation number to distinguish rotated logs • "%u" a unique number to resolve conflicts • "%%" translates to a single percent sign "%" If no "%g" field has been specified and the file count is greater than one, then the generation number will be added to the end of the generated filename, after a dot. Thus for example a pattern of "%t/java%g.log" with a count of 2 would typically cause log files to be written on Solaris to /var/tmp/java0.log and /var/tmp/java1.log whereas on Windows 95 they would be typically written to C:\TEMP\java0.log and C:\TEMP\java1.log Generation numbers follow the sequence 0, 1, 2, etc. Normally the "%u" unique field is set to 0. However, if the FileHandler tries to open the filename and finds the file is currently in use by another process it will increment the unique number field and try again. This will be repeated until FileHandler finds a file name that is not currently in use. If there is a conflict and no "%u" field has been specified, it will be added at the end of the filename after a dot. (This will be after any automatically added generation number.) Thus if three processes were all trying to log to fred%u.%g.txt then they might end up using fred0.0.txt, fred1.0.txt, fred2.0.txt as the first file in their rotating sequences. Note that the use of unique ids to avoid conflicts is only guaranteed to work reliably when using a local disk file system. The property "derby.infolog.append" is also supported. When set to derby.infolog.append=true an existing log file, if any, will be appended to. When set to derby.infolog.append=false the existing log files, if any, will be rolled and a new log file will be created.
          Hide
          Kim Haase added a comment -

          Thanks very much for this information. I plan to get to it soon and will let you know if I have any questions.

          Show
          Kim Haase added a comment - Thanks very much for this information. I plan to get to it soon and will let you know if I have any questions.
          Hide
          Kim Haase added a comment -

          I would like to clarify the meaning of this sentence:

          "The rolling file implementation can either write to a specified file, or it can write to a rotating set of files."

          If you write to a specified file, you are not using a rolling file implementation, are you? Writing to a single file named derby.log is the default behavior, and writing to a specified file is the behavior with the derby.stream.error.file property, which is overridden by the derby.stream.error.style=rollingFile property, I think?

          So would it be more correct to say that the rolling file implementation writes to a specified set of files? Thanks very much.

          Show
          Kim Haase added a comment - I would like to clarify the meaning of this sentence: "The rolling file implementation can either write to a specified file, or it can write to a rotating set of files." If you write to a specified file, you are not using a rolling file implementation, are you? Writing to a single file named derby.log is the default behavior, and writing to a specified file is the behavior with the derby.stream.error.file property, which is overridden by the derby.stream.error.style=rollingFile property, I think? So would it be more correct to say that the rolling file implementation writes to a specified set of files? Thanks very much.
          Hide
          Brett Bergquist added a comment -

          If configured with a derby.stream.error.rollingFile.count=1 and derby.stream.error.rollingFile.limit=0, then in effect it is writing to one file of unlimited size, with the file being specified by derby.stream.error.rollingFile.pattern (if present) and if not defaulting to "%d/derby-%g.log (which will be derby-0.log in the directory of derby.system.home property or user.home property if that is not set).

          We need to document that "derby.stream.error.rollingFile.limit=0" is unlimited.

          So you probably will never want to it to be configured this way as you could just as well not use the rolling file implementation, but if you did configure limit=1 and count=0, then it will write to a specified file.

          Show
          Brett Bergquist added a comment - If configured with a derby.stream.error.rollingFile.count=1 and derby.stream.error.rollingFile.limit=0, then in effect it is writing to one file of unlimited size, with the file being specified by derby.stream.error.rollingFile.pattern (if present) and if not defaulting to "%d/derby-%g.log (which will be derby-0.log in the directory of derby.system.home property or user.home property if that is not set). We need to document that "derby.stream.error.rollingFile.limit=0" is unlimited. So you probably will never want to it to be configured this way as you could just as well not use the rolling file implementation, but if you did configure limit=1 and count=0, then it will write to a specified file.
          Hide
          Kim Haase added a comment -

          Thanks, Brett, that's very helpful.

          Would it be the case that if you specified limit=0, then it wouldn't matter what you set the count to, since the file would just keep getting bigger and never turn over?

          Show
          Kim Haase added a comment - Thanks, Brett, that's very helpful. Would it be the case that if you specified limit=0, then it wouldn't matter what you set the count to, since the file would just keep getting bigger and never turn over?
          Hide
          Kim Haase added a comment -

          I'm making a couple of additional assumptions:

          1) The properties are system-wide and static, like the other derby.stream.error properties.

          2) The three subordinate properties (count, limit, pattern) are ignored if derby.stream.error.style is not set to rollingFile.

          Hope those are correct.

          Show
          Kim Haase added a comment - I'm making a couple of additional assumptions: 1) The properties are system-wide and static, like the other derby.stream.error properties. 2) The three subordinate properties (count, limit, pattern) are ignored if derby.stream.error.style is not set to rollingFile. Hope those are correct.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-6359.diff, DERBY-6359.stat, and DERBY-6359.zip, with 4 new topics and changes to 2 others as well as the map file:

          M src/ref/crefproper22250.dita
          M src/ref/rrefproper13217.dita
          A src/ref/rrefproperrollingfilepattern.dita
          A src/ref/rrefproperrollingfilelimit.dita
          A src/ref/rrefproperrollingfile.dita
          A src/ref/rrefproperrollingfilecount.dita
          M src/ref/refderby.ditamap

          I'll be grateful for your comments.

          Show
          Kim Haase added a comment - Attaching DERBY-6359 .diff, DERBY-6359 .stat, and DERBY-6359 .zip, with 4 new topics and changes to 2 others as well as the map file: M src/ref/crefproper22250.dita M src/ref/rrefproper13217.dita A src/ref/rrefproperrollingfilepattern.dita A src/ref/rrefproperrollingfilelimit.dita A src/ref/rrefproperrollingfile.dita A src/ref/rrefproperrollingfilecount.dita M src/ref/refderby.ditamap I'll be grateful for your comments.
          Hide
          Brett Bergquist added a comment -

          Your comment on the properties being system wide are correct.
          Your comment on the other properties being ignored is correct if the style is not set to 'rollingFile'. These properties are only looked for when the style is 'rollingStyle'.

          The count must be >= 1 if it is specified and defaults to 10 if not.
          The limit must be >= 0 if specified, where 0 means no limit and if not specified defaults to 1024000
          The pattern must be >= 1 characters if specified and defaults to "%d/derby-%g.log" if not specified

          I think those are the extent of the rules.

          Show
          Brett Bergquist added a comment - Your comment on the properties being system wide are correct. Your comment on the other properties being ignored is correct if the style is not set to 'rollingFile'. These properties are only looked for when the style is 'rollingStyle'. The count must be >= 1 if it is specified and defaults to 10 if not. The limit must be >= 0 if specified, where 0 means no limit and if not specified defaults to 1024000 The pattern must be >= 1 characters if specified and defaults to "%d/derby-%g.log" if not specified I think those are the extent of the rules.
          Hide
          Kim Haase added a comment -

          Thanks, Brett! I will add those items and submit a revised patch.

          Show
          Kim Haase added a comment - Thanks, Brett! I will add those items and submit a revised patch.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-6359-2.diff and DERBY-6359-2.zip, with the recommended additions to the topics on the count, limit, and pattern properties. Also moved a sentence in the limit topic (about what happens when you specify 0) to a more appropriate location.

          Show
          Kim Haase added a comment - Attaching DERBY-6359 -2.diff and DERBY-6359 -2.zip, with the recommended additions to the topics on the count, limit, and pattern properties. Also moved a sentence in the limit topic (about what happens when you specify 0) to a more appropriate location.
          Hide
          Myrna van Lunteren added a comment -

          Kim, your last patch looks good to me, so far. Were you waiting for further comments/reviews?

          Show
          Myrna van Lunteren added a comment - Kim, your last patch looks good to me, so far. Were you waiting for further comments/reviews?
          Hide
          Kim Haase added a comment -

          Yes, I was waiting for final okay of the last patch.

          I have also been waiting for DERBY-6350 to be resolved. It appears that a patch was committed in late October, though no message appeared – so I'm not sure if the feature is completed or not.

          Thanks for checking, Myrna.

          Show
          Kim Haase added a comment - Yes, I was waiting for final okay of the last patch. I have also been waiting for DERBY-6350 to be resolved. It appears that a patch was committed in late October, though no message appeared – so I'm not sure if the feature is completed or not. Thanks for checking, Myrna.
          Hide
          Myrna van Lunteren added a comment -

          Yes, for some reason the automatic update didn't work for that commit, but the code is in.

          I think the remaining bit in DERBY-6350 is what to do regarding the empty derby.log file that gets created, but I don't think that should hold up the update to the documentation.

          Show
          Myrna van Lunteren added a comment - Yes, for some reason the automatic update didn't work for that commit, but the code is in. I think the remaining bit in DERBY-6350 is what to do regarding the empty derby.log file that gets created, but I don't think that should hold up the update to the documentation.
          Hide
          Kim Haase added a comment -

          Thanks, Myrna. I will go ahead and commit the last patch, then. If we need to say anything about that file, we can reopen the issue.

          Show
          Kim Haase added a comment - Thanks, Myrna. I will go ahead and commit the last patch, then. If we need to say anything about that file, we can reopen the issue.
          Hide
          ASF subversion and git services added a comment -

          Commit 1542028 from Kim Haase in branch 'docs/trunk'
          [ https://svn.apache.org/r1542028 ]

          DERBY-6359 Document rolling derby.log file feature

          Modified 2 Reference Manual topics and the map file, added 4 new topics.

          Patch: DERBY-6359-2.diff

          Show
          ASF subversion and git services added a comment - Commit 1542028 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1542028 ] DERBY-6359 Document rolling derby.log file feature Modified 2 Reference Manual topics and the map file, added 4 new topics. Patch: DERBY-6359 -2.diff
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-6359-2.diff to documentation trunk at revision 1542028.

          Show
          Kim Haase added a comment - Committed patch DERBY-6359 -2.diff to documentation trunk at revision 1542028.
          Hide
          Kim Haase added a comment -

          Fixes appear in latest alpha docs.

          Show
          Kim Haase added a comment - Fixes appear in latest alpha docs.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Brett Bergquist
            • Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development