Structured Logging Keys

Liquibase uses a Mapped Diagnostic Context (MDC) to generate structured logs in a JSON format. The output is a nested group of key-value pairs. You can access data from your structured logs by calling on the keys described on this page.

Most values in the log are strings. Other JSON types such as arrays and integers are used for some nested keys.

In Liquibase 4.23.2+, you can create a custom metadata file that controls exactly which keys appears in your Structured Logs. For more information, see Custom and Private Data in Structured Logs.

System keys

The following keys can appear in all structured logs, regardless of which command the log originates from:

Key Description
class Liquibase Java class associated with log event
changelog Name of the changelog associated with the log event
changesetAuthor Value of --author. Author of the changeset being logged
changesetCount Number of changesets associated with the log event
changesetId Value of --id. ID of the changeset being logged
changesetOutcome Outcome of deploying this changeset
deploymentId ID of database deployment. Appears in all logs in Liquibase 4.25.0+.
deploymentOutcome Outcome of the database deployment. Appears in all logs in Liquibase 4.25.0+.
deploymentOutcomeCount Number of changesets deployed. Appears in all logs in Liquibase 4.25.0+.
level Value of --log-level. Level of detail of the output.
liquibaseInternalCommand Name of the internal Liquibase operation
liquibaseCatalogName Value of --liquibase-catalog-name. Name of the database catalog. Appears in all logs in Liquibase 4.25.0+.
liquibaseCommandName Name of the command entered in the CLI
liquibaseSchemaName Value of --liquibase-schema-name. Name of the database schema. Appears in all logs in Liquibase 4.25.0+.
liquibaseSystemName System name running Liquibase
liquibaseSystemUser Name of user running Liquibase
liquibaseTargetUrl URL of the target database associated with the log
liquibaseVersion Version of Liquibase installed
message Short descriptor of log event
operationStart UTC timestamp of operation start
operationStop UTC timestamp of operation end
rowsAffected Number of rows in a table the change affects
thread Thread being used
timestamp UTC timestamp of log event

checks run

In Liquibase 4.25.1+, the checks run output delivers an expansive log of Policy Checks that can run against changelogs and databases. This allows you to dive deep into what policy checks are run, if they are customized, and more.

Keys that can appear in a checks run Structured Log:

Top-level keys

Key Description
changelogChecks The checks that run against the changelog
databaseChecks The checks that run against the database

Keys within changelogChecks array

Key Description
executedChecks The checks executed against the changelog
hasProLicense The changelogs that have a Pro license key
changesetsValidated The changelogs that have valid changesets.
productVersion The version of Liquibase currently being used with the given changelog
username Value of username
issueCount The issue count occurring in the changelog
executionDate The date each check was executed against the changelog
unlicensedChangesetsCount Number count of unlicensed changeset that exist in the given changelog
unlicensedChangesets List of unlicensed changesets that exist in the given changelog
unrecognizedChecks Any unrecognized checks that exist in the given changelog
executedChecksCount Number count of executed checks that ran against the changelog
issues Any issues existing within the changelog
changesetsValidatedCount Number count of validated changesets existing in the given changelog
changelogFilePath The file path of the given changelog
integration changelog integrated checks
unparseableChangesets List of any unparseable changesets within the given changelog
unparseableChangesetsCount Number count of the unparseable changesets within the given changelog
checksSettingsFile The checks settings file being utilized
returnCode The return code of each issue that exists within a changelog

Keys within each executedChecks object inside changelogChecks

Key Description
customizations Any customizations performed on checks executed against the changelog
description The description of the checks executed against the changelog
checkName The name of the checks executed against the changelog
enabled A list of enabled checks executed against the changelog
checkShortName The abbreviation of the checks executed against the changelog
severity The severity of the checks executed against the changelog

Keys within customizations object inside executedChecks

Key Description
constraint Any customized constraints assigned to checks that are executed
objectTypes List of existing object types within the customized executed checks
stripComments Allows you to strip comments from customized, executed checks
exceptionsList

List of any exceptions within the customized, executed checks

This includes:

  • exception primaryClass
  • exception primaryReason
  • exception source
  • exception details

