# Logging Sample Configuration File

Below is a sample logging configuration file. This file can be tweaked to control how your homeserver will output logs. A restart of the server is generally required to apply any changes made to this file.

Note that the contents below are not intended to be copied and used as the basis for a real homeserver.yaml. Instead, if you are starting from scratch, please generate a fresh config using Synapse by following the instructions in Installation.

    # Log configuration for Synapse.
    #
    # This is a YAML file containing a standard Python logging configuration
    # dictionary. See [1] for details on the valid settings.
    #
    # Synapse also supports structured logging for machine readable logs which can
    # be ingested by ELK stacks. See [2] for details.
    #
    # [1]: https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema
    # [2]: https://github.com/matrix-org/synapse/blob/master/docs/structured_logging.md

    version: 1

    formatters:
        precise:
            format: '%(asctime)s - %(name)s - %(lineno)d - %(levelname)s - %(request)s - %(message)s'

    handlers:
        file:
            class: logging.handlers.TimedRotatingFileHandler
            formatter: precise
            filename: /var/log/matrix-synapse/homeserver.log
            when: midnight
            backupCount: 3  # Does not include the current log file.
            encoding: utf8

        # Default to buffering writes to log file for efficiency. This means that
        # will be a delay for INFO/DEBUG logs to get written, but WARNING/ERROR
        # logs will still be flushed immediately.
        buffer:
            class: logging.handlers.MemoryHandler
            target: file
            # The capacity is the number of log lines that are buffered before
            # being written to disk. Increasing this will lead to better
            # performance, at the expensive of it taking longer for log lines to
            # be written to disk.
            capacity: 10
            flushLevel: 30  # Flush for WARNING logs as well

        # A handler that writes logs to stderr. Unused by default, but can be used
        # instead of "buffer" and "file" in the logger handlers.
        console:
            class: logging.StreamHandler
            formatter: precise

    loggers:
        synapse.storage.SQL:
            # beware: increasing this to DEBUG will make synapse log sensitive
            # information such as access tokens.
            level: INFO

        twisted:
            # We send the twisted logging directly to the file handler,
            # to work around https://github.com/matrix-org/synapse/issues/3471
            # when using "buffer" logger. Use "console" to log to stderr instead.
            handlers: [file]
            propagate: false

    root:
        level: INFO

        # Write logs to the `buffer` handler, which will buffer them together in memory,
        # then write them to a file.
        #
        # Replace "buffer" with "console" to log to stderr instead. (Note that you'll
        # also need to update the configuration for the `twisted` logger above, in
        # this case.)
        #
        handlers: [buffer]

    disable_existing_loggers: false
    ``__`