How to find logs

If you file a ticket with Stardog Support, chances are you'll be asked to provide logs. The following logs you may be asked to provide include:

• stardog.log
• ZooKeeper log (cluster installations only)    
  
• audit log

How to find the logs

The easiest way to gather everything

The easiest way to gather log files is to run a diagnostics report. You can do that by running:

• For single-node deployments    
  • `stardog-admin diagnostics report`
• For cluster deployments
  • `stardog-admin cluster diagnostics report`

If for some reason the diagnostics report is not able to grab the log file(s) you need (this most often happens in cluster deployments when a node is out of the cluster), see the below sections to retrieve logs manually.

How to find stardog.log

Your stardog.log file is configured via log4j2. The default `log4j2.xml` file can be found at `<stardog-installation-directory>/server/dbms`. If you want to make modifications to this file, you can copy it to your $STARDOG_HOME directory.

To find your stardog.log file, open your `log4j2.xml` file and look for: 

<Property name="LOG_DIR">${sys:stardog.home}</Property>

`${sys:stardog.home}` is the default value, but another directory may be listed if you've changed this property. If you see the default value, this means your stardog.log file is located in your home directory.

How to find the ZooKeeper log

Like stardog.log, your zookeeper.log file is configured via log4j2. The ZooKeeper log will be found in the same directory your stardog.log is (likely $STARDOG_HOME).

How to find the audit log

The audit log is not enabled by default, and it can be enabled by setting the following property in `stardog.properties`:

logging.audit.enabled = true

By default, the audit log is saved as `audit.log` in the $STARDOG_HOME directory. If you want to change its name and/or directory, you can set the following property in `stardog.properties`:

logging.audit.file = /path/to/my_audit.log

Sending logs to support

What to do if your log file is very large

If your log file is very large, this is probably because it covers multiple months or years. The log being large can make moving/attaching it take a long time. To avoid this, you have two options:

• Enable log rotation (covered in the appendix)
• Use a text editor to delete the log entries that are irrelevant to your issue
  • For example, if your issue started occurring on August 8th and your log has entries dating back three years, you can safely delete all entries before August of the current year for the copy of the log you send to support. (Please do not delete any log entries in your permanent log file!)
  • If you erroneously deleted log entries that support needs to troubleshoot your issue, we'll let you know. Because you didn't delete any entries in your permanent log file, you'll still have them on hand.

How to attach your logs to a ticket

Files smaller than 20MB can be attached directly to the ticket. For files larger than this, you can upload the file to Dropbox.

Appendix

If you're using Kubernetes

If you're running Stardog in Kubernetes, you'll need to get the logs off of the pods and onto your local filesystem so you can send them to support. To do this, you can use the `kubectl cp` command like so:

kubectl cp [flags] <local file> <namespace>/<pod>:<container file path>

How to enable log rotation

stardog.log

• Comment out the following code in your `log4j2.xml` file. (Note: you must copy the `log4j2.xml` file to $STARDOG_HOME modify it.)

  • <File name="stardogAppender"
        fileName="${LOG_DIR}/${STARDOG_LOG}.log">
      <PatternLayout pattern="${PATTERN}"/>
    </File>

• Add the following to your `log4j2.xml` file. 

  • <RollingFile
      name="stardogAppender"
      fileName="${LOG_DIR}/${STARDOG_LOG}.log"
            filePattern="${LOG_DIR}/${STARDOG_LOG}-%d{MM-dd-yyyy}-%i.log.gz">
      <PatternLayout pattern="${PATTERN}"/>
      <Policies>
        <!-- <SizeBasedTriggeringPolicy size="500 MB"/> -->
        <TimeBasedTriggeringPolicy interval="1" modulate="true"/>
      </Policies>
      <DefaultRolloverStrategy max="1">
        <Delete basePath="${LOG_DIR}" maxDepth="2">
            <IfFileName glob="${STARDOG_LOG}-*.log.gz" />
            <IfLastModified age="30d" />
        </Delete>
      </DefaultRolloverStrategy>
    </RollingFile>

  • `fileName` determines the directory and name of the stardog.log file. Please do not change this.
  • `filePattern` determines the pattern for rotated files. These rotated files will have a date and index appended to their names and will be compressed using gzip.
  • There are two options for how logs can be rotated: based on log size, or based on time since last rotation. The above code snippet has size-based rotation commented out, so the stardog.log it corresponds to will be rotated based on time since last rotation. You should only have one of these options set and comment out the other one.
    • For size-based policies, `size` corresponds to the size limit after which the log will be rotated. 500MB is the default.
    • For time-based policies, `interval` corresponds to the number of days after which logs are rotated. 1 day is the default.
  • `IfLastModified` determines for how long rotated logs will be kept. 30 days is the default.

The process to enable log rotation for the ZooKeeper log is very similar to enabling it for stardog.log.

• Comment out the following code in your `log4j2.xml` file. (Note: you must copy the `log4j2.xml` file to $STARDOG_HOME modify it.)

  • <File name="zookeeperAppender"
        fileName="${LOG_DIR}/${ZOOKEEPER_LOG}.log">
      <PatternLayout pattern="${PATTERN}"/>
    </File>

• Add the following to your `log4j2.xml` file. 

  • <RollingFile
      name="zookeeperAppender"
      fileName="${LOG_DIR}/${ZOOKEEPER_LOG}.log"
            filePattern="${LOG_DIR}/${ZOOKEEPER_LOG}-%d{MM-dd-yyyy}-%i.log.gz">
      <PatternLayout pattern="${PATTERN}"/>
      <Policies>
        <!-- <SizeBasedTriggeringPolicy size="500 MB"/> -->
        <TimeBasedTriggeringPolicy interval="1" modulate="true"/>
      </Policies>
      <DefaultRolloverStrategy max="1">
        <Delete basePath="${LOG_DIR}" maxDepth="2">
            <IfFileName glob="${ZOOKEEPER_LOG}-*.log.gz" />
            <IfLastModified age="30d" />
        </Delete>
      </DefaultRolloverStrategy>
    </RollingFile>

  • For a description of what these properties mean, see the above section for enabling log rotation for the stardog.log file.

The following options can be set in your `stardog.properties` file to enable and configure log rotation:

# `time` or `size`. Must be set to enable log rotation
logging.audit.rotation.type = time

# `time`: A positive integer followed by 'd' for days or 'h' for hours
# `size`:  A positive integer. Represents the size limit in bytes
logging.audit.rotation.interval = 1d 

# Whether rotated logs will be compressed with gzip
logging.audit.rotation.compress = true

# Number of rotated logs to keep before deletion
logging.audit.rotation.file.count = 5

Note the values for these properties are examples and can be set freely.