Learn more here: Structured Logging
constraintOperator The constraint operator assigned to customized, executed checks
tableName List of existing tables within customized, executed checks
columnName List of existing columns within customized, executed checks
changeTypeList List of existing Change Types within customized, executed checks
maxColumns maximum number of columns allowed within customized, executed checks
allowedList the list of allowed customizations within executed checks
privilegeList the list of privileges within executed checks
message the executed checks message
operator the operator who carries out the customized, executed checks
searchString keywords that can be used to search the customized, executed checks
caseSensitive Customized, executed checks that are case sensitive

Keys within each issues object inside changelogChecks

Key Description
changesetAuthor The changeset author of each issue that exists within a changelog
changesetFilePath The changeset file path of each issue that exists within a changelog
changesetId The changeset ID of each issue that exists within a changelog
checkMessage The message of each issue that exists within a changelog
checkName The name of each issue that exists within a changelog
checkReturnCode The return code of each issue that exists within a changelog
checkSeverity the severity of each issue that exists within a changelog
checkShortName the abbreviated name of a changelog check from each issue

Keys within databaseChecks array

Key Description
target The targeted database
executedChecks The checks executed against the given database
hasProLicense States if the database has a Pro license key, or not
databaseObjectsValidatedCount The count of all objects validated within the database
productVersion States the version of Liquibase that is being utilized in the current database
username The username of who runs any database checks
issueCount The number of existing issues
executionDate The date the database check was executed on
unrecognizedChecks Lists any unrecognized checks
executedChecksCount The number of executed checks
issues List of any existing issues
integration Database integrated checks
databaseObjectsValidated List of database objects validated
targetType The type of target being used by the database
unparseableDatabaseObjectCount Number of any unparseable database objects
checksSettingsFile The checks settings file being utilized
returnCode the check return code of database checks

Keys within each executedChecks object inside databaseChecks

Key Description
customizations Any customizations performed on executed database checks
description The description of executed database checks
checkName The name of executed database checks
enabled List of the enabled database checks
checkShortName The abbreviated name of an executed database check
severity The severity of an executed database check

Keys within each customizations object inside databaseChecks

Key Description
constraint Constraints on the customized executed checks
objectTypes Customized object types of executed checks
stripComments Allows you to strip comments from customized, executed checks
exceptionsList

List of exceptions in customized, executed checks

This includes:

  • exception primaryClass
  • exception primaryReason
  • exception source
  • exception details

Learn more here: Structured Logging
constraintOperator The constraint operator assigned to customized, executed checks
tableName List of existing tables within customized, executed checks
columnName List of existing columns within customized, executed checks
changeTypeList List of existing Change Types within customized, executed checks
maxColumns maximum number of columns allowed within customized, executed checks
allowedList the list of allowed customizations within executed checks
privilegeList the list of privileges within executed checks
message the executed checks message
operator the operator who carries out the customized, executed checks
searchString keywords that can be used to search the customized, executed checks
caseSensitive Customized, executed checks that are case sensitive

Keys within each issues object inside databaseChecks

Key Description
checkMessage Message displayed about each issue appearing in the database
checkName The name of each issue appearing in the database
checkReturnCode the return code of each issue that exists within a database
checkSeverity The severity of each issue within the database
checkShortName The abbreviation of each issue within the database
databaseObjectLocation The location of a object within the database
databaseObjectName the name of an object within the database
databaseObjectType the type of object within the database

Keys within each object inside databaseObjectsValidated

Key Description
objectType List of the object type that are validated in the database
count Number count that are validated in the database
objects List of the objects that are validated in the database

changelog-sync

Keys that can appear in a changelog-sync structured log:

Key Description
changelogFile The changelog being synced
changelogSyncOutcome Whether the sync was executed or failed
changesetSyncCount Number of changesets added to the DATABASECHANGELOG table
changesetFilepath Path to changeset. Repeats in every changeset log message
changesetContext Context applied to changeset. Repeats in every changeset log message
changesetLabel Label applied to changeset. Repeats in every changeset log message
changesetOperationStart UTC timestamp of operation start. Repeats in every changeset log message
changesetOperationStop UTC timestamp of operation end. Repeats in every changeset log message
changesetSyncOutcome Outcome of changeset sync. Repeats in every changeset log message
databaseChangelogSql SQL to update the DATABASECHANGELOG table
databaseChangelogTableOutcome Outcome of update to the DATABASECHANGELOG table

dbcl-history

Keys that can appear in a dbcl-history structured log:

Key

 Description
arguments

A list of arguments the user specified, including the command.
author

Value from the changeset author attribute.
command

Name of the command the user specified.
contexts

Context(s) used to execute the changeset.
description

Short, auto-generated, human-readable description of the changeset.
end

Timestamp in the user's local timezone that the operation ended.
executedSql

The SQL Liquibase executed in the operation.
extensions

A list of extensions to Liquibase, including pre-installed drivers.
filename

Path to the changelog. This may be an absolute path or a relative path depending on how the changelog was passed to Liquibase. For best results, it should be a relative path. The logicalFilePath attribute can be used on the changelog or on individual changesets.
hostname

Name of the machine Liquibase executed the operation on.
id

Value from the changeset id attribute.
interface

The way you called Liquibase, such as the CLI or a flow file.
internalCommand

Internal name of the command Liquibase ran.
labels

Label(s) used to execute the changeset.
liquibaseVersion

Version of Liquibase used to execute the changeset.
md5Sum

Checksum of the changeset when it was executed. Used on each run to ensure there have been no unexpected changes to changesets in the changelog file. See Changeset Checksums.
outcome

Description of how the changeset was executed. Possible values include EXECUTED, FAILED, SKIPPED, RERAN, and MARK_RAN.
start

Timestamp in the user's local timezone that the operation started.
systemUser

Name of the system account who initiated the Liquibase operation.
tag

Tracks which changesets correspond to tag operations.

diff

Keys that can appear in a diff and/or diff-changelog structured log:

Key Command Description
diffOutcome diff Whether the diff was successful
diffResultsSummary diff

Diff result info. Contains nested keys:

  • changed
    • count
  • missing
    • count
  • unexpected
    • count
format diff Value of --format
outputFile diff Value of --output-file
schema diff Value of --schemas
diffTypes diff, diff-changelog Value of --diff-types
excludeObjects diff, diff-changelog Value of --exclude-objects
includeObjects diff, diff-changelog Value of --include-objects
liquibaseReferenceUrl diff, diff-changelog Value of --reference-url
outputSchemas diff, diff-changelog Value of --output-schemas
referenceDefaultCatalogName diff, diff-changelog Value of --reference-default-catalog-name
referenceDefaultSchemaName diff, diff-changelog Value of --reference-default-schema-name
referenceSchemas diff, diff-changelog Value of --reference-schemas
referenceUsername diff, diff-changelog Value of --reference-username
changesetComment diff-changelog Comment applied to changeset
changesetLabel diff-changelog Label applied to changeset
commandContextFilter diff-changelog Value of --context-filter
commandLabelFilter diff-changelog Value of --label-lilter
databaseChangelogSql diff-changelog SQL to update the DATABASECHANGELOG table
databaseChangelogTableOutcome diff-changelog Outcome of update to the DATABASECHANGELOG table
diffChangelogFile diff-changelog <path/to/the/generated/changelog>
includeCatalog diff-changelog Value of --include-catalog
includeSchema diff-changelog Value of --include-schema
includeTablespace diff-changelog Value of --include-tablespace
schemas diff-changelog Value of the --schemas property

flow

Keys that can appear in Structured Logs for the flow command:

Key Description
changelogFile The changelog file you are using with the flow command
commandContextFilter Value of --context-filter
commandLabelFilter Value of --label-filter
rollbackOnError  

history

Keys that can appear in a Structured Log for the history command:

Key Description
changelogPath Path to the changelog you are using with the history command
changesets  
history  
updateDate Date of last deployment

rollback

Keys that can appear in a structured log for commands in the rollback* family. For information about the commands, see rollback, rollback-count, rollback-one-changeset, rollback-one-update, and rollback-to-date.

Key Command Description
changelogFile rollback* The changelog containing changesets being rolled back
changesetComment rollback* Comment applied to changeset
changesetLabel rollback* Label applied to changeset
changesetOperationStart rollback* UTC timestamp of operation start. Repeats in every changeset log message
changesetOperationStop rollback* UTC timestamp of operation end. Repeats in every changeset log message
changesetOutcome rollback* Individual changeset outcomes
changesetSql rollback* Generated/executed SQL
changesetsRolledBack rollback*

The changesets that were rolled back. Contains nested keys:

  • changesetCount
  • changeset
    • changesetAuthor
    • changesetFilepath
    • changesetId
    • changesetOutcome
    • deploymentId
commandContextFilter rollback* Value of --context-filter
commandLabelFilter rollback* Value of --label-filter
databaseChangelogSql rollback* SQL to update the DATABASECHANGELOG table
databaseChangelogTableOutcome rollback* Outcome of update to the DATABASECHANGELOG table
rollbackCount rollback-count Value of --count in rollback-count logs only
rollbackDate rollback-to-date Value of --date in rollback-date logs only
rollbackOneChangesetForce rollback-one-changeset Value of --force in rollback-one-changeset logs only
rollbackOneUpdateForce rollback-one-update Value of --force in rollback-one-update logs only
rollbackScript rollback* Value of --rollback-script
rollbackToTag rollback Value of --tag

status

Keys that can appear in a Structured Log for the status command:

Key Description
changelogFile The changelog potentially containing undeployedchangesets
commandContextFilter Value of --context-filter
commandLabelFilter Value of --label-filter

update

Keys that can appear in structured log for commands in the update* family. For information about the commands, see update, update-count, update-one-changeset, update-testing-rollback, and update-to-tag.

Key Command Description
changelogFile update* The changelog containing changesets being deployed
changesetComment update* Comment applied to changeset
changesetLabel update* Label applied to changeset
changesetOperationStart update* UTC timestamp of operation start. Repeats in every changeset log message
changesetOperationStop update* UTC timestamp of operation end. Repeats in every changeset log message
changesetSql update* Generated/executed SQL
changesetsUpdated update*

The changesets that were updated. Contains nested keys:

  • changesetCount
  • changeset
    • changesetAuthor
    • changesetFilepath
    • changesetId
    • changesetOutcome
    • deploymentId
commandContextFilter update* Value of --context-filter
commandLabelFilter update* Value of --label-filter
databaseChangelogSql update* SQL to update the DATABASECHANGELOG table
databaseChangelogTableOutcome update* Outcome of update to the DATABASECHANGELOG table
rollbackOnError update* Value of --rollback-on-error
updateSummary update*

Only if --show-summary=summary. Contains nested keys:

  • value
  • run
  • runPreviously
  • skipped
    • dbmsUnknown
    • labels
    • context
    • totalSkipped
  • totalChangesets

version

Keys that can appear in a Structured Log for the version global argument:

Key Description
javaHome

Contains nested keys:

  • path
  • version
liquibaseLibraries

Contains nested keys:

libraries

  • "name": "Apache Commons Collections",
    "path": "internal/lib/commons-collections4.jar"
  • "name": "Apache Commons Lang",
    "path": "internal/lib/commons-lang3.jar"
  • "name": "Apache Commons Text",
    "path": "internal/lib/commons-text.jar"
  • "name": "H2 Database Engine",

    "path": "internal/lib/h2.jar"
  • "name": "HSQLDB",

    "path": "internal/lib/hsqldb.jar"
  • "name": "jaxb-api",

    "path": "internal/lib/jaxb-api.jar"
  • "name": "JAXB Core",

    "path": "internal/lib/jaxb-core.jar"
  • "name": "JAXB Runtime",

    "path": "internal/lib/jaxb-runtime.jar"
  • "name": "Jaybird",

    "path": "internal/lib/jaybird.jar"
  • "name": "IBM JCC JDBC 4 Driver",

    "path": "internal/lib/jcc.jar"
  • "name": "Commercial Liquibase Functionality",

    "path": "internal/lib/liquibase-commercial.jar"
  • "name": "mariadb-java-client",

    "path": "internal/lib/mariadb-java-client.jar"
  • "name": "Microsoft JDBC Driver for SQL Server",

    "path": "internal/lib/mssql-jdbc.jar"
  • "name": "JDBC",

    "path": "internal/lib/ojdbc8.jar"
  • "name": "opencsv",

    "path": "internal/lib/opencsv.jar"
  • "name": "picocli",

    "path": "internal/lib/picocli.jar"
  • "name": "PostgreSQL JDBC Driver",

    "path": "internal/lib/postgresql.jar"
  • "name": "SnakeYAML",

    "path": "internal/lib/snakeyaml.jar"
  • "name": "snowflake-jdbc",

    "path": "internal/lib/snowflake-jdbc.jar"
  • "name": "SQLite JDBC",

    "path": "internal/lib/sqlite-jdbc.jar